DepAlert Agent

CTWall

此工具是 CTWall 平台的一部分。 参阅：CTWall

描述

DepAlert 是用于 CI/CD 管道的开源安全门。它通过分析 SBOM 与恶意软件情报数据，快速告知您的构建是否包含已知的恶意软件包。

DepAlert 解决直接影响发布速度、风险和成本的核心软件供应链问题：

• 通过将 SBOM 分析转化为自动化的 CI/CD 发布门，防止恶意软件进入生产环境。
• 通过在每次管道运行中向团队提供快速、确定的判定（MALWARE、CLEAN、UNKNOWN），减少安全瓶颈。
• 通过一致的策略模型（fail-on）和可审计的异常工作流，跨团队标准化风险决策。
• 通过在部署前（而非部署后）强制执行项目范围检查，降低事件和合规风险。
• 通过用一个可重用于任何管道的 CLI 步骤替换手动安全交接，提高开发人员生产力。

快速开始

参阅 00_quick_start.md 了解分步说明。

工具用途

depalert 是一个 CI/CD CLI，它：

1. 将 SBOM 上传到 CTWall（POST /api/v1/ingest）
2. 同步等待修订判定（GET /api/v1/tests/{testId}/revisions/{revisionId}/depalert-verdict）
3. 返回管道友好的结果和退出码

该工具是项目范围的。 您可以通过以下方式选择目标项目：

• project-id（UUID），或
• project-name（通过 API 解析）。

如果同时提供了两者，则 project-id 优先。

Depalert 结果

DepAlert 返回一个修订结果：

• CLEAN - 未检测到恶意软件发现 - 退出码 0
• MALWARE - 在修订中检测到至少一个恶意软件发现 - 退出码 1
• UNKNOWN - 分析尚未完成 - 退出码 2（或使用 fail-on=NONE 时退出码 0）

CLI 输出格式：

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

可通过 --format json（或 CTWALL_OUTPUT=json）使用 JSON 模式。

JSON 输出示例：

{
  "version": "1.1.0",
  "status": "success",
  "exitCode": 0,
  "projectId": "28e241e3-b924-4e1a-abc2-d592e8dd811c",
  "testId": "13271a70-cf47-4f3b-9e33-cb41ed0c793e",
  "revisionId": "c4d1f1a4-c018-488e-9dd0-6cfdbed83bf3",
  "verdict": "CLEAN",
  "malwareComponents": 0,
  "cleanComponents": 12,
  "unknownComponents": 0,
  "totalComponents": 12,
  "elapsedMs": 1842,
  "timedOut": false,
  "failOn": "MALWARE",
  "message": "depalert completed"
}

预期结果

VERDICT: <MALWARE|CLEAN|UNKNOWN> (malware=<n> clean=<n> unknown=<n> total=<n>, elapsed=<t>)

• 退出码 0 = 通过
• 退出码 1 = 策略失败或运行时错误
• 退出码 2 = 最终判定为 UNKNOWN 且 fail-on 不是 NONE

CLI 和环境配置

项目定位规则

• 至少需要 project-id 或 project-name 中的一个。
• project-name 通过 GET /api/v1/projects 解析。
• 名称匹配不区分大小写，精确匹配。
• 如果有多个活动项目匹配同一名称，运行将因歧义错误而失败。
• 必需值可以通过标志或环境变量提供；标志优先。

连接

• 对于非本地主机，需要使用 https。
• 对于测试/非生产环境，可以使用：
  • --allow-insecure，或
  • CTWALL_ALLOW_INSECURE=true。
• 对于自签名 HTTPS 证书（仅测试/非生产环境），可以使用：
  • --skip-tls-verify，或
  • CTWALL_SKIP_TLS_VERIFY=true。

安全性

请参阅

许可证

DepAlert 使用 BSD 3-Clause 许可证