aegis · v0.9.0

Adaptive Engagement & Generic Inspection Scanner

An autonomous, AI-orchestrated web penetration testing agent. Aegis handles reconnaissance, fingerprinting, vulnerability discovery, and verification so the human pentester focuses on what actually requires human judgment.

What it is

Aegis runs structured, methodology-driven engagements against web targets. It profiles the host environment, fingerprints the target stack, selects relevant tools and tests from the PTES + OWASP WSTG v4.2 playbook, executes them concurrently, and produces a verified findings report with remediation guidance.

It is not a Burp Suite replacement. It is the autonomous recon and vuln-discovery layer that feeds the human pentester, eliminating roughly 70% of routine busywork.

Hard constraints built into the runtime:

• Every engagement requires a signed scope.yaml before any network egress.
• Every outbound request is matched against in-scope and out-of-scope rules before the socket opens.
• Scope violations abort the current task and are written to the audit log.
• There is no --force flag that bypasses scope.

What's new in v0.9.0

What's new in v0.8.0

What's new in v0.7.0

Installation

Option A — Docker (recommended, all tools pre-installed)

# Pull pre-built image (~4 GB) or build locally (~15-30 min)
aegis docker pull                          # from GitHub Container Registry
# OR
aegis docker build                         # build locally from Dockerfile

# Run an engagement
export ANTHROPIC_API_KEY=sk-ant-...
aegis docker run engagements/2026-acme

# Interactive shell with all 80+ tools on PATH
aegis docker shell

# Check image status and tool inventory
aegis docker status

The Docker image is based on Kali rolling and includes every tool in the catalog — nmap, nuclei, httpx, ffuf, gobuster, dalfox, sqlmap, masscan, hydra, wfuzz, theharvester, bbot, semgrep, trivy, and 65+ more.

Option B — Native install (one-liner)

# Auto-detects Arch, Kali, Ubuntu/Debian, Fedora, macOS
curl -fsSL https://raw.githubusercontent.com/glorybnat/aegis-pentest/main/scripts/install.sh | bash

# Or from the repo
bash scripts/install.sh

# Build Docker image instead
bash scripts/install.sh --docker

Option C — Manual

# Install AEGIS
pipx install aegis-pentest

# Install missing pentest tools
aegis init                          # detect what's installed
aegis env tools --missing           # show what's missing + install commands
aegis env install --missing         # install everything (no-sudo tools)
aegis env install --missing --dry-run   # preview first

Requirements:

• Python 3.12+
• ANTHROPIC_API_KEY in environment
• Docker (Option A) or pentest toolchain (Option B/C)

Quickstart

# Docker quickstart (zero host setup)
export ANTHROPIC_API_KEY=sk-ant-...
aegis docker build                          # or: aegis docker pull
aegis docker run engagements/2026-acme

# Native quickstart
# First run: profiles host, lists missing tools
aegis init

# Sync the knowledge base (NVD, GHSA, nuclei-templates)
aegis kb sync

# Create a new engagement
aegis engagement new --client "Acme Corp" --domain "acme.com"

# Fill in the authorization details
vim engagements/2026-05-acme/scope.yaml

# Run
aegis run engagements/2026-05-acme

# Generate report
aegis report engagements/2026-05-acme --format html

scope.yaml

Aegis refuses to run without this file. No exceptions.

engagement_id: "BL-2026-007"
client: "Acme Corp"
operator: "Majd Bnat <[email protected]>"
authorization:
  document_ref: "SOW-2026-007.pdf"
  signed_date: "2026-05-12"
  expiry: "2026-06-12"
in_scope:
  domains:
    - "*.acme.com"
    - "api-staging.acme.io"
  ips:
    - "203.0.113.0/24"
out_of_scope:
  - "admin.acme.com"
  - "*.internal.acme.com"
rules_of_engagement:
  rate_limit_rps: 10
  business_hours_only: false
  destructive_tests: false
  no_credential_stuffing: true
  no_dos_tests: true

Architecture

                          aegis CLI
                              |
                      Engagement Manager
           (scope validation, lifecycle, audit log)
                              |
            +-----------------+-----------------+
            |                 |                 |
        Environment         Target          Methodology
         Profiler          Profiler           Engine
       (host info)      (fingerprint)      (PTES phases)
            |                 |                 |
            +--------+--------+--------+--------+
                              |
                       LLM Orchestrator
                   (Haiku / Sonnet / Opus)
                              |
         +----------+---------+----------+----------+
         |          |         |          |          |
        Tool    Knowledge  Findings    PTT       PoC
      Registry    Base       DB      Graph    Generator
     (153 tools) (NVD/GHSA) (SQLite) (aiosqlite) (14 types)
         |                              |
   Tool Executor               Hallucination Guard
  (async, sandboxed)          (output verification)
         |
      Reporter
    (md/html/json)

The orchestrator runs a bounded loop per phase:

plan(phase_context) -> execute(action) -> observe(result) -> update(state)
  ^                                                               |
  +---------------------------------------------------------------+
                   until phase complete OR budget exceeded

Three independent budgets bound each phase: token budget, wall-clock time, and action count. Whichever trips first ends the phase and triggers finalize mode.

Token model

Aegis is designed to complete a full medium-scope engagement for under $2 in LLM tokens. This is achieved through several layered tactics:

Model tiers:

The live cost meter runs in the terminal throughout each phase:

Phase: VULN_ANALYSIS  [>>>>>>>>--] 80%
Budget: $0.74 / $5.00   Tokens: 41.2k / 200k   Time: 12m / 60m
Tier breakdown: NANO 24% . MAIN 71% . DEEP 5%   Cache hit: 82%

Tool catalog

Aegis wraps 153 tools exposed as native MCP tools. Raw output is never passed to the LLM — each tool has a typed parser that produces structured Finding or Observation models. A nmap scan returning 47 open ports becomes 47 OpenPort observations of ~80 bytes each, not 200 KB of XML.

All tools degrade gracefully: if a binary is not installed, the tool returns a structured error with the exact install command.

Environment profiling

On first run, aegis init profiles the host and derives auto-tuned concurrency settings:

Host: arch-workstation
  OS        Arch Linux (rolling, kernel 6.9.3-arch1-1)
  CPU       AMD Ryzen 7 5800X . 8 cores / 16 threads . 4.7 GHz
  Memory    32 GB total . 24 GB available
  Repos     core, extra, multilib, blackarch

Pentest toolchain: 28/35 detected
  nmap 7.95       nuclei 3.2.9      httpx 1.6.6
  ffuf 2.1.0      subfinder 2.6.6   katana 1.1.0
  sqlmap 1.8.5    wpscan 3.8.27     nikto 2.5.0
  gobuster 3.6.0  amass 4.2.0       gowitness 3.0.3

Missing: testssl.sh  feroxbuster  dnsrecon  arjun  paramspider  trufflehog
  -> Run: aegis env install --missing

Auto-tuned concurrency:
  nmap_parallelism=16   nuclei_concurrency=32   ffuf_threads=64
  httpx_concurrency=80  max_parallel_tools=4

CLI reference

aegis init                                    First-run setup and env profile
aegis env show                                Display host profile
aegis env tools                               Tool inventory
aegis env install --missing                   Generate install commands for missing tools
aegis env refresh                             Re-detect host profile

aegis kb sync [--source nvd|ghsa|nuclei]      Sync knowledge base
aegis kb stats                                Knowledge base summary
aegis kb query --product nginx --min-cvss 7   Query CVEs

aegis engagement new --client X --domain Y   Scaffold engagement dir and scope.yaml
aegis engagement list                         List engagements

aegis run <dir> [--phase PHASE]              Run engagement
aegis run <dir> --dry-run                    Preview planned actions
aegis run <dir> --budget-usd 2.00           Cap spend

aegis report <dir> [--format md|html|json]   Generate report
aegis findings list <dir> [--severity high]  List findings
aegis findings verify <finding-id>           Re-run verification probe
aegis findings suppress <finding-id> --reason "..."

aegis cost <dir>                             Detailed cost breakdown
aegis audit <dir>                            Full audit log

All commands support --json for scripting, -v/-vv/-vvv for verbosity, --quiet for CI.

Configuration

Global config lives at ~/.config/aegis/config.toml. Any key can be overridden per engagement in engagement_dir/config.toml.

[api]
anthropic_api_key_env = "ANTHROPIC_API_KEY"

[models]
nano  = "claude-haiku-4-5-20251001"
main  = "claude-sonnet-4-6"
deep  = "claude-opus-4-7"

[models.local]
enabled  = false
endpoint = "http://localhost:11434"
model    = "qwen2.5:7b"

[budgets]
tokens_per_phase       = 30000
tokens_per_engagement  = 200000
usd_per_engagement     = 5.00
wall_time_per_phase_sec = 1800

[caching]
prompt_cache          = true
kb_cache_dir          = "~/.cache/aegis/kb"
fingerprint_cache_ttl_hours = 168

[tooling]
docker_isolate         = false
default_rate_limit_rps = 10
respect_robots_txt     = false

[reporting]
default_format   = "html"
include_audit_log = true

Tech stack

License

MIT. Use responsibly and only against systems you are authorized to test.

Built by Majd Bnat