はじめに
Corgea CLIは、コードのセキュリティ脆弱性を見つけて修正する強力な開発者ツールです。当社のAI搭載スキャナー(BLAST)とプラットフォームを用いて、Corgeaはビジネスロジックの欠陥、認証の脆弱性、その他見つけにくいバグなどの複雑なセキュリティ問題を特定します。CLIはコードベースのスキャン、検出結果の検査、修正とのやり取りなど、優れた開発者体験を念頭に置いて設計されたコマンドを提供します。機能
- 複数スキャナーのサポート:BLAST（当社のAI搭載スキャナー）でスキャンし、Semgrep、Snyk、Checkmarx、CodeQL、Fortify、Coverityのレポートをアップロードできます。
- 問題管理:セキュリティの検出結果を一覧表示、確認、管理できます。
- 修正機能との連携:ターミナルからAIが生成した脆弱性の修正を表示して適用できます。
- 依存関係スキャン:
corgea depsを使用して、オフラインの依存関係インベントリの作成、依存関係グラフの確認、SBOMの生成、依存関係ポリシーの評価を行えます。 - コンテナイメージスキャン:
corgea scan --include-imageを使用して、ビルド済みのコンテナイメージをコードと合わせてスキャンできます。 - パッケージアドバイザリーチェック:npmやPyPIのパッケージを選択またはインストールする前に、既知のアドバイザリを確認できます。
- パッケージマネージャーのインストールゲート:
npm、yarn、pnpm、pip、uvによるインストールを事前に検査し、既知の脆弱性があるパッケージ、悪意のあるパッケージ、公開直後で疑わしいパッケージの導入を防ぎます。詳細はパッケージマネージャーのインストールゲートを参照してください。 - 柔軟な出力:人間が読みやすい形式とJSON形式の両方をサポートし、CIとの連携を容易にします。
- CI/CD連携:重大度やカスタムブロッキングルールに基づいてビルドを失敗させることができます。
- スキャン管理:プロジェクト全体のスキャン進捗と結果を追跡できます。
- Agent Skillsインストール:Corgeaレジストリから承認されたAgent Skillsをサポートされたコーディングエージェントにインストールします。
前提条件
- Corgeaアカウント:アクティブなCorgeaアカウント。
- 認証用トークン:有効なCorgea APIトークンまたはJWTアクセストークン。
corgea deps scan、 graph、 explain、 diff、 sbom、 policy init コマンドは、Corgeaアカウント、トークン、設定、ネットワークアクセスを必要としません。
インストールガイド
npmでインストール
uvでインストール
Pythonユーザーには、このインストール方法を推奨します。uv tool installはPyPIパッケージから独立したツール環境を作成し、CLIをPATH上のcorgeaコマンドとして利用できるようにします。
uvからツールディレクトリがPATHに含まれていないと報告された場合は、次のコマンドを実行します。
pipでインストール
uvを使わない場合は、Pythonのパッケージインストーラーpipを使ってCorgea CLIをインストールすることができます。
Homebrewでインストール
HomebrewでCorgea CLIツールをインストールするには、まずCorgea Tapを追加し、その後CLIをインストールしてください:手動でインストール
最新リリースからプラットフォームのアーカイブをダウンロードし、解凍してcorgeaバイナリをPATHに移してください。以下のlatest/downloadURLは常に最新のリリースに割り当てられています。
corgea-x86_64-unknown-linux-musl.zipとcorgea-aarch64-unknown-linux-musl.zipとして提供されています。最小構成のコンテナやCIランナーではこちらを使用してください。
認証
CLIでログイン
CLIで認証するには、以下のコマンドを使用します。これにより、CLIを承認するためのウェブアプリケーションにリダイレクトされます:カスタムスコープでログイン(シングルテナントインスタンスの顧客向け)
ヒント: あなたの会社の範囲はCorgeaのサブドメインです。例えば:https://your-company.corgea.app
トークン(APIトークンまたはJWT)でログイン
自動化されたパイプラインやCI/CD環境では、信頼性が高く非対話的なログインフローのためにトークン認証を活用してください。Corgea APIトークンかJWTアクセストークンのいずれかを渡すことができます:シングルテナントインスタンスを指定
シングルテナントインスタンスを使用している顧客は、CLIを--url オプションで特定のインスタンスを指すように設定する必要があります。
使用法
コマンドとオプション
パッケージアドバイザリーの確認
npmやPyPIのパッケージを選択またはインストールする前に、corgea advisories checkで既知のアドバイザリを確認します。パッケージ名のみを指定するとアドバイザリ履歴が表示され、正確なバージョンを追加するとそのリリースに対する判定が表示されます。
npmまたはpypiを指定できます（pipも別名として使用できます）。npmのバージョンには1.2.3のような完全かつ正確なバージョンが必要です。範囲、タグ、部分バージョンには対応していません。PyPIのチェックでは、package@versionまたはpip形式のpackage==version構文を使用できます。
パッケージ名のみを指定した結果では、バージョンを選択する前にアドバイザリの履歴を確認できます。正確なバージョンを指定した結果には、既知のアドバイザリの詳細、利用可能な場合は修正済みバージョンの情報、報告されたすべてのアドバイザリに修正がある場合は安全な推奨バージョンが含まれます。このコマンドは読み取り専用で、ネットワークアクセスが必要です。実際のインストール制御はパッケージマネージャーのインストールゲートで行います。
機械可読なスキーマバージョン1のレスポンスを取得するには、--jsonを使用します。アドバイザリが見つからない場合の終了コードは0、見つかった場合は1、エラーの場合は2です。アドバイザリデータベースに存在しないパッケージは、終了コード0で終了します。
パッケージマネージャーインストールゲート
依存関係をインストールする前にCorgeaのチェックを実行するには、対応するパッケージマネージャーのコマンドをcorgea npm、corgea yarn、corgea pnpm、corgea pip、corgea uv経由で実行します。
corgea pip --force install requests）。
公開日の新しさに基づくゲート。 脆弱性データの確認に加えて、Corgeaは指定されたインストール対象の解決済みバージョンが所定の期間内に公開されている場合にブロックします。これにより、アドバイザリフィードに情報が反映される前でも、公開直後のタイポスクワッティングや乗っ取りを検出できます。この機能はデフォルトで有効で、期間は14日間です。
~/.corgea/config.tomlで設定するか（recency_gate = falseで無効化、recency_threshold_daysで期間を変更）、環境変数CORGEA_RECENCY_GATEとCORGEA_RECENCY_THRESHOLD_DAYSを使用します。公開日を特定できないパッケージはこのゲートの対象になりません。脆弱または悪意ありという判定は公開日の新しさより優先され、--forceを指定するとその1回のインストールに限りゲートを回避できます。
カバレッジ。 pip installとnpm installでは、推移的依存関係を含むインストール予定のパッケージ一式を解決するため、脆弱な推移的依存関係があるとコマンドをブロックします。ドライランによる依存関係の解決に失敗した場合、Corgeaは警告を表示し、指定された対象のみのチェックに切り替えます。npm ciはプロジェクトのロックファイル、uv syncはuv.lockを基にチェックするため、コマンドにパッケージ名が含まれていなくても、ロックされたパッケージ一式が検査されます。uvゲートは、対象を指定したuv add ...とuv pip install ...もチェックします。uv lockはパッケージをインストールしないため、そのまま実行されます。yarnとpnpmは安全なドライランリゾルバーがないため、指定された対象のみをチェックします。
パッケージ名を指定しないインストール。 パッケージ名を指定しないnpm installは、プロジェクトのpackage.jsonを基にチェックされます。パッケージ名を指定しないyarn、pnpm、およびインストール形式のuvコマンドは事前にチェックできないため、Corgeaは注意事項を表示して、チェックせずに実行します。
CORGEA_TOKENまたはcorgea loginのトークンを使用すると、ゲートは認証モードで動作し、フェイルクローズになります。検証不能なパッケージ、依存関係の解決失敗、脆弱性APIの停止、および通常は依存関係ツリー全体を解決するマネージャー（pip、npm、uv）でのツリーカバレッジ低下は、--forceを指定しない限りインストールをブロックします。
カスタム脆弱性API。 CORGEA_VULN_API_URLでカスタムエンドポイントを指定した場合、Corgeaはそのエンドポイントにトークンを送信しないため、ゲートはパブリックモードのままです。信頼できるエンドポイントに対して認証モードのチェックを有効にするには、CORGEA_VULN_API_SEND_TOKEN_TO_CUSTOM_URL=1を設定します。
外部管理のPython環境。 pipでは、レジストリをチェックする前に、外部管理環境（PEP 668）へのインストールを拒否します。仮想環境を有効にするか、--forceを指定して回避します。
Corgeaは、PATHにある対応パッケージマネージャーを実行します。corgea pip ...では、pipが見つからない場合にpip3を試します。どちらも存在しない場合、CLIは不足しているバイナリ名を表示し、終了コード127で終了します。
インストール以外のコマンドとフラグはパッケージマネージャーに転送されます。たとえば、corgea npm --versionはインストール済みのnpmバージョンを表示し、corgea --versionはCorgea CLIのバージョンを表示します。
検出結果。 解決済みパッケージが脆弱な場合、ツリーの検出結果はその発生源を示します:
(from requirements)— PIP要件ファイルを通じて要求される。(already in package.json)— すでに直接的なnpm依存関係。(transitive)— 別の依存関係を通じて引き込まれる。
safe version: axios@0.21.2が表示され、脆弱なnpm直接依存関係ではfix with: corgea npm install package-name@version (advertised fix)が表示される場合もあります。脆弱性の件数と終了動作は、最初に指定したインストール対象に従います。
JSON出力。 --jsonは標準出力にレポートを1件返します。解決とパッケージチェックの進捗は標準エラー出力に書き出し、標準出力を機械可読な出力用に確保します。パッケージマネージャーの標準出力も標準エラー出力へリダイレクトされます。スキーマバージョン2では、manager、subcommand、args、recency_threshold_days（現在の期間。ゲートが無効な場合はnull。各結果のage_secondsと組み合わせて使用）、namedとtreeに分けた件数を含むsummary、verdict_mode、results配列が報告されます。依存関係ツリーを解決した場合はtreeオブジェクトも含まれます。ツリー内の各エントリのoriginは、requested、pre-existing、transitiveのいずれかです。既知の悪意のあるパッケージでは、固有の判定statusであるmalicious、一致項目ごとのmalwareブール値、各集計オブジェクト内の独立したmalicious件数が報告されます。こうしたパッケージはアップグレードではなく削除する必要があるため、remediationは常にnullです。脆弱なパッケージについては、すべてのアドバイザリを解決できる場合に限り、安全なバージョンが引き続き報告されます。
Agent Skillsのインストール
Corgeaレジストリから承認されたスキルをコーディングエージェントのスキルディレクトリにインストールしてください:cursor、 claude-code、 codex、 github-copilot、 gemini-cli、 windsurf、 opencode、 universalです。 --scope project を使って現在のリポジトリにインストールし、 --scope user でユーザーアカウントにインストールし、 --dir でカスタムスキルディレクトリにインストールしてください。
特定のバージョンをインストールするには、スキル名に付け加えてください:
--set-defaultを付けると、インストール時に指定した--agentの値をそのままデフォルトとして保存できます。
CORGEA_DEFAULT_AGENTは保存されたデフォルトより優先されます。設定ファイルに書き込みたくないCI環境で便利です。
スキャンレポートをアップロード
スキャンレポートをSTDINまたはファイル(JSON、SARIF、FPR、またはCoverity XML)でCorgeaにアップロードしてください:--project-nameを使用します。省略した場合、CLIはGitリポジトリ名を使用し、取得できなければ現在のディレクトリ名を使用します。
--waitを追加します。
コードベースをスキャンする
デフォルトのBLASTスキャナーで現在のディレクトリをスキャンするには:--fail-on（BLASTスキャンのみ）には、CR、HI、ME、LO、maliciousの条件をカンマ区切りで1つ以上指定できます。重大度の条件は指定した重大度以上の検出結果に一致します。たとえば、MEはHIとCRの検出結果にも一致します。maliciousは、悪意ありと分類された依存関係の検出結果に一致します。指定した条件のいずれかに一致すると、コマンドはゼロ以外の終了コードで終了します。
例:
--fail-on MEはME、HI、CRの検出結果で失敗します。複数の条件を指定した場合、いずれかに一致するとスキャンは失敗します。悪意ありと分類されていない脆弱な依存関係は、malicious条件には一致しません。
あるいは、プルリクエスト向けかCI向けかに関係なく、ウェブアプリで定義されたすべてのアクティブなブロッキングルールに基づいて失敗させることもできます:
--failはCLI 1.10.0以降で非推奨です。パイプラインで適用するCIルールを指定するには、--block-onを使用してください。
CIパイプラインで特定のルールを適用するには、ウェブアプリで各ルールのApplies ToをCIに設定し、生成されたスラッグを--block-onに渡します（CLI 1.10.0以降）:
criticals,malicious-deps）。使用できるのはアクティブなCIルールのみです。未知のスラッグ、非アクティブなルール、またはプルリクエスト向けルールを指定すると、設定エラーでコマンドが失敗します。--block-onはBLASTスキャナーのみで使用でき、--failや--fail-onと併用できません。--failと--fail-onも同時には指定できません。
ブロッキングルールはCorgeaクラウドで評価されるため、コマンドはその完了を最大15分間待機します。待機時間を超えた場合は、評価されていないスキャンを通過させるのではなく、終了コード 1 を返します。より長く待機するには、CORGEA_BLOCKING_RULES_TIMEOUT_SECONDS に待機する秒数を設定してください:
--out-fileのレポートと--sbomの出力は書き出されます。
デフォルトでは、スキャンコマンドはプロジェクト全体をスキャンします。コミット前の変更だけをスキャンするには、--only-uncommittedオプションを使用します。
--targetオプションを使用すると、特定のファイルやプロジェクトの一部だけを対象にできます（BLASTスキャンのみ）。カンマ区切りで複数の値を指定でき、ファイルパス、ディレクトリパス、Globパターン、Gitセレクター、標準入力をサポートしています。
例:
--excludeオプションでBLASTスキャンからファイルを除外できます。これはカンマ区切られたグロブパターンを受け入れ、--targetの有無にかかわらず使用できます。
--only-uncommitted と --target は併用できません。
BLASTスキャンでファイルをスキップするには、--excludeにカンマ区切りのGlobパターンを指定します。--targetと組み合わせて、対象の一部をスキャンしながら、その中でパターンに一致するファイルを除外することもできます。
--project-nameを使用します。省略すると、CLIは利用可能な場合にgitリポジトリ名をデフォルトで使い、現在のディレクトリ名に戻します。
KEY=VALUEのペアごとに--metadataを繰り返し指定します。これらの値はスキャンと、JSON形式のスキャン一覧出力に含まれます。
--metadataはBLASTスキャナーのみで使用できます。各エントリには空でないキーが必要です。同じキーを複数回指定した場合は、最後の値が使用されます。
Corgeaのウェブアプリでは、スキャンメタデータはScansページ、スキャン詳細、問題の詳細に読み取り専用のラベルとして表示されます。
has:keyとkey:valueも使えます。例: has:pipeline_urlやenvironment:production。
- Blast Base AIスキャン
- PolicyIQスキャン
- 悪意のあるコード検出スキャン
- シークレット検出スキャン
- 個人識別情報(PII)検出スキャン
--scan-typeオプションを使用すると、1つ以上のスキャンタイプだけを対象にできます。
--policyオプションに1つ以上のポリシーIDを指定します。
--scan-typeと--policyはBLASTスキャンにのみ適用されます。--scan-type policyなしで--policyを指定すると、ほかのBLASTスキャンタイプも実行され、警告が表示されます。
コンテナイメージをスキャン
デフォルトでは、CorgeaはプロジェクトのDockerfileやDocker Composeファイルが参照しているイメージを検出します。代わりにビルド済みのイメージ、たとえばCIでビルドしたばかりでレジストリにプッシュしていないイメージをスキャンするには、--include-imageで渡します。
--include-imageを指定した場合、Corgeaはソースコードからベースイメージを探す代わりに、指定されたイメージをスキャンします。
要件と動作:
- コンテナスキャンがアカウントで有効になっている必要があります。
dockerまたはpodmanがPATH上にある必要があります。Corgeaは最初に見つかったものを使用します。明示的に指定するにはCORGEA_CONTAINER_ENGINEを設定します。- ローカルに存在しないイメージは事前にプルされます。そのため、コンテナエンジンが認証済みであれば、プライベートレジストリのイメージも利用できます。
--include-imageはBLASTスキャナーでのみ使用できます。
スキャンレポートをエクスポート
Corgea CLIではスキャン結果をファイルにエクスポートできます。これは特にCIパイプライン内で実行する場合に便利です。--out-formatオプションと--out-fileオプションを使用します。
--sbomを追加すると完了後にCycloneDX SBOMが生成されます。デフォルトはbom.jsonで、別のパスも指定できます。
--failと--block-onが評価される前に書き出されます。ブロッキングルールに該当してゼロ以外の終了コードで終わったスキャンでも、レポートとSBOMはディスクに残るため、後続のCIステップから必ず取り込めます。
同じコミットの最近のスキャンを再利用
変更のないコミットで再実行されるパイプラインでは、重複したスキャンを実行する代わりに、Corgeaが既に保持しているスキャンを再利用できます。BLASTスキャンに--skip-if-commit-scanned-recentlyを追加します。
--block-onのゲートとその終了コード、--out-fileのレポートはすべてそのスキャンから生成されます。実際にスキャンが実行されたかどうかにかかわらず、パイプラインの挙動は同じです。
期間は--scanned-withinで指定します。このオプションは--skip-if-commit-scanned-recentlyと一緒にのみ指定できます。90s、30m、24h、7dのような値を指定でき、単位のない数値は時間として解釈されます。デフォルトは24hです。コードが変わっていなくても、前回のスキャン以降に公開されたアドバイザリーの影響を受ける可能性があるためです。
worktree_dirty=trueを記録している場合でも最近のスキャンを再利用するには、--ignore-dirty-worktree（CLI 1.11.1以降）を指定します。このフラグは--skip-if-commit-scanned-recentlyと一緒にのみ使用できます。新規スキャンでは、実際のダーティ状態がそのままCorgeaに報告されます。
CORGEA_SCAN_SKIPPED=trueとCORGEA_SCAN_ID=<id>が、スキャンを実行した場合はCORGEA_SCAN_SKIPPED=falseが出力されます。これらは環境変数ではなく、標準出力のマーカーです。現在のコミットを解決できずにコマンドが終了した場合は出力されません。再利用の確認でAPIに到達できない場合、CLIは警告を出して新しいスキャンを実行します。
再利用できるスキャン。 Corgeaは同じ条件を満たすスキャンのみを再利用します。これはコミットが一致するだけでは足りません。対象となるのは、現在のコミットに対する完了済みのBLASTスキャンで、プルリクエストではなくブランチ上で実行され、変更のないワークツリーから作成され、スキャナーの問題が報告されていないものです。それ以外の場合は実際のスキャンが実行されます。期間内に該当するスキャンがない場合、既存のスキャンが失敗しているか実行中の場合、ワークツリーがコミットと一致しない場合などです。--ignore-dirty-worktreeは、その判定のうちダーティなワークツリーに関する部分を上書きします。現在のワークツリーがダーティな場合や、以前のスキャンがworktree_dirty=trueを記録している場合でも再利用されます。フラグを一度も報告していない以前のスキャンは、対象範囲が不明なため、引き続き再利用されません。
併用できないオプション。 過去のスキャンがどの範囲を対象にしていたかを知るAPIはありません。そのため--skip-if-commit-scanned-recentlyは--only-uncommitted、--target、--scan-type、--policy、--include-imageと併用できず、これらを指定するとコマンドは失敗します。--excludeは指定できますが、スキャンを再利用した場合は警告が表示されます。再利用されたスキャンは今回の実行が除外したファイルも含むため、結果は過剰に報告されることはあっても、不足することはありません。
現在のコミットを解決できない場合、たとえばディレクトリがGitリポジトリでない場合やリポジトリにまだコミットがない場合は、暗黙的に全体スキャンを実行するのではなく、ゼロ以外の終了コードで終了します。
スキャンを再利用した場合でも、--sbomは再利用されたスキャンの過去のSBOMではなく、現在のワークスペースを反映します。
依存関係インベントリ
corgea depsを使用して、npm、Python、Javaのマニフェストとロックファイルからオフラインの依存関係インベントリを作成します。このコマンドは依存関係のバージョン固定ポリシーを評価し、検出結果に基づいてCIを失敗させることができます。ログインやネットワークアクセスは必要ありません。
scan、graph、explain、diff、policy initのターミナル出力は、--format human、agent、json、quietのいずれかで制御できます。エージェント環境が検出された場合、corgea depsはデフォルトで簡潔なagent形式を使用します。通常のターミナル出力を使用するには、--format humanを指定します。
corgea deps scanでレポートをエクスポートする場合は、--out-format table、json、sarifのいずれかを使用し、必要に応じて--out-fileを指定します。同じdeps scanコマンドで--formatと--out-formatを併用することはできません。
依存関係ポリシーをカスタマイズするには、.corgea/deps.ymlを初期化します。
latest、SemVer範囲を使用する直接依存関係を報告するかを制御できます。CIの例、ポリシー設定、トラブルシューティングについては、依存関係スキャンを参照してください。
スキャンを待つ
最新の進行中のスキャンを待つために:corgea wait、corgea scan、corgea upload --wait は、スキャンが失敗すると終了コード 1 を返し、その理由と問題を報告したスキャナーを出力します。いずれかのスキャナーの結果が欠けたまま完了したスキャンは、警告とともに終了コード 0 を返します。
待機は10時間で終了します。最終ステータスを報告しないスキャンがCIジョブを無期限に占有しないようにするためです。タイムアウト時、コマンドは終了コード1で終了します。スキャン自体はCorgeaクラウドで実行され続けます。より長い待機が必要な場合は、CORGEA_SCAN_TIMEOUT_SECONDS に待機する秒数を設定してください:
--repo org/repo（またはURL）、正確なプロジェクト名には--project-nameを使用します。corgea wait SCAN_ID --project-id PROJECT_IDではプロジェクト解決を省略できます。
corgea scan、corgea wait、corgea upload --waitはいずれも、スキャンが失敗するとゼロ以外の終了コードで終了し、その理由と問題が発生したスキャナーを表示します。スキャナーが欠けた状態で完了したスキャンは、代わりに0で終了し、警告を表示します。
待機は10時間で打ち切られます。この上限はCORGEA_SCAN_TIMEOUT_SECONDSで変更できます。--failまたは--block-onを使用した場合、CLIはその後最大15分間ブロッキングルールの評価を待ちます。こちらはCORGEA_BLOCKING_RULES_TIMEOUT_SECONDSで変更できます。
スキャン、セキュリティ問題、SCA問題、コード品質問題の一覧表示
現在のディレクトリに関連するすべてのスキャンを一覧表示するには、次のコマンドを使用します（デフォルトではページ分割されます）。--json オプションは、 list や inspect などのコマンドでJSON形式の結果を出力するためのもので、統合や自動化に役立ちます。
N/Aと表示されます。JSON出力には、Corgeaから返された完全なgit_sha値、null許容のworktree_dirty値、およびスキャンのmetadataが含まれます。worktree_dirtyは、スキャンにコミットされていないローカル変更が含まれていた場合はtrueとなり、古いバージョンのCLIで作成されたスキャンではnullになることがあります。
プロジェクトまたはスキャンのSCA問題を一覧表示するには、--sca-issuesまたは短縮形の-cを使用します。表には各問題の分類が含まれ、JSON出力には提供されている場合にclassificationフィールドが含まれます。
--code-quality（または--quality/-q）を使用します。--scan-idで特定のスキャンに限定できます。
--repo org/repo（またはURL）、正確なプロジェクト名には--project-nameを使用します。
スキャンまたは問題の詳細を確認
特定のスキャンを調べる方法:Gitフックとの連携
コードの品質とセキュリティを確保するために、pre-commitフックを使ってCorgea CLIをGitワークフローに組み込めます。この機能により、コミットやプッシュの前にコードの変更をスキャンできます。pre-commitフックを設定するには、次のコマンドを実行します。環境変数
デバッグモード
デバッグログを有効にするには、コマンドを実行する前にCORGEA_DEBUG=1 を設定してください。