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)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/26zl/cybersec-toolkit/badge)](https://scorecard.dev/viewer/?uri=github.com/26zl/cybersec-toolkit)
[![Last commit](https://img.shields.io/github/last-commit/26zl/cybersec-toolkit)](https://github.com/26zl/cybersec-toolkit/commits/main)
[![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)
[![Glama score](https://glama.ai/mcp/servers/26zl/cybersec-toolkit/badges/score.svg)](https://glama.ai/mcp/servers/26zl/cybersec-toolkit)

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

__A security toolkit that AI agents can drive, under rules you set.__ One command installs 670+ security tools on Linux or Termux. An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server lets Claude Code, Codex, Gemini CLI, OpenCode, and other MCP clients discover, recommend, and run those tools through a governed execution path, inside a disposable Kata Containers VM by default. 872 Agent Skills supply the methodology for CTF, pentest, bug bounty, DFIR, and blue-team work.

| Component | What you get |
| --------- | ------------ |
| [Installer](#installer) | 670+ tools in 18 modules, 14 profiles, and 12 install methods for Debian/Ubuntu/Kali/Parrot, Fedora/RHEL, Arch, openSUSE, and Termux |
| [MCP server](#mcp-server) | 15 tools for discovery, advice, and governed execution; external targets and script execution are off by default |
| [Sandbox](#sandbox-and-host-mode) | One Kata Containers VM per session by default; `--local` runs the server on the host |
| [Agent Skills](#agent-skills) | 872 skills (31 project-authored, 841 curated), also installable as a Claude Code plugin |

> __What makes it different:__ most toolkits stop at _installing_ tools. Here an AI can also _drive_ them: infer the problem type, pick tools from every module and profile, and work through the problem with you step by step. When you explicitly authorize it, the same toolchain runs an autonomous solver loop. __Companion by default; autonomous only when you ask.__ It complements Kali, Parrot, or BlackArch rather than replacing them: it runs on the machine you already have, Termux included.

[Quick start](#quick-start) · [How it works](#how-it-works) · [Trust & safety](#trust--safety) · [Installer](#installer) · [MCP server](#mcp-server) · [Agent Skills](#agent-skills) · [Development](#development) · [License](#license)

## Quick start

__1. Install the tools__ on a supported Linux distro or on Termux:

```bash
git clone --depth 1 --branch v1.4.0 https://github.com/26zl/cybersec-toolkit.git && cd cybersec-toolkit
./install.sh --doctor             # read-only preflight: distro, prerequisites, MCP server, sandbox
sudo ./install.sh --profile ctf   # one profile; with no flags, all 18 modules
```

__2. Connect an AI client.__ The tracked configs for Claude Code (`.mcp.json`, also read by the GitHub Copilot CLI), Codex, Gemini CLI, and OpenCode start the server through `scripts/mcp-launch.sh`, with external targets and script execution disabled. Choose where the tools run:

| Mode | Tools run | Host needs | One-time setup |
| ---- | --------- | ---------- | -------------- |
| Sandbox (default) | In a disposable Kata VM, from the sandbox image | Linux with KVM, Docker 23+ with a Kata runtime, Node.js 22+ | `make sandbox-image`, then `npm --prefix sandbox ci --ignore-scripts` |
| Host (`--local`) | As your user, with the tools `install.sh` installed | [uv](https://docs.astral.sh/uv/) | Add `--local` to the launcher, or set `CYBERSEC_SANDBOX_MODE=local` in the client's `env` |

Kata needs KVM: on macOS, on Windows, and in VMs without nested virtualization, use host mode.

__3. Restart the client.__ The 15 tools appear (`/mcp` in Claude Code). Then ask for what you need, for example "triage this binary" or "map the attack surface of my lab at 10.10.0.0/24".

## How it works

Two entry points share one tool registry. An __operator__ runs the bash installer to put tools on disk: on the host, or into the sandbox image at build time. An __AI agent__ talks to the MCP server, which runs inside a Kata VM by default, to discover, recommend, and execute those tools through one governed path. `tools_config.json` is the single source of truth that the modules define and the MCP advisors read; 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, which runs in a Kata VM by default, to discover, recommend, and execute them. The installer and MCP server meet at the tools_config.json registry and the installed tools, with security.py governing tool execution and CI validators keeping the Python and bash sides in sync.](assets/how-it-works.png)

Solid arrows are runtime or installation actions; dashed arrows are validation and context relationships. Client configurations enter through the root-aware launcher, which boots the VM through a [Sandcastle](https://github.com/mattpocock/sandcastle) Kata provider (`sandbox/kata.mjs`) — or, with `--local`, starts the server on the host. `security.py` governs `run_tool` and `run_pipeline` through the allowlist, argument checks, and network policy without invoking a shell. `run_script` is a separate, disabled-by-default capability that runs arbitrary code. Agent Skills stay outside the execution path: `.claude/skills/` is canonical, and `scripts/sync-skills.sh` generates `.agents/skills/` for clients that read the portable mirror. Mermaid source: [`assets/how-it-works.mmd`](assets/how-it-works.mmd).

## Trust & safety

What runs, and what is gated:

- __Default-safe MCP.__ `CYBERSEC_MCP_ALLOW_EXTERNAL=0` rejects network targets that do not resolve to private or loopback ranges, and `CYBERSEC_MCP_ALLOW_SCRIPTS=0` disables `run_script`. External scopes and scripting are explicit opt-ins.
- __One gate for governed execution__ (`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 and target-injection flags), target and network policy, rate limiting, output caps, and timeouts. The policy knows enough CLI grammar to tell a target from a header, wordlist, output path, or target-list flag. Tool output reaches the model without terminal escape sequences or LLM control markers, and lines addressed to an AI reader are flagged.
- __Tools run in a disposable VM by default.__ The launcher boots a [Kata Containers](docs/SANDBOX.md) VM with its own kernel, no host filesystem beyond an optional `CYBERSEC_SANDBOX_WORKSPACE` mount, no Docker socket, a non-root user with every capability dropped, and memory, CPU, and process limits. It is destroyed when the client disconnects. Startup fails closed instead of falling back to the host; `--local` is the explicit opt-out.
- __Know the limits.__ The VM is not a network boundary: it reaches whatever its Docker network reaches, and `CYBERSEC_MCP_ALLOW_EXTERNAL` is a preflight check on resolved addresses, not a firewall (set `CYBERSEC_SANDBOX_NETWORK=none` or use a filtered network). Inside the VM, and on your host in `--local` mode, allowed tools run with the server user's permissions, and some of them spawn child processes or load plugins.
- __Tool output goes to your model provider.__ Whatever a tool prints — scan results, page content, and any credential or personal data it finds on a target — is returned to the AI client and sent to the model it uses. By default only the local audit log is redacted; set `CYBERSEC_MCP_REDACT_OUTPUT=1` to also redact credential-shaped strings from what the client receives. If an engagement's rules forbid sharing client data with a third party, drive the server from a local model (see [AI clients](docs/AI_CLIENTS.md)).
- __Repository hooks run automatically.__ Opening this repository in Claude Code runs the tracked hooks in `.claude/settings.json`: `scripts/agent-guard.sh` at session start and before each Bash command. They only emit routing context or a deny decision, make no network calls, and fail open; set `CYBERSEC_AGENT_GUARD=0` to disable them.
- __Audit trail without leaks.__ Actions are logged as JSON lines 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 stored, only their SHA256 and length, and credential-shaped strings are redacted from tool arguments. A sandboxed server mirrors its records to the same host log, and records ar