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

サイオステクノロジーは、OSS管理ツール「SCANOSS」の日本国内初の代理店です。

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

本記事では、SCANOSS Code Scan Actionを使ったGitHub Actionsでのコードスキャン自動化の手順を紹介します。公式のREADMEは入力パラメータの一覧が中心で、「どれを組み合わせると何が起きるか」までは書かれていません。そこを埋めるリファレンスとして書いています。

この記事でわかること:

• GitHub Actionsでの基本的なスキャン設定と実行方法
• ポリシーチェック（Copyleft / Undeclared）の設定と、Check Runに何が出るか
• Dependency Trackとは何をするもので、Actionはそのどこを担当するのか
• API Keyあり/なしの挙動差（鍵なしでどこまで動くか）
• スキャン範囲の絞り方（scanPathと、変更ファイルだけを見るscanMode: delta）
• scanoss.jsonをActionがどこから読むか（scanPathを指定すると変わります）
• 観察モードから始めて、あとからゲートを固める手順

前提条件

• GitHubリポジトリにActions実行権限があること
• SCANOSS API Keyを取得済みであること（SCANOSSとの契約が必要。⚠️ 試すだけなら無くても動きます。後述）
• リポジトリのSettings > Secrets にSCANOSS_KEYを登録済みであること

本文中の例は、メジャーバージョンの移動タグ@v1を指しています。SCANOSSはv1タグをメジャーバージョンの最新に付け替えて運用しており、執筆時点ではv1.7.0（2026-06-25）と同じコミットを指しています。バージョンを固定したい場合は@v1.7.0のようにパッチまで書いてください。本記事の記述はv1.7.0（スキャンに使うscanoss-pyはv1.54.2）で確認しています。

基本スキャン（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
      with:
        api.key: ${{ secrets.SCANOSS_KEY }}

外部に送られるのはソースコードそのものではありません。 Actionはコンテナ内でscanoss-pyを実行し、ファイルから生成したフィンガープリント（WFP）をAPIに送って照合します。ファイルの中身がアップロードされるわけではないので、CIのログやArtifactに出るのも照合の結果だけです。仕組みは前回の記事で扱っています。

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

CycloneDXとSPDXそれぞれの仕様の違いは「SBOMの仕様：CycloneDX（CDX）・SPDX」で解説しています。

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

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

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

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

policiesに並べたぶんだけ、チェックが1本ずつ立ちます。copyleft, undeclaredなら2本、dtも足せば3本です。判定はワークフローの成否ではなくこのチェックのほうに出るので、何がどう見えるかを先に押さえておきます。

ポリシーの結果はどこに出るか

判定の本体はChecks APIのCheck Runです。 ポリシーごとに1本ずつ立ち、Policy Check: Copyleft / Policy Check: Undeclaredという名前になります（scanPathを指定した場合は名前の末尾にそのパスが付きます）。

Pull Requestで動かしたときは、これに加えてPRにコメントも貼られます。 検出件数のサマリー（SCANOSS SCAN Completed）と、ファイル丸ごと一致があったときの一覧（SCANOSS Code Similarity Detected）の2本です。pushやworkflow_dispatchで動かしたときは貼られません。ジョブを複数に分けていると、その本数だけコメントが増えます。

検出が無ければ、summaryは1行だけです。

Policy Check: Copyleft     conclusion: success
  ### :white_check_mark: Policy Pass
  #### No copyleft licenses were found

検出があった場合は、scanoss-py inspectが出したMarkdownの表がそのままsummaryに入ります。

Policy Check: Copyleft     conclusion: neutral
  ### Copyleft Licenses
   | Component | License | URL | Copyleft |
   | - | :-: | - | - |
   | pkg:pypi/mysqlclient | GPL-2.0-or-later | https://spdx.org/licenses/GPL-2.0-or-later.html | YES |

上の例のneutralは観察モードでの見え方です。 既定ではポリシー違反時のconclusionはaction_requiredになり、PRに「対応が必要」と表示されます。切り替えは次節のpolicies.halt_on_failureで行います。

Undeclaredが違反したときは、検出コンポーネントの一覧に加えてQuick Fixが付きます。scanoss.jsonのJSONスニペットと、そのファイルを編集する（無ければ作る）GitHubのリンクです。スニペットは差分ではなく、既存の設定を保ったままマージされたファイル全体になっています。

ただし、Quick Fixが挙げてくるPURLにはコピーレフトのコンポーネントも含まれます。貼るとUndeclaredは通りますが、Copyleftの判定は動きません。宣言で閉じられるのは「気づいていなかった」という状態だけで、検出されたコードそのものは残ります。何をどう直すかはSCANOSS CLIの記事で扱っています。

止めるかどうかは2つのフラグで決まる

「違反が出たとき」と「実行そのものが失敗したとき」は別扱いで、決める入力も別です。 名前が似ていて混ざるので、ポリシーを足す時点で両方見ておいてください。

どちらもfalseにするとneutralになり、Check Run上は赤くなりません。

どちらのフラグでも、ワークフローのジョブ自体はsuccessで終わります。 止めるのはCheck Runの色だけです。実際にマージを止めるにはbranch protectionが要ります。観察から始めてゲートを固める手順は後述の「段階的な導入ステップ」で扱います。

dtを混ぜると、Dependency Trackサーバーを用意していない間はそのCheck Runだけがfailureになります。まずはpolicies: copyleft, undeclaredから始めるのが素直です。詳しくは次の節で扱います。

Dependency Trackとの連携

dtは他の2つと性質が違います。CopyleftとUndeclaredがスキャン結果そのものを見るのに対し、dtは外部のサーバーに問い合わせるポリシーです。前提となるものが多いので、節を分けて説明します。

Dependency Trackとは何をするものか

Dependency TrackはOWASPのプロジェクトで、SBOMを預けておくと、そこに載っているコンポーネントを継続的に監視してくれるサーバーです。自分たちでホストして使います。

スキャンは「実行した時点」の写真でしかありません。今日クリーンだったライブラリに、来週CVEが公表されることがあります。SBOMをDependency Trackに登録しておくと、新しい脆弱性情報が入ってきたときに、登録済みのプロジェクトに対して警告が出ます。

• CI側のスキャンは「これから入ってくるもの」の検査。PRのたびに走る
• Dependency Trackは「すでに入っているもの」の見張り。コードが変わらなくても状況が変わる

dtポリシーは、この見張り側で溜まっている違反をCIに引っ張ってくるための連携です。Dependency Trackを運用していない場合、このポリシーは指定しても意味がありません。

Actionが担当するのは2つ

Dependency Track連携には、まったく別の2つの入力が関わります。ここが混ざりやすいところです。

policies: dtを書いてもSBOMは送られません。 アップロードはdeptrack.upload: trueが担当します。片方だけ有効にすると、Actionは「古いデータを見ている可能性がある」旨の警告をCheck Runのsummaryに足してきます。監視まで含めて回したいなら両方を有効にしてください。

- uses: scanoss/gha-code-scan@v1
  with:
    policies: copyleft, undeclared, dt
    deptrack.upload: true
    deptrack.url: ${{ secrets.DEPTRACK_URL }}
    deptrack.apikey: ${{ secrets.DEPTRACK_APIKEY }}
    deptrack.projectname: my-service
    deptrack.projectversion: main
    api.key: ${{ secrets.SCANOSS_KEY }}

必要なパラメータ

• deptrack.url — Dependency TrackのベースURL（http://またはhttps://で始まること）
• deptrack.apikey — Dependency TrackのAPIキー
• deptrack.projectid、またはdeptrack.projectname + deptrack.projectversionの両方

プロジェクトの指定は「IDで直接指す」か「名前とバージョンで指す」かのどちらかです。projectnameだけ、projectversionだけ、といった中途半端な指定は設定エラーとして扱われます。

設定を間違えたときの見え方

パラメータが足りない場合も、サーバーに繋がらない場合も、Dependency TrackのCheck Runだけがfailureになり、ワークフローのジョブ自体はsuccessで完了します。ジョブのログだけを見ていると気づきません。

Check Runには原因が出ます。deptrack.*を1つも渡さずにpoliciesへdtだけ足すと、こうなります。

Policy Check: Dependency Track     conclusion: failure
  ### :warning: Configuration Error
  #### Dependency Track policy check misconfigured

  Dependency Track Policy Check Failed: Required parameters are missing.
  Missing: deptrack.url, deptrack.apikey,
           Either deptrack.projectid or BOTH deptrack.projectname AND deptrack.projectversion

サーバーに繋がらない場合も同じ形で出ます。接続失敗、認証失敗（401）、プロジェクトが見つからない、タイムアウトが区別されるので、まずここを見てください。

このfailureはhalt_on_errorの既定（true）による見え方です。 falseにすればここはneutralになり、赤くなりません。ポリシー違反側のpolicies.halt_on_failureとは別物です（前述の「止めるかどうかは2つのフラグで決まる」）。

Dependency Track連携が不要であれば、policies: copyleft, undeclaredのようにdtを外して構いません。

API Keyなしでどこまでできるか

api.keyを渡さないと、無料のOSSKBエンドポイント（api.osskb.org/scan/direct）が使われます。スキャンが通ることはあります。

// api.key なしで実行した結果（scanoss-raw.json）
{
  "in_scope.py": [
    { "id": "none", "server": { "kb_version": { "daily": "26.09.08" }, "version": "5.4.25" } }
  ]
}

ただしscanoss.jsonを読ませた瞬間に落ちます。

Loading settings file /scanoss/scanoss.json...
Warning: Error response code 400 (ERROR invalid scanning configuration) from https://api.osskb.org/scan/direct. Retrying...
（5回リトライして）
ERROR: The SCANOSS API returned the following error: HTTP 400, ERROR invalid scanning configuration.
Error: Scanning analysis ran into some trouble. Not producing results file.

bomを持たないsettingsだけのscanoss.jsonでも同じです。設定を伴うスキャンを無料エンドポイントが受け付けない、という切り分けです。

結果ファイルが作られないまま終わります。 400で中断したときはscanoss-raw.jsonが空のまま残るので、後続のステップで結果を読むように組んでいると、そこで初めて気づくことになります。「検出ゼロ」と見分けが付く形にしておいてください。

上の「成功」を「無料枠でCIを回せる」と読まないでください。 OSSKBの無料エンドポイントには実行回数ベースの利用制限があり、1回通ったからといって次も通るとは限りません。GitHub Actionsの共有IPからのアクセスが既に上限に達していて、Rate limit exceededで1回も実行できないこともあります。同じIPを多数の利用者が共有しているので、通るかどうかは実行するタイミング次第です。

鍵なしで確かめられるのはワークフローの配線が合っているかまでです。scanoss.jsonは運用に入れると必ず要りますし、PRのたびに回すなら回数制限のない経路も要るので、CIに定着させる段階でAPI Keyが必要になります。

スキャンする範囲を絞る

スキャン対象を絞る方法は2つあります。場所で絞る（scanPath）か、変更で絞る（scanMode: delta）かです。目的が違うので、順に見ていきます。

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

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

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

絞る意味は2つあります。スキャンの対象が減るぶん速くなることと、ポリシーの範囲がそのディレクトリに閉じることです。モノレポのようにコンポーネントごとに判断を分けたい構成では、後者のほうが効いてきます。

絞る前と後で検出結果そのものが変わることがあります。 ドキュメントや生成物の比率が高いリポジトリほど差が出ます。どう変わるかはリポジトリの中身次第なので、導入時にルートと対象ディレクトリを1回ずつ流して比べてください。

scanoss.jsonの読み込み位置も変わる

scanoss.jsonは、スキャン対象ディレクトリの直下から読まれます。

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

変更されたファイルだけスキャンする（scanMode: delta）

scanMode: deltaを指定すると、そのPull Request（またはpush）で変更されたファイルだけをスキャンします。リポジトリが大きくなるほど、1回あたりのスキャン時間とAPIへの問い合わせ量が減ります。

- uses: scanoss/gha-code-scan@v1
  with:
    scanMode: delta
    policies: copyleft, undeclared
    api.key: ${{ secrets.SCANOSS_KEY }}

内部の動きは3ステップです。

1. GitHub APIから、そのPR（またはpush）の変更ファイル一覧を取得する
2. その一覧をscanoss-py delta copyに渡し、delta-xxxxxxxx/という作業ディレクトリへコピーする
3. そのディレクトリだけをスキャンする

コピー先ではリポジトリ内の相対パス構造がそのまま保たれます。src/lib/format.pyを変更した場合、delta-xxxxxxxx/src/lib/format.pyとして置かれ、スキャン結果に出るパスはsrc/lib/format.pyのままです。scanoss.jsonでパスを指定したルールも、そのまま効きます。

押さえておく点をまとめます。

scanPathとの併用には穴がある

scanMode: deltaとscanPathは併用できません。 deltaの実装は、変更ファイルをGitHub APIから取得して変更種別（added / modified / renamed）で絞るだけで、パスによる絞り込みを行いません。作られたdeltaディレクトリがそのままスキャン対象になるので、scanPathで指定したはずのディレクトリ外のファイルも一緒に見られます。

scanPath: verify/scopedを指定したうえで、その外側のファイルも変更して流したときの結果です。

# 結果 JSON（scanoss-raw.json）のキー = 実際にスキャンされたファイル
verify/outside/out_of_scope.py     <- scanPath の外側。入ってしまっている
verify/scoped/in_scope.py

Check Runの名前はscanPathを名乗ります。 上の実行でもPolicy Check: Copyleft - verify/scopedという名前で立ち、summaryにも(📁 verify/scoped)と出ます。名前が示す範囲と、実際に見た範囲がずれます。

モノレポでコンポーネントごとにジョブを分けている場合、これは実害になります。scanPath: application/backendのジョブが、application/frontend配下の変更ファイルまでスキャンしてしまい、backendのscanoss.jsonでfrontendのファイルが判定されます。Copyleftは宣言に依存しないので結論は変わりませんが、Undeclaredは宣言に依存するので誤検出します。観察モードのうちは気づきにくく、ハードゲートに切り替えた瞬間に誤ブロックとして出てきます。

Actionの入力で直す口はありません。「コンポーネントごとに見る」と「変更ファイルだけ見る」は、このActionでは両立しません。

コンポーネントごとに分けるほうを採るなら、変更検出はdeltaではなくパスフィルタに任せることになります。⚠️ ただしパスフィルタが絞るのは発火であって、スキャンの中身ではありません。 発火したジョブは自分のscanPathをまるごとフルスキャンします。範囲はずれませんが、変更ファイル単位まで軽くなるわけではない、という妥協です。その構成は「SCANOSS GitHub Actions モノレポ対応：変更コンポーネントだけスキャンする構成」で解説しています。

ブランチを切った最初のpushは必ず落ちる

pushトリガでdeltaを使う場合、ブランチを新規作成したpushだけは必ず失敗します。新規ブランチのpushではgithub.event.beforeが全ゼロになり、Actionがそれをそのまま「比較元」としてGitHub APIに渡すためです。

before=0000000000000000000000000000000000000000 after=b95ab60...
Delta scan mode enabled, preparing delta directory...
Fetching changed files from push commit...
##[error]Failed to prepare delta scan: Failed to fetch changed files from GitHub API: Not Found

フルスキャンにフォールバックしません。 「変更が0件ならフル」の逃げ道は一覧を取得できたうえで0件だったときのもので、取得そのものが失敗したときはジョブが落ちます。pushでdeltaを回すなら、ブランチ作成時はscanModeをfullに落とすか、pull_requestトリガに寄せてください。

ブランチ作成時の話はここまでです。トリガに関係なく、deltaを使うなら気をつけておくことがもう2つあります。

集める先をドット始まりのディレクトリにしないでください。 scanoss-pyはドットで始まるディレクトリ配下を丸ごと対象外にするため、.scanoss-delta/のような名前にすると結果が常に0件になり、「見て0件だった」と「そもそも見ていない」の区別がつかなくなります。

deltaは「速いフルスキャン」ではありません。 触っていないファイルは見ないので、過去に混入したコードは検出されません。導入時に1回はフルスキャンを流して現状を把握し、以降の日常的なPRチェックをdeltaにする、という組み合わせが現実的です。定期的に（週次など）フルスキャンを別ワークフローで回しておくと、取りこぼしを拾えます。

段階的な導入ステップ

いきなりPRを止める設定にすると、最初の1回で開発が詰まります。まずポリシーを観察モードで回して、何がどれだけ出るかを見てから固めてください。

観察モードへの切り替えはpolicies.halt_on_failureです。

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

どちらでもジョブ自体は緑です。 ポリシー違反はCheck Runのconclusionを変えるだけで、ワークフローを失敗させません。実際にマージを止めたいなら、branch protectionでこのCheck Runをrequired checkに指定する必要があります。halt_on_failure: trueにしただけでは、赤いチェックが1つ増えるだけでマージはできてしまいます。指定の手順はRequire status checks before mergingにあります。

デフォルトはtrueです。 policiesを足した時点でゲートになります。観察から始めたいなら、policiesと一緒にpolicies.halt_on_failure: falseも書いてください。

順序としては以下になります。

1. API Keyの準備: SCANOSSとの契約後、GitHub SecretsにSCANOSS_KEYを登録
2. Non-Policyで開始: 基本スキャンで動作確認（workflow_dispatchトリガー）
3. 結果の確認: Artifactからscanoss-raw.jsonをダウンロードして内容確認
4. 観察モードでポリシーを追加: policies: copyleft, undeclaredとpolicies.halt_on_failure: false
5. チューニング: 誤検出が多い場合はscanoss.jsonで調整し、出る件数を落ち着かせる（書き方はSCANOSS CLIの記事）
6. PRトリガーに変更: workflow_dispatch→pull_requestに変更して自動化
7. deltaに切り替え: 日常のPRチェックをscanMode: deltaにし、フルスキャンは定期実行に回す
8. ゲートを固める: policies.halt_on_failureを外す（デフォルトのtrueに戻す）

入力パラメータ一覧

v1.7.0時点の入力パラメータと既定値です。入力名と既定値の正本はActionのaction.ymlなので、新しい版での増減はそちらで確認してください。

まとめ

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

検出結果の読み方と、scanoss.jsonでの対処（宣言・除外・差し替え）は「SCANOSS CLIでローカルスキャン：インストールからSBOM生成まで」で扱っています。

モノレポで、変更のあったコンポーネントのワークフローだけを発火させる構成は「SCANOSS GitHub Actions モノレポ対応：変更コンポーネントだけスキャンする構成」で解説しています。

参考資料

関連リンク

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