CLI
ガイド
Scanverra CLI
@scanverra/cliを使えば、ターミナルやCIパイプラインから任意のコードベースをスキャンできます。スキャンは自分のマシン上で実行され、Scanverraに送信されるのはスキャン結果のみです。
クイックスタート
グローバルに何もインストールする必要はありません。scanverraコマンドを常設したい場合はnpm i -g @scanverra/cliを実行してください。
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
仕組み
常に最新
個別にCLIのバージョンを管理したり手動でアップグレードしたりすることなく、常に最新のチェックが実行されます。
ダッシュボードと同じエンジン
どこで実行しても、Scanverraで開始したスキャンと同じ結果になります。
ローカルでスキャン
ソースファイルは自分のマシン上で読み込まれます。デフォルトではScanverraに送信されるのはスキャン結果のみで、ファイルの内容や該当したコード行は送信されません。
ダッシュボードに表示される
各スキャンにはAIが作成した要約とリンクが付き、ダッシュボードから開始したスキャンと同じ結果ページが表示されます。
コマンド
| コマンド | 説明 |
|---|---|
scanverra login | APIキーを確認して保存する |
scanverra logout | 保存済みのキーを削除する |
scanverra whoami | キーに紐づくアカウントとプランを表示する |
scanverra scan [path] | フォルダをスキャンし（デフォルトはカレントフォルダ）、結果を表示してアップロードする |
主なオプション
| オプション | 説明 |
|---|---|
--json / --sarif | 機械可読な出力。SARIFはGitHub code scanningやSonarのインポートに対応 |
--fail-on <severity> | この重大度以上の結果があれば失敗として終了する（デフォルト: high） |
--category <list> | security、dependency、iac、qualityのいずれかの結果のみを含める |
--exclude <glob> | 一致するパスをスキップする。.scanverraignoreファイルも同様に機能する |
--no-upload | スキャンのみを行い、結果をScanverraに送信しない |
--include-code | 各結果の該当コード行もアップロードする（デフォルトでは無効） |
--offline | ネットワーク通信を行わず、キャッシュ済みのルールを使用する |
--api-key, --api-url | 認証情報やサーバーを上書きする。CIで便利 |
アップロードされる内容
ファイルパス、行番号、ルールID、タイトル、説明、修正提案、重大度、依存パッケージ名とバージョン、およびプロジェクト名、ブランチ、コミット、PR番号。
ファイルの内容、および各結果の該当コード行。シークレットの検出結果にシークレットの値そのものが含まれることはありません。ダッシュボードで該当行を表示したい場合は--include-codeを指定してください。
対象ファイルの選び方
- Gitリポジトリ内では追跡済み・未追跡のファイルが対象となり、.gitignoreが尊重されます。Git外では一般的なビルドフォルダや依存関係フォルダはスキップされます。
- .scanverraignoreファイル（1行に1つのglobパターン）と、繰り返し指定できる--excludeフラグで、さらに除外を追加できます。
- 対象行の直前にscanverra-ignoreまたはnosecコメントを置くと、その1件の結果を抑制できます。
終了コード
| 0 | 成功。--fail-onのしきい値に達した結果はありません |
| 1 | しきい値に達した結果があった、または--fail-on-gateでquality gateが失敗した |
| 2 | 使用方法のエラー、またはサーバーがキーかプランを拒否した |
CIでの利用
他のScanverra CI連携と同様にAPIキーをシークレットとして保存し、新しいランナーが毎回ルールを再ダウンロードしないようルールフォルダをキャッシュしてください。
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npx @scanverra/cli scan . --fail-on high
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}実行間でルールをキャッシュする
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-トラブルシューティング
| メッセージ | 対処方法 |
|---|---|
Not logged in | scanverra loginを実行するか、SCANVERRA_API_KEYを設定してください |
API key was rejected | キーが間違っているか失効しています。API Keysで新しいキーを作成してください |
Requires a Pro, Team or Enterprise plan | プランをアップグレードしてから再度お試しください |
Daily limit for downloading the scanner rules reached | 上記の通りCIでルールフォルダをキャッシュしてください |
No scannable files found | パスと.gitignoreまたは.scanverraignoreを確認してください |
ターミナルからスキャンする準備はできましたか？
APIキーを発行して、1分以内に最初のスキャンを実行しましょう。