Aegis

# Aegis — Local Monitoring for AI Agents

> Aegis is an open-source, monitor-first desktop app for local AI-agent processes, file activity, TCP endpoints and behavioral anomalies.

## Purpose and scope

AI agents can access local files, credentials, shell commands and external services. AEGIS observes supported activity from outside the agent and records attribution evidence. It is one of several approaches to agent observability; in-agent instrumentation and OS-level tools have different coverage.

Monitoring runs locally without telemetry or an account. Optional AI analysis sends activity metadata to Anthropic using the user's API key; update checks contact GitHub. AEGIS has manual process controls but no automatic OS-level enforcement.

This document describes current source. Installed releases can lag behind it; consult the release tag and README limitations.

## Installation

```bash
git clone https://github.com/antropos17/Aegis.git
cd Aegis
npm ci
npm start
```

Building from source requires Node.js 24.x, as declared in package.json and pinned in .nvmrc and CI. The packaged app ships its own runtime. Windows 10/11 is the primary platform; macOS/Linux remain experimental. For a browser demo, follow the built-preview instructions in the README.

## Features

### Process Monitoring
Tracks 112 known AI agents (265 process-name signatures across their `names` arrays) with parent-child tree resolution and IDE host detection. Covers coding assistants (Claude Code, Copilot, Cursor), autonomous agents (OpenClaw, AutoGPT, CrewAI, Devin), desktop AI (Gemini, Apple Intelligence), frameworks (LangChain, AutoGen, MetaGPT), and local LLMs (Ollama, LM Studio, llama.cpp).

### File System Access
Watches sensitive directories (.ssh, .aws, .gnupg, .env, cloud configs) and the 35 AI agent config paths registered in AGENT_CONFIG_PATHS for file activity. Database configPaths metadata does not register watch roots automatically.

### Network Activity
Logs eligible observed TCP endpoints per detected agent PID with forward-confirmed reverse DNS and allowlisted, unknown or flagged verdicts. Provider outages and polling gaps limit coverage; an unresolved endpoint is not assumed safe.

### Behavioral Analysis
Applies 73 detection rules across 8 categories (AI config, secrets, SSH, cloud, browser, devtools, crypto, certificates) with rolling 10-session baselines and 4-axis anomaly scoring (Network/FS/Process/Baseline).

### Trust Scoring
Assigns real-time risk scores with trust grades (A+ through F) using time-decay algorithms and multi-dimensional threat assessment.

### Dashboard
Radar overview, summary cards, filtered/grouped activity feeds, network panel, expandable agent/application cards and footer sensor health. Monitoring presets: Paranoid, Strict, Balanced, Developer. Presets do not enforce OS-level blocking.

### Export and Audit
JSON, CSV, HTML reports, one-click ZIP archive and hash-chained JSONL audit logging with daily rotation and 30-day retention. Settings JSON and diagnostic ZIP exports omit the configured API key. Paths, endpoints and agent metadata in exports remain sensitive.

### YAML Rulesets
73 sensitive-path detection rules, validated against rules/_schema.json. Existing ruleset edits hot-reload in unpacked runs; packaged ASAR watchers are disabled. Extend by adding a .yaml to rules/ and reloading or restarting; sensitive-rule IDs must be unique and duplicates are skipped. Sequence correlations live separately in rules/sequences/: keep their IDs unique across files because the sequence loader currently does not reject cross-file duplicates.

## Documentation

- [README](https://github.com/antropos17/Aegis/blob/master/README.md)
- [Security Policy](https://github.com/antropos17/Aegis/blob/master/SECURITY.md)
- [Contributing Guide](https://github.com/antropos17/Aegis/blob/master/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/antropos17/Aegis/blob/master/CODE_OF_CONDUCT.md)

## Technical Details

- **Stack**: Electron, Svelte 5, Vite; CommonJS JavaScript in main, TypeScript in the renderer and shared types. Exact versions: package.json
- **Tests**: Vitest; run `npm test` for current pass/skip and file counts
- **License**: MIT
- **Version**: 0.17.0-alpha <!-- x-release-please-version -->
- **Platform**: Windows primary; macOS/Linux experimental

## Links

- Repository: https://github.com/antropos17/Aegis
- Local demo instructions: https://github.com/antropos17/Aegis#try-without-ai-agents
- Privacy and external requests: https://github.com/antropos17/Aegis/blob/master/SECURITY.md#privacy-architecture