aegis · v0.12.0

Adaptive Engagement & Generic Inspection Scanner

An autonomous, AI-orchestrated web penetration testing agent. Aegis handles reconnaissance, fingerprinting, vulnerability discovery, verification, and reporting 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.
• Destructive tools (sqlmap, wpscan, commix, kerbrute, crackmapexec, …) refuse to run without operator approval unless scope.yaml explicitly enables them.
• There is no --force flag that bypasses scope.

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 every tool 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.

Option B — PyPI

pip install aegis-pentest
# or
pipx install aegis-pentest

Option C — Arch (AUR)

yay -S aegis-pentest
# or
paru -S aegis-pentest

Optdepends cover the full tool surface; install only what you need.

Option D — Native install script (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 E — From source

git clone https://github.com/glorybnat/aegis-pentest.git
cd aegis-pentest
pip install -e .
cd tui && npm install && npm run build

After installing AEGIS, detect what's already on the host and fill in the rest:

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–E)

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, CISA KEV, FIRST EPSS)
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

# Optional: seed endpoints from an existing API spec or proxy trace
aegis ingest openapi engagements/2026-05-acme/spec.yaml --engagement engagements/2026-05-acme
aegis ingest postman engagements/2026-05-acme/collection.json --engagement engagements/2026-05-acme
aegis ingest har     engagements/2026-05-acme/burp.har       --engagement engagements/2026-05-acme

# Run
aegis run engagements/2026-05-acme

# Resume from the last completed phase after a crash or Ctrl+C
aegis run engagements/2026-05-acme   # picks up state.json automatically

# Generate report — md/html/json/sarif/h1/bugcrowd, or "all"
aegis report engagements/2026-05-acme --format html
aegis report engagements/2026-05-acme --format sarif    # GitHub/GitLab code scanning
aegis report engagements/2026-05-acme --format h1       # HackerOne JSON, one per finding
aegis report engagements/2026-05-acme --format bugcrowd # Bugcrowd VRT bundle

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
  confirm_before:                  # per-engagement gate for destructive tools
    - sqlmap
    - hydra
    - commix

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
     (173 tools) (NVD/GHSA  (SQLite) (aiosqlite) (14 types)
                +KEV/EPSS)
         |                              |
   Tool Executor               Hallucination Guard
  (async, sandboxed,          (output verification)
   destructive-gated)
         |
      Reporter
    (md/html/json/sarif/h1/bugcrowd)

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.

State is persisted to <engagement_dir>/state.json after every phase advance via atomic tmp + os.replace. Re-running aegis run against the same directory resumes at the last saved phase.

Reasoning engine

v0.12 repositions AEGIS from "tool dispatcher" to "brilliant bug-hunting partner". The agent reads observations, opens a structured theory, dispatches probes to test it, and writes a self-critique before advancing. The OOHA loop is the spine:

Four reasoning verbs land in PLAN_TOOLS and bypass the per-phase enum filter (the agent reasons at every phase, not just VULN_ANALYSIS):

The Hypothesis lifecycle is PROPOSED → TESTING → CONFIRMED | REFUTED | DEAD_END. Open hypotheses are injected back into the observation summary every turn so the agent sees its own working theory across turns.

Parallel dispatch. Non-control tool calls in a single turn now run concurrently via asyncio.gather, capped by a per-runner semaphore (defaults to executor.max_parallel_tools, falls back to 4). Control verbs — advance_phase, change_phase, abort — stay serial so the orchestrator can short-circuit. One crashing dispatch never kills the rest of the batch.

Structured failure signals. _recent_calls was dict[(tool, target), int] carrying "failed N times". It's now dict[(tool, target), FailureSignal] with an 8-kind classifier (TIMEOUT, RATE_LIMITED, PERMISSION_DENIED, AUTH_REQUIRED, OUT_OF_SCOPE, BINARY_MISSING, ZERO_RESULTS, EXCEPTION) and an attacker-flavoured pivot hint per kind:

• rate_limited → use aegis_verify in-process; it's not rate-limited
• auth_required → ingest the captured Burp/ZAP HAR with cookies via aegis ingest har --replay
• binary_missing → aegis env install --missing, or aegis_tool_list_help <category> for equivalents

The STUCK SIGNALS block in the observation summary renders kind + count + pivot, most-recent-first, capped at 5.

Attack chain detection

Findings carry structured tags. The chain detector matches on tag sets, not title substrings. 25 chains ship out of the box — 7 legacy web chains, 10 modern web/API chains, 5 Active Directory chains, and 3 v0.12 high-ROI gaps (host header, web cache deception, parameter pollution):

For engagements predating the tag rollout, a substring fallback still fires the legacy 7 rules against finding titles.

Guided hunting

Chains are post-hoc detection — they fire when findings are already in the DB. Playbooks are the proactive counterpart: 28 entries in src/aegis/analysis/vuln_playbooks.py say "when you suspect X, run these probes; when you confirm X, hunt Y next".

Initial set (one playbook per chain tag):

sqli, nosqli, cmdi, ssti, xxe, xss_stored, xss_reflected, ssrf, lfi, cloud_metadata_v1, bucket_open, request_smuggling, cache_poisoning, prototype_pollution, jwt_alg_confusion, jwt_weak_secret, csrf, idor, race_condition, mass_assignment, git_exposure, cors_wildcard, ad_kerberoast, ad_no_preauth, ad_dcsync, host_header_injection, web_cache_deception, http_parameter_pollution.

After every phase tick, EngagementRunner._suggested_next builds an escalation state from confirmed findings (tags + endpoints + tech stack) and runs adaptive.escalate. The top three actions are injected into the next observation summary as a Suggested next probes block; the model can act on them or ignore. Either way the recommendation is logged to audit_event with event_type='escalation_suggested' so aegis stats can answer "how often did the model take the suggestion?".

Tag inference (src/aegis/analysis/tag_inference.py) runs at the persistence boundary inside FindingsDB.add_finding. Findings get tags from a tool-base map (e.g. impacket_get_userspns → [ad_kerberoast, ad_spn]) plus a 31-rule substring matcher over the title + evidence text (distinguishing jwt_alg_confusion from jwt_weak_secret, xss_stored from xss_reflected, IMDSv1 in payloads tagging cloud_metadata_v1). Explicit tags from the caller are preserved.

Lateral pivots (v0.12). src/aegis/reasoning/lateral.py encodes the post-confirmation question every brilliant bug hunter asks: "given primitive X, what NEW classes does it unlock?" 10 hand-curated rows cover the highest-leverage chains — SSRF → IMDS → IAM → S3 → credential pivot; SQLi → file read via INTO OUTFILE → log poisoning → RCE; .git exposure → source review → JWT secret extraction → forge any token. Every confirmed primitive auto-proposes one hypothesis per unlocked class (proposed_by="lateral:<source_tag>") so the agent sees concrete next probes already framed as "given X, hunt Y because…".

Partial-chain primers (v0.12). Most chains need 2–3 required tag groups. When one group matches but at least one is missing, chains.partial_matches() returns the near-miss; the orchestrator surfaces them in the obs summary as PARTIAL CHAINS (one probe away) with what we have and what's missing — the agent sees concrete one-probe-away opportunities without an LLM planning call.

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 exposes 173 MCP tools wrapping 105 external binaries plus orchestration primitives. 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.

* marks tools that require operator approval before each run (destructive-gated).

Tool playbooks

165 per-tool markdown playbooks ship inside the wheel under aegis/_docs/tools/. The agent fetches them on demand instead of carrying full flag references in the system prompt every turn.

Every doc follows a fixed schema so the model can rely on the section ordering:

# tool_name
**Purpose:** one-sentence summary.

## Args
- arg (type): meaning

## Common flags worth knowing
- -X  short note

## Pitfalls
- short bullet

## When to use
- which phase, what precondition triggers it

## Example
`tool_name(target="…", flags="…")`

The 11 hot-path tools have hand-curated playbooks; the rest are scaffolded by scripts/gen_tool_docs.py from the existing docstring + ToolSpec.install hint. Override or hand-edit anything under docs/tools/<category>/<name>.md — the on-disk source layout wins over the packaged copy during editable installs.

Verification probes

43 in-process probes (aegis.verify.probes) confirm findings without re-invoking external binaries. Each probe targets a specific class and emits a structured ProbeResult. Probes are HTTP-only by default and rate-limited per scope.

blind_cmdi, blind_cmdi_oob, blind_sqli, cache, cache_poisoning,
cmdi_oob, cors, cors_misconfig, csrf, csrf_missing, exposure,
file_exposure, headers, http_smuggling, jwt, jwt_alg_confusion,
lfi, misconfig, oauth, oauth_redirect, open_redirect, pp,
prototype_pollution, race, race_condition, redirect,
request_smuggling, smuggling, sqli, sqli_error, ssrf, ssrf_oob,
ssti, subdomain_takeover, takeover, template_injection,
timing_cmdi, timing_sqli, toctou, xml_injection, xss,
xss_reflected, xxe

Probes adopted three reliability upgrades in v0.12:

• aegis.verify.baseline — differential request/response diffs (status, body hash, content-length above a 200-byte threshold, redirect Location). Kills the catch-all-200 false positive where a server returns identical HTML for every URL.
• aegis.verify.oob_waiter.confirm_oob — polls the OOB session until a callback matches the nonce (substring or regex) or the deadline hits. v0.11 sent the payload and returned immediately; this is the real confirmation seam for blind SSRF / CMDi / XXE.
• aegis.verify.mutations — per-probe-type WAF-evasion retries when a payload hits 403/406/419. sqli (double-URL-encode, backtick swap, /**/ comment inject), xss (fullwidth unicode, mixed case), lfi (null-byte + .png/.jpg suffix), plus ssrf, ssti, cmdi, header_injection.

Reports and webhooks

Six output formats, all driven from the same Reporter context:

PII redaction is opt-in via [reporting] redact_pii = true. Sweeps emails, JWTs, AWS keys, GitHub PATs, Slack tokens, US SSNs, credit-card-shaped numbers, and phone numbers. IP redaction is a separate switch. Audit log records counts only — never content. Scope metadata (engagement_id, client) is intentionally preserved.

Live findings webhook via aegis watch:

aegis watch engagements/2026-acme \
    --webhook https://hooks.slack.com/services/... \
    --webhook-format slack \
    --webhook-min-severity high

Supported platforms: slack (Block Kit), discord (severity-coloured embeds), linear (issue title/description/priority), json (stable schema for n8n / Zapier).

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|kev|epss]   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 ingest openapi <spec>  --engagement <dir>     Seed endpoints from OpenAPI / Swagger
aegis ingest postman <coll>  --engagement <dir>     Seed endpoints from Postman v2.x
aegis ingest har     <trace> --engagement <dir> [--replay]   Seed endpoints from a browser HAR; --replay re-issues each request and diffs the response

aegis run <dir> [--phase PHASE]               Run engagement (resumes from state.json)
aegis run <dir> --dry-run                     Preview planned actions
aegis run <dir> --budget-usd 2.00             Cap spend

aegis watch <dir> --webhook <url>             Live findings webhook
                  --webhook-format slack|discord|linear|json
                  --webhook-min-severity critical|high|medium|low|info

aegis report <dir> [--format md|html|json|sarif|h1|bugcrowd|all]   Generate report
aegis findings list <dir> [--severity high]   List findings
aegis findings suppress <finding-id> --reason "..."

aegis cost <dir>                              Detailed cost breakdown
aegis audit <dir>                             Full audit log
aegis stats [<root>] [--json]                 Cross-engagement metrics
aegis shells                                  Tool execution history (last scan)
aegis shells --all [--tool X] [--engagement Y]   Cross-engagement shell history (SQLite)

aegis docker build|run|shell|pull|status      Docker sub-app

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
redact_pii        = false
redact_ips        = false

Tech stack

License

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

Built by Majd Bnat