SCANOSS GitHub Actionsでコードスキャンを自動化

前回の記事ではSCANOSS CLIを使ったローカルスキャンの手順を紹介しました。ローカルで動作確認ができたら、次はCI/CDパイプラインへの統合です。

本記事では、SCANOSS Code Scan Actionを使ったGitHub Actionsでのコードスキャン自動化の手順を紹介します。

この記事でわかること:

• GitHub Actionsでの基本的なスキャン設定と実行方法
• ポリシーチェック（Copyleft / Undeclared）の設定と挙動
• API Keyあり/なしの挙動差（GitHub ActionsではAPI Key必須）
• scanoss.jsonによるスキャン結果の制御とポリシーチェックへの影響
• サブディレクトリスキャンやスキャンチューニングの活用方法

前提条件

• GitHubリポジトリにActions実行権限があること
• SCANOSS API Keyを取得済みであること（SCANOSSとの契約が必要）
• リポジトリのSettings > Secrets にSCANOSS_KEYを登録済みであること

基本スキャン（Non-Policy）

最もシンプルな構成です。ポリシーチェックなしで、コードスキャンのみを実行します。

# .github/workflows/scanoss-scan.yml
name: SCANOSS Security Scan
on:
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  checks: write
  actions: read

jobs:
  scanoss-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: scanoss/gha-code-scan@v1.5.0
      with:
        api.key: ${{ secrets.SCANOSS_KEY }}

実行すると、以下のArtifactが自動生成されます。

今回の検証では、実行時間は約33秒でした（Docker imageのpull含む）。

ポリシーチェック付きスキャン（Full Policy）

ライセンスポリシーの自動チェックを有効にする構成です。

- uses: scanoss/gha-code-scan@v1.5.0
  with:
    policies: copyleft, undeclared, dt
    matchAnnotations: false
    api.key: ${{ secrets.SCANOSS_KEY }}

チェック結果はGitHubのChecks APIを通じてCheck Runとして表示されます。今回の検証では、Copyleft: success、Undeclared: success、Dependency Track: failure（サーバー未構築のため）という結果でした。

matchAnnotationsはスニペットマッチ検出時にコミットコメントを自動作成する機能です。デフォルトはtrueで、不要な場合はfalseを指定してください。

Dependency Trackポリシーについて

dt（Dependency Track）ポリシーを使うには、Dependency Trackサーバーの構築と以下のパラメータ設定が必要です。

• deptrack.url
• deptrack.apikey
• deptrack.projectid（またはdeptrack.projectname + deptrack.projectversion）

設定がない場合はwarningが出ますが、ワークフロー全体はsuccessで完了します。Dependency Track連携が不要であれば、policies: copyleft, undeclaredのようにdtを外しても問題ありません。

API Keyは必須

ローカルスキャンではAPI Keyなしでも動作しましたが、GitHub ActionsではAPI Keyが必須です。

API Keyなしで実行した場合、以下のエラーが即座に返されます。

ERROR: SCANOSS API rejected the scan request due to service limits being exceeded
ERROR: Details: {"error":"Rate limit exceeded","retry_after":411781}

retry_afterの値は約411,788秒（約5日）です。つまり約5日に1回しかリクエストできない計算になります。GitHub Actionsの共有IPからの無料APIへのアクセスがレート制限に達しているため、API Keyなしでは実質的にスキャンできません。（お試しでは十分です！あとは週次スキャンには対応できますね…）

サブディレクトリスキャン

scanPathパラメータで、スキャン対象をリポジトリの特定ディレクトリに限定できます。

- uses: scanoss/gha-code-scan@v1.5.0
  with:
    scanPath: ./application
    api.key: ${{ secrets.SCANOSS_KEY }}

今回の検証では、ルートスキャンとサブディレクトリスキャンでスキャン結果が大きく変わりました。

ルートスキャンではMarkdown等のドキュメントファイルが大量に含まれるため、コードファイルのスニペットマッチがfilteredされていました。scanPathでコードディレクトリのみに絞ることで、検出精度が向上します。モノレポ構成では積極的に活用してください。

なお、scanPathを指定するとscanoss.jsonの読み込みパスも変わります。詳しくは後述の「scanoss.jsonによるスキャン制御」セクションを参照してください。

scanoss.jsonによるスキャン制御

リポジトリにscanoss.jsonを配置すると、スキャン結果のフィルタリングやポリシーチェックの挙動を制御できます。GitHub Actionsではデフォルトで自動読み込みが有効（scanossSettings: true）になっているため、ファイルを配置するだけで設定が反映されます。

読み込みの仕組み

scanoss.jsonはスキャン対象ディレクトリの直下から自動的に読み込まれます。

scanPathを指定している場合、ルートのscanoss.jsonは読み込まれません。settingsFilepathパラメータで明示的にパスを指定するか、scanPathで指定したディレクトリにscanoss.jsonを配置してください。

設定できる内容

scanoss.jsonでは以下の3つの制御が可能です（公式ドキュメント）。

{
  "bom": {
    "include": [
      { "purl": "pkg:github/owner/repo", "comment": "宣言済みコンポーネント" }
    ],
    "remove": [
      { "path": "src/app.py", "purl": "pkg:github/owner/repo", "comment": "誤検出" }
    ]
  },
  "skip": {
    "patterns": ["*.pyc", "__pycache__/**", "docs/**"]
  },
  "settings": {
    "file_snippet": {
      "min_snippet_hits": 3,
      "min_snippet_lines": 5,
      "ranking_enabled": true,
      "ranking_threshold": 5,
      "honour_file_exts": true
    }
  }
}

Undeclaredポリシーとの連携

undeclaredポリシーは、スキャンで検出されたOSSコンポーネントがbom.includeで宣言されていない場合に違反として報告します。

運用の流れは以下の通りです。

1. Full Policyスキャンを実行し、Undeclared違反が報告される
2. 違反コンポーネントのPURLをスキャン結果から確認する
3. 正しく使用しているものであれば、bom.includeにPURLを追加する
4. 再スキャンでUndeclared違反が解消されることを確認する

スキャンチューニング（v1.5.0）

v1.5.0から、scanoss.jsonのsettings.file_snippetセクションでスニペットマッチの感度を調整できるようになりました。最小ヒット数や最小行数の閾値を設定することで、誤検出を減らすことができます。

チューニングパラメータはGitHub Actionの入力パラメータではなく、scanoss.jsonで設定します。詳細は公式ドキュメント（Scan Tuning Parameters）を参照してください。

推奨する運用フロー

1. scanoss.jsonなしでスキャンを実行し、検出結果を確認する
2. 誤検出があればbom.removeで除外、正規利用のOSSはbom.includeで宣言する
3. 不要なファイル（テストデータ、ドキュメント等）はskip.patternsで除外する
4. スニペットの誤検出が多い場合はsettings.file_snippetで感度を調整する
5. scanoss.jsonをリポジトリにコミットし、以降のCI/CDスキャンに反映させる

段階的な導入ステップ

1. API Keyの準備: SCANOSSとの契約後、GitHub SecretsにSCANOSS_KEYを登録
2. Non-Policyで開始: 基本スキャンで動作確認（workflow_dispatchトリガー）
3. 結果の確認: Artifactからscanoss-raw.jsonをダウンロードして内容確認
4. Full Policyに拡張: policies: copyleft, undeclaredを追加
5. チューニング: 誤検出が多い場合はscanoss.jsonで感度を調整
6. PRトリガーに変更: workflow_dispatch→pull_requestに変更して自動化

まとめ

SCANOSS GitHub Actionsを使ったCI/CDでのコードスキャン自動化の手順を紹介しました。

参考資料

関連リンク

• SCANOSS Code Scan Action（GitHub リポジトリ）
• SCANOSS Code Scan Action（GitHub Marketplace）
• SCANOSS 公式ドキュメント
• scanoss-py 公式ドキュメント
• SCANOSS Pricing
• Dependency Track