{
  "markdown": "# Kali MCP\n\nAn ethical hacking toolkit that connects AI agents to Kali Linux security tools via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/).\n\nCompatible with any AI agent that supports MCP: Claude Code, Gemini CLI, OpenCode, Cursor, Copilot, Codex, Aider, Windsurf, goose, and others.\n\n```\n> /kali-start 192.168.1.50\n\n  SESSION INITIALIZED\n  Target:  192.168.1.50\n  Scope:   Passive + Credential testing\n  Dir:     sessions/192_168_1_50_20260331_1430/\n\n> /kali-audit 192.168.1.50\n\n  Scanning with nmap...\n  PORT    SERVICE       VERSION\n  22/tcp  ssh           OpenSSH 8.9\n  80/tcp  http          Apache 2.4.54\n  443/tcp https         nginx 1.18\n  445/tcp microsoft-ds  Samba 4.15\n\n  Launching 10 parallel sub-agents...\n    [Service Enum :22]  -> SSH scripts, searchsploit CVEs\n    [Service Enum :80]  -> nikto, gobuster, ffuf, dirb\n    [Web Dirs :80]      -> ffuf directories, sensitive files\n    [Web Fuzz :80]      -> arjun params, nuclei templates\n    [OSINT :80]         -> whatweb, wafw00f, searchsploit\n    [API Testing :80]   -> IDOR, auth bypass\n    [Auth Testing :80]  -> SQLi on login, JWT analysis\n    [SMB Enum :445]     -> crackmapexec, enum4linux, smbclient\n    [AD Audit :445]     -> impacket, kerberoast\n    [Vuln Scan]         -> nmap vuln scripts, nuclei\n\n  All sub-agents completed. Results saved to session assets.\n\n> /kali-finish\n\n  SESSION FINALIZED — 14 findings (2 Critical, 4 High, 5 Medium, 3 Low)\n  Report: sessions/192_168_1_50_20260331_1430/findings.md\n```\n\n## Prerequisites\n\n- **Docker** and **Docker Compose** (v2+)\n- An AI agent with MCP support (see [Compatibility](#compatibility))\n- A terminal with `curl` (used by `init.sh` to health-check the container)\n\n## Getting Started\n\n### 1. Clone and start\n\n```bash\ngit clone https://github.com/pabpereza/kali-mcp.git\ncd kali-mcp\n./init.sh\n```\n\n`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.\n\n### 2. Launch your AI agent\n\nOpen your agent **from the project directory** so it auto-detects `.mcp.json`:\n\n```bash\nclaude          # Claude Code (recommended — supports parallel sub-agents)\ngemini          # Gemini CLI\nopencode        # OpenCode\n```\n\n### 3. Start hacking\n\nYou can use natural language or slash commands:\n\n```\n> Scan ports on 10.10.10.5 with version detection\n> Find hidden directories on http://target.com\n> Check if FTP allows anonymous login on 10.10.10.5\n```\n\n## Typical Workflow (Claude Code)\n\nThe 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.\n\n```\n/kali-start 10.10.10.5          # 1. Select target and scope\n/kali-audit 10.10.10.5          # 2. Run the audit/pentest (parallel sub-agents)\n/kali-finish                    # 3. Double-check + consolidated report + knowledge consolidation\n```\n\n#### Step 1: Initialize (`/kali-start`)\n\nThe start command asks two questions:\n1. **Target(s)** — IP, hostname, URL, or CIDR range\n2. **Scope** — Passive only, Passive + Credentials, or Full pentest\n\nIt creates a session directory with the structure:\n```\nsessions/10_10_10_5_20260331_1430/\n├── session.md      # Metadata: target, date, scope, status\n├── targets.md      # Target list and progress\n├── findings.md     # Consolidated findings (generated by /kali-finish)\n└── assets/         # Raw output from each sub-agent\n```\n\n#### Step 2: Run the audit (`/kali-audit`)\n\nDiscovers 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/`.\n\nYou 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.\n\n#### Step 3: Finalize (`/kali-finish`)\n\nThe finish command:\n1. **Inventories** all sub-agent outputs in `assets/`\n2. **Double-checks** completeness — flags missing or failed sub-agents\n3. **Compiles** deduplicated findings by severity (Critical/High/Medium/Low)\n4. **Generates** the consolidated report in `findings.md`\n5. **Updates** `session.md` with executive summary and statistics\n6. **Consolidates** any new, generalizable tool-efficiency lessons into `knowledge/`\n\n### Session output example\n\nAfter `/kali-finish`, your session directory looks like:\n\n```\nsessions/10_10_10_5_20260331_1430/\n├── session.md                          # Status: COMPLETED, executive summary\n├── targets.md                          # Targets with findings count\n├── findings.md                         # 14 findings by severity\n└── assets/\n    ├── nmap_discovery.md               # Initial port scan\n    ├── service_enum_port22.md          # SSH audit\n    ├── service_enum_port80.md          # HTTP service audit\n    ├── web_directory_enum_port80.md    # Hidden directories found\n    ├── api_security_port80.md          # API testing results\n    ├── auth_session_testing_port80.md  # Auth bypass attempts\n    ├── service_enum_port445.md         # SMB audit\n    └── vuln_scanning.md                # CVE identification\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│  AI Agent (Claude / Gemini / OpenCode / ...)        │\n│                                                     │\n│  Follows AGENTS.md (single source of truth);        │\n│  CLAUDE.md just points Claude Code there            │\n│  Uses MCP tools to execute security actions         │\n│                                                     │\n│  [Claude Code: parallel sub-agents per port]        │\n└──────────────────────┬──────────────────────────────┘\n                       │ MCP (HTTP) localhost:666\n┌──────────────────────┼──────────────────────────────┐\n│  Docker: kali-mcp    │                              │\n│                      ▼                              │\n│  ┌─────────────────────────────────────┐            │\n│  │ supergateway :8000                  │            │\n│  │ Streamable HTTP  <->  MCP stdio    │            │\n│  └──────────────┬──────────────────────┘            │\n│                 │                                   │\n│  ┌──────────────▼──────────────────────┐            │\n│  │ kali-server-mcp :5000 (Flask API)   │            │\n│  │                                     │            │\n│  │  nmap · gobuster · dirb · nikto     │            │\n│  │  sqlmap · hydra · john · wpscan     │            │\n│  │  enum4linux · metasploit            │            │\n│  │  ffuf · nuclei · crackmapexec       │            │\n│  │  whatweb · amass · impacket · ...   │            │\n│  │  (50+ tools — see full list below)  │            │\n│  └─────────────────────────────────────┘            │\n└─────────────────────────────────────────────────────┘\n```\n\n## Available Tools\n\n50+ 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.\n\nThe 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.\n\n## Slash Commands Reference (Claude Code)\n\nOnly three commands, by design — see [Repository Structure](#repository-structure) and [Knowledge Base](#knowledge-base) for why.\n\n| Command | Description |\n|---------|-------------|\n| `/kali-start <target>` | Initialize session: select target and scope |\n| `/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 |\n| `/kali-finish` | Finalize: double-check sub-agents, compile findings, generate report, consolidate tool-efficiency knowledge |\n\nFor 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.\n\n## Authorization Policy\n\nIntrusive tools (sqlmap, hydra, john, metasploit) **always require user confirmation** before execution.\n\nThree authorization levels:\n\n| Level | Tools allowed | Risk |\n|-------|--------------|------|\n| **Passive only** | nmap, gobuster, dirb, nikto, wpscan, enum4linux | None |\n| **Passive + Credentials** | + hydra with small wordlists | May trigger lockouts |\n| **Full pentest** | + sqlmap, metasploit, full brute force | May disrupt services |\n\n## Compatibility\n\n| Agent | Instruction file read first | MCP | `/kali-*` commands | Parallel sub-agents |\n|-------|-----------------------------|-----|---------------------|----------------------|\n| **Claude Code** | `AGENTS.md` (via `CLAUDE.md` pointer) | Native | Native (`.claude/commands/`) | Yes |\n| **Gemini CLI** | `AGENTS.md` | Native | Native (`.gemini/commands/` adapters) | No — sequential |\n| **OpenCode** | `AGENTS.md` | Native | Native (`.opencode/commands/` adapters) | No — sequential* |\n| **Cursor** | `AGENTS.md` | Native | Ask in plain text, e.g. \"follow `.claude/commands/kali-audit.md`\" | No — sequential |\n| **GitHub Copilot** | `AGENTS.md` | Native | Same as Cursor | No — sequential |\n| **Codex (OpenAI)** | `AGENTS.md` | Native | Same as Cursor — see note below | No — sequential |\n| **Aider** | `AGENTS.md` | Native | Same as Cursor | No — sequential |\n| **Windsurf** | `AGENTS.md` | Native | Same as Cursor | No — sequential |\n| **goose** | `AGENTS.md` | Native | Same as Cursor | No — sequential |\n\n> **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.\n>\n> `/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.\n>\n> 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.\n\n### Manual MCP configuration\n\nMost agents auto-detect `.mcp.json`. If yours requires manual setup, point it to:\n\n```json\n{\n  \"mcpServers\": {\n    \"kali\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:666/mcp\"\n    }\n  }\n}\n```\n\n## Supported Services\n\n20 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).\n\n## Repository Structure\n\n```\nkali-mcp/\n├── init.sh                  # Bootstrap: build, start, wait for readiness\n├── .mcp.json                # MCP endpoint config (auto-detected by agents)\n├── AGENTS.md                # Single source of truth: tools, methodology, session system, sub-agent architecture\n├── CLAUDE.md                # One-line pointer to AGENTS.md for Claude Code\n├── docker/\n│   ├── Dockerfile           # Kali Linux image with security tools\n│   ├── compose.yml          # Docker Compose service definition\n│   └── entrypoint.sh        # Starts Flask API + supergateway\n├── .claude/\n│   └── commands/            # Canonical runbooks (Claude Code native; source for the adapters below)\n│       ├── kali-start.md         # /kali-start — Initialize session\n│       ├── kali-audit.md         # /kali-audit — Full audit/pentest (10+ sub-agents)\n│       └── kali-finish.md        # /kali-finish — Finalize + consolidated report + knowledge\n├── .gemini/\n│   └── commands/            # Gemini CLI adapters — inject AGENTS.md + the matching runbook\n│       ├── kali-start.toml\n│       ├── kali-audit.toml\n│       └── kali-finish.toml\n├── .opencode/\n│   └── commands/            # OpenCode adapters — inject AGENTS.md + the matching runbook\n│       ├── kali-start.md\n│       ├── kali-audit.md\n│       └── kali-finish.md\n├── knowledge/                # Knowledge base (git-tracked, OKF format)\n│   ├── index.md\n│   ├── log.md\n│   ├── tools/                # How to use each tool: full catalog + per-tool efficiency notes\n│   └── protocols/            # Which tool(s) for each protocol/application (20 playbooks)\n└── sessions/                # Session data (git-ignored)\n    └── <target>_<timestamp>/\n        ├── session.md\n        ├── targets.md\n        ├── findings.md\n        └── assets/\n```\n\n## Knowledge Base\n\n`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:\n\n- [`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.\n- [`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.\n\n`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/`.\n\n- `/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.\n- `/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.\n- Because it's plain markdown in git, you can read, edit, or review it like any other part of the codebase.\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| `init.sh` hangs at \"Waiting for MCP server\" | Check Docker is running: `docker ps`. Inspect logs: `docker logs kali-mcp`. |\n| Agent can't connect to MCP | Verify the container is up: `curl http://localhost:666/mcp`. Restart with `./init.sh`. |\n| Port 666 already in use | Change the host port in `docker/compose.yml` (`\"<new-port>:8000\"`) and update `.mcp.json`. |\n| Image build fails | Ensure internet access. Kali repos may be temporarily unavailable — retry. |\n| Tools timeout on large scans | Some scans take minutes. Add resource limits in `compose.yml` if needed. |\n\n## Disclaimer\n\n> **WARNING**: This toolkit is intended **exclusively** for authorized security testing. Misuse may violate local, national, and international laws.\n\n**You must ensure that:**\n\n- You have **explicit written authorization** from the system owner before testing.\n- You are operating within the **agreed scope** of the engagement.\n- You understand that intrusive tools **can disrupt services**, corrupt data, or trigger security alerts.\n\n**Acceptable use cases:**\n\n- Penetration testing engagements with a signed agreement\n- CTF (Capture The Flag) competitions\n- Lab environments (HackTheBox, TryHackMe, VulnHub, personal labs)\n- Defensive security research\n\n**The authors assume no liability for damages caused by misuse. You are solely responsible for your actions.**\n\n## License\n\nThis project is provided as-is for educational and authorized security testing purposes. See individual tool licenses (nmap, sqlmap, metasploit, etc.) for their respective terms.\n",
  "bytes": 17188,
  "sha": "a057a84c90124f8c49881a5a50535d5f8bbb1e316a421fa80821810e8830d0d1",
  "repo_slug": "pabpereza/kali-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_pabpereza_kali_mcp_knowledge_index_md_d9278c78/readme"
}