Kali Factory 使用说明

为需要访问 Kali Linux OSINT 工具的 AI 代理提供更安全的主机本地控制平面。

此包采用了与 GPU Factory 相同的架构——类型化作业提交（带持有者令牌认证）、排队工作进程执行、允许列表 Docker 镜像运行——但应用于不同的问题：在不向代理提供未经身份验证的 shell 的情况下，分发对 Kali 侦察和流量分析工具的访问权限。

• FastAPI 控制 API

• Redis 队列

• RQ 工作进程

• 针对加固 Kali 镜像的 Docker 优先容器执行

• 类型化作业（osint、流量捕获、JS 分析、泄露查找），而非原始 shell

• 持有者令牌认证

• 适用于支持 MCP 的代理的本地 MCP 服务器

• 可选的 ChromaDB 边车，用于在多次运行中保留侦察结果

为什么存在此项目

Kali 附带了数百种工具，其中许多对于合法的竞争情报和安全研究非常有用，但有些工具不适合代理驱动的自动化。天真的做法——将代理放入 Kali shell 并让它自行处理——会产生三个问题：

1. 代理可以访问所有工具，包括不应在自动化上下文中访问的利用框架（metasploit、sqlmap、hashcat、john、aircrack-ng、exploitdb）。

2. 工具调用是无结构的 shell 字符串，这既容易产生参数注入错误，也无法进行清晰的审计。

3. 对代理的操作没有速率限制、时间限制或输出预算——单个行为不端的代理可能会攻击目标或填满磁盘。

此包通过公开一个类型化作业 API 解决了所有这三个问题：每个可调用工具都在清单中声明，每个参数都由 Pydantic 验证，每个容器运行都通过镜像前缀进行允许列表限制，并且每次调用都需要持有者令牌。

核心安全属性

• 无 shell=True

• 无通用的“运行任何命令”端点

• 作业通过显式模式进行验证

• 容器执行通过镜像前缀进行允许列表限制

• 容器内的工具执行通过二进制名称进行允许列表限制

• API 需要持有者令牌

• 工作进程和 API 是独立的进程

• 利用/凭据破解/无线工具在镜像构建时被显式清除

• 对每个接触网络的工具进行出口日志记录

作业类型

• kali_probe

  • 验证 Kali 容器是否可达且工具允许列表完整

• osint_run

  • 使用结构化参数执行允许列表中的类型化 OSINT 工具（amass、whatweb、gobuster、dnsenum 等）

• traffic_capture

  • 在有限时间内运行 mitmdump，返回捕获文件

• js_analysis

  • 针对 JavaScript URL 运行 linkfinder / secretfinder / arjun

• leak_scan

  • 针对 GitHub 组织/仓库运行 trufflehog 以查找已提交的凭据

• subdomain_enum

  • 针对目标域运行 amass enum（仅限被动源）

• web_fingerprint

  • 运行 whatweb 以识别目标的技术栈

• nuclei_exposures

  • 仅针对目标运行 nuclei，并使用 exposures/ 模板子集

  • cves/、vulnerabilities/、default-logins/、fuzzing/ 模板目录被显式阻止

快速入门

1. 复制环境变量：

cp .env.example .env
./scripts/bootstrap-secrets.sh

2. API 令牌存储在：

.secrets/api_token

且 .env 通过 KALI_FACTORY_API_TOKEN_FILE 指向它。

3. 启动 Redis：

docker compose up -d redis

4. 构建 Kali 运行时镜像：

docker build -t kali-factory/recon:latest runtimes/kali/

5. 创建 Python 环境：

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

6. 运行 API：

./scripts/start-api.sh

7. 运行工作进程：

./scripts/start-worker.sh

8. 运行 MCP 服务器：

./scripts/start-mcp.sh

示例请求

健康检查：

curl http://localhost:8081/health

Kali 探测：

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"kali_probe"}'

子域枚举：

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"subdomain_enum",
    "domain":"example.com",
    "max_runtime_sec": 300
  }'

Web 指纹识别：

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"web_fingerprint",
    "url":"https://example.com"
  }'

GitHub 泄露扫描：

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"leak_scan",
    "github_org":"example-org"
  }'

文件

• START_HERE_FOR_AGENTS.md — 使用此控制平面的代理的单入口指南

• runtimes/kali/Dockerfile — 安装了允许列表工具的 Kali 容器镜像

• runtimes/kali/tools.json — 声明式工具清单（允许列表 + 参数模板）

• scripts/bootstrap-secrets.sh — 创建并锁定 API 令牌文件的权限

• scripts/start-api.sh — API 的启动包装器

• scripts/start-worker.sh — 工作进程的启动包装器

• scripts/start-mcp.sh — 本地 MCP 服务器的启动包装器

• scripts/install-user-services.sh — 安装用户级 systemd 单元

• src/kali_factory/api/ — API 服务器 (FastAPI)

• src/kali_factory/worker/ — 基于 RQ 的作业执行

• src/kali_factory/models/ — Pydantic 作业模式

• src/kali_factory/jobs/ — 每个作业类型的处理程序

• src/kali_factory/policy/ — 认证、允许列表强制执行、速率限制

• src/kali_factory/mcp/server.py — 基于本地 Kali Factory API 的 stdio MCP 适配器

• compose.yaml — Redis（及可选的 ChromaDB）边车

• Dockerfile — API/工作进程的应用容器

• .env.example — 所需设置

• DEPLOYMENT.md — 主机特定的运行和部署指南

建议的后续加固

• 将 API 放在 Tailscale、Caddy 或其他仅限内部的网关之后

• 定期轮换 API 令牌

• 将审计日志添加到文件或 SQLite

• 添加显式的作业配额和每个工具的速率限制

• 添加每个目标的允许列表（仅允许代理侦察您拥有或有权测试的域）

• 在 Kali 容器上连接出口日志记录，以便捕获每个出站请求

服务模型

• kali-factory-api.service 应持续运行

• kali-factory-worker.service 应持续运行

• MCP 服务器不应作为持久服务运行

• MCP 客户端应按需通过 stdio 生成 scripts/start-mcp.sh

与其他 Factory 包的关系

这两个包共享相同的架构形态（FastAPI + Redis + RQ + 持有者认证 + 类型化作业 + 允许列表 Docker 执行），并设计为在同一主机上共存，使用不重叠的端口（GPU Factory 为 8080，Kali Factory 为 8081）。

未来的 parallel-OS 编排器可以将代理请求路由到与其所需运行时匹配的 Factory。

Kali Factory 不是什么

• 不是漏洞扫描器。 包含 nuclei 但仅限于 exposures/ 模板。CVE / 利用 / 默认登录 / 模糊测试模板被显式阻止。

• 不是利用框架。 Metasploit、sqlmap、hashcat、john、aircrack-ng、exploitdb、hydra、medusa、ncrack、nikto、wpscan、responder、impacket、crackmapexec 在构建时均已从运行时镜像中清除。

• 不是未经授权的测试工具。 仅针对您拥有或有权测试的目标使用。API 会记录每个作业；滥用行为由您自行负责。

许可证

Apache 2.0 (见 LICENSE)。