project_astro

MCP Server and Kali API Server- With Claude Desktop Integ

31 stars PythonAI & Machine Learning Updated Nov 2, 2025

Documentation

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)

bash

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)

bash

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

bash

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)

bash

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:

json

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

Ollama bridge (offline / local LLM)

bash

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

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

Terminal UI

bash

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:

yaml

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

bash

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

code

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

code

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

bash

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

License

MIT

Frequently asked questions

What is project_astro?

project_astro is MCP Server and Kali API Server- With Claude Desktop Integ

How do I install project_astro?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is project_astro open source?

Yes — it is hosted on GitHub at https://github.com/whit3rabbit0/project_astro/ and has 31 stars.

Related MCP tools

openhands

🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.

64,677 Python

agentartificial-intelligencechatgpt+6

mem0

Universal memory layer for AI Agents; Announcing OpenMemory MCP - local and secure memory management. Python-based implementation.

42,646 Python

agentsaiai-agents+12

chatgpt-on-wechat

基于大模型搭建的聊天机器人，同时支持微信公众号、企业微信应用、飞书、钉钉等接入，可选择ChatGPT/Claude/DeepSeek/文心一言/讯飞星火/通义千问/ Gemini/GLM-4/Kimi/LinkAI，能处理文本、语音和图片，访问操作系统和互联网，支持基于自有知识库进行定制企业智能客服。

39,573 Python

aiai-agentchatgpt+17

gpt-researcher

An LLM agent that conducts deep research (local and web) on any given topic and generates a long report with citations. Built for the Model Context Protocol to

24,026 Python

agentaiautomation+8

fastmcp

🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.

19,927 Python

agentsfastmcpllms+6

maxkb

🔥 MaxKB is an open-source platform for building enterprise-grade agents. MaxKB 是强大易用的开源企业级智能体平台。 for the Model Context Protocol. Enhance AI assistants with po

19,062 Python

agentagentic-aichatbot+11

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP