aegis-pentest 0.1.1

AEGIS — Adaptive Engagement & Generic Inspection Scanner

aegis

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.

---

Installation

Via pipx (recommended):

pipx install aegis-pentest
aegis init

Via AUR (Arch Linux):

yay -S aegis-pentest
aegis init

Requirements:

• Python 3.12+
• ANTHROPIC_API_KEY in environment
• Pentest toolchain (see aegis env tools after init)

---

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 <[e-mail]>"
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
           Registry      Base          DB
           (35+ tools)   (NVD/GHSA)    (SQLite)
               |                            |
         Tool Executor                  Reporter
         (async, sandboxed)             (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:

Tactic	Impact
Tiered model routing (Haiku handles ~70% of calls)	-60% cost
Prompt caching on system prompt + engagement context	-40% on input tokens
Parsed tool output, never raw stdout to the LLM	-80% on tool-heavy phases
Structured tool-use schema, no prose planning	-30% output tokens
Methodology-driven action space pruning	-50% wasted calls
SQLite-cached recon reused across phases	variable
Finding deduplication before LLM sees results	-10-30%

Model tiers:

Tier	Model	Used for
NANO	claude-haiku-4-5	Parsing, classification, summarization
MAIN	claude-sonnet-4-6	Planning, hypothesis generation, verification probes
DEEP	claude-opus-4-7	Attack chain analysis, hard reasoning
LOCAL	ollama (optional)	Offline pre-classification

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 35+ 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.

Category	Tools
Subdomain enumeration	subfinder, amass, assetfinder, dnsx
Live host detection	httpx, httprobe
Port scanning	nmap, naabu, rustscan
Web crawling	katana, gospider, hakrawler
Content discovery	ffuf, feroxbuster, gobuster, dirsearch
Tech fingerprinting	whatweb, wappalyzer-cli, httpx -tech-detect
Vulnerability scanning	nuclei, nikto, wpscan, droopescan, joomscan
TLS auditing	testssl.sh, sslscan, sslyze
Parameter discovery	arjun, paramspider, x8
Secrets	trufflehog, gitleaks
Visual recon	gowitness, aquatone
SQLi verification	sqlmap (safe flags only: --batch --crawl=0 --level=1 --risk=1)

---

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

Layer	Choice
Language	Python 3.12+
CLI	Typer + Rich
Async	asyncio + anyio
HTTP	httpx (async, HTTP/2)
Models	Pydantic v2
Storage	SQLite + SQLModel
LLM	Anthropic SDK (Claude)
Templating	Jinja2
Logging	structlog + rich
Packaging	uv (dev), hatch (build)
Testing	pytest + pytest-asyncio + respx

---

License

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

---

Built by Majd Bnat