cybersec-toolkit

<!-- mcp-name: io.github.26zl/cybersec-toolkit -->
[![CI](https://github.com/26zl/cybersec-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/26zl/cybersec-toolkit/actions/workflows/ci.yml)
[![Integration](https://github.com/26zl/cybersec-toolkit/actions/workflows/integration.yml/badge.svg)](https://github.com/26zl/cybersec-toolkit/actions/workflows/integration.yml)
[![Security](https://github.com/26zl/cybersec-toolkit/actions/workflows/security.yml/badge.svg)](https://github.com/26zl/cybersec-toolkit/actions/workflows/security.yml)
[![uv update](https://github.com/26zl/cybersec-toolkit/actions/workflows/uv-update.yml/badge.svg)](https://github.com/26zl/cybersec-toolkit/actions/workflows/uv-update.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Docker image](https://img.shields.io/badge/ghcr.io-cybersec--toolkit-2496ED?logo=docker&logoColor=white)](https://github.com/26zl/cybersec-toolkit/pkgs/container/cybersec-toolkit)
![Status: Under Active Development](https://img.shields.io/badge/status-under%20active%20development-blue)

```text
    /\   /\        ______      __              _____
   (o ) ( o)      / ____/_  __/ /_  ___  _____/ ___/___  _____
    \ \_/ /      / /   / / / / __ \/ _ \/ ___/\__ \/ _ \/ ___/
  <==\   /==>   / /___/ /_/ / /_/ /  __/ /   ___/ /  __/ /__
     \ V /      \____/\__, /_.___/\___/_/   /____/\___/\___/
     /_ _\           /____/                          by 26zl
      |_|                     Toolkit
```

<p align="center"><em>&ldquo;I am a friend of virtue, not of fortune.&rdquo;</em><br>&mdash; Gjergj Kastrioti &middot; Skanderbeg (1405&ndash;1468)</p>

__Cybersecurity toolkit with built-in AI integration.__ An embedded [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server lets MCP-capable clients query the tool registry, check install status, recommend tools for a CTF category or bug-bounty target, and run installed tools through a governed execution path. Jump to [MCP Server (AI Integration)](#mcp-server-ai-integration).

Bundled with a modular installer for Linux and Termux (Android) covering __670+ tools__, __18 modules__, __14 profiles__, and __12 install methods__.

> __What makes it different:__ most toolkits stop at _installing_ tools. Here an AI can also _drive_ them — infer the problem type, pick the right tools from all modules/profiles, and work with you as an interactive companion. When you explicitly authorize it, the same MCP toolchain can enter an autonomous solver loop. __Companion by default; autonomous only when you ask.__

### Works with

| Client | Integration | Label |
| ------ | ----------- | ----- |
| Claude Code | `.mcp.json` (tracked) + `.claude/skills/` | Native configuration included |
| Claude Desktop | `claude_desktop_config.json` | Configuration example documented |
| OpenCode | `opencode.jsonc` (tracked) + `.agents/skills/` | Live tested |
| Codex | `.codex/config.toml` (tracked) | Native configuration included |
| Gemini CLI | `GEMINI.md` + `.gemini/settings.json` (tracked) | Native configuration included |
| GitHub Copilot | `.mcp.json` (CLI) + `.github/copilot-instructions.md` | CLI live tested; VS Code documented |
| Hermes Agent | User `~/.hermes/config.yaml` | Live tested |
| OpenClaw | User `~/.openclaw/openclaw.json` + `.agents/skills/` | Live tested |
| Cursor / Cline / Goose | Client MCP settings + Agent Skills | Compatible through MCP; skills supported |
| Continue | Client MCP settings; rules/prompts for context | Compatible through MCP |
| LM Studio (>=0.3.17) | `mcp.json`; manual or MCP-provided context | Compatible through MCP |
| Ollama | MCP host in front of it | Compatible through an MCP host |
| Aider | — | Not applicable |
| Open WebUI | MCP-to-OpenAPI bridge | Compatible through MCP host or bridge |

See [`docs/AI_CLIENTS.md`](docs/AI_CLIENTS.md) for detailed configuration per client, and [`docs/ORCHESTRATION.md`](docs/ORCHESTRATION.md) for coordinating multiple agents across any MCP client.

---

## How it works

Two entry points share one tool registry. An __operator__ runs the bash installer to put tools on disk; an __AI agent__ talks to the MCP server to discover, recommend, and execute those same tools through its governed tool path. `tools_config.json` is the single source of truth the modules define and the MCP advisors read, and CI validators keep the Python and bash sides in sync.

<!-- Rendered from assets/how-it-works.mmd so it displays consistently everywhere.
     Re-render with:
     npm_config_cache=/tmp/cybersec-npm-cache npx --yes \
       --package @mermaid-js/mermaid-cli@11.16.0 mmdc \
       -i assets/how-it-works.mmd -o assets/how-it-works.png -t dark -b "#0d1117" -s 3 -->
![How it works: an operator runs the bash installer to put tools on disk; an AI agent drives the MCP server to discover, recommend, and execute them. The installer and MCP server meet at the tools_config.json registry and the installed tools on disk, with security.py governing tool execution and CI validators keeping the Python and bash sides in sync.](assets/how-it-works.png)

Mermaid source: [`assets/how-it-works.mmd`](assets/how-it-works.mmd).

__Reading the diagram:__ solid arrows are runtime or installation actions; dashed arrows are validation and context relationships. Client configurations enter through the root-aware launcher before reaching FastMCP. `security.py` governs `run_tool` and `run_pipeline` through the allowlist, argument checks, and network policy without invoking a shell. `run_script` remains a separate, disabled-by-default full-code-execution capability. Agent Skills stay outside the execution path: `.claude/skills/` is canonical and `scripts/sync-skills.sh` produces `.agents/skills/` for clients that use the portable mirror.

---

## Why not just Kali (or another installer)?

Kali/Parrot/BlackArch ship the tools; this is __complementary, not a replacement__. It runs on the box you already have (incl. Termux) and adds an __AI control plane__ that can discover, recommend, chain, and execute installed tools through one governed interface. Want all the tools? A distro is fine. Want an MCP client that can select and run them under explicit policy? That's the gap.

## Trust & safety

Security users should be paranoid — here's exactly what runs and what's gated:

- __Default-safe MCP.__ Out of the box `CYBERSEC_MCP_ALLOW_EXTERNAL=0` rejects network targets that do not resolve to private/loopback ranges, and `CYBERSEC_MCP_ALLOW_SCRIPTS=0` disables `run_script`. You opt into external scopes / scripting explicitly.
- __Governed tool execution passes one gate__ (`mcp_server/security.py`): registry allowlist, no shell (`create_subprocess_exec`, never `shell=True`), argument sanitization, a per-tool blocked-flag denylist (e.g. `sqlmap --os-shell`, `nmap -iL`, file-list/target-injection flags), target/network policy, rate limiting, output caps, and timeouts.
- __The execution policy is not an OS sandbox.__ Allowed tools run with the MCP process user's permissions, and some security tools can launch child processes or load plugins. Disabling `run_script` only disables that endpoint; run the MCP server as a least-privileged user or inside an isolation boundary appropriate for untrusted targets.
- __Tool-aware policy is not solver hardcoding.__ The solver chooses tools from the registry/advisors; the policy layer only understands enough CLI grammar to tell a real target from a header, wordlist, output path, config file, or target-list flag. That keeps normal commands usable without letting file-list/config flags bypass scope checks.
- __Audit trail, not leaks.__ Actions are logged as JSON to an owner-only (`0600`) rotating log under the user's state directory (`~/.local/state/cybersec-tools-mcp/audit.log` by default). Script bodies are never persisted — only an irreversible SHA256 + length is logged for correlation — and credential-shaped strings are redacted from tool arguments.
- __Least privilege in the installer.__ It runs as root but drops to the invoking user (`$SUDO_USER`) for cloned-repo builds and `pip`/`cargo`/`gem` installs; binary releases are SHA256-verified when checksums are published.
- __Dual-use tooling is gated.__ C2 and phishing frameworks (Sliver, Caldera, gophish, evilginx, …) are __off by default__ and install only with `--include-c2` (the `redteam`/`full` profiles); the MCP layer reflects this and never auto-runs them.
- __Authorized use only.__ See [`SECURITY.md`](SECURITY.md), the [Supply Chain Model](#supply-chain-model), and the [Disclaimer](#disclaimer).

---

## Install

All required runtimes (Python, Go, Ruby, Java, Rust, Node.js), dev libraries, pipx, and build tools are installed automatically. The only prerequisite is a supported Linux distro. Windows and macOS are not supported (use WSL or Docker).

> __Docker__ is the one exception — install it manually if you want C2 frameworks, MobSF, BeEF, BloodHound, TheHive, or Cortex (`--enable-docker`). See [Docker install docs](https://docs.docker.com/engine/install/).
> __GitHub authentication__ is recommended. The installer downloads ~30 binary releases and makes ~30+ API calls to GitHub. Without auth, you're limited to __60 requests/hour__ and some downloads may fail. With auth, the limit is __5,000/hour__. The easiest way:
>
> ```bash
> # Install gh CLI and log in (one-time) — the installer auto-detects it
> sudo apt install gh && gh auth login
> ```
>
> Alternatively, export a [personal access token](https://github.com/settings/tokens) (no scopes needed):
>
> ```bash
> export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
> ```

__From the latest release__ (pinned and stable — recommended):

```bash
# Newest tag is on the Releases page: https://github.com/26zl/cybersec-toolkit/releases
git clone --depth 1 --branch v1.1.0 https://github.com/26zl/cybersec-toolkit.git && cd cybersec-toolkit && sudo ./install.sh
```

__From `main`__ (newest tools, fixes, and changes; may include unreleased work