antropos17/aegis

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.