Kali MCP — Knowledge Base
Bundle OKF 0.1 · 2 conceitos · pabpereza/kali-mcp
Open source Repository Open in the app JSON README (API)
About
# Kali MCP — Knowledge Base
How to use this toolkit well: which tool to reach for, and how to run it
efficiently. This bundle follows the
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
(markdown + YAML frontmatter). Process and methodology (authorization
policy, audit workflow, session system) live in `AGENTS.md`, not here.
This is **not** a vulnerability, CVE, or target database. No IP, hostname,
credential, or client-identifying detail belongs here — that data lives only
in `sessions/` (gitignored). See `AGENTS.md` § Knowledge Base for how
sub-agents consult and update this bundle.
# Bundles
* [tools/](tools/index.md) - How to run each tool: full command reference, plus accumulated efficiency notes (flags, timeouts, wordlists, pitfalls)
* [protocols/](protocols/index.md) - Which tool(s) to run for a given protocol or application (SSH, SMB, HTTP/WordPress, MySQL, ...)
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- pabpereza
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 57
- Forks
- 12
- Last push
- 2026-07-21T08:30:18Z
- Repository state
- ativo
- Language
- Dockerfile
- License
- MIT
- Added
- 2026-09-08 16:02:35
- Updated
- 2026-09-08 16:02:35
- Origin id
pabpereza/kali-mcp:knowledge/index.md
README
# Kali MCP
An ethical hacking toolkit that connects AI agents to Kali Linux security tools via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/).
Compatible with any AI agent that supports MCP: Claude Code, Gemini CLI, OpenCode, Cursor, Copilot, Codex, Aider, Windsurf, goose, and others.
```
> /kali-start 192.168.1.50
SESSION INITIALIZED
Target: 192.168.1.50
Scope: Passive + Credential testing
Dir: sessions/192_168_1_50_20260331_1430/
> /kali-audit 192.168.1.50
Scanning with nmap...
PORT SERVICE VERSION
22/tcp ssh OpenSSH 8.9
80/tcp http Apache 2.4.54
443/tcp https nginx 1.18
445/tcp microsoft-ds Samba 4.15
Launching 10 parallel sub-agents...
[Service Enum :22] -> SSH scripts, searchsploit CVEs
[Service Enum :80] -> nikto, gobuster, ffuf, dirb
[Web Dirs :80] -> ffuf directories, sensitive files
[Web Fuzz :80] -> arjun params, nuclei templates
[OSINT :80] -> whatweb, wafw00f, searchsploit
[API Testing :80] -> IDOR, auth bypass
[Auth Testing :80] -> SQLi on login, JWT analysis
[SMB Enum :445] -> crackmapexec, enum4linux, smbclient
[AD Audit :445] -> impacket, kerberoast
[Vuln Scan] -> nmap vuln scripts, nuclei
All sub-agents completed. Results saved to session assets.
> /kali-finish
SESSION FINALIZED — 14 findings (2 Critical, 4 High, 5 Medium, 3 Low)
Report: sessions/192_168_1_50_20260331_1430/findings.md
```
## Prerequisites
- **Docker** and **Docker Compose** (v2+)
- An AI agent with MCP support (see [Compatibility](#compatibility))
- A terminal with `curl` (used by `init.sh` to health-check the container)
## Getting Started
### 1. Clone and start
```bash
git clone https://github.com/pabpereza/kali-mcp.git
cd kali-mcp
./init.sh
```
`init.sh` builds the Kali Docker image, starts the container, and waits until the MCP server is healthy at `http://localhost:666/mcp`. First build may take several minutes.
### 2. Launch your AI agent
Open your agent **from the project directory** so it auto-detects `.mcp.json`:
```bash
claude # Claude Code (recommended — supports parallel sub-agents)
gemini # Gemini CLI
opencode # OpenCode
```
### 3. Start hacking
You can use natural language or slash commands:
```
> Scan ports on 10.10.10.5 with version detection
> Find hidden directories on http://target.com
> Check if FTP allows anonymous login on 10.10.10.5
```
## Typical Workflow (Claude Code)
The whole workflow is three commands: **start**, **audit**, **finish**. There are no standalone per-tool commands — for anything ad hoc outside this flow, just ask in natural language (e.g. "check if FTP allows anonymous login on 10.10.10.5") and the agent runs the matching tool directly.
```
/kali-start 10.10.10.5 # 1. Select target and scope
/kali-audit 10.10.10.5 # 2. Run the audit/pentest (parallel sub-agents)
/kali-finish # 3. Double-check + consolidated report + knowledge consolidation
```
#### Step 1: Initialize (`/kali-start`)
The start command asks two questions:
1. **Target(s)** — IP, hostname, URL, or CIDR range
2. **Scope** — Passive only, Passive + Credentials, or Full pentest
It creates a session directory with the structure:
```
sessions/10_10_10_5_20260331_1430/
├── session.md # Metadata: target, date, scope, status
├── targets.md # Target list and progress
├── findings.md # Consolidated findings (generated by /kali-finish)
└── assets/ # Raw output from each sub-agent
```
#### Step 2: Run the audit (`/kali-audit`)
Discovers services with nmap, then launches up to 10+ parallel sub-agents (per-port enumeration plus specialized web/AD sub-agents) across two waves — recon/loot first, brute-force/exploitation second, seeded with anything harvested in the first wave. Saves everything to the session's `assets/`.
You can re-run `/kali-audit <target>` against the same target later in the same session (e.g. after fixing a gap) — it reuses the existing `IN PROGRESS` session directory.
#### Step 3: Finalize (`/kali-finish`)
The finish command:
1. **Inventories** all sub-agent outputs in `assets/`
2. **Double-checks** completeness — flags missing or failed sub-agents
3. **Compiles** deduplicated findings by severity (Critical/High/Medium/Low)
4. **Generates** the consolidated report in `findings.md`
5. **Updates** `session.md` with executive summary and statistics
6. **Consolidates** any new, generalizable tool-efficiency lessons into `knowledge/`
### Session output example
After `/kali-finish`, your session directory looks like:
```
sessions/10_10_10_5_20260331_1430/
├── session.md # Status: COMPLETED, executive summary
├── targets.md # Targets with findings count
├── findings.md # 14 findings by severity
└── assets/
├── nmap_discovery.md # Initial port scan
├── service_enum_port22.md # SSH audit
├── service_enum_port80.md # HTTP service audit
├── web_directory_enum_port80.md # Hidden directories found
├── api_security_port80.md # API testing results
├── auth_session_testing_port80.md # Auth bypass attempts
├── service_enum_port445.md # SMB audit
└── vuln_scanning.md # CVE identification
```
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ AI Agent (Claude / Gemini / OpenCode / ...) │
│ │
│ Follows AGENTS.md (single source of truth); │
│ CLAUDE.md just points Claude Code there │
│ Uses MCP tools to execute security actions │
│ │
│ [Claude Code: parallel sub-agents per port] │
└──────────────────────┬──────────────────────────────┘
│ MCP (HTTP) localhost:666
┌──────────────────────┼──────────────────────────────┐
│ Docker: kali-mcp │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ supergateway :8000 │ │
│ │ Streamable HTTP <-> MCP stdio │ │
│ └──────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────▼──────────────────────┐ │
│ │ kali-server-mcp :5000 (Flask API) │ │
│ │ │ │
│ │ nmap · gobuster · dirb · nikto │ │
│ │ sqlmap · hydra · john · wpscan │ │
│ │ enum4linux · metasploit │ │
│ │ ffuf · nuclei · crackmapexec │ │
│ │ whatweb · amass · impacket · ... │ │
│ │ (50+ tools — see full list below) │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```
## Available Tools
50+ tools across OSINT & recon, web application testing, network & AD pentesting, traffic analysis, password/hash cracking, and forensics — the `nmap_scan`/`hydra_attack`/etc. native MCP wrappers are deprecated (unreliable health check, return HTTP 500); every tool is invoked through the single `execute_command` MCP tool instead.
The full, up-to-date catalog — canonical command per tool, function, and which ones are intrusive — lives in [`knowledge/tools/index.md`](knowledge/tools/index.md), not duplicated here. See [Knowledge Base](#knowledge-base) below.
## Slash Commands Reference (Claude Code)
Only three commands, by design — see [Repository Structure](#repository-structure) and [Knowledge Base](#knowledge-base) for why.
| Command | Description |
|---------|-------------|
| `/kali-start <target>` | Initialize session: select target and scope |
| `/kali-audit <target>` | Full audit/pentest: 1 sub-agent per discovered port/service + specialized web/AD sub-agents, up to 10+ parallel, two-wave loot-before-exploit |
| `/kali-finish` | Finalize: double-check sub-agents, compile findings, generate report, consolidate tool-efficiency knowledge |
For anything outside this flow (a single ad hoc check, digging into one file, cracking one hash), just ask in natural language — every tool listed below is reachable via `execute_command` without a slash command.
## Authorization Policy
Intrusive tools (sqlmap, hydra, john, metasploit) **always require user confirmation** before execution.
Three authorization levels:
| Level | Tools allowed | Risk |
|-------|--------------|------|
| **Passive only** | nmap, gobuster, dirb, nikto, wpscan, enum4linux | None |
| **Passive + Credentials** | + hydra with small wordlists | May trigger lockouts |
| **Full pentest** | + sqlmap, metasploit, full brute force | May disrupt services |
## Compatibility
| Agent | Instruction file read first | MCP | `/kali-*` commands | Parallel sub-agents |
|-------|-----------------------------|-----|---------------------|----------------------|
| **Claude Code** | `AGENTS.md` (via `CLAUDE.md` pointer) | Native | Native (`.claude/commands/`) | Yes |
| **Gemini CLI** | `AGENTS.md` | Native | Native (`.gemini/commands/` adapters) | No — sequential |
| **OpenCode** | `AGENTS.md` | Native | Native (`.opencode/commands/` adapters) | No — sequential* |
| **Cursor** | `AGENTS.md` | Native | Ask in plain text, e.g. "follow `.claude/commands/kali-audit.md`" | No — sequential |
| **GitHub Copilot** | `AGENTS.md` | Native | Same as Cursor | No — sequential |
| **Codex (OpenAI)** | `AGENTS.md` | Native | Same as Cursor — see note below | No — sequential |
| **Aider** | `AGENTS.md` | Native | Same as Cursor | No — sequential |
| **Windsurf** | `AGENTS.md` | Native | Same as Cursor | No — sequential |
| **goose** | `AGENTS.md` | Native | Same as Cursor | No — sequential |
> **Note**: `AGENTS.md` is the only file with real content — tools, authorization policy, audit methodology, session system, sub-agent architecture, knowledge base. `CLAUDE.md` is a one-line pointer that sends Claude Code there, so every agent ends up following the exact same instructions instead of a second, divergent copy.
>
> `/kali-start`, `/kali-audit`, `/kali-finish` are canonically defined once, as runbooks under `.claude/commands/`. Gemini CLI and OpenCode both support project-local custom slash commands that inject file content, so their adapters under `.gemini/commands/` and `.opencode/commands/` pull in `AGENTS.md` + the matching runbook and translate the Claude-only mechanics (parallel sub-agents → sequential steps, `AskUserQuestion` → plain-text question) — giving native `/kali-*` invocation there too, off the same source, no duplicated instructions. *OpenCode has its own subagent primitives; if the model judges they can genuinely run tasks in parallel it's free to use them, but the adapter doesn't assume it.
>
> Codex CLI's custom-prompt mechanism (`~/.codex/prompts/`) is user-home-only, not project-local, and is marked deprecated by OpenAI — it can't be shipped inside this repo, so there's no adapter for it. Cursor, GitHub Copilot, Aider, Windsurf, and goose don't expose a project-shippable custom-command format either as of this writing; on those, just ask in plain text and the agent follows `AGENTS.md`'s translation notes.
### Manual MCP configuration
Most agents auto-detect `.mcp.json`. If yours requires manual setup, point it to:
```json
{
"mcpServers": {
"kali": {
"type": "http",
"url": "http://localhost:666/mcp"
}
}
}
```
## Supported Services
20 built-in playbooks — HTTP/HTTPS (incl. WordPress), SSH, FTP, SMB/NetBIOS, MySQL, PostgreSQL, MSSQL, SMTP, DNS, RDP, SNMP, LDAP, Kerberos/Active Directory, VNC, Redis, MongoDB, Elasticsearch, Docker API, WinRM, NFS — plus a generic fallback for anything else. Each one is a short "which tool, in what order" checklist in [`knowledge/protocols/`](knowledge/protocols/index.md), which is what `/kali-audit` actually reads at dispatch time — see [Knowledge Base](#knowledge-base).
## Repository Structure
```
kali-mcp/
├── init.sh # Bootstrap: build, start, wait for readiness
├── .mcp.json # MCP endpoint config (auto-detected by agents)
├── AGENTS.md # Single source of truth: tools, methodology, session system, sub-agent architecture
├── CLAUDE.md # One-line pointer to AGENTS.md for Claude Code
├── docker/
│ ├── Dockerfile # Kali Linux image with security tools
│ ├── compose.yml # Docker Compose service definition
│ └── entrypoint.sh # Starts Flask API + supergateway
├── .claude/
│ └── commands/ # Canonical runbooks (Claude Code native; source for the adapters below)
│ ├── kali-start.md # /kali-start — Initialize session
│ ├── kali-audit.md # /kali-audit — Full audit/pentest (10+ sub-agents)
│ └── kali-finish.md # /kali-finish — Finalize + consolidated report + knowledge
├── .gemini/
│ └── commands/ # Gemini CLI adapters — inject AGENTS.md + the matching runbook
│ ├── kali-start.toml
│ ├── kali-audit.toml
│ └── kali-finish.toml
├── .opencode/
│ └── commands/ # OpenCode adapters — inject AGENTS.md + the matching runbook
│ ├── kali-start.md
│ ├── kali-audit.md
│ └── kali-finish.md
├── knowledge/ # Knowledge base (git-tracked, OKF format)
│ ├── index.md
│ ├── log.md
│ ├── tools/ # How to use each tool: full catalog + per-tool efficiency notes
│ └── protocols/ # Which tool(s) for each protocol/application (20 playbooks)
└── sessions/ # Session data (git-ignored)
└── <target>_<timestamp>/
├── session.md
├── targets.md
├── findings.md
└── assets/
```
## Knowledge Base
`knowledge/` is a small, git-tracked bundle in [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (markdown + YAML frontmatter), split in two:
- [`knowledge/tools/`](knowledge/tools/index.md) — **how** to use each tool: the full command reference catalog, plus per-tool notes on running it efficiently (flags, timeouts, wordlists, concurrency, pitfalls) that accumulate as real engagements teach us something.
- [`knowledge/protocols/`](knowledge/protocols/index.md) — **which** tool(s) to reach for on a given protocol or application (SSH, SMB, HTTP/WordPress, MySQL, ...), one short checklist per service.
`AGENTS.md` deliberately holds neither — it's process and methodology only (authorization policy, audit workflow, session system). This is not a vulnerability or target database either: nothing target-identifying (IP, hostname, credentials) is ever written there, only in the gitignored `sessions/`.
- `/kali-audit` reads the matching `knowledge/protocols/<service>.md` before dispatching each service's sub-agent(s) and copies its steps into their prompts, and consults `knowledge/tools/<tool>.md` for efficiency notes on top of that.
- `/kali-finish` distills genuinely new, generalizable efficiency lessons from the session back into `knowledge/tools/` — most sessions won't add anything, and that's expected. A protocol/application worth a dedicated playbook gets added to `knowledge/protocols/` the same way.
- Because it's plain markdown in git, you can read, edit, or review it like any other part of the codebase.
## Troubleshooting
| Problem | Solution |
|---------|----------|
| `init.sh` hangs at "Waiting for MCP server" | Check Docker is running: `docker ps`. Inspect logs: `docker logs kali-mcp`. |
| Agent can't connect to MCP | Verify the container is up: `curl http://localhost:666/mcp`. Restart with `./init.sh`. |
| Port 666 already in use | Change the host port in `docker/compose.yml` (`"<new-port>:8000"`) and update `.mcp.json`. |
| Image build fails | Ensure internet access. Kali repos may be temporarily unavailable — retry. |
| Tools timeout on large scans | Some scans take minutes. Add resource limits in `compose.yml` if needed. |
## Disclaimer
> **WARNING**: This toolkit is intended **exclusively** for authorized security testing. Misuse may violate local, national, and international laws.
**You must ensure that:**
- You have **explicit written authorization** from the system owner before testing.
- You are operating within the **agreed scope** of the engagement.
- You understand that intrusive tools **can disrupt services**, corrupt data, or trigger security alerts.
**Acceptable use cases:**
- Penetration testing engagements with a signed agreement
- CTF (Capture The Flag) competitions
- Lab environments (HackTheBox, TryHackMe, VulnHub, personal labs)
- Defensive security research
**The authors assume no liability for damages caused by misuse. You are solely responsible for your actions.**
## License
This project is provided as-is for educational and authorized security testing purposes. See individual tool licenses (nmap, sqlmap, metasploit, etc.) for their respective terms.