文档中心

SecClaw 文档中心:快速开始、API 概览与集成指南

本页是文档中心的入口摘要,覆盖部署要求、快速开始步骤、OpenAPI 接口概览、适配器与 Webhook 集成、 离线私有化部署要点与常见错误处理。完整接口手册与适配器开发指南随交付包提供,也可离线查阅。

快速开始

从零到第一条降噪结论:四步走

标准私有化部署通常在 2 周内完成基础接入与降噪调优。下文为流程摘要,完整步骤见交付包中的《部署与接入手册》。

  1. STEP 01

    环境准备

    确认计算与存储资源、网络分区与时间同步,导入离线授权文件,完成平台初始化与三权分立账号创建。

  2. STEP 02

    数据源接入

    为每个数据源创建只读账号,选择对应适配器,完成字段映射与归一化校验,确认接入健康度正常。

  3. STEP 03

    基线与策略

    采集 3–7 天真实数据建立行为基线,配置误报抑制规则、四档分流阈值与业务保护白名单。

  4. STEP 04

    审批链与灰度

    配置动作风险等级、审批人与超时升级策略,并按照 L1 → L2 → L3 的顺序逐步放开处置权限。

部署要求(摘要)

  • 操作系统:主流 Linux 发行版(具体支持版本以交付包中的兼容性清单为准)。
  • 资源量级:按数据源数量、归一化吞吐与日志留存周期做容量规划;单节点起步可满足基础版规格,专业版建议高可用三节点起。
  • 网络要求:与数据源、执行目标之间按最小必要开通;支持纯离线内网部署,不要求互联网出口。
  • 时间同步:全组件与数据源需保持时间同步(建议 NTP),否则跨源关联与时间线重建会失真。
  • 账号要求:数据源侧仅需只读账号;执行侧账号按 L0–L3 权限分级单独申请,凭据短时效。
  • 浏览器要求:控制台为纯静态前端,支持主流现代浏览器;无需安装任何插件或客户端。

具体资源规格与端口清单会在方案阶段给出。我们不做「一台低配机器跑全量」这类不切实际的承诺—— 容量规划不到位会让归因质量与降噪效果直接失真。

初始化与授权导入(示意)quickstart / init
# 1) 导入离线授权文件(纯离线环境同样适用)
secclawctl license import ./license/secclaw-license.json
secclawctl license verify

# 2) 初始化平台(创建三权分立角色)
secclawctl init \
  --roles system-admin,security-admin,audit-admin \
  --timezone Asia/Shanghai

# 3) 注册第一个数据源适配器(只读)
secclawctl adapter add ./adapters/splunk-notable.yaml
secclawctl adapter test splunk-notable
# => connection: ok   schema: secclaw.event.v1   fields: 14/14 mapped

# 4) 启动只读观察模式(不产生任何写操作)
secclawctl mode set --readonly
secclawctl status
# => mode: readonly   agents: noise,analysis,response   eps: 1,240

# 5) 生成第一份降噪基线报告
secclawctl report baseline --window 7d --out ./reports/baseline-7d.json

API 概览

OpenAPI:把七个智能体的能力接进你的流程

所有智能体能力均通过统一 OpenAPI 暴露,支持按智能体、按事件、按审计链三类资源访问。以下为接口分组摘要。

SecClaw OpenAPI 接口分组摘要(示意,完整定义见交付包中的 OpenAPI 描述文件)
接口分组 方法 路径 用途 权限
事件GET/v1/events按时间、分流档位、资产、置信度检索事件组只读
事件GET/v1/events/{id}获取事件详情,含攻击链与证据引用只读
事件POST/v1/events/{id}/verdict提交人工研判结论(覆盖或补充 AI 结论)分析员
归因GET/v1/chains/{id}获取 ATT&CK 攻击链结构、缺口标注与爆炸半径只读
处置POST/v1/actions提交处置动作(L2/L3 将创建审批请求)响应员 + 审批令牌
处置GET/v1/actions/{id}查询动作状态、效果验证结果与回滚点只读
处置POST/v1/actions/{id}/rollback触发回滚(需填写理由并具备权限)响应主管
审批GET/v1/approvals列出待审批请求(供 IM / 工单系统拉取)审批人
审批POST/v1/approvals/{id}/decide提交同意 / 拒绝决定与理由审批人
狩猎POST/v1/hunts提交假设并启动一次狩猎任务狩猎分析员
漏洞GET/v1/vulnerabilities/priority获取上下文优先级排序后的修复清单只读
审计GET/v1/audit/entries按主体、动作、时间检索审计链记录审计只读
审计POST/v1/audit/verify触发审计链校验并返回校验报告审计管理员
报表GET/v1/reports/{type}生成 SOAR / 留存 / 访问 / 价值四类报表合规只读

认证与授权

  • 认证方式:服务令牌(Bearer)与短期会话令牌,支持与企业身份提供方对接。
  • 授权模型:基于角色的访问控制 + 字段级权限,写操作额外校验动作风险等级与作用域。
  • 高危动作:调用 POST /v1/actions 提交 L2/L3 动作时,接口会返回审批请求 ID 而非直接执行;需在审批通过后由平台下发。
  • 幂等性:写接口支持 Idempotency-Key 请求头,避免重试导致重复处置。
  • 限流:按令牌维度限流,超限返回 429 并携带 Retry-After。
调用示例:查询高置信事件curl / GET /v1/events
# 查询最近 24 小时内 ESCALATE 档事件(只读接口)
curl -sS -X GET "https://secclaw.local/v1/events" \
  -H "Authorization: Bearer ${SECCLAW_TOKEN}" \
  -H "Accept: application/json" \
  --data-urlencode "window=24h" \
  --data-urlencode "dispatch=ESCALATE" \
  --data-urlencode "min_confidence=0.8"

# 响应(节选)
{
  "total": 12,
  "items": [
    {
      "event_id": "EV-2025-0417-0031",
      "dispatch": "ESCALATE",
      "severity": "high",
      "confidence": 0.91,
      "chain_id": "CH-2025-0417-0031",
      "assets": ["WIN-FIN-07", "WIN-DB-02"],
      "evidence_refs": 27,
      "unverified_claims": 0
    }
  ]
}
调用示例:提交高危处置(将进入审批流程)curl / POST /v1/actions
# L3 高危动作不会立即执行,接口返回审批请求 ID
curl -sS -X POST "https://secclaw.local/v1/actions" \
  -H "Authorization: Bearer ${SECCLAW_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9c1a7e-2b44-4d10-9f7a-1c8e5b0d2a61" \
  -d '{
    "event_id": "EV-2025-0417-0031",
    "action": "edr.isolate_host",
    "target": { "host": "WIN-FIN-07" },
    "risk_level": "L3",
    "reason": "confirmed_c2_beacon",
    "require": ["sandbox:pass", "rollback:ok", "approval:human"]
  }'

# 响应:等待审批,不会直接执行
{
  "action_id": "ACT-2025-0417-0088",
  "status": "pending_approval",
  "approval_id": "APR-2025-0417-0042",
  "sandbox": { "result": "pass", "impact_hosts": 1 },
  "rollback_point": "RB-2025-0417-0031-01",
  "timeout_policy": "escalate_to: soc_manager after 10m"
}

集成指南

对接 SIEM / EDR / NDR / TI / IM / ITSM

SecClaw 不要求改造现有设备。下面按集成类型说明推荐方式与注意事项。

SIEM 集成(如 Splunk)

推荐使用只读检索接口或索引只读账号拉取告警与原始事件,避免直接修改 SIEM 配置。

  • 字段映射需覆盖时间、源/目标、账号、主机、规则名
  • 注意时区与时间精度一致性
  • 建议先做 3 天字段完整率校验
  • 避免高频全量拉取,使用增量窗口

EDR 集成

检测数据只读接入;处置动作(终止进程、隔离主机、采集取证包)需单独授权并纳入 L2/L3 审批。

  • 主机标识需与资产主数据对齐
  • 隔离动作必须配置业务白名单
  • 回滚接口需提前验证可用性
  • 避免使用共享管理员账号

NDR / 流量检测集成

流量告警与元数据接入后可支撑横向移动路径推断与异常外联识别。

  • 内网东西向流量对横向移动识别最关键
  • 会话元数据比全包留存更经济
  • 注意传感器覆盖盲区对结论的影响
  • 链路层时间同步要求更高

威胁情报(TI)集成

支持多源情报交叉验证;离线环境可导入离线情报包,按更新周期滚动替换。

  • 多源交叉可降低单源误判
  • 情报有效期需显式配置
  • 离线情报包需签名校验
  • 情报命中置信度参与综合评分

Webhook 与 IM / ITSM 集成

通过 Webhook 双向联动:事件升级推送、审批卡推送与回执、工单状态同步。

  • Webhook 出站目标需白名单配置
  • 审批回执必须校验签名防伪造
  • 支持重试与失败降级到备用通道
  • Webhook 载荷不包含未脱敏敏感字段

适配器插件开发

对无标准接口的设备,可基于适配器接口自行开发插件:声明字段映射、归一化规则与健康检查。

  • 插件独立版本化,可灰度升级与回滚
  • 禁止在适配器内实现写操作
  • 需通过归一化一致性与性能测试
  • 可提交至平台适配器清单共享
Webhook 审批卡回调验证(伪代码)integration / webhook-verify
// 校验来自 SecClaw 的 Webhook 签名,防止伪造审批回执
function verifySecClawWebhook(req, secret) {
  const timestamp = req.headers['x-secclaw-timestamp'];
  const signature = req.headers['x-secclaw-signature'];

  // 1) 时间窗校验:拒绝过期请求,防止重放
  if (Math.abs(Date.now() - Number(timestamp)) > 300000) {
    return { ok: false, reason: 'timestamp_out_of_window' };
  }

  // 2) 使用原始请求体(不要用已解析后的对象)重算 HMAC
  const expected = hmacSha256(secret, timestamp + '.' + req.rawBody);

  // 3) 恒定时间比较,避免时序侧信道
  if (!timingSafeEqual(expected, signature)) {
    return { ok: false, reason: 'bad_signature' };
  }

  // 4) 幂等校验:同一 approval_id 只处理一次
  const payload = JSON.parse(req.rawBody);
  if (seenApprovalIds.has(payload.approval_id)) {
    return { ok: true, duplicate: true };
  }
  return { ok: true, payload };
}

离线部署

纯离线私有化部署要点

面向关基单位与强合规行业:完全断网内网运行,无外部依赖、无外部回传通道。

离线交付物

  • 平台安装包与依赖组件包(含完整性校验值)
  • 离线授权文件(绑定环境标识,具备有效期)
  • 离线升级包(签名校验,支持回滚到上一版本)
  • 离线情报包与模型包(按更新周期滚动替换)
  • 离线校验工具(用于审计链验签与验链)
  • 完整文档包(含部署、接入、适配器开发手册)

离线环境注意事项

  • 时间同步:内网必须有可用的时间源,否则跨源关联结论失真。
  • 授权续期:授权到期的续期文件需通过离线方式导入,请提前规划续期流程。
  • 模型更新:模型包更新同样走离线导入,建议先在测试环境验证再上生产。
  • 情报新鲜度:离线情报包的更新周期直接决定情报类判定的有效性,建议明确更新责任人与频率。
  • 日志留存:离线环境的存储规划需按合规留存周期倒推容量,避免中途扩容困难。
离线升级流程(示意)offline / upgrade
# 1) 在联网环境下载升级包与校验值,拷贝到离线环境
#    (升级包与校验值需分别通过受控介质传递)

# 2) 导入前先校验完整性与签名
secclawctl package verify ./upgrade/secclaw-1.0.3.pkg

# 3) 查看升级影响与回滚可行性
secclawctl upgrade plan ./upgrade/secclaw-1.0.3.pkg
# => components: 12   restart_required: true   rollback_available: true

# 4) 备份当前状态并记录审计链锚点
secclawctl backup create --label pre-1.0.3
secclawctl audit anchor --note "before upgrade to 1.0.3"

# 5) 应用升级(失败可回滚)
secclawctl upgrade apply ./upgrade/secclaw-1.0.3.pkg
secclawctl status
# => version: 1.0.3   mode: readonly   agents: healthy

# 6) 校验审计链连续性(升级不应造成链断裂)
secclawctl audit verify --full

常见错误处理

部署与接入中最常遇到的六类问题

这些来自实际交付经验。多数问题的根因在数据质量与时间同步,而不是平台本身。

常见问题、可能原因与排查方向
现象 可能原因 排查方向
数据源显示已连接但没有事件 查询窗口配置错误、账号权限不足、字段映射未命中 检查适配器健康度中的实际拉取条数与字段完整率;用只读账号手工查询验证
跨源关联结果明显不合理 时区或时间精度不一致、资产标识未对齐 核对各源时间偏移;检查主机标识是否统一为资产 ID 而非 IP 或主机名
降噪率异常偏高 误报抑制规则过宽、基线把真实异常当成常态 抽查被归档的事件组;暂时收紧抑制策略并重新观察;检查基线训练窗口是否包含异常期
高危动作一直停在待审批 审批人未配置、通知通道不可用、超时策略未设置 检查审批链配置与通知通道健康度;设置超时升级避免夜间阻塞
处置执行成功但问题依旧 动作未真正生效、存在旁路通道、验证窗口过短 查看效果验证指标;确认目标设备策略是否立即生效;适当延长验证窗口
审计链校验失败 记录被外部工具修改、存储层写入异常、升级导致链断裂 定位首个校验失败的序号;导出该段记录与检查点比对;必要时从备份恢复并记录事件
排查原则:先确认数据质量,再怀疑算法。绝大多数「AI 判断不准」的问题, 根因都是字段缺失、时间不同步或资产台账不完整。平台会显式标注数据质量缺口,帮助你把问题定位到正确的层面。

需要完整的接口手册与适配器开发指南?

完整文档随交付包提供,也可离线查阅。如果你在评估阶段就需要接口清单与字段字典,我们可以先行提供脱敏版本。