CyberStrikeAI/docs/zh-CN/runbooks.md

运维 Runbooks

English

Runbook 是“遇到一个真实任务时照着做”的步骤清单。本文覆盖 CyberStrikeAI 最常见的运维和安全测试操作。

Runbook 1：生产实例从 0 到可用

适用：内网团队或生产红队平台首次部署。

如果只是本地或临时验证，优先用仓库自带脚本启动：

chmod +x run.sh && ./run.sh

确认可用后，再决定是否升级为 systemd + 反向代理的长期部署。

前置确认

• 运行主机已纳入资产管理。
• 访问路径确定：内网、VPN、堡垒机或反向代理。
• 有模型 API Key 和允许使用的模型。
• 已决定是否启用 C2、WebShell、外部 MCP。

步骤

1. 准备目录：

mkdir -p /opt/CyberStrikeAI

2. 放置二进制和资源目录：

cyberstrike-ai
web/
tools/
roles/
skills/
agents/
docs/
config.yaml

3. 修改关键配置：

auth:
  password: "<long-random-password>"
server:
  host: 127.0.0.1
  port: 8080
  tls_enabled: false
audit:
  enabled: true
c2:
  enabled: false

4. 配置反向代理 HTTPS，并限制来源 IP。
5. 使用 systemd 托管进程。
6. 登录 Web，测试模型。
7. 检查工具列表和审计日志。
8. 建立备份策略。

验收

• /api/auth/validate 登录后返回成功。
• 模型测试成功。
• tools/ 能正常加载。
• 审计页面能看到登录事件。
• C2 在不需要时访问返回禁用状态。

回滚

恢复：

• 上一版二进制。
• 上一版 config.yaml。
• 升级前 data/。

Runbook 2：接入外部 MCP

适用：接入本地工具服务、Burp 辅助服务、资产查询服务等。

前置确认

• MCP 服务可信。
• 明确它是否能读文件、写文件、执行命令或访问第三方网络。
• 确定接入方式：stdio、HTTP、SSE。

步骤

1. 在外部 MCP 页面新增服务。
2. 如果是 stdio，填写命令、参数、工作目录和环境变量。
3. 如果是 HTTP/SSE，填写 URL 和认证信息。
4. 启动服务。
5. 查看 /api/external-mcp/stats。
6. 检查工具列表是否出现。
7. 用低风险参数执行一次工具。
8. 把高风险工具排除在全局免审批白名单之外。

验收

• MCP 状态为 running。
• 工具 schema 可见。
• Agent 能通过 tool_search 找到工具。
• 工具执行记录出现在监控页。
• 配置变更出现在审计页。

回滚

• 停止 MCP。
• 删除外部 MCP 配置。
• 从角色/白名单中移除相关工具。
• 检查 Agent 当前任务是否仍持有旧上下文。

Runbook 3：启用知识库并调优召回

适用：把内部安全知识、漏洞手册或测试方法接入 Agent。

步骤

1. 修改配置：

knowledge:
  enabled: true
  base_path: knowledge_base
  embedding:
    model: text-embedding-v4
  retrieval:
    top_k: 5
    similarity_threshold: 0.4

2. 把 Markdown 放入 knowledge_base/。
3. 在 Web 知识库页面执行扫描。
4. 重建索引。
5. 准备 5 到 10 个固定测试问题。
6. 搜索并记录命中情况。
7. 根据结果调 threshold、top_k、chunk 参数和文档标题。

验收

• index-status 显示索引完成。
• 常见问题能命中正确文档。
• Agent 在不确定时会先查知识库。
• 检索日志能显示查询和命中文档。

常见回滚

• 关闭 knowledge.enabled。
• 恢复旧的 data/knowledge.db。
• 降低 batch_size 后重新索引。

Runbook 4：一次授权 Web 测试标准流程

适用：对授权目标做 Web 安全测试。

步骤

1. 创建项目，记录授权范围。
2. 新建对话，绑定项目。
3. 选择最小角色，例如“信息收集”或“Web 应用扫描”。
4. 明确目标、时间窗口、禁止动作。
5. 先执行只读信息收集。
6. 发现线索后写入项目事实。
7. 对高风险验证请求使用 HITL。
8. 确认漏洞后写入漏洞管理。
9. 生成攻击链或报告材料。
10. 清理上传文件、临时 workspace 和无用执行记录。

验收

• 每个漏洞都有证据、影响、复现和修复建议。
• 高风险操作有 HITL 记录。
• 项目事实能复现测试路径。
• 报告不包含无关敏感数据。

Runbook 5：C2 演练结束清理

适用：授权演练中启用了 C2。

步骤

1. 停止所有 listener。
2. 列出 sessions，确认没有仍在线的授权会话。
3. 导出必要 task 结果。
4. 删除 payload 或移动到受控归档。
5. 删除无用 task、event、file。
6. 审计 C2 操作记录。
7. 将关键结果写入项目事实或报告。
8. 将 c2.enabled 改回 false，除非平台持续需要。

验收

• 无运行中 listener。
• 无待处理 task。
• payload 不再公开可下载。
• 审计与报告能解释整个生命周期。

Runbook 6：Agent 不调用工具

排查顺序：

1. 当前角色是否绑定了该工具。
2. 工具是否在 /api/config/tools 中出现。
3. tool_search 是否隐藏了该工具。
4. 工具描述是否过短或命名不清。
5. HITL 是否挂起。
6. Agent 是否处于总结/结束阶段。
7. 多代理子 Agent 是否有自己的工具限制。

修复方式：

• 把工具加入角色。
• 优化 short_description。
• 加入 tool_search_always_visible_tools。
• 在提示词中明确什么时候使用。
• 检查过程详情和监控记录。