DepAlert Agent

CTWall

This tool is part of the CTWall platform. See: CTWall

説明

DepAlertは、CI/CDパイプライン向けのオープンソースセキュリティゲートです。SBOMをマルウェアインテリジェンスデータと分析し、ビルドに既知の悪意のあるパッケージが含まれているかどうかを迅速に通知します。

DepAlertは、リリース速度、リスク、コストに直接影響を与えるソフトウェアサプライチェーンの核心的問題を解決します：

• SBOM分析を自動CI/CDリリースゲートに変えることで、マルウェアが本番環境に到達するのを防ぎます。
• 各パイプライン実行で迅速で確定した判定（MALWARE、CLEAN、UNKNOWN）をチームに提供することで、セキュリティのボトルネックを削減します。
• 一貫したポリシーモデル（fail-on）と監査可能な例外ワークフローにより、チーム全体でリスク判断を標準化します。
• デプロイ後ではなく前にプロジェクトスコープのチェックを適用することで、インシデントとコンプライアンスのエクスポージャーを低減します。
• 手動のセキュリティハンドオフを、任意のパイプラインで再利用可能な1つの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は1つのリビジョン結果を返します：

• CLEAN - マルウェア検出なし - 終了コード0
• MALWARE - リビジョンに少なくとも1つのマルウェア検出あり - 終了コード1
• UNKNOWN - 分析がまだ完了していない - 終了コード2（またはfail-on=NONEの場合は終了コード0）

CLI出力形式：

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

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> (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ライセンスの下でライセンスされています。