Project Astro V2 - Disclaimer - This is DEVKIT

Intelligence layer for LLM-driven penetration testing. Ships as an MCP server with 38 Kali tool wrappers, engagement tracking, scope enforcement, and structured output for any MCP-compatible client.

This is a devkit. Use only against targets you own or have explicit authorization to test.

What changed from V1

V1 was a Flask proxy that shuttled JSON between Claude Desktop and a kali_api_server.py process. It worked, but the architecture was fragile — two servers, no state, no safety rails, 10 tools hard-wired to HTTP endpoints.

V2 is a ground-up rewrite:

New tools (V2 additions)

Recon: amass, subfinder, ffuf, whatweb, dnsrecon, theharvester, nuclei

Exploitation: searchsploit, crackmapexec, hashcat, responder, smbclient, evil-winrm

Impacket suite: secretsdump, psexec, wmiexec, kerberoast, getnpusers, getst, ticketer

Post-exploitation: linpeas, winpeas, bloodhound, chisel, netcat, msfvenom

Tunneling/C2: burp (proxy integration), certipy (AD CS attacks)

Flex: custom_script (arbitrary bash/python with timeout + sandbox)

Removed

• kali_api_server.py — no longer needed; tools execute directly
• run.py — replaced by astro CLI
• requirements.txt — replaced by pyproject.toml
• setup.sh — replaced by pip install . or Docker

Quick start

Docker (recommended)

export API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose up --build

The server starts on http://localhost:8080 with streamable-HTTP transport. MCP clients must send the configured key in the X-API-Key header. All 38 Kali tools are pre-installed in the image.

Docker lab (with a target)

export API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose -f docker-compose.lab.yml up --build

Starts Astro + a Metasploitable2 target on an isolated 172.28.0.0/24 network with scope pre-configured. The published Astro port remains host-loopback-only.

Local install

python3 -m venv .venv && source .venv/bin/activate
pip install ".[dev,reporting]"
astro serve --port 8080

The default HTTP bind is loopback-only and may run without network authentication for local development. A non-loopback HTTP bind requires API_KEY or OIDC configuration and otherwise refuses to start. Requires the underlying Kali tools to be installed on the host.

See docs/HTTP_SECURITY.md for the HTTP startup and request-authentication policy.

Usage

MCP server (default)

astro serve --transport streamable-http --port 8080
API_KEY="replace-with-a-strong-key" astro serve --transport streamable-http --host 0.0.0.0 --port 8080
astro serve --transport stdio  # for Claude Desktop / Claude Code

Connect any MCP client to http://localhost:8080 or wire it up via stdio in your client config:

{
  "mcpServers": {
    "astro": {
      "command": "astro",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Ollama bridge (offline / local LLM)

astro ollama --model llama3 --scope config/lab_scope.yaml

Interactive chat session with tool-calling against a local Ollama instance.

Terminal UI

astro tui --target 10.10.10.10 --engagement "HTB-Box"

Rich terminal interface with live tool output, methodology tracking, and engagement management.

Scope enforcement

Create a YAML scope file to restrict what targets tools can hit:

scope:
  allowed_cidrs:
    - "10.10.10.0/24"
  allowed_domains:
    - "target.htb"
  excluded_targets: []

  tool_restrictions:
    hydra:
      enabled: true
      max_threads: 4
      service_whitelist: ["ssh", "http"]
    sqlmap:
      risk_level: 2

astro serve --scope config/scope.yaml

Every tool call validates its target against the scope before execution. Out-of-scope targets are rejected.

Tools (38)

Recon

Exploitation

Impacket suite

Post-exploitation

Other

Engagement tracking

create_engagement("HTB-Devvortex")  →  engagement ID
  └─ nmap_scan(...)                 →  finding recorded
  └─ nikto_scan(...)                →  finding recorded
  └─ sqlmap_scan(...)               →  finding recorded
get_engagement_summary()            →  all findings + metadata
export_to_obsidian("~/Vault/HTB")   →  interlinked markdown notes

Findings are persisted in SQLite. Export to SARIF for CI integration or HTML for client reports.

Project structure

src/astro/
├── __main__.py          CLI entry point (serve, ollama, tui, version)
├── core/
│   ├── executor.py      Shell command executor with timeout + sandboxing
│   ├── scope.py         CIDR/domain scope enforcer
│   ├── engagement.py    SQLite-backed engagement + finding manager
│   ├── rate_limiter.py  Per-tool async rate limiting
│   ├── auth.py          API key + OIDC authentication
│   ├── validators.py    Input validation (shell metachar blocking, flag filtering)
│   └── parallel.py      Concurrent tool execution
├── tools/
│   ├── base.py          BaseTool ABC (validate → build_command → execute → parse)
│   ├── registry.py      Tool registry with category filtering
│   ├── nmap.py          ... 38 tool wrappers, one per file
│   └── nuclei.py
├── parsers/             Structured output parsers (nmap XML, sqlmap, wpscan JSON)
├── intel/
│   ├── cve_correlator.py   NVD API CPE→CVE lookup
│   ├── attack_graph.py     NetworkX-based attack path modeling
│   └── methodology.py      Phase tracker (recon → exploit → post-exploit)
├── server/
│   ├── mcp_server.py       FastMCP server (all tool + engagement endpoints)
│   ├── ollama_bridge.py    Native Ollama chat with tool calling
│   ├── openai_bridge.py    OpenAI-compatible API bridge
│   └── config.py           Environment-based config loader
├── reporting/
│   ├── sarif.py            SARIF 2.1.0 export
│   ├── html_report.py      Standalone HTML report generator
│   ├── obsidian.py         Obsidian vault export (interlinked notes)
│   └── remediation.py      CWE → remediation mapping
├── observability/
│   ├── logging.py          structlog-based structured logging
│   └── metrics.py          Execution metrics tracking
└── tui/
    ├── app.py              Textual-based terminal UI
    └── widgets.py          Custom TUI widgets

Environment variables

Development

pip install ".[dev]"
pytest                    # run tests
ruff check src/ tests/    # lint
mypy src/                 # type check

License

MIT