SIEM 集成(如 Splunk)
推荐使用只读检索接口或索引只读账号拉取告警与原始事件,避免直接修改 SIEM 配置。
- 字段映射需覆盖时间、源/目标、账号、主机、规则名
- 注意时区与时间精度一致性
- 建议先做 3 天字段完整率校验
- 避免高频全量拉取,使用增量窗口
文档中心
本页是文档中心的入口摘要,覆盖部署要求、快速开始步骤、OpenAPI 接口概览、适配器与 Webhook 集成、 离线私有化部署要点与常见错误处理。完整接口手册与适配器开发指南随交付包提供,也可离线查阅。
快速开始
标准私有化部署通常在 2 周内完成基础接入与降噪调优。下文为流程摘要,完整步骤见交付包中的《部署与接入手册》。
确认计算与存储资源、网络分区与时间同步,导入离线授权文件,完成平台初始化与三权分立账号创建。
为每个数据源创建只读账号,选择对应适配器,完成字段映射与归一化校验,确认接入健康度正常。
采集 3–7 天真实数据建立行为基线,配置误报抑制规则、四档分流阈值与业务保护白名单。
配置动作风险等级、审批人与超时升级策略,并按照 L1 → L2 → L3 的顺序逐步放开处置权限。
具体资源规格与端口清单会在方案阶段给出。我们不做「一台低配机器跑全量」这类不切实际的承诺—— 容量规划不到位会让归因质量与降噪效果直接失真。
# 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 暴露,支持按智能体、按事件、按审计链三类资源访问。以下为接口分组摘要。
| 接口分组 | 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|---|
| 事件 | 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 / 留存 / 访问 / 价值四类报表 | 合规只读 |
POST /v1/actions 提交 L2/L3 动作时,接口会返回审批请求 ID 而非直接执行;需在审批通过后由平台下发。Idempotency-Key 请求头,避免重试导致重复处置。429 并携带 Retry-After。# 查询最近 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
}
]
}
# 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"
}
集成指南
SecClaw 不要求改造现有设备。下面按集成类型说明推荐方式与注意事项。
推荐使用只读检索接口或索引只读账号拉取告警与原始事件,避免直接修改 SIEM 配置。
检测数据只读接入;处置动作(终止进程、隔离主机、采集取证包)需单独授权并纳入 L2/L3 审批。
流量告警与元数据接入后可支撑横向移动路径推断与异常外联识别。
支持多源情报交叉验证;离线环境可导入离线情报包,按更新周期滚动替换。
通过 Webhook 双向联动:事件升级推送、审批卡推送与回执、工单状态同步。
对无标准接口的设备,可基于适配器接口自行开发插件:声明字段映射、归一化规则与健康检查。
// 校验来自 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 };
}
离线部署
面向关基单位与强合规行业:完全断网内网运行,无外部依赖、无外部回传通道。
# 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 或主机名 |
| 降噪率异常偏高 | 误报抑制规则过宽、基线把真实异常当成常态 | 抽查被归档的事件组;暂时收紧抑制策略并重新观察;检查基线训练窗口是否包含异常期 |
| 高危动作一直停在待审批 | 审批人未配置、通知通道不可用、超时策略未设置 | 检查审批链配置与通知通道健康度;设置超时升级避免夜间阻塞 |
| 处置执行成功但问题依旧 | 动作未真正生效、存在旁路通道、验证窗口过短 | 查看效果验证指标;确认目标设备策略是否立即生效;适当延长验证窗口 |
| 审计链校验失败 | 记录被外部工具修改、存储层写入异常、升级导致链断裂 | 定位首个校验失败的序号;导出该段记录与检查点比对;必要时从备份恢复并记录事件 |