Aegis is an autonomous AI security engineer designed to observe software systems, reason about abnormal behavior, identify likely vulnerabilities, propose verified mitigations, and assist humans during secure incident response and software hardening.
Aegis is composed of three architectural layers:
- Aegis Core: the shared reasoning and orchestration engine
- Aegis Forge: the pre-production offensive validation environment
- Aegis Shield: the runtime defensive and incident-response environment
The design intentionally keeps a single reasoning core while exposing different product surfaces for defense and validation.
The canonical operator path is the Aegis Demonstration Runbook. It covers setup, host and Linux VM monitoring, safe telemetry generation, triage/case inspection, shutdown, persistence, recovery, and command reference. Do not use an older operational guide instead.
Architecture and handoff references retained alongside the runbook:
- System Architecture Overview
- Threat Model and Safety Policy
- Data and Event Model
- Research and Learning Roadmap
- Aegis Monitoring Core Specification
- Investigation Agent Handoff
- Investigation Case Schema
- Event Schema
- Agentic Defense Architecture
Aegis is built around five non-negotiable rules:
- Observe before acting
- Reason before responding
- Verify before deployment
- Explain every decision
- Keep humans as the final authority for production changes
Per project architecture (OSInstruction.txt), Aegis is designed as a cross-platform platform from Day 1 across Linux, Windows, and macOS:
- Dynamic host environment and privilege discovery
- Platform-aware telemetry adapters behind clear abstraction boundaries
- Canonical Universal Event Model (
aegis_core.Event) and tamper-evident SQLite storage - Non-signature behavioral anomaly detection
- Reconstructing attack progression via temporal and graph correlation
Active Implementation & Production Foundation:
- Aegis Core (
aegis_core/): 13 implemented modules including the unifiedMonitoringEngine,ProcessLifecycleCollector,FileEventCollector(withwatchdogand polling fallback),AuthEventCollector(supportingjournalctl/auth.logon Linux andwevtutilon Windows), andNetworkBridgeCollector. - Network Telemetry Subsystem (
network_monitor/): Platform adapters for Linux (polling + eBPF connection tracing), Windows (psutil connection polling, DNS, process attribution), and macOS (capability boundaries and stubs). - Evidence & Detection: Tamper-evident SQLite
EvidenceStorewith cryptographic hash chain, four explainable detectors (AuthFailureBurstDetector,FileChangeBurstDetector,NetworkRateDetector,NewProcessWithNetworkDetector), in-memoryCorrelationIndex, andTimelinereconstruction. - Automated Test Suite: deterministic tests across
tests/andnetwork_monitor/tests/; runpython -m pytest -qfor the current count. - E2E Validation: End-to-end real host validation is available through
validate_e2e.pyand the isolated procedure in the Aegis Demonstration Runbook. - Optional LLM interpretation: A bounded, evidence-grounded explanation layer can enrich a completed investigation without changing deterministic classification or gaining host/tool access. See LLM setup.
Use Python 3.11 or newer. The base installation includes the process and file collector dependencies required for the supported monitoring path; install the test extra when running the test suite.
python -m pip install -e ".[test]"# Display host capability report
python -m aegis_core --capability-report
# Run a safe observation cycle in development mode
python -m aegis_core --environment development --data-dir .\aegis-data --interval-seconds 1 --run-seconds 10
# Analyze existing evidence store
python -m aegis_core --data-dir .\aegis-data --analyze
# Run automated test suite
python -m pytest -q