open·kritt 详细部署教程

项目概述

open·kritt 是一个开源、自托管的 AI 漏洞研究平台。它将安全研究分解为小而明确的任务，通过 AI 代理并行运行，并将输出合并为可验证和优先级排序的发现。

核心理念：将模型指向整个仓库并要求其查找漏洞很少有效。open·kritt 采取聚焦方法：将研究分解为小型、明确定义的任务，在 AI 代理中并行运行，并将它们的输出组合成你可以验证和优先级排序的发现。

主要功能：

功能 说明
构建工作流 将聚焦提示链入可复用的安全研究剧本
运行扫描 使用 Codex 或 Claude Code 分析远程或本地仓库及其依赖
验证发现 使用后脚本验证问题、构建概念验证并生成报告
导出扫描结果 将规范发现、结构化数据、报告和 PoC 打包为 ZIP 归档
优先级排序 应用自定义严重性排序器、一致的发现模式和自动去重
自带模型访问 使用 Codex 登录或通过 OpenAI、Anthropic、OpenRouter 或 xAI 连接

源于真实安全研究。 Kritt 团队以研究员名称 Blockian 在漏洞赏金中获得了超过 $1,500,000 的报酬。open·kritt 是这项工作背后内部项目的开源精华。

部署前准备

系统要求

根据官方文档和社区实践，建议配置如下：

项目 最低要求 推荐配置
操作系统 Ubuntu 24.04 / Debian 12 / Rocky Linux 9 (x86_64 或 ARM64) Ubuntu 24.04
内存 8 GB RAM 16 GB RAM（并发扫描）
CPU 4 vCPU 8 vCPU
存储 50 GB NVMe 100 GB NVMe
Docker Docker Engine + Compose 插件 最新稳定版
Node.js 20+（仅用于 CLI，手动 Docker 路径不需要） 20 LTS

重要安全警告：open·kritt 运行 AI 代理来分析潜在不可信的源代码。工具启用的代理在一次性作业容器中以 root 身份运行，具有可写的工作区副本和直接互联网访问权限，以便安装工具、编译目标、运行测试和构建概念验证。请在专用的 Docker 主机或 VM 上运行 open·kritt，并在扫描不可信代码之前阅读威胁模型。

环境检查

1
2
3
4
docker --version
docker compose version
node --version
git --version

获取模型访问凭证

open·kritt 需要一种 AI 访问方法即可开始。你可以配置多个并在每次运行时选择，但单个可用的提供商就足够启动。

提供商 访问方式 模型输入
Codex ChatGPT/Codex 登录或 OpenAI Platform 密钥 账户特定选择器
Claude Claude 订阅登录或 ANTHROPIC_API_KEY 订阅别名或账户特定选择器
OpenRouter OPENROUTER_API_KEY 可搜索的认证目录
xAI Grok 设备登录或 XAI_API_KEY 可搜索的认证目录

方案一：交互式 CLI 部署（推荐）

这是最简单的部署方式，使用仓库自带的交互式 CLI。

步骤 1：克隆仓库

1
2
git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt

步骤 2：运行设置

1
./kritt setup

CLI 会创建环境文件并引导你完成模型访问设置。

步骤 3：启动服务栈

1
./kritt start

步骤 4：访问 Web UI

服务启动后，打开浏览器访问 http://localhost:5173。

后端健康检查端点位于 http://localhost:3002/api/health。

手动配置方式

如果你更倾向于手动配置：

1
2
3
4
5
6
7
8
9
10
# 复制环境文件模板
cp .env.example .env
chmod 600 .env

# 编辑 .env，设置你的提供商密钥，例如：
# ANTHROPIC_API_KEY=your-key-here

# 创建 Codex harness 期望的凭证目录
mkdir -p .data/codex
chmod 700 .data/codex

启动服务栈

1
2
3
./kritt start
# 或手动运行
docker compose up --build

启动完成后，验证后端健康状态：

1
curl http://127.0.0.1:3002/api/health

方案二：Headless 模式部署（无图形界面）

在无浏览器或桌面的服务器上，保持服务栈运行，并在另一个 shell 中使用 headless CLI。

1
./kritt-headless

Headless CLI 功能：

  • 导入可移植的工作流、后脚本、技能和排序器 JSON
  • 创建扫描（与 Web 表单相同的后端验证）
  • 显示扫描状态、阶段和失败原因
  • 编辑非秘密运行时设置
  • 导出发现包

注意：Headless CLI 不在终端中显示发现内容。

配置 AI 提供商

通用设置流程

从仓库根目录运行：

1
./kritt setup

选择 Codex 登录、OpenAI API 密钥、Codex API 密钥、Anthropic API 密钥、OpenRouter API 密钥 或 xAI API 密钥。

重要提示：如果 open·kritt 已在运行，请先用 Ctrl+C 停止已附加的服务栈。现有容器在新更改的 .env 值被 Compose 重新创建之前不会收到该值。

验证提供商

再次运行 ./kritt setup 并确认所选方法标记为存在。工作流生成器、后脚本生成器和新建扫描表单将仅列出 open·kritt 检测到已配置的提供商。

凭证处理

  • API 密钥由 CLI 写入仓库的 .env 文件
  • Codex 登录存储在 ENGINE_CODEX_ACCOUNTS_HOST（默认 ./.data/codex-accounts）
  • Claude 登录存储在 ENGINE_CLAUDE_HOME（默认 ./.data/claude）
  • Grok/xAI 登录存储在 ./.data/grok 和 ./.data/grok-accounts

安全提醒：将 .env、./.data/codex、./.data/claude 等视为机密。永远不要提交它们、粘贴到 issue 中或与另一个用户共享。如果凭证暴露，请立即撤销并替换。

扫描仓库

通过 Web UI

  1. 打开 http://localhost:5173
  2. 进入 Scans → New scan
  3. 选择工作流、目标仓库、模型/harness 和严重性级别

通过 Headless CLI

1
2
./kritt-headless
# 使用交互式菜单导入资源、创建扫描、检查状态

安全与威胁模型

open·kritt 是一个安全工具，它运行 AI 代理来分析潜在不可信的源代码，并处理模型 API 密钥和仓库凭证。

核心安全原则

一句话总结：扫描代理以 root 身份在一次性容器中运行，具有可写工作区和直接互联网访问权限。将仓库和模型输出视为不可信，隔离 Docker 主机，最小化凭证范围，并保持 API 私密。

信任边界

边界 说明
操作员 ↔ 后端/UI API 和 UI 默认无认证。任何能访问它们的人都可以读取/创建扫描、读取发现并更改提供商账户配置。你必须自己实施边界（网络隔离/带认证的反向代理）
引擎 ↔ 分析的代码 引擎检出任意仓库并对其运行 AI 代理。工具启用的作业在一次性嵌套容器中以 root 身份运行，具有可写的每作业检出和直接出站互联网访问
open·kritt ↔ 模型/提供商 仓库内容发送到配置的 OpenAI/Codex、Anthropic 或 OpenRouter 端点。这是数据出口边界

关键威胁与缓解措施

1. 不可信代码与提示注入

引擎分析受攻击者影响的代码，仓库可能包含精心制作的内容来操纵代理（提示注入）以泄露机密或行为异常。

设计缓解措施：

  • 每个工具启用的作业获得一次性容器、可写的每作业检出、复制的作业主目录和专用 Docker 网络
  • 作业不挂载 Docker socket、数据库、项目 .env 或其他作业
  • Harness 输出受 schema 约束为 JSON

操作员缓解措施：

  • 在专用 VM 或 Docker 主机上运行完整服务栈
  • 不要与无关的敏感工作负载共置
  • 假设任何扫描都可能是敌对的

2. 机密泄露

  • 将 .env、./.data/ 等视为机密
  • 最小化令牌范围并轮换它们
  • 永远不要提交机密

3. 数据出口

  • 扫描将仓库内容发送到你配置的模型/提供商端点
  • 在扫描敏感代码之前，了解数据去向

常用命令

根据官方文档，CLI 命令如下：

命令 用途
./kritt 交互式 CLI 菜单
./kritt setup 创建环境文件、配置模型访问
./kritt start 启动服务栈
./kritt-headless 无 Web UI 操作运行中的服务栈
./kritt-headless help 显示 headless 交互式和命令模式用法

常见问题排查

问题 解决方案
Docker Compose 启动失败 检查 Docker 是否运行，确认端口 5173/3002 未被占用
无法访问 Web UI 确认服务栈已启动，检查 curl http://127.0.0.1:3002/api/health 返回正常
提供商未显示 运行 ./kritt setup 重新配置，确认凭证已正确保存
扫描无结果 检查目标仓库是否可访问，确认模型提供商配额充足
内存不足 增加 Docker 内存分配（建议 8GB+，推荐 16GB）
API 密钥泄露 立即撤销并替换密钥，检查 .env 是否被意外提交

数据持久化

open·kritt 使用以下持久化目录：

  • ./.data/engine/ — 引擎运行时配置
  • ./.data/codex/ — Codex 登录状态
  • ./.data/claude/ — Claude 登录状态
  • ./local_repos/ — 本地仓库（只读挂载）

建议定期备份这些目录。

文档预览（可选）

预览文档站点：

1
2
3
npm install -g mint
cd docs-site
npm run dev

打开 http://localhost:3001 查看站点。

总结

部署方式 适用场景 难度 推荐度
交互式 CLI 大多数用户 ⭐ ⭐⭐⭐⭐⭐
Headless 模式 无图形界面服务器 ⭐⭐ ⭐⭐⭐⭐
手动 Docker 需要自定义配置 ⭐⭐⭐ ⭐⭐⭐

对于大多数用户，交互式 CLI 部署是最简单直接的选择：

1
2
3
4
5
6
7
8
9
10
11
# 克隆仓库
git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt

# 运行设置
./kritt setup

# 启动服务
./kritt start

# 访问 http://localhost:5173

部署前务必注意：

  1. 在专用 Docker 主机或 VM 上运行，不要与敏感工作负载共置
  2. 默认端口绑定到 127.0.0.1，后端不含应用认证，保持服务栈私密
  3. 扫描代理以 root 身份运行，具有直接互联网访问权限，将扫描的仓库视为不可信
  4. 使用 SSH 隧道或带认证的反向代理来安全访问界面