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:

	V1	V2
Architecture	Flask API + MCP shim (2 processes)	Single FastMCP server (mcp SDK)
Transport	HTTP only	Streamable-HTTP or stdio
Tools	10, inline in one file	38 wrappers (+ custom script executor), each in src/astro/tools/
Tool validation	None — raw strings to shell	Pydantic-based validation, shell metacharacter blocking, blocked-flag list
Scope enforcement	None	CIDR + domain allowlists via YAML config; every tool call is checked
Rate limiting	None	Per-tool async semaphores
Auth	None	API key + OIDC support
Engagement tracking	None	SQLite-backed finding recorder with per-engagement isolation
Output parsing	Raw stdout	Structured parsers for nmap, sqlmap, wpscan, nuclei, subfinder, etc.
Reporting	None	SARIF, HTML, Obsidian vault export, remediation mapping
Intelligence	None	CVE correlator (NVD API), attack graph builder (NetworkX), methodology tracker
CLI	run.py (starts 2 servers)	astro serve, astro ollama, astro tui, astro version
Packaging	requirements.txt + venv	pyproject.toml, installable via pip install .
Container	None	Multi-stage Kali Linux Dockerfile, docker-compose for lab environments
LLM support	Claude Desktop only	Any MCP client, plus native Ollama bridge and OpenAI-compatible bridge
Tests	None	pytest suite (unit + integration), ruff, mypy strict

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)

docker compose up --build

The server starts on http://localhost:8080 with streamable-HTTP transport. All 38 Kali tools are pre-installed in the image.

Docker lab (with a target)

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.

Local install

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

Requires the underlying Kali tools to be installed on the host.

Usage

MCP server (default)

astro serve --transport streamable-http --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

Tool	Description
nmap	Network scanner with structured output parsing
gobuster	Directory/DNS/vhost brute-forcer
dirb	Web content scanner
nikto	Web server vulnerability scanner
wpscan	WordPress vulnerability scanner
enum4linux	Windows/Samba enumeration
subfinder	Passive subdomain discovery
amass	Attack surface mapping
ffuf	Web fuzzer
whatweb	Technology fingerprinting
dnsrecon	DNS reconnaissance
theharvester	OSINT email/subdomain harvesting
nuclei	Template-based vulnerability scanner

Exploitation

Tool	Description
sqlmap	SQL injection tester with DB enumeration
metasploit	Exploitation framework (msfconsole)
hydra	Network login brute-forcer
john	Password cracker
hashcat	GPU-accelerated password cracker
searchsploit	Exploit-DB local search
crackmapexec	Network protocol attack tool
responder	LLMNR/NBT-NS/mDNS poisoner
smbclient	SMB client
evil-winrm	WinRM shell

Impacket suite

Tool	Description
impacket_secretsdump	SAM/LSA/NTDS credential extraction
impacket_psexec	Remote command execution via SMB
impacket_wmiexec	Remote command execution via WMI
impacket_kerberoast	SPN-based Kerberos ticket extraction
impacket_getnpusers	AS-REP roasting
impacket_getst	Service ticket requests
impacket_ticketer	Silver/golden ticket forging

Post-exploitation

Tool	Description
linpeas	Linux privilege escalation scanner
winpeas	Windows privilege escalation scanner
bloodhound	Active Directory relationship mapper
msfvenom	Payload generator
netcat	Network Swiss army knife
chisel	TCP/UDP tunnel over HTTP
certipy	AD Certificate Services attacks
burp	Burp Suite proxy integration

Other

Tool	Description
custom_script	Run arbitrary bash/python with timeout sandbox

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

Variable	Default	Description
ASTRO_HOST	127.0.0.1	Server bind address
ASTRO_PORT	8080	Server listen port
ASTRO_TRANSPORT	streamable-http	MCP transport (streamable-http or stdio)
ASTRO_DB_PATH	~/.astro/engagements.db	SQLite database path
ASTRO_SCOPE_CONFIG	—	Path to scope YAML config
ASTRO_DEBUG	false	Enable debug logging
API_KEY	—	API key for authenticated access

Development

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

License

MIT