如何读懂 CloudAI Fusion API 参考:/api/v1/capabilities、证据链与红队报告接口完整指南
如何读懂 CloudAI Fusion API 参考:/api/v1/capabilities、证据链与红队报告接口完整指南
CloudAI Fusion 是一款云原生 AI 调度与 AISecOps 安全运营平台,其 REST API 以 http://localhost:8080/api/v1 为基地址,覆盖能力自检(/capabilities)、可信证据链(/evidence)、红队验证(/redteam)三大核心接口组。本文面向新手用户,用最直白的语言带你从"平台是否真实可用"一路走到"如何取回可验证的红队报告",读完即可独立调用全部关键接口 🧭。
核心概念速览:三组接口各解决什么问题?
在开始之前,先建立一个心智模型。CloudAI Fusion 的 API 按业务域分为多个 tag(在 api/openapi.yaml 中可完整检索):
| 接口组 | 前缀 | 解决的问题 | 一句话理解 |
|---|---|---|---|
| 能力自检 | /api/v1/capabilities |
平台现在到底"真不真"? | 每个子系统是 real 还是 simulated,一目了然 |
| 证据链 | /api/v1/evidence/* |
我的操作记录能被第三方复核吗? | 每条操作都有 Ed25519 签名 + Merkle 证明 |
| 红队报告 | /api/v1/redteam/* |
授权渗透测试的结果可信吗? | 报告内嵌签名检查点(STH),可离线验真 |
这三者构成一条完整的"诚实性闭环":能力声明 → 行为留痕 → 结果验真。下面逐个拆解。
第一步:用 /api/v1/capabilities 判断平台真实度
这是所有自动化脚本的第一站。它回答一个最朴素的问题:"这套平台现在是真后端在跑,还是模拟降级在兜底?"
无需鉴权的诚实报告
GET /api/v1/capabilities 完全不需要认证,任何人都可以查询。返回结构非常简洁:
{
"run_mode": "production",
"all_real": false,
"simulated_count": 3,
"backends": [
{"component": "gpu-scheduler", "mode": "real", "driver": "nvml"}
],
"simulated": [
{"component": "rl-optimizer", "mode": "simulated", "detail": "no GPU visible"}
]
}
关键字段解读:
run_mode:当前运行模式,由策略引擎(pkg/runmode/runmode.go)决定;all_real:所有子系统是否都跑在真实后端上;simulated_count/simulated:被降级为模拟模式的子系统清单及原因。
💡 为什么这很重要?在 AI 平台领域,"看起来能跑"和"真的在跑"差别巨大。CloudAI Fusion 的设计原则是 HONESTY:模拟回退不是隐瞒,而是主动上报(参见 pkg/api/hardware_handlers.go 中的注释)。
配套工具:cafctl status 直接消费该接口
命令行工具 cafctl status 会自动查询此接口并渲染成面板,源码逻辑在 cmd/cafctl/cmd_status.go:
curl http://localhost:8080/api/v1/capabilities
若平台处于降级状态,cafctl up 也会明确提示哪些子系统是 simulated,绝不假装真实运行。
进阶:/api/v1/wells 查看"深井"成熟度
/api/v1/wells 是 capabilities 在 AISecOps 层的对应物,逐条公布每个"deep well"(深度能力模块)的机器核验状态:wired(是否接线)、backend_mode(real/simulated/none)、fabric_connected、evidence_backed 与 claimed_maturity(0~5 成熟度)。其核心价值在于:过度声明会直接导致生产环境启动失败(wellreadiness.Enforce 强制校验),规格见 api/openapi.yaml#L328-L365。
第二步:证据链 /api/v1/evidence —— 让每次操作可审计
证据链(Evidence Chain)是 CloudAI Fusion 的可信基石:平台内所有敏感操作(调度、审批、删除、密钥轮换)都会生成签名回执,并可导出供离线复核。
证据链接口全清单
| 接口 | 方法 | 作用 |
|---|---|---|
/api/v1/evidence |
GET | 账本摘要:规模、密钥 ID、锚定后端 |
/api/v1/evidence/pubkey |
GET | Ed25519 公钥(PEM),无需鉴权,可离线钉扎 |
/api/v1/evidence/records |
GET | 列出签名回执,支持按 action/subject/actor 过滤 |
/api/v1/evidence/records/{id} |
GET | 查看单条回执 |
/api/v1/evidence/records/{id}/proof |
GET | 该回执的 Merkle 包含证明 |
/api/v1/evidence/verify |
GET | 服务端整链校验,返回验证报告 |
/api/v1/evidence/export |
GET | 导出"链 + 公钥"捆绑包,供 cafctl 离线验证 |
/api/v1/evidence/checkpoint |
GET | 签名树头(STH, Signed Tree Head) |
/api/v1/evidence/consistency |
GET | 两个树规模之间的一致性证明(?from=N&to=M) |
/api/v1/evidence/rotate-key |
POST | 轮换签名密钥(需 security:manage 权限) |
新手最关心的两个问题
Q1:怎么离线验证一条操作记录?
标准流程三步走:
- 调
GET /api/v1/evidence/pubkey取得公钥并保存(钉扎); - 调
GET /api/v1/evidence/records/{id}/proof取 Merkle 包含证明; - 本地用公钥 + STH 校验签名与包含关系,全程不需要再连服务器。
生产环境也可直接 GET /api/v1/evidence/export 一次性拿到可导出的验证捆绑包。
Q2:一致性证明有什么用?
/consistency?from=100&to=120 可证明"第 120 号检查点确实包含了第 100 号检查点的全部内容",即历史账本不可被篡改或截断——这是审计场景的硬保障。
相关实现可参考 pkg/audit/evidence_chain.go,OpenAPI 规格位于 api/openapi.yaml#L1822-L1908。
第三步:红队平台 /api/v1/redteam —— 从发起授权攻击到取回可验证报告
CloudAI Fusion 内置了授权、证据级的红队子系统:攻击范围必须签署授权(signed scope)、高危动作需要人工审批、所有动作回执进证据链。这不是"无差别渗透",而是受控的、可审计的安全验证。
红队工作流一图看懂
创建 engagement(签署 scope)
│
▼
运行中:高危动作暂停 → 人工 /approve
│
▼
随时可 /abort(kill-switch)
│
▼
GET /report(内嵌签名 STH)
GET /evidence(该 engagement 的全部签名回执)
关键接口详解
1. 创建授权攻击任务(POST /api/v1/redteam/engagements)
请求体核心是 scope(授权范围),结构上包含:
targets:目标清单,kind支持cidr/host/url/cluster;allow_techniques:允许使用的技术白名单(MITRE ATT&CK 映射);max_risk_tier:风险上限(0只读、1利用、2横向移动);approval_required_at:达到该风险等级必须人工审批。
范围非法或为空时返回 400,成功返回 201。
2. 过程管控三接口
GET /api/v1/redteam/engagements/{id}:查状态与发现(findings);POST /api/v1/redteam/engagements/{id}/approve:批准挂起的高危动作(需提交action_id与risk_tier);POST /api/v1/redteam/engagements/{id}/abort:一键急停(kill-switch)。
3. 取回可验证报告
GET /api/v1/redteam/engagements/{id}/report:返回的报告中内嵌签名的 STH,意味着报告内容被证据链锚定,事后无法否认或抵赖;GET /api/v1/redteam/engagements/{id}/evidence:拉取该任务产生的全部签名回执,可对接上一节的/evidence/verify做整链复核。
更细的字段定义见 api/openapi.yaml#L1909-L2110,完整用户手册见 REDTEAM_USER_MANUAL.md、开发者指南见 REDTEAM_DEVELOPER_GUIDE.md。
用 CVE-Bench 基准验证平台自身能力
平台还自带确定性基准测试,用来客观衡量红队引擎的求解能力:
GET /api/v1/redteam/benchmark/cases:列出内置 CVE-Bench v2 用例(每例标注需解出的 MITRE 技术);POST /api/v1/redteam/benchmark:在隔离的内存证据链上运行全套用例,返回数值指标——solve_rate(求解率)、scope_violations(越界次数,必须为 0)、all_verified(所有回执是否全部验真)。
这三个数字是判断"引擎是否真的在按授权规则行事"的最硬证据:宁可少解,不可越界。
附赠:临时靶场(Ranges)
POST /api/v1/redteam/ranges 可一键供给一个临时练习/评估靶场(支持声明 apps 与可 kubectl apply 的 manifests),用 DELETE /api/v1/redteam/ranges/{id} 销毁。适合团队安全演练,避免污染生产环境。
鉴权、限流与错误处理:三个通用约定
无论调用哪组接口,以下约定通用(详见 API_REFERENCE.md):
1. 鉴权:绝大多数接口要求 Authorization: Bearer YOUR_TOKEN;/health、/capabilities、/evidence/pubkey 等只读诚实性接口无需鉴权。v2 规范还支持 X-API-Key 与 OAuth2(read/write/admin 三级 scope),见 api/openapi-v2.yaml。
2. 限流:默认 100 请求/分钟,生产环境会在响应头返回 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset,超限返回 429 RATE_LIMITED。
3. 统一错误格式:
{
"error_code": "CONFLICT",
"message": "State conflict",
"request_id": "req-xyz123",
"timestamp": "2026-09-05T16:00:00Z"
}
常见错误码速查:400 请求体校验失败、401 令牌无效、403 权限不足(红队高危操作常见)、404 资源不存在、409 状态冲突(如取消已运行任务)、429 限流。
新手上手路线图:5 分钟验证一条完整证据链
按下面的顺序调用,你就完整体验了平台的核心信任模型:
GET /api/v1/capabilities—— 确认平台当前真实度(all_real为 true 最好);POST /api/v1/redteam/engagements—— 以最小scope(max_risk_tier: 0,只读)创建一个 engagement;GET /api/v1/redteam/engagements/{id}—— 轮询状态直到完成;GET /api/v1/redteam/engagements/{id}/report—— 取回内嵌 STH 的报告;GET /api/v1/evidence/pubkey+GET /api/v1/evidence/verify—— 用公钥离线钉扎,服务端整链复核。
整个过程你得到的不只是一份 JSON,而是一条从能力声明到行为回执、再到可离线验真报告的完整信任链——这正是 CloudAI Fusion API 区别于普通运维接口的地方。
延伸阅读
- 完整 OpenAPI 规格:api/openapi.yaml(v1 全量端点)与 api/openapi-v2.yaml(v2 认证与限流策略)
- REST API 参考:API_REFERENCE.md
- 红队 API 参考:REDTEAM_API_REFERENCE.md
- 核心路由实现:pkg/api/router.go(
handleCapabilities位于 router.go#L819-L829) - 能力注册表:pkg/capability/registry.go
- 证据链实现:pkg/audit/evidence_chain.go
- v1→v2 迁移说明:docs/api/migration-v1-to-v2.md
⚠️ 提示:所有
/evidence/rotate-key、/redteam/*高危写操作都需要security:manage权限,普通只读 token 请勿尝试,否则会收到403 FORBIDDEN。建议先在本地cafctl up起的开发实例上演练,再切到生产。