kmcp 0.1.5.dev0__tar.gz

kmcp-0.1.5.dev0/.env.example

@@ -0,0 +1,29 @@
+# Kali MCP Server Configuration
+MCP_HOST=0.0.0.0
+MCP_PORT=8399
+MCP_SERVER_NAME=kali-mcp
+MCP_SERVER_VERSION=1.0.0
+MCP_DEFAULT_TIMEOUT=300
+MCP_MAX_TIMEOUT=3600
+MCP_MAX_CONCURRENT=10
+MCP_LOG_DIR=logs
+MCP_ARTIFACT_DIR=artifacts
+MCP_ENCODING=utf-8
+MCP_DEBUG=false
+MCP_TRANSPORT=sse
+
+# Authentication (set in production)
+MCP_API_TOKEN=
+
+# CORS (comma-separated origins, default: * = all origins)
+MCP_ALLOWED_ORIGINS=*
+
+# Rate limiting (requests per minute per IP, 0 = unlimited)
+MCP_RATE_LIMIT=0
+
+# Path containment (comma-separated allowed directories, empty = unrestricted)
+MCP_ALLOWED_WRITE_DIRS=
+MCP_ALLOWED_READ_DIRS=
+
+# GitHub token for zizmor (GitHub Actions scanner)
+GH_TOKEN=

kmcp-0.1.5.dev0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      # Fire the release on both conventions: `v0.5.0` and `0.5.0`.
+      - "v*"
+      - "[0-9]*"
+
+permissions:
+  contents: read
+  id-token: write # trusted publishing (OIDC) — no PyPI token secret required
+
+jobs:
+  test:
+    name: Test (unit + integration)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-asyncio ruff
+
+      - name: Run unit tests
+        run: python -m pytest tests/unit
+
+      - name: Run integration tests
+        run: python -m pytest tests/integration
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+  build-and-publish:
+    name: Build and publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      # Full history so setuptools-scm (if enabled later) can resolve versions.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      # Trusted Publishing: authenticates via OIDC against the Trusted
+      # Publisher configured on pypi.org for this repository
+      # (owner magichrist, repo kali-mcp, workflow release.yml).
+      # Do NOT add a username/password here — the action would fall back
+      # to token auth and fail.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-github-release:
+    name: Create GitHub release
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the GitHub release
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          generate_release_notes: true

kmcp-0.1.5.dev0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.env
+logs/
+artifacts/
+data/
+.venv
+.venv/

kmcp-0.1.5.dev0/Justfile

@@ -0,0 +1,108 @@
+# Kali MCP Server — Just Commands
+set dotenv-load
+
+# Show available commands
+default:
+    @just --list
+
+# Install dependencies (editable install of the kali_mcp package + deps)
+install:
+    pip install -e .
+
+# Start the server (foreground)
+start:
+    python -m kali_mcp
+
+# Start in debug mode
+debug:
+    MCP_DEBUG=true python -m kali_mcp
+
+# Run the full pytest suite (unit + integration)
+test:
+    .venv/bin/python -m pytest
+
+# Run only fast unit tests
+test-unit:
+    .venv/bin/python -m pytest tests/unit
+
+# Run integration tests (uses local subprocesses; no external binaries needed except coreutils)
+test-integration:
+    .venv/bin/python -m pytest tests/integration
+
+# Run end-to-end protocol tests (spawns a real server)
+test-e2e:
+    .venv/bin/python -m pytest tests/e2e -m e2e
+
+# Show server health (requires running server)
+health:
+    @curl -sf http://127.0.0.1:8399/sse -o /dev/null && echo "Server running" || echo "Server not running"
+
+# View logs
+logs:
+    tail -f logs/server.log
+
+# View execution logs
+exec-logs:
+    tail -f logs/executions.jsonl
+
+# Clean build artifacts
+clean:
+    rm -rf logs/*.log logs/*.jsonl
+    rm -rf artifacts/*
+    find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# Purge stored data: just purge db | just purge vault | just purge all
+purge scope="all":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -z "${CONFIRM:-}" ]; then
+        read -r -p "Purge '{{scope}}' data — this cannot be undone. Continue? [y/N] " c
+        [[ "$c" =~ ^[Yy]$ ]] || { echo "aborted"; exit 1; }
+    fi
+    case "{{scope}}" in
+      db)
+        rm -fv data/kali-mcp.sqlite data/kali-mcp.sqlite-wal data/kali-mcp.sqlite-shm
+        ;;
+      vault)
+        rm -rf artifacts/vault
+        ;;
+      all)
+        rm -fv data/kali-mcp.sqlite data/kali-mcp.sqlite-wal data/kali-mcp.sqlite-shm
+        rm -rf artifacts/vault
+        ;;
+      *)
+        echo "unknown scope '{{scope}}' — use: db | vault | all" >&2
+        exit 1
+        ;;
+    esac
+    echo "purged: {{scope}}"
+    echo "note: if the server is running, restart it (or just deploy) so it reconnects cleanly."
+
+# Show all registered tools
+tools:
+    python -c "from kali_mcp.tools import ALL_TOOLS; [print(f'  {t.name:20s} {t.description[:60]}') for t in ALL_TOOLS]"
+
+# Deploy to the Kali VM and restart the server (requires ssh key auth)
+deploy host="kali-linux.shared" dest="~/kali-mcp":
+    rsync -av --exclude '.venv' --exclude '__pycache__' --exclude '.git' \
+        --exclude 'logs' --exclude 'artifacts' --exclude 'data' \
+        ./ {{host}}:{{dest}}/
+    ssh {{host}} "pkill -f '[k]ali_mcp' || true; cd {{dest}} && \
+        nohup python -m kali_mcp > logs/stdout.log 2>&1 & sleep 2; \
+        curl -sf --max-time 5 http://127.0.0.1:8399/sse -o /dev/null \
+        && echo 'server restarted OK' || echo 'server did not come up — check logs/stdout.log'"
+
+# Commit all changes, tag with version, and push — triggers PyPI release
+release version="0.0.0":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ "{{version}}" = "0.0.0" ]; then
+        echo "Usage: just release version=0.1.3" >&2
+        exit 1
+    fi
+    git add -A
+    git commit -m "chore: release v{{version}}" || echo "nothing to commit"
+    git tag -f "v{{version}}"
+    git push origin master
+    git push origin "v{{version}}" --force
+    echo "Released v{{version}} — GitHub Actions will build and publish to PyPI"

kmcp-0.1.5.dev0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: kmcp
+Version: 0.1.5.dev0
+Summary: MCP server exposing Kali Linux penetration-testing tools to AI agents
+Author: kali-mcp
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<2,>=1.26.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: fastmcp
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Requires-Dist: httpx
+
+# ✦ kali-mcp
+
+*A warm, expressive MCP server that puts 56 Kali Linux pentesting tools at your AI agent's fingertips — soft voltage around sharp security tooling.*
+
+The Kali MCP Server is a production-grade Model Context Protocol (MCP) server that exposes Kali Linux penetration-testing tools (nmap, sqlmap, nuclei, hydra, metasploit, and 50 more) to AI agents. Every tool call is validated, every execution is sandboxed with timeouts, and every result can be shared between agents through a built-in inter-agent vault.
+
+## ✧ At a glance
+
+| | |
+|---|---|
+| **Transport** | HTTP/SSE or streamable-http on `:8399/mcp` |
+| **Tools** | 56 native Kali wrappers + `generic_command` escape hatch |
+| **Persistence** | SQLite (targets, scans, findings, credentials) + inter-agent vault |
+| **Orchestration** | Playbooks (recon / webapp / AD / custom engine) with `{{target}}` substitution and resume |
+| **Parallelism** | `parallel_execute` with deduplicated aggregate results |
+| **Monitoring** | Live CLI/TUI with SSE push, job kill, force cleanup |
+| **Safety** | 3-layer timeout defense, process-tree cleanup, semaphore limits, output truncation |
+
+## ♡ Get started
+
+### Requirements
+
+- Python 3.10+
+- A host with the Kali tools you want to run installed (the server wraps binaries; it doesn't install them)
+- `pip`
+
+### Install
+
+```bash
+pip install kmcp
+```
+
+### Start the server
+
+Use the `kmcp` CLI:
+
+```bash
+kmcp start
+
+# With custom host/port
+kmcp start --host 127.0.0.1 --port 9000
+
+# Aliases: s, monitor (m), purge (p)
+kmcp s
+```
+
+The server listens on `http://0.0.0.0:8399/mcp` by default. Point your MCP client at that URL.
+
+### Debug mode
+
+```bash
+MCP_DEBUG=true kmcp start
+```
+
+### Configuration
+
+Copy `.env.example` to `.env` and adjust:
+
+| Variable | Default | What it does |
+|---|---|---|
+| `MCP_HOST` | `0.0.0.0` | Listen address |
+| `MCP_PORT` | `8399` | Listen port |
+| `MCP_TRANSPORT` | `sse` | `sse` or `streamable-http` |
+| `MCP_API_TOKEN` | *(empty)* | Bearer token for HTTP auth |
+| `MCP_DEFAULT_TIMEOUT` | `300` | Default command timeout (seconds) |
+| `MCP_MAX_TIMEOUT` | `3600` | Maximum allowed timeout |
+| `MCP_MAX_CONCURRENT` | `10` | Max concurrent tool executions |
+| `MCP_DB_ENABLED` | `true` | Write executions to SQLite |
+| `MCP_DEBUG` | `false` | Verbose structured logging |
+
+## ✦ Features
+
+**56 Kali tools, natively wrapped.** Nmap, sqlmap, nuclei, ffuf, katana, subfinder, amass, hydra, metasploit, bettercap, responder, zap, wpscan, and more. Each tool validates its arguments against a JSON schema, builds a safe subprocess argument list (no shell injection for native tools), and returns structured JSON with stdout, stderr, exit code, and timing.
+
+**`generic_command`** — the escape hatch. Run any shell command or pipeline not covered by a native wrapper. Full bash scripting supported (pipes, redirects, here-docs).
+
+**`python_command`** — execute Python scripts directly on the host. Full access to installed libraries (scapy, impacket, requests, etc.).
+
+**Playbooks** — multi-step pipelines with `{{target}}` substitution and resume support:
+- `playbook_recon` — subfinder → httpx → masscan → whatweb+nmap → nuclei
+- `playbook_webapp` — katana → arjun+ffuf → nuclei → sqlmap+commix
+- `playbook_ad` — enum4linux → bloodhound → netexec+crackmapexec
+- `playbook_engine` — run a custom playbook definition
+
+**`parallel_execute`** — fan out to multiple tools concurrently, then aggregate and deduplicate open ports, vulnerabilities, and credentials.
+
+**Inter-agent vault** — SQLite-backed knowledge store (`artifacts/vault/vault.sqlite` + JSON mirrors). Any agent can write findings, credentials, or notes; any other agent can query them back by category, target, tool, or free-text search. Every tool run is automatically deposited.
+
+**Live monitor TUI** — `kmcp monitor` launches a pastel cyber dashboard showing connected users, running jobs, and server health with SSE push updates. Kill stuck jobs or force cleanup from the dashboard. Press `q` to quit; the screen clears on exit.
+
+**MCP resources & prompts** — `kali://config`, `kali://tools`, `kali://health`, `kali://vault/index`, plus guided workflow prompts (recon, webapp, AD, OSINT, quick scan, report).
+
+## ⟡ How it works
+
+Every tool call follows the same path:
+
+1. **Validate** — arguments checked against the tool's JSON schema (required fields, IP/CIDR/domain/URL/timeout formats, enums).
+2. **Build command** — arguments converted to a safe subprocess argument list. No shell interpolation for native tools; `generic_command` is the only shell path.
+3. **Execute** — subprocess runs in its own process group with a 3-layer timeout defense:
+   - `asyncio.wait_for` enforced timeout
+   - Watchdog thread kills stuck executions
+   - Semaphore limits concurrent executions (`MCP_MAX_CONCURRENT`, default 10)
+4. **Persist** — run recorded to SQLite (`targets`, `scans`, `findings`, `credentials`) and deposited to the vault.
+5. **Respond** — structured JSON with stdout, stderr, exit_code, timing, and success flag.
+
+**Session tracking** — the monitor tracks connected MCP client sessions (connect time, last activity, client info) so you can see who's using the server.
+
+## ☾ Configuration
+
+Configuration is loaded from environment variables via `.env`. All values have safe defaults.
+
+| Variable | Default | Description |
+|---|---|---|
+| `MCP_HOST` | `0.0.0.0` | Listen address |
+| `MCP_PORT` | `8399` | Listen port |
+| `MCP_SERVER_NAME` | `kali-mcp` | Server name advertised to MCP clients |
+| `MCP_SERVER_VERSION` | `1.0.0` | Server version |
+| `MCP_TRANSPORT` | `sse` | `sse` or `streamable-http` |
+| `MCP_API_TOKEN` | *(empty)* | Bearer token; when set, all HTTP routes require `Authorization: Bearer <token>` |
+| `MCP_DEFAULT_TIMEOUT` | `300` | Default command timeout (seconds) |
+| `MCP_MAX_TIMEOUT` | `3600` | Hard cap on tool timeout |
+| `MCP_MAX_CONCURRENT` | `10` | Semaphore limit for concurrent executions |
+| `MCP_LOG_DIR` | `logs` | Structured log directory |
+| `MCP_ARTIFACT_DIR` | `artifacts` | Artifact and vault directory |
+| `MCP_DEBUG` | `false` | Verbose debug logging |
+| `MCP_ENCODING` | `utf-8` | Default text encoding |
+| `MCP_RATE_LIMIT` | `0` | Rate limit per minute (0 = unlimited) |
+| `MCP_VAULT_MAX_ROW_BYTES` | `26214400` | Max vault row size (25 MB; 0 = unlimited) |
+| `MCP_DB_PATH` | `data/kali-mcp.sqlite` | SQLite database path |
+| `MCP_DB_ENABLED` | `true` | Write executions to SQLite |
+
+## ◈ Architecture
+
+```
+MCP Client (AI agent)
+        │ HTTP/SSE
+        ▼
+┌─────────────────────────────────────────┐
+│         Kali MCP Server (:8399)         │
+│                                         │
+│  ┌─────────────┐  ┌─────────────────┐   │
+│  │ Token Auth  │  │ CORS Middleware │   │
+│  │  (optional) │  │                 │   │
+│  └─────────────┘  └─────────────────┘   │
+│         │              │                │
+│         ▼              ▼                │
+│   FastMCP tool dispatch layer           │
+│         │              │                │
+│   ┌─────────────────────────────┐       │
+│   │  Tool registry (56 tools)   │       │
+│   └─────────────────────────────┘       │
+│         │              │                │
+│   ┌─────────────────────────────┐       │
+│   │     Execution engine        │       │
+│   │  (3-layer timeout, semaphore, │   │
+│   │   process-tree cleanup)     │       │
+│   └─────────────────────────────┘       │
+│         │              │                │
+│   ┌─────────────────────────────┐       │
+│   │   SQLite DB + Vault store   │       │
+│   └─────────────────────────────┘       │
+│         │              │                │
+│   ┌─────────────────────────────┐       │
+│   │   Monitor SSE stream        │       │
+│   └─────────────────────────────┘       │
+└─────────────────────────────────────────┘
+        │              │
+        ▼              ▼
+  Kali Linux      Monitor TUI
+  subprocesses    (kmcp monitor)
+```
+
+**Package layout (`src/kali_mcp/`):**
+
+- `server.py` — MCP server, tool dispatch, health monitor, REST routes
+- `execution.py` — hardened execution engine (timeout, watchdog, semaphore)
+- `security.py` — allowlist, input validation, shell-injection prevention
+- `config.py` — env-based configuration
+- `models.py` — `ExecutionResult`, `ToolError` dataclasses
+- `responses.py` — standardized MCP response builders
+- `registry.py` — tool registration and lookup
+- `logging_utils.py` — structured JSON logging
+- `notifications.py` — MCP server→client notification helpers
+- `prompts.py` — MCP prompt templates
+- `resources.py` — MCP resources (`kali://*`)
+- `db/manager.py` — SQLite persistence
+- `utils/process.py` — process tree cleanup
+- `utils/vault.py` — SQLite-backed inter-agent vault
+- `tools/` — 56 tool wrappers + base class + parsers + playbooks
+
+## 🧪 Tests & checks
+
+```bash
+# Full suite (unit + integration + e2e)
+just test
+
+# Fast unit tests only
+just test-unit
+
+# Integration tests (async engine + tool execution)
+just test-integration
+
+# End-to-end (spawns a real server, speaks MCP over HTTP)
+just test-e2e
+```
+
+The suite runs on `pytest` with `pytest-asyncio`. 803 tests pass, 11 skipped (conditional/environment-dependent). Coverage is approximately 84% across the package.
+
+Quality checks:
+- `ruff` — linting (line-length 100)
+
+## ⚠ Known limitations
+
+- **Kali tools must be installed on the host.** The server wraps binaries like `nmap`, `sqlmap`, `hydra`; it does not install them. If a binary isn't in `PATH`, the tool returns a structured "Binary not found" error with an install hint.
+- **`generic_command` runs arbitrary shell.** It's the escape hatch — use it deliberately. It is subject to the same timeout and semaphore limits as native tools.
+- **In-memory monitor state.** The live monitor (sessions, active jobs) lives in memory and resets on server restart. Persisted data (SQLite, vault) survives restarts.
+- **No alerting yet.** The monitor displays status but does not send alerts for stuck executions or high error rates.
+- **Output truncation.** stdout/stderr are capped at 100 KB per stream to prevent memory exhaustion.
+
+## ◈ Troubleshooting
+
+| Symptom | Likely cause | Next step |
+|---|---|---|
+| Server won't start | Port 8399 in use | Set `MCP_PORT` to a free port |
+| Tool returns "Binary not found" | Kali tool not installed or not in `PATH` | Install the tool or add it to `PATH` |
+| `401 Unauthorized` | `MCP_API_TOKEN` set but no/invalid token | Provide `Authorization: Bearer <token>` or `?token=` query param |
+| Monitor TUI shows no jobs | No executions currently running | Run a tool first; jobs appear while active |
+| `q` doesn't quit TUI | Terminal rendering glitch | Press `q` again; if stuck, `Ctrl+C` |
+
+## License
+
+MIT
+
+---
+
+*Built with soft voltage — sharp security tooling wrapped in a warm, expressive MCP server.*