{"id":50792865,"url":"https://github.com/cryptojones/kalimcp","last_synced_at":"2026-06-12T12:02:25.627Z","repository":{"id":358571319,"uuid":"1241056059","full_name":"CryptoJones/KaliMCP","owner":"CryptoJones","description":"MCP server exposing a curated subset of Kali Linux security tools to an AI agent. Refuse-list guard + audit log on every invocation.","archived":false,"fork":false,"pushed_at":"2026-06-02T07:11:23.000Z","size":83,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T09:09:43.620Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CryptoJones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T22:52:04.000Z","updated_at":"2026-06-02T07:11:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CryptoJones/KaliMCP","commit_stats":null,"previous_names":["cryptojones/kalimcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CryptoJones/KaliMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FKaliMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FKaliMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FKaliMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FKaliMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CryptoJones","download_url":"https://codeload.github.com/CryptoJones/KaliMCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2FKaliMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T12:01:46.317Z","updated_at":"2026-06-12T12:02:25.560Z","avatar_url":"https://github.com/CryptoJones.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║                                                              ║\n║                 K  A  L  I  M  C  P                          ║\n║                                                              ║\n║       Kali Linux security tools for AI agents                ║\n║                                                              ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n**An MCP server that exposes a curated subset of Kali Linux's security\ntools to an AI agent.** Every invocation is audit-logged.\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?logo=apache)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![Kali](https://img.shields.io/badge/Base-kali--rolling-557C94?logo=kalilinux\u0026logoColor=white)](https://www.kali.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-D97757?logo=anthropic\u0026logoColor=white)](https://modelcontextprotocol.io/)\n[![Codeberg](https://img.shields.io/badge/Codeberg-CryptoJones%2FKaliMCP-2185D0?logo=codeberg\u0026logoColor=white)](https://codeberg.org/CryptoJones/KaliMCP)\n[![GitHub](https://img.shields.io/badge/GitHub-CryptoJones%2FKaliMCP-181717?logo=github\u0026logoColor=white)](https://github.com/CryptoJones/KaliMCP)\n\n\u003c/div\u003e\n\n\u003e Mirrored on both [GitHub](https://github.com/CryptoJones/KaliMCP) and\n\u003e [Codeberg](https://codeberg.org/CryptoJones/KaliMCP). Issues filed on\n\u003e either are welcome; commits are pushed to both.\n\n---\n\n## Authorization \u0026 scope\n\nKaliMCP exposes offensive security tools — port scanners, web\nvuln scanners, network logon brute-force, automated SQL injection\n— to an AI agent. The operator is solely responsible for using it\nonly against targets they are authorized to scan: pentest\nengagements with written scope, CTFs you have a flag for, your\nown lab, bug bounty programs whose scope covers what you're\nscanning. Cracking passwords or injecting SQL against systems\nwithout authorization is a federal-grade mistake.\n\nEvery invocation appends one JSON line to `/var/log/kalimcp.log`\n(target, argv, exit code, elapsed time). That audit trail is the\noperator-accountability mechanism; the project does not enforce a\nhard-coded refuse list.\n\nCredential tools (`hydra_crack`, `medusa_crack`, `netexec_spray`,\n`john_crack`, `hashcat_crack`) take password / hash / wordlist\nvalues on the command line. Those values are redacted in the\naudit log — the flag stays, but the value is rewritten to\n`sha256:\u003c8hex\u003e` so the literal never lands in the log file.\n\n---\n\n## What it does\n\nExposes the following [MCP](https://modelcontextprotocol.io/) tools to\nany compliant client (Claude Code, Claude Desktop, future MCP-aware\nclients):\n\n**Recon / scanning**\n\n| Tool | Wraps | Purpose |\n|------|-------|---------|\n| `nmap_scan` | `nmap` | port + service scan (5 named profiles); structured `parsed` JSON |\n| `nikto_scan` | `nikto` | web-server vulnerability scan; structured `parsed` JSON |\n| `gobuster_dir` | `gobuster` | directory / file enumeration; structured `parsed` JSON |\n| `ffuf_fuzz` | `ffuf` | flexible web fuzzing (dir / vhost / param / ext modes) |\n| `whatweb_fingerprint` | `whatweb` | HTTP / CMS / framework fingerprinting |\n| `sslscan_scan` | `sslscan` | TLS / SSL cipher + cert enumeration; structured `parsed` JSON |\n| `smb_enum` | `enum4linux-ng` | SMB shares / users / groups / OS / signing |\n| `snmp_enum` | `snmp-check` | SNMP enumeration (hostname / contact / processes / software) |\n| `ldap_enum` | `ldapsearch` | anonymous LDAP rootDSE query (naming contexts / vendor) |\n\n**Auth \u0026 credentials**\n\n| Tool | Wraps | Purpose |\n|------|-------|---------|\n| `hydra_crack` | `hydra` | network logon brute-force (ssh/ftp/smb/http-…); 4 profiles |\n| `medusa_crack` | `medusa` | alt logon brute-force (different protocol modules: cvs/afp/smbnt) |\n| `netexec_spray` | `netexec` | credential spray across smb/winrm/ldap/mssql/ssh; pass-the-hash |\n| `john_crack` | `john` | offline hash cracking |\n| `hashcat_crack` | `hashcat` | GPU-accelerated offline hash cracking |\n| `sqlmap_scan` | `sqlmap` | automated SQL injection detection + exploitation; 4 profiles |\n\n**Windows AD post-exploit**\n\n| Tool | Wraps | Purpose |\n|------|-------|---------|\n| `impacket_getnpusers` | `GetNPUsers.py` | AS-REP roastable user enumeration |\n| `impacket_getuserspns` | `GetUserSPNs.py` | Kerberoasting (request SPN TGS hashes) |\n| `impacket_secretsdump` | `secretsdump.py` | SAM / LSA / NTDS dump (incl. DCSync) |\n| `impacket_smbclient` | `smbclient.py` | one-shot SMB shell command |\n| `winrm_exec` | `netexec winrm -X` | one-shot PowerShell over WinRM |\n| `msfvenom_payload` | `msfvenom` | payload generation (NO Metasploit framework) |\n\n**Engagement workspace (agent working memory)**\n\n| Tool | Purpose |\n|------|---------|\n| `engagement_create` | bootstrap a new engagement dir with scope + operator |\n| `engagement_list` / `engagement_use` / `engagement_status` | switch \u0026 inspect |\n| `finding_record` / `finding_query` / `host_list` | append-only structured findings |\n| `cred_record` / `cred_query` | credential cache (file mode 0600) |\n| `loot_write` / `loot_list` / `loot_read` | extracted blob store |\n| `note_append` | operator free-form notes.md |\n| `wordlist_list` | enumerate wordlists under `/usr/share/wordlists` + seclists |\n\nSet `KALIMCP_AUTORECORD=1` to have active-scan tools mirror their\nparsed findings into the active engagement automatically (nmap →\nfindings, hydra/netexec → creds, etc.). If the active engagement\nhas a `scope` list, calls to out-of-scope targets get a non-\nblocking `warning: \"out_of_scope\"` in the result + an audit event.\n\n**Passive lookups**\n\n| Tool | Wraps | Purpose |\n|------|-------|---------|\n| `whois_lookup` | `whois` | domain / IP registration info |\n| `dig_record` | `dig` | DNS record lookup |\n| `searchsploit_search` | `searchsploit` | local Exploit-DB grep |\n| `cert_dump` | `openssl s_client` | TLS cert chain inspection |\n\n---\n\n## Install\n\n### Docker (recommended)\n\n```bash\ngit clone https://github.com/CryptoJones/KaliMCP.git\ncd KaliMCP\ndocker build -t kalimcp .\n```\n\nThe image pulls from `kalilinux/kali-rolling` and installs the full\nwrapped tool set alongside the Python package:\n\n- **recon / web**: nmap, nikto, gobuster, sslscan, ffuf, whatweb,\n  enum4linux-ng, snmp, ldap-utils\n- **auth / credentials**: hydra, sqlmap, netexec, medusa, john,\n  hashcat\n- **Windows AD post-exploit**: impacket-scripts, metasploit-framework\n  (only `msfvenom` is wired — see below)\n- **passive**: whois, dnsutils, exploitdb, openssl\n- **wordlists**: wordlists, seclists\n\n### Bare metal (Kali Linux only — needs the tools installed already)\n\n```bash\ngit clone https://github.com/CryptoJones/KaliMCP.git\ncd KaliMCP\npython3 -m venv .venv\n.venv/bin/pip install -e .\n```\n\n---\n\n## Wire into Claude Code\n\nEdit (or create) `~/.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"kalimcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-v\", \"/home/YOU/.kalimcp:/root/.kalimcp\",\n        \"-v\", \"/var/log/kalimcp.log:/var/log/kalimcp.log\",\n        \"kalimcp\"\n      ]\n    }\n  }\n}\n```\n\n(Replace `/home/YOU` with `$HOME`.) Or bare-metal:\n\n```json\n{\n  \"mcpServers\": {\n    \"kalimcp\": {\n      \"command\": \"/path/to/.venv/bin/kalimcp\"\n    }\n  }\n}\n```\n\nRestart Claude Code. The tools above will be available to the\nagent. Ask it to **\"scan 10.0.0.5 with nmap-fast\"** and it will\nissue the call.\n\n---\n\n## Audit log\n\nEvery tool call appends one JSON line to `/var/log/kalimcp.log` (or\n`~/.kalimcp/kalimcp.log` if the system path isn't writable). The\nlog records:\n\n- `event`: `tool_invoke`, `passive_invoke`, `tool_exception`.\n- `tool`: which wrapper was called.\n- `target`: the scanned host / URL (full string).\n- `elapsed_ms`, `exit_code`, `timed_out`, `truncated`.\n\nTo use the standard system path without sudo on every invocation:\n\n```bash\nsudo touch /var/log/kalimcp.log\nsudo chown $(id -un):$(id -gn) /var/log/kalimcp.log\n```\n\nThe audit log is a strict side channel. Errors writing it never\naffect tool execution. `KALIMCP_NO_LOG=1` disables it entirely\n(for tests).\n\n---\n\n## What's NOT here\n\nThe v0.4 → v0.9 red-team overhaul is shipped: recon, web-vuln,\nauth/credential, Windows AD post-exploit, and the engagement\nworkspace are all live (see the Status table). What's\ndeliberately left out:\n\n- **Go-binary recon tools not in the Kali apt repos** — subfinder,\n  amass, feroxbuster, gowitness, kerbrute. These need curl-install\n  layers or a Go builder stage in the Dockerfile; deferred to a\n  follow-up phase. The `screenshots/` dir in each engagement is\n  reserved for a future `gowitness`-backed screenshot tool.\n- **evil-winrm's interactive shell** — `winrm_exec` covers\n  single-shot PowerShell over WinRM (`netexec winrm -X`); there's\n  no persistent interactive session.\n- **The Metasploit framework's exploit modules and the\n  `msfconsole` driver.** The `metasploit-framework` package is\n  installed only to provide `msfvenom`. `msfvenom_payload` is\n  payload generation only — output is written to disk under\n  `~/.kalimcp/payloads/` (operators retrieve the binary\n  themselves) so the MCP server never serves executable bytes\n  inline.\n\n---\n\n## Status\n\n| Version | Feature | Status |\n|---------|---------|--------|\n| v0.1 | nmap / nikto / gobuster / sslscan / whois / dig / searchsploit / cert_dump; audit log; Dockerfile on kali-rolling | shipped |\n| v0.2 | `authorization_token` parameter removed from active-scan tools (breaking); `argv` recorded in `tool_invoke` audit events; ruff lint gate; full test coverage on tool wrappers | shipped |\n| v0.3 | structured nmap XML output → JSON; `kalimcp-authz` CLI dropped | shipped |\n| v0.4 | `hydra_crack` + `sqlmap_scan` wired in; refuse list removed (audit log remains the accountability channel) | shipped |\n| v0.5 | structured `parsed` JSON for `nikto_scan`, `sslscan_scan`, `gobuster_dir` | shipped |\n| v0.6 | recon expansion: ffuf, whatweb, smb/snmp/ldap enum | shipped |\n| v0.7 | credential operations: netexec, medusa, john, hashcat; argv-secret redaction in audit log | shipped |\n| v0.8 | Windows AD post-exploit: impacket suite (NPUsers/UserSPNs/secretsdump/smbclient), winrm_exec, msfvenom payload generation | shipped |\n| v0.9 | engagement workspace (`~/.kalimcp/engagements/\u003cname\u003e/`) — findings/creds/loot/screenshots + scope-warning audit + auto-record hook | shipped |\n| (later) | Go-binary recon tools (subfinder, feroxbuster, gowitness, kerbrute) — need curl-install layers in Dockerfile | planned |\n\nSee [CHANGELOG.md](CHANGELOG.md) for the per-release detail.\n\n---\n\n## Development\n\n```bash\npython3 -m venv .venv\n.venv/bin/pip install -e '.[dev]'\n\n.venv/bin/ruff check .          # lint (E, F, W, B, I, UP)\n.venv/bin/mypy                  # type check (src/)\n.venv/bin/pip-audit             # dependency CVE scan\n.venv/bin/python -m pytest -q   # tests (no real subprocesses spawn)\n```\n\nCI (Woodpecker + GitHub Actions) runs ruff, mypy, pip-audit, and pytest on\nPython 3.11 and 3.12, plus a hadolint pass on the Dockerfile. See\n[CONTRIBUTING.md](CONTRIBUTING.md) for the tool-wrapper checklist.\n\n---\n\n## Contributing \u0026 security\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, the tool-wrapper\n  checklist, and the dual-mirror (GitHub + Codeberg) workflow.\n- [SECURITY.md](SECURITY.md) — authorized-use responsibility and how to\n  report a vulnerability in the server code itself.\n\n---\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\nProudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fkalimcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptojones%2Fkalimcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fkalimcp/lists"}