aegis-pentest

aegis · v0.11.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 <hey@majdb.com>"
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.

---

Attack chain detection

Findings carry structured tags. The chain detector matches on tag sets, not title substrings. 22 chains ship out of the box — 7 legacy web chains, 10 modern web/API chains, and 5 Active Directory chains:

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: 24 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.

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.

---

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

---

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