Skip to content
SemesterProjectsPublic

About

An explainable, AI-assisted cybersecurity framework for behavioural threat detection, evidence-driven investigation, and human-controlled incident response.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

31 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Aegis

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.

Product concept

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.

Documentation set

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:

Product principles

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

Architectural and Platform Focus

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

Current status

Active Implementation & Production Foundation:

  • Aegis Core (aegis_core/): 13 implemented modules including the unified MonitoringEngine, ProcessLifecycleCollector, FileEventCollector (with watchdog and polling fallback), AuthEventCollector (supporting journalctl/auth.log on Linux and wevtutil on Windows), and NetworkBridgeCollector.
  • 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 EvidenceStore with cryptographic hash chain, four explainable detectors (AuthFailureBurstDetector, FileChangeBurstDetector, NetworkRateDetector, NewProcessWithNetworkDetector), in-memory CorrelationIndex, and Timeline reconstruction.
  • Automated Test Suite: deterministic tests across tests/ and network_monitor/tests/; run python -m pytest -q for the current count.
  • E2E Validation: End-to-end real host validation is available through validate_e2e.py and 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.

Installation

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]"

Quick Start / CLI Usage

# 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

About

An explainable, AI-assisted cybersecurity framework for behavioural threat detection, evidence-driven investigation, and human-controlled incident response.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages