# bgx-11/shadowlog architecture

> Architecture diagram of the GitHub repository bgx-11/shadowlog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bgx-11/shadowlog
- Repository: https://github.com/bgx-11/shadowlog

## Overview

1. **Repository shape**
   - This is a Windows-only Go monorepo with three runtime binaries: the main agent (`WinUpdateSvc.exe`), a local forensic viewer/decryptor (`Decryptor.exe`), and a cleanup tool (`Uninstaller.exe`).
   - It also includes a separate Next.js marketing/documentation site under `site/`, plus build/release artifacts like a manifest and packaged ZIP.

2. **Primary runtime boundary**
   - `main.go` is the entrypoint for the installed monitor/service-like agent.
   - Its job is to initialize the environment, elevate privileges, apply anti-analysis checks, load encrypted config, set persistence, then start telemetry collection and outbound delivery.

3. **Configuration and identity layer**
   - The `config/` package centralizes encrypted configuration storage, machine-specific key derivation, and filesystem/registry path handling.
   - A notable boundary is that configuration is stored in the Windows Registry rather than a normal config file, while runtime data is written to a disguised Windows directory path.

4. **Monitoring and capture subsystem**
   - The `monitor/` package is the core telemetry engine.
   - Submodules split by signal source: clipboard (`clipboard.go`), USB events (`usb.go`), Wi‑Fi information (`wifi.go`), network channels (`smtp.go`, `doh.go`), and command/control or shutdown logic (`killswitch.go`).
   - `monitor.go` acts as the orchestration layer for hooks, window/context tracking, and screenshot capture.

5. **Data flow from event to record**
   - Captured events are contextualized with active-window/process metadata, then written locally and/or forwarded out through configured channels.
   - The design emphasizes a single event pipeline feeding multiple sinks: local encrypted storage, email, DNS-over-HTTPS, and other network-based delivery paths.

6. **Local storage and log management**
   - The repository uses encrypted local log storage with rotation support to bound disk usage.
   - The storage path is intentionally disguised under a legitimate-looking Windows cache location, and the README indicates timestamp spoofing to reduce forensic visibility.

7. **Outbound delivery boundaries**
   - Exfiltration is not hard-wired to one transport; it is modularized across SMTP email and DNS-over-HTTPS, with Telegram-related command/control behavior implied by the kill-switch logic.
   - This makes the network boundary a fan-out stage rather than a single endpoint, with different transports acting as primary and fallback channels.

8. **Persistence and removal**
   - `persistence/persistence.go` handles startup persistence, likely through registry Run keys and scheduled tasks as described in the README.
   - `uninstaller/main.go` is a separate operational boundary that reverses those changes and purges stored artifacts, rather than being embedded into the main agent flow.

9. **Decryptor / forensic viewer**
   - `decryptor/main.go` is an offline companion tool for reading the encrypted local data store and presenting it in a dashboard at `localhost`.
   - Architecturally, it is the inverse of the agent: it consumes the agent’s stored artifacts, unlocks them using either a password or machine-bound derivation, and exposes them for analysis/export.

10. **Setup UI and public site**
   - `ui/ui.go` is the local configuration/setup layer for the agent, including initial onboarding and delivery-channel setup.
   - The `site/` directory is a separate Next.js frontend for the product website, privacy/terms pages, and download navigation; it is not part of the Windows runtime, but it supports distribution and user-facing setup documentation.

11. **Build and packaging**
   - `build.bat`, the `.manifest`, and generated `.syso` resource file show a Windows-focused build pipeline with embedded elevation behavior.
   - The release artifacts (`ShadowLog_Release_v4.0.zip`, the EXEs) indicate the repo is organized around producing a packaged Windows deployment rather than a library or server application.

12. **High-level architecture in one sentence**
   - The system is a Windows agent that collects contextual user activity, stores it locally in encrypted form, sends it through multiple outbound channels, persists itself on the host, and is paired with separate decryptor and uninstaller utilities plus a standalone marketing website.

Main entry points: [`monitor/monitor.go`](https://github.com/bgx-11/shadowlog/blob/main/monitor/monitor.go) (Telemetry engine), [`main.go`](https://github.com/bgx-11/shadowlog/blob/main/main.go) (Agent entry), [`build.bat`](https://github.com/bgx-11/shadowlog/blob/main/build.bat) (Windows build), [`config/config.go`](https://github.com/bgx-11/shadowlog/blob/main/config/config.go) (Config core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Windows runtime"]
  node_main["Agent entry<br/>go entrypoint<br/>[main.go]"]
  node_ui["Setup UI<br/>go setup<br/>[ui.go]"]
  node_config["Config core<br/>go config<br/>[config.go]"]
  node_machine["Machine keys<br/>go identity<br/>[machine.go]"]
  node_paths["Paths<br/>[paths.go]"]
  node_monitor["Telemetry engine<br/>go orchestrator<br/>[monitor.go]"]
  node_clipboard["Clipboard<br/>go source<br/>[clipboard.go]"]
  node_usb["USB<br/>go source<br/>[usb.go]"]
  node_wifi["Wi-Fi<br/>go source<br/>[wifi.go]"]
  node_smtp["SMTP<br/>go transport<br/>[smtp.go]"]
  node_doh["DoH<br/>go transport<br/>[doh.go]"]
  node_killswitch["Kill switch<br/>go control<br/>[killswitch.go]"]
  node_persistence["Persistence<br/>[persistence.go]"]
  node_decryptor["Decryptor<br/>go viewer<br/>[main.go]"]
  node_uninstaller["Uninstaller<br/>go cleanup<br/>[main.go]"]
end

subgraph group_site["Public site"]
  node_site["Website<br/>nextjs app<br/>[page.js]"]
end

subgraph group_build["Build and release"]
  node_build["Windows build<br/>bat packaging<br/>[build.bat]"]
  node_artifact["Release bundle<br/>release artifact"]
end

node_main -->|"load"| node_config
node_main -->|"derive"| node_machine
node_main -->|"resolve"| node_paths
node_main -->|"bootstrap"| node_ui
node_main -->|"install"| node_persistence
node_main -->|"start"| node_monitor
node_monitor -->|"source"| node_clipboard
node_monitor -->|"source"| node_usb
node_monitor -->|"source"| node_wifi
node_monitor -->|"fan-out"| node_smtp
node_monitor -->|"fan-out"| node_doh
node_monitor -->|"control"| node_killswitch
node_monitor -->|"read/write"| node_config
node_config -->|"protect"| node_machine
node_config -->|"store"| node_paths
node_decryptor -->|"unlock"| node_config
node_decryptor -->|"locate"| node_paths
node_uninstaller -->|"remove"| node_persistence
node_uninstaller -->|"purge"| node_paths
node_site -->|"distribute"| node_artifact
node_build -->|"package"| node_artifact
node_build -->|"compile"| node_main
node_build -->|"compile"| node_decryptor
node_build -->|"compile"| node_uninstaller
node_build -.->|"build"| node_site

click node_main "https://github.com/bgx-11/shadowlog/blob/main/main.go"
click node_ui "https://github.com/bgx-11/shadowlog/blob/main/ui/ui.go"
click node_config "https://github.com/bgx-11/shadowlog/blob/main/config/config.go"
click node_machine "https://github.com/bgx-11/shadowlog/blob/main/config/machine.go"
click node_paths "https://github.com/bgx-11/shadowlog/blob/main/config/paths.go"
click node_monitor "https://github.com/bgx-11/shadowlog/blob/main/monitor/monitor.go"
click node_clipboard "https://github.com/bgx-11/shadowlog/blob/main/monitor/clipboard.go"
click node_usb "https://github.com/bgx-11/shadowlog/blob/main/monitor/usb.go"
click node_wifi "https://github.com/bgx-11/shadowlog/blob/main/monitor/wifi.go"
click node_smtp "https://github.com/bgx-11/shadowlog/blob/main/monitor/smtp.go"
click node_doh "https://github.com/bgx-11/shadowlog/blob/main/monitor/doh.go"
click node_killswitch "https://github.com/bgx-11/shadowlog/blob/main/monitor/killswitch.go"
click node_persistence "https://github.com/bgx-11/shadowlog/blob/main/persistence/persistence.go"
click node_decryptor "https://github.com/bgx-11/shadowlog/blob/main/decryptor/main.go"
click node_uninstaller "https://github.com/bgx-11/shadowlog/blob/main/uninstaller/main.go"
click node_site "https://github.com/bgx-11/shadowlog/blob/main/site/app/page.js"
click node_build "https://github.com/bgx-11/shadowlog/blob/main/build.bat"
click node_artifact "https://github.com/bgx-11/shadowlog/blob/main/ShadowLog_Release_v4.0.zip"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_ui,node_config,node_machine,node_paths,node_monitor,node_clipboard,node_usb,node_wifi,node_smtp,node_doh,node_killswitch,node_persistence,node_decryptor,node_uninstaller toneBlue
class node_site toneAmber
class node_build,node_artifact toneMint
```

## Components

### Windows runtime

Installed agent, telemetry, persistence, and companion utilities.

- [Agent entry](https://github.com/bgx-11/shadowlog/blob/main/main.go): go entrypoint · Initializes the installed Windows agent and starts the core runtime. · `main.go`
- [Setup UI](https://github.com/bgx-11/shadowlog/blob/main/ui/ui.go): go setup · Local onboarding and delivery-channel configuration layer. · `ui/ui.go`
- [Config core](https://github.com/bgx-11/shadowlog/blob/main/config/config.go): go config · Encrypted configuration storage and access boundary. · `config/config.go`
- [Machine keys](https://github.com/bgx-11/shadowlog/blob/main/config/machine.go): go identity · Machine-bound key derivation for protecting local data and config. · `config/machine.go`
- [Paths](https://github.com/bgx-11/shadowlog/blob/main/config/paths.go): go paths · Windows registry and filesystem path handling for disguised runtime storage. · `config/paths.go`
- [Telemetry engine](https://github.com/bgx-11/shadowlog/blob/main/monitor/monitor.go): go orchestrator · Coordinates hooks, context tracking, and capture flow. · `monitor/monitor.go`
- [Clipboard](https://github.com/bgx-11/shadowlog/blob/main/monitor/clipboard.go): go source · Captures clipboard-derived events. · `monitor/clipboard.go`
- [USB](https://github.com/bgx-11/shadowlog/blob/main/monitor/usb.go): go source · Captures USB-related events. · `monitor/usb.go`
- [Wi-Fi](https://github.com/bgx-11/shadowlog/blob/main/monitor/wifi.go): go source · Captures wireless/network environment information. · `monitor/wifi.go`
- [SMTP](https://github.com/bgx-11/shadowlog/blob/main/monitor/smtp.go): go transport · Email-based outbound delivery path. · `monitor/smtp.go`
- [DoH](https://github.com/bgx-11/shadowlog/blob/main/monitor/doh.go): go transport · DNS-over-HTTPS delivery path. · `monitor/doh.go`
- [Kill switch](https://github.com/bgx-11/shadowlog/blob/main/monitor/killswitch.go): go control · Remote control and shutdown boundary for the monitoring runtime. · `monitor/killswitch.go`
- [Persistence](https://github.com/bgx-11/shadowlog/blob/main/persistence/persistence.go): go persistence · Startup persistence installation and removal logic. · `persistence/persistence.go`
- [Decryptor](https://github.com/bgx-11/shadowlog/blob/main/decryptor/main.go): go viewer · Offline tool that unlocks and displays encrypted local data. · `decryptor/main.go`
- [Uninstaller](https://github.com/bgx-11/shadowlog/blob/main/uninstaller/main.go): go cleanup · Removes persistence and purges stored artifacts. · `uninstaller/main.go`

### Public site

Next.js marketing and documentation frontend.

- [Website](https://github.com/bgx-11/shadowlog/blob/main/site/app/page.js): nextjs app · Public marketing and documentation site. · `site/app/page.js`

### Build and release

Windows packaging and shipped artifacts.

- [Windows build](https://github.com/bgx-11/shadowlog/blob/main/build.bat): bat packaging · Build and packaging flow for the Windows binaries and release artifacts. · `build.bat`
- [Release bundle](https://github.com/bgx-11/shadowlog/blob/main/ShadowLog_Release_v4.0.zip): release artifact · Packaged release outputs and shipped binaries. · `ShadowLog_Release_v4.0.zip`

## Connections

- Agent entry → Config core: load · Loads encrypted runtime configuration.
- Agent entry → Machine keys: derive · Uses machine-bound identity for keys and protection.
- Agent entry → Paths: resolve · Resolves registry and filesystem storage locations.
- Agent entry → Setup UI: bootstrap · Invokes local setup and channel configuration.
- Agent entry → Persistence: install · Applies startup persistence.
- Agent entry → Telemetry engine: start · Starts the telemetry and capture pipeline.
- Telemetry engine → Clipboard: source · Reads clipboard events into the pipeline.
- Telemetry engine → USB: source · Reads USB events into the pipeline.
- Telemetry engine → Wi-Fi: source · Reads Wi-Fi context into the pipeline.
- Telemetry engine → SMTP: fan-out · Sends records through email delivery.
- Telemetry engine → DoH: fan-out · Sends records through DNS-over-HTTPS delivery.
- Telemetry engine → Kill switch: control · Checks for remote stop or command-control actions.
- Telemetry engine → Config core: read/write · Uses configuration for capture and delivery behavior.
- Config core → Machine keys: protect · Binds stored secrets to the host machine.
- Config core → Paths: store · Uses registry and disguised directory paths.
- Decryptor → Config core: unlock · Reads the encrypted store using password or machine-bound derivation.
- Decryptor → Paths: locate · Finds the agent's local stored artifacts.
- Uninstaller → Persistence: remove · Reverses startup persistence changes.
- Uninstaller → Paths: purge · Deletes stored artifacts and traces.
- Website → Release bundle: distribute · Supports product distribution and download navigation.
- Windows build → Release bundle: package · Produces the Windows release bundle and executables.
- Windows build → Agent entry: compile · Builds the primary agent binary.
- Windows build → Decryptor: compile · Builds the decryptor utility.
- Windows build → Uninstaller: compile · Builds the cleanup utility.
- Windows build → Website: build · Builds the Next.js site for distribution.