CyberGabiSoft/DepAlert

# DepAlert Agent ## CTWall 此工具是 CTWall 平台的一部分。 参见：[CTWall](https://github.com/CyberGabiSoft/CTWall) ## 描述 DepAlert 是一个用于 CI/CD 流水线的开源安全门禁。它根据恶意软件情报数据对 SBOM 进行分析，并快速告知您的构建是否包含已知的恶意包。 DepAlert 解决了直接影响发布速度、风险和成本的核心软件供应链问题： - 通过将 SBOM 分析转化为自动化的 CI/CD 发布门禁，防止恶意软件进入生产环境。 - 在每次流水线运行中为团队提供快速、确定的判定结果（`MALWARE`、`CLEAN`、`UNKNOWN`），从而减少安全瓶颈。 - 通过一致的策略模型（`fail-on`）和可审计的异常工作流，标准化跨团队的风险决策。 - 通过在部署前（而非部署后）执行项目范围的检查，降低事件和合规风险。 - 用一个可在任何流水线中复用的 CLI 步骤取代手动安全交接，从而提高开发人员的生产力。 ## 快速开始 请参阅 [00_quick_start.md](./docs/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= total=, elapsed=) ``` JSON 模式可通过 `--format json`（或 `CTWALL_OUTPUT=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= total=, elapsed=) ``` - 退出代码 `0` = 通过 - 退出代码 `1` = 策略失败或运行时错误 - 退出代码 `2` = 最终判定为 `UNKNOWN` 且 `fail-on` 不为 `NONE` ## CLI 和环境配置 | 标志 | 环境变量 | 必需 | 默认值 | 描述 | |---|---|---|---|---| | `--url` | `CTWALL_API_URL` | 是 | `http://localhost:8080` | CTWall API URL | | `--key` | `CTWALL_API_KEY` | 否 | 空 | API token (`Authorization: Bearer ...`) | | `--project-id` | `CTWALL_PROJECT_ID` | 条件性 | 无 | 目标项目 UUID（优先级高于 `project-name`） | | `--project-name` | `CTWALL_PROJECT_NAME` | 条件性 | 无 | 目标项目名称（通过 API 解析为 UUID） | | `--file` | `CTWALL_SBOM_FILE` (或旧版 `SBOM_FILE`) | 是 | 无 | SBOM 文件路径 | | `--product` | `CTWALL_PRODUCT` | 是 | 无 | 产品名称 | | `--scope` | `CTWALL_SCOPE` | 是 | 无 | 范围名称 | | `--test` | `CTWALL_TEST` | 是 | 无 | 测试名称 | | `--fail-on` | `CTWALL_FAIL_ON` | 否 | `MALWARE` | CSV 判定列表：`MALWARE,CLEAN,UNKNOWN` 或 `NONE` | | `--ignore-file` | `CTWALL_IGNORE_FILE` | 否 | `depalert.ignore` | 用于本地判定覆盖 + 分类更新的可选 YAML 异常文件 | | `--format` | `CTWALL_OUTPUT` | 否 | `text` | 输出格式：`text` 或 `json` | | `--timeout-seconds` | `CTWALL_WAIT_TIMEOUT_SECONDS` | 否 | `180` | 同步等待超时时间（秒） | | `--allow-insecure` | `CTWALL_ALLOW_INSECURE` | 否 | `false` | 允许非本地主机使用 HTTP | | `--skip-tls-verify` | `CTWALL_SKIP_TLS_VERIFY` | 否 | `false` | 跳过 HTTPS 的 TLS 证书验证（不安全，仅用于测试） | ### 项目定位规则 - 至少需要 `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 许可证授权

标签：CI/CD 安全, Cybersecurity, DevSecOps, EVTX分析, Google Gemini, GPT, SBOM, SBOM 分析, 上游代理, 代码安全门禁, 依赖项扫描, 威胁情报, 开发者工具, 开源安全工具, 数据投毒防御, 数据集, 文档安全, 文档结构分析, 漏洞管理, 硬件无关, 结构化查询, 网络安全, 自动化安全, 自定义DNS解析器, 软件供应链安全, 远程方法调用, 逆向工程平台, 隐私保护