Codex Kali MCP Server

Kali安全MCP服务器

容器化模型上下文协议（MCP）服务器，封装了一组精心策划的Kali Linux实用程序，因此可以从Codex或任何兼容MCP的客户端调用它们。

先决条件

• Docker引擎可以访问守护进程套接字（安装程序挂载 /var/run/docker.sock).
• 支持MCP的Codex CLI(codex mcp list 应该工作）。
• 位于的本地MCP配置文件夹 ~/.docker/mcp/ （第一次跑步时自动创建 docker mcp 命令）。

1.拉取（或构建）Kali MCP映像

已发布的容器可以在GitHub容器注册表中找到：

docker pull ghcr.io/h47r15/kali-mcp-server:latest

致力于地方变革？使用相同的标签重建图像，以便您的目录 不断指向 ghcr.io/h47r15/kali-mcp-server:latest: ``bash docker build -t ghcr.io/h47r15/kali-mcp-server:latest . ``

2.创建自定义目录条目

编辑 ~/.docker/mcp/catalogs/custom.yaml （如果文件不存在，则创建该文件）并添加Kali服务器块：

version: 2
name: cbyte-mcp
displayName: Cbyte MCP Servers
registry:
  kali:
    description: "Helper utilities for Kali-based security workflows (tool lookups, CVE summaries)."
    title: "Kali Security"
    type: server
    dateAdded: "2025-01-24T00:00:00Z"
    image: ghcr.io/h47r15/kali-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: 
    tools:
      - name: list_categories
      - name: list_tools
      - name: describe_tool
      - name: tool_details
      - name: search_tools
      - name: suggest_tools
      - name: latest_cves
      - name: run_kali_tool
      - name: run_kali_tool_stream
      - name: export_run_history
    env:
      - name: KALI_TOOL_DATA
        example: /mnt/datasets/custom_kali_tools.json
      - name: KALI_POLICY_FILE
        example: /mnt/config/policy.yaml
      - name: KALI_TARGET_WHITELIST
        example: "192.168.1.,10.0."
      - name: KALI_MAX_CONCURRENT_RUNS
        example: "2"
      - name: KALI_DEFAULT_TIMEOUT
        example: "60"
      - name: KALI_EXTRA_PATHS
        example: /opt/security/bin
    metadata:
      category: monitoring
      tags:
        - security
        - pentesting
        - vulnerability
        - scanning
        - kali
      license: MIT
      owner: local

3.在Docker MCP上注册目录

确保全局注册表知道新的 kali 通过更新进入 ~/.docker/mcp/registry.yaml:

registry:
  docker:
    ref: ""
  mcp-discord:
    ref: ""
  redis:
    ref: ""
  kali:
    ref: ""

如果文件已经存在，只需添加 kali 块下 registry.

4.（可选）提供秘密

设置环境变量（例如通过Docker secrets或shell 配置文件），然后启动网关。最低配置 KALI_TARGET_WHITELIST 使用CIDR前缀，您有权进行扫描。

5.在Codex注册网关

使用Codex运行官方Docker MCP网关容器，挂载您刚才编辑的目录和注册表：

codex mcp add MCP_DOCKER_TOOL -- docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /Users/cbyte/.docker/mcp:/mcp \
  docker/mcp-gateway \
  --catalog=/mcp/catalogs/docker-mcp.yaml \
  --catalog=/mcp/catalogs/custom.yaml \
  --config=/mcp/config.yaml \
  --registry=/mcp/registry.yaml \
  --tools-config=/mcp/tools.yaml \
  --transport=stdio

替换 /Users/cbyte/.docker/mcp 如果不同，请使用您的实际MCP配置目录。

6.验证服务器

列出MCP服务器并确认 kali 出现：

codex mcp list

您还可以直接使用MCP检查器来操作服务器：

npx @modelcontextprotocol/inspector docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /Users/cbyte/.docker/mcp:/mcp \
  docker/mcp-gateway \
  --catalog=/mcp/catalogs/custom.yaml \
  --registry=/mcp/registry.yaml \
  --transport=stdio

快速本地试运行

直接运行已发布的容器，挂载本地数据集/策略覆盖：

docker run --rm -it \
  -v "$PWD/data:/app/data" \
  -v "$PWD/config:/app/config" \
  -e KALI_TOOL_DATA=/app/data/kali_tools.json \
  -e KALI_POLICY_FILE=/app/config/policy.yaml \
  -e KALI_TARGET_WHITELIST="192.168.1.,10.0." \
  ghcr.io/h47r15/kali-mcp-server:latest \
  kali-mcp-server

打包资产 src/kali_mcp_server/assets/ 如果满足以下条件，则已提供默认值 您忽略了覆盖；仅挂载您想要自定义的文件。

地方发展与诗歌

• 安装依赖项： poetry install
• 在本地启动MCP服务器： poetry run python kali_server.py
• Docker构建的导出要求： poetry export --without-hashes -f requirements.txt -o requirements.txt

Docker镜像消耗 requirements.txt，因此，每当您通过Poetry添加或升级依赖项时，请重新运行导出。

可用工具

• list_categories –枚举来自生成数据集的类别。
• list_tools –显示类别（包、摘要、二进制路径）中的每个工具。
• describe_tool / tool_details –返回特定工具的丰富元数据。
• search_tools –按关键字在名称、摘要、包或类别之间进行模糊匹配。
• suggest_tools –自由形式任务描述的有主见的助手（关键字包装器）。
• latest_cves –从NVD API获取最新匹配的CVE。
• run_kali_tool –从容器内执行任何允许列出的Kali二进制文件，并返回stdout/stderr。
• run_kali_tool_stream –为长时间运行的命令实时流式传输stdout/stderr。
• export_run_history –检索最近的调用日志以进行审核。

工具数据集工作流程

• 权威数据集位于 data/kali_tools.json （可选CSV镜像位于 data/kali_tools.csv).
• 使用以下命令重新生成数据集 真实的 卡利环境：

1. 塑造形象(docker build -t ghcr.io/h47r15/kali-mcp-server:latest .). 1. 启动交互式容器： docker run --rm -it -v "$PWD/data:/app/data" ghcr.io/h47r15/kali-mcp-server:latest bash. 1. 集装箱内部运行 python scripts/sync_tools.py --csv-output data/kali_tools.csv. 1. 提交生成的JSON/CSV，README覆盖块将自动保持同步。

• 对于没有Docker支持的本地实验，请使用回退数据集(python scripts/sync_tools.py --fallback-only).
• 集 KALI_TOOL_DATA=/absolute/path/to/custom.json 在不重建图像的情况下将服务器指向备用数据集。
• 通过以下方式管理执行护栏 config/policy.yaml （允许的标志、超时、目标白名单）。在运行时使用覆盖 KALI_POLICY_FILE, KALI_MAX_CONCURRENT_RUNS, KALI_DEFAULT_TIMEOUT, KALI_TARGET_WHITELIST，以及 KALI_EXTRA_PATHS （将自定义二进制文件添加到 PATH).
• 要限制资源使用，请设置 resource_limits 在 config/policy.yaml （全局默认值或每个工具的覆盖）。支持的密钥有 cpu_time_limit （CPU时间秒）和 memory_limit_mb （MiB中的地址空间）。
• Meta包是在Docker构建过程中偶然安装的。如果 kali-tools-* 元包不适用于当前架构（例如，某些集合仅支持x86_64），它会自动跳过，不会出现在生成的数据集中。

发布工作流程

语义发布使用常规提交自动化版本控制和变更日志更新。

• 安装依赖项一次： npm install （建议使用Node.js 18+）。
• 本地试运行： npx semantic-release --no-ci --dry-run.
• 真正的发布（通常在CI中执行）： npx semantic-release.

配置位于 .releaserc.json，并生成了钞票 CHANGELOG.md.

测试

• 安装开发依赖项： poetry install --with dev （或 pip install -r requirements.txt && pip install -r dev-requirements.txt 如果你更喜欢pip）。
• 运行单元测试： pytest。该套件包括通过以下方式模拟的NVD响应 pytest-httpx 以及政策执行检查。
• 集成测试（可选）：通过设置构建和练习Docker镜像 KALI_INTEGRATION=1 poetry run pytest tests/integration/test_run_tool_container.py。要重用预构建的映像，请设置 KALI_TEST_IMAGE=；否则，测试将在本地构建一个（可能需要几分钟）。
• 浏览以下使用片段 examples/ 用于在本地测试MCP表面时快速使用Python和CLI帮助程序。

Docker MCP注册表准备

计划将此服务器上游到Docker的MCP注册表？从下面的模板开始 docker/ 并遵循 docs/docker-mcp-registry.md, docs/catalog.md，以及中的检查表 docs/registry-checklist.md 用于端到端工作流（任务CLI命令、目录导入和PR检查表）。

出版前：

• 使用以下命令刷新容器内的数据集 python scripts/sync_tools.py --csv-output data/kali_tools.csv.
• 跑 python scripts/validate_registry_manifest.py 确保 docker/server.yaml 和 docker/tools.json 与代码库保持同步。

Kali工具数据集摘要 --生成于2025-09-1706:37 UTC 跟踪的二进制文件总数：15