# antropos17/aegis architecture

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

- Interactive diagram: https://gitdiagram.com/antropos17/aegis
- Repository: https://github.com/antropos17/aegis

## Overview

#### Purpose and Entry Points
AEGIS is a local, monitor-first desktop application for observing AI coding-agent processes, sensitive file activity, TCP endpoints, and behavioral risk without agent plugins. Electron’s main process starts the monitoring system; the Svelte renderer presents live state and manual process actions. Core entry points: `src/main/main.js`, `src/main/preload.js`, `src/renderer/main.js`, and `src/renderer/App.svelte`.

#### Process Discovery and Identity
The scan loop repeatedly enumerates processes, detects known agents from the shared signature database, resolves parent/IDE/WSL context, and assigns lifetime-aware identities. Identity and attribution are deliberately allowed to be weak or unknown, forming a key correctness boundary under PID reuse and incomplete OS metadata. Main components: `src/main/scan-loop.js`, `src/main/process-scanner.js`, `src/main/process-identity.js`; signatures reside in `src/shared/agent-database.json`.

#### Observation Sensors
Sensors independently collect process, file, network, resource, and runtime evidence. File watching runs through a worker-thread boundary and registered watch roots; network monitoring maps TCP endpoints back to detected PIDs. Platform adapters isolate Windows, macOS, Linux, proc-snapshot, Restart Manager, and experimental ETW mechanisms. Relevant paths: `src/main/file-watcher.js`, `src/main/watch-worker-thread.js`, `src/main/network-monitor.js`; platform boundary: `src/main/platform/index.js`, `src/main/platform/win32.js`, `src/main/platform/linux.js`.

#### Evidence Normalization, Attribution, and Health
Raw observations are normalized into a shared event model, linked to process identities, attributed at confirmed/inferred/unattributed confidence, and monitored for data gaps or degraded sensors. This separates sensor-specific collection from downstream detection and audit semantics. Primary modules: `src/main/attribution.js`, `src/main/audit-normalize.js`, `src/main/sensor-health.js`; shared normalization/types: `src/shared/ecs-normalizer.js`, `src/shared/types/events.ts`.

#### Detection and Risk Pipeline
Normalized events are evaluated against YAML sensitive-path rules, correlated by sequence rules, compared to rolling session baselines, and scored for anomalies. Rules are data-driven and hot-loadable rather than embedded in individual sensors. Components: `src/main/rule-loader.js`, `src/main/sequence-engine.js`, `src/main/anomaly-detector.js`; rule sources: `rules/_schema.json`, `rules/sequences/sequences.yaml`, `rules/ai-config.yaml`.

#### Durable Audit and Export Boundary
Events enter bounded audit logging and a hash-chained JSONL trail with rotation/retention. An audit index supports queries and rebuilds; exports stream data to JSON, CSV, HTML, or ZIP. The chain detects modification relative to trusted state but is not proof of complete capture, so observation-loss and health records are material inputs. Paths: `src/main/audit-logger.js`, `src/main/audit-hashchain.js`, `src/main/audit-index.js`, `src/main/exports.js`.

#### IPC, UI, and External Services
The preload bridge exposes constrained Electron IPC; handlers connect renderer requests to monitoring state, settings, audit queries, exports, and manual process controls. The renderer maintains event/risk/health stores and visualizes feeds, timelines, agent details, network activity, and reports. Paths: `src/main/ipc-handlers.js`, `src/renderer/lib/stores/ipc.ts`, `src/renderer/lib/components/ActivityFeed.svelte`, `src/renderer/lib/components/ThreatAnalysis.svelte`. Runtime stack is Node.js 24/Electron plus CommonJS main code and Svelte/TypeScript UI. Data stays local by default; optional AI analysis contacts Anthropic, while update checks/releases use GitHub and signed update verification is implemented in `src/main/update-verification.js`.

#### Windows Sidecars and Evaluation
C# sidecars provide Windows-specific ETW lifecycle/probing and process-snapshot experiments, invoked across a protocol boundary rather than embedded in the Electron process. The benchmark subsystem records/replays scenarios and compares observations with Sysmon oracle evidence to quantify specific sensor behavior. Paths: `sidecar/etw-lifecycle/Program.cs`, `sidecar/procsnap/Program.cs`, `src/main/platform/proc-snapshot-client.js`; evaluation orchestration: `bench/run.js`, `bench/replay.js`.

Main entry points: [`src/main/audit-normalize.js`](https://github.com/antropos17/aegis/blob/master/src/main/audit-normalize.js) (Normalize & attribute), [`src/main/main.js`](https://github.com/antropos17/aegis/blob/master/src/main/main.js) (Main process), [`src/main/ipc-handlers.js`](https://github.com/antropos17/aegis/blob/master/src/main/ipc-handlers.js) (IPC handlers), [`src/main/platform/index.js`](https://github.com/antropos17/aegis/blob/master/src/main/platform/index.js) (Platform adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Electron Runtime"]
  node_main["Main process<br/>Electron entry<br/>[main.js]"]
  node_preload["Preload bridge<br/>Electron IPC bridge<br/>[preload.js]"]
  node_ipc["IPC handlers<br/>main IPC API<br/>[ipc-handlers.js]"]
  node_renderer["Svelte renderer<br/>desktop UI<br/>[App.svelte]"]
end

subgraph group_observation["Observation"]
  node_scan["Scan &amp; identity<br/>process discovery<br/>[scan-loop.js]"]
  node_agents["Agent signatures<br/>signature database"]
  node_filewatch["File watcher<br/>file sensor<br/>[file-watcher.js]"]
  node_network["Network monitor<br/>TCP sensor<br/>[network-monitor.js]"]
end

subgraph group_evidence["Evidence &amp; Detection"]
  node_normalize["Normalize &amp; attribute<br/>evidence pipeline<br/>[audit-normalize.js]"]
  node_health["Sensor health<br/>coverage monitoring<br/>[sensor-health.js]"]
  node_rules["Rules &amp; sequences<br/>hot-loaded detection rules<br/>[rule-loader.js]"]
  node_anomaly["Anomaly detector<br/>risk scoring"]
end

subgraph group_audit["Audit &amp; Export"]
  node_auditlog[("Bounded audit log<br/>durable event log<br/>[audit-logger.js]")]
  node_hashchain[("Hash-chained trail<br/>integrity trail<br/>[audit-hashchain.js]")]
  node_index[("Audit index<br/>query index<br/>[audit-index.js]")]
  node_exports["Export service<br/>streaming export<br/>[exports.js]"]
end

subgraph group_external["Platform &amp; External"]
  node_platform{{"Platform adapters<br/>OS abstraction<br/>[index.js]"}}
  node_sidecars["Windows sidecars<br/>C&#35; sidecar processes<br/>[Program.cs]"]
  node_ai(("Optional AI analysis<br/>Anthropic service"))
  node_updates(("Signed updates<br/>GitHub update path"))
  node_bench["Benchmark replay<br/>sensor evaluation<br/>[replay.js]"]
end

node_main -->|"starts"| node_scan
node_main -->|"starts"| node_filewatch
node_main -->|"starts"| node_network
node_main -->|"registers"| node_ipc
node_agents -->|"identifies agents"| node_scan
node_platform -->|"process context"| node_scan
node_platform -->|"OS collection"| node_filewatch
node_platform -->|"endpoint data"| node_network
node_sidecars -.->|"protocol boundary"| node_platform
node_scan -->|"process evidence"| node_normalize
node_filewatch -->|"file evidence"| node_normalize
node_network -->|"network evidence"| node_normalize
node_normalize -->|"coverage signals"| node_health
node_normalize -->|"normalized events"| node_rules
node_rules -->|"rule matches"| node_anomaly
node_normalize -->|"event stream"| node_anomaly
node_health -->|"loss records"| node_auditlog
node_anomaly -->|"risk events"| node_auditlog
node_normalize -->|"audit events"| node_auditlog
node_auditlog -->|"chains records"| node_hashchain
node_auditlog -->|"indexes"| node_index
node_index -->|"query data"| node_exports
node_preload -->|"constrained IPC"| node_ipc
node_renderer -->|"UI requests"| node_preload
node_ipc -->|"live state"| node_renderer
node_ipc -->|"export requests"| node_exports
node_ipc -.->|"optional analysis"| node_ai
node_main -.->|"verified update checks"| node_updates
node_bench -.->|"evaluates sensors"| node_platform

click node_main "https://github.com/antropos17/aegis/blob/master/src/main/main.js"
click node_preload "https://github.com/antropos17/aegis/blob/master/src/main/preload.js"
click node_ipc "https://github.com/antropos17/aegis/blob/master/src/main/ipc-handlers.js"
click node_renderer "https://github.com/antropos17/aegis/blob/master/src/renderer/App.svelte"
click node_scan "https://github.com/antropos17/aegis/blob/master/src/main/scan-loop.js"
click node_agents "https://github.com/antropos17/aegis/blob/master/src/shared/agent-database.json"
click node_filewatch "https://github.com/antropos17/aegis/blob/master/src/main/file-watcher.js"
click node_network "https://github.com/antropos17/aegis/blob/master/src/main/network-monitor.js"
click node_platform "https://github.com/antropos17/aegis/blob/master/src/main/platform/index.js"
click node_sidecars "https://github.com/antropos17/aegis/blob/master/sidecar/etw-lifecycle/Program.cs"
click node_normalize "https://github.com/antropos17/aegis/blob/master/src/main/audit-normalize.js"
click node_health "https://github.com/antropos17/aegis/blob/master/src/main/sensor-health.js"
click node_rules "https://github.com/antropos17/aegis/blob/master/src/main/rule-loader.js"
click node_anomaly "https://github.com/antropos17/aegis/blob/master/src/main/anomaly-detector.js"
click node_auditlog "https://github.com/antropos17/aegis/blob/master/src/main/audit-logger.js"
click node_hashchain "https://github.com/antropos17/aegis/blob/master/src/main/audit-hashchain.js"
click node_index "https://github.com/antropos17/aegis/blob/master/src/main/audit-index.js"
click node_exports "https://github.com/antropos17/aegis/blob/master/src/main/exports.js"
click node_updates "https://github.com/antropos17/aegis/blob/master/src/main/update-verification.js"
click node_bench "https://github.com/antropos17/aegis/blob/master/bench/replay.js"

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_preload,node_ipc,node_renderer toneBlue
class node_scan,node_agents,node_filewatch,node_network toneAmber
class node_normalize,node_health,node_rules,node_anomaly toneMint
class node_auditlog,node_hashchain,node_index,node_exports toneRose
class node_platform,node_sidecars,node_ai,node_updates,node_bench toneIndigo
```

## Components

### Electron Runtime

- [Main process](https://github.com/antropos17/aegis/blob/master/src/main/main.js): Electron entry · Starts and coordinates local monitoring. · `src/main/main.js`
- [Preload bridge](https://github.com/antropos17/aegis/blob/master/src/main/preload.js): Electron IPC bridge · `src/main/preload.js`
- [IPC handlers](https://github.com/antropos17/aegis/blob/master/src/main/ipc-handlers.js): main IPC API · `src/main/ipc-handlers.js`
- [Svelte renderer](https://github.com/antropos17/aegis/blob/master/src/renderer/App.svelte): desktop UI · Displays live events, risk, health, and manual actions. · `src/renderer/App.svelte`

### Observation

- [Scan & identity](https://github.com/antropos17/aegis/blob/master/src/main/scan-loop.js): process discovery · Enumerates agents and assigns lifetime-aware identities under uncertain attribution. · `src/main/scan-loop.js`
- [Agent signatures](https://github.com/antropos17/aegis/blob/master/src/shared/agent-database.json): signature database · `src/shared/agent-database.json`
- [File watcher](https://github.com/antropos17/aegis/blob/master/src/main/file-watcher.js): file sensor · Watches registered roots through a worker-thread boundary. · `src/main/file-watcher.js`
- [Network monitor](https://github.com/antropos17/aegis/blob/master/src/main/network-monitor.js): TCP sensor · Maps TCP endpoints to detected PIDs. · `src/main/network-monitor.js`

### Evidence & Detection

- [Normalize & attribute](https://github.com/antropos17/aegis/blob/master/src/main/audit-normalize.js): evidence pipeline · Converts raw observations into shared events with attribution confidence. · `src/main/audit-normalize.js`
- [Sensor health](https://github.com/antropos17/aegis/blob/master/src/main/sensor-health.js): coverage monitoring · Records data gaps and degraded collection. · `src/main/sensor-health.js`
- [Rules & sequences](https://github.com/antropos17/aegis/blob/master/src/main/rule-loader.js): hot-loaded detection rules · Sensitive-path and sequence rules remain data-driven. · `src/main/rule-loader.js`
- [Anomaly detector](https://github.com/antropos17/aegis/blob/master/src/main/anomaly-detector.js): risk scoring · Compares events to rolling session baselines. · `src/main/anomaly-detector.js`

### Audit & Export

- [Bounded audit log](https://github.com/antropos17/aegis/blob/master/src/main/audit-logger.js): durable event log · Writes rotating, retained audit records. · `src/main/audit-logger.js`
- [Hash-chained trail](https://github.com/antropos17/aegis/blob/master/src/main/audit-hashchain.js): integrity trail · Detects modification relative to trusted state, not capture completeness. · `src/main/audit-hashchain.js`
- [Audit index](https://github.com/antropos17/aegis/blob/master/src/main/audit-index.js): query index · Supports audit queries and rebuilds. · `src/main/audit-index.js`
- [Export service](https://github.com/antropos17/aegis/blob/master/src/main/exports.js): streaming export · Produces JSON, CSV, HTML, and ZIP exports. · `src/main/exports.js`

### Platform & External

- [Platform adapters](https://github.com/antropos17/aegis/blob/master/src/main/platform/index.js): OS abstraction · Isolates Windows, Linux, macOS, and OS-specific collection. · `src/main/platform/index.js`
- [Windows sidecars](https://github.com/antropos17/aegis/blob/master/sidecar/etw-lifecycle/Program.cs): C# sidecar processes · ETW and process-snapshot experiments run across a protocol boundary. · `sidecar/etw-lifecycle/Program.cs`
- **Optional AI analysis**: Anthropic service · Only external analysis path; data is local by default.
- [Signed updates](https://github.com/antropos17/aegis/blob/master/src/main/update-verification.js): GitHub update path · `src/main/update-verification.js`
- [Benchmark replay](https://github.com/antropos17/aegis/blob/master/bench/replay.js): sensor evaluation · Compares replayed observations with Sysmon oracle evidence. · `bench/replay.js`

## Connections

- Main process → Scan & identity: starts
- Main process → File watcher: starts
- Main process → Network monitor: starts
- Main process → IPC handlers: registers
- Agent signatures → Scan & identity: identifies agents
- Platform adapters → Scan & identity: process context
- Platform adapters → File watcher: OS collection
- Platform adapters → Network monitor: endpoint data
- Windows sidecars → Platform adapters: protocol boundary
- Scan & identity → Normalize & attribute: process evidence
- File watcher → Normalize & attribute: file evidence
- Network monitor → Normalize & attribute: network evidence
- Normalize & attribute → Sensor health: coverage signals
- Normalize & attribute → Rules & sequences: normalized events
- Rules & sequences → Anomaly detector: rule matches
- Normalize & attribute → Anomaly detector: event stream
- Sensor health → Bounded audit log: loss records
- Anomaly detector → Bounded audit log: risk events
- Normalize & attribute → Bounded audit log: audit events
- Bounded audit log → Hash-chained trail: chains records
- Bounded audit log → Audit index: indexes
- Audit index → Export service: query data
- Preload bridge → IPC handlers: constrained IPC
- Svelte renderer → Preload bridge: UI requests
- IPC handlers → Svelte renderer: live state
- IPC handlers → Export service: export requests
- IPC handlers → Optional AI analysis: optional analysis
- Main process → Signed updates: verified update checks
- Benchmark replay → Platform adapters: evaluates sensors