コード スキャン

GitHub Advanced Security for Azure DevOps のコード スキャンを使用すると、Azure DevOps リポジトリ内のコードを分析して、セキュリティの脆弱性やコーディング エラーを見つけることができます。 分析によって特定された問題は、アラートとして発生します。 コード スキャンでは、CodeQL を使用して脆弱性を特定します。

CodeQL は、セキュリティ チェックを自動化するために GitHub によって開発されたコード分析エンジンです。 CodeQL を使用してコードを分析し、結果をコード スキャン アラートとして表示できます。

GitHub Advanced Security for Azure DevOps は、Azure Repos と連携して動作します。 GitHub リポジトリで GitHub Advanced Security を使用する場合は、「GitHub Advanced Security」を参照してください。

CodeQL アラート

GitHub の専門家、セキュリティ研究者、コミュニティの共同作成者が、コード スキャンに使用される既定の CodeQL クエリを作成し、維持しています。 クエリは、分析を改善し、誤検知の結果を減らすために定期的に更新されます。 クエリはオープンソースであるため、github/codeql リポジトリ内のクエリを表示したり投稿したりできます。

CodeQL に関するより具体的なドキュメントについては、GitHub の CodeQL ドキュメントを参照してください。

CodeQL ではコンパイル済みおよびインタープリターの両方の言語をサポートし、サポートされている言語で記述されたコード内の脆弱性とエラーを検出できます。

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Kotlin (ベータ)
• Python
• Ruby
• Swift

詳細については、「サポートされている言語とフレームワーク」で CodeQL Web サイトのドキュメントを参照してください。

依存関係スキャンと同様に、ビルド ログを調べると、CodeQL で使用される特定のクエリとタスクの詳細を表示できます。

コード スキャンのアラート

GitHub Advanced Security for Azure DevOps コード スキャン アラートには、コード レベルのアプリケーションの脆弱性を警告するリポジトリ別のコード スキャン フラグが含まれています。

コード スキャンを使用するには、まず GitHub Advanced Security for Azure DevOps を構成する必要があります。

Azure DevOps の [Repos] の下にある [Advanced Security] タブは、コード スキャン アラートを表示するためのハブです。 [コード スキャン] タブを選択して、スキャン アラートを表示します。 ブランチ、状態、パイプライン、ルールの種類、重大度ごとにフィルター処理できます。 現時点では、アラート ハブには、PR ブランチで完了したスキャンに関するアラートは表示されません。

パイプラインまたはブランチの名前が変更されても、結果に影響はありません。新しい名前が表示されるまでに最大 24 時間かかる場合があります。

カスタム CodeQL クエリを実行する場合、既定では、異なるクエリ パックから生成されたアラートに対して個別のフィルターはありません。 ルールでフィルター処理でき、これはクエリごとに異なります。

リポジトリの Advanced Security をオフにすると、[高度なセキュリティ] タブ内の結果と、[タスクの構築] にアクセスできなくなります。 タスクの構築は失敗しませんが、Advanced Security が無効になっている状態でタスクが実行した構築の結果はすべて非表示になり、保持されません。

[アラートの詳細]

アラートを選択すると、修復ガイダンスなどの詳細を確認できます。 各アラートには、場所、説明、例、重大度が含まれます。

セクション	説明
場所	[場所] セクションには、CodeQL が脆弱性を検出した特定のインスタンスについての詳しい説明があります。 同じルールに違反しているコードのインスタンスが複数ある場合は、異なる場所ごとに新しいアラートが生成されます。 [場所] カードには、影響を受けるコード スニペットへの直接リンクが含まれているため、スニペットを選択して Azure DevOps Web UI に移動して編集することができます。
説明	この説明は、問題に基づいて CodeQL ツールによって提供されます。
推奨	推奨事項は、特定のコード スキャン アラートに対して推奨される修正プログラムです。
例	例のセクションでは、コード内で特定された弱点の簡略化された例を示します。
重大度	重大度レベルは、低、中、高、クリティカルのいずれかになります。 重大度スコアは、特定の共通脆弱性タイプ一覧 (CWE) に与えられた共通脆弱性評価システム (CVSS) スコアに基づいています。 重大度のスコア付け方法の詳細については、こちらの GitHub ブログ記事を参照してください。

コード スキャン アラートを管理する

リポジトリのアラートの表示

リポジトリの共同作成者アクセス許可を持つすべてのユーザーは、[Repos] の下の [Advanced Security] タブで、リポジトリのすべてのアラートの概要を表示できます。 [コード スキャン] タブを選択して、すべてのシークレット スキャン アラートを表示します。

結果を表示するには、コード スキャン タスクを最初に実行する必要があります。 最初のスキャンが完了すると、検出されたすべての脆弱性が [Advanced Security] タブに表示されます。

既定では、アラート ページには、リポジトリの既定のブランチの依存関係スキャン結果が表示されます。

特定のアラートの状態には、他のブランチとパイプラインにアラートが存在する場合でも、既定のブランチと最新の実行パイプラインの状態が反映されます。

コード スキャン アラートの無視

アラートを無視するには、適切なアクセス許可が必要です。 既定では、プロジェクト管理者のみが Advanced Security のアラートを無視できます。

アラートを無視するには:

1. クローズするアラートに移動し、アラートを選択します。
2. [アラートを閉じる] ドロップダウンを選択します。
3. クローズする理由として [リスクの許容] または [誤検知] を選択します (まだ選択していない場合)。
4. [コメント] テキスト ボックスに、任意でコメントを追加します。
5. [閉じる] を選択してアラートを送信して閉じます。
6. アラートの状態が [オープン] から [クローズ] に変わり、無視の理由が表示されます。

これにより、選択したブランチのアラートのみが無視されます。 同じ脆弱性を含む他のブランチは、無視されるまでアクティブなままです。 以前に無視したアラートを手動で再度オープンにすることができます。

CodeQL でのカスタム クエリの使用

既定では、パイプラインのセットアップでカスタム構成ファイルを指定していない場合、CodeQL はコードを分析するために security-extended クエリ パックを実行します。 カスタム CodeQL クエリを使用して独自のクエリを記述し、特定の脆弱性とエラーを見つけることができます。 また、CodeQL の既定の分析を変更するためのカスタム構成ファイルを作成する必要もあります。

既存のカスタム クエリを検索したり、独自のカスタム クエリを投稿したりするには、「CodeQL に投稿する」を参照してください。

カスタム クエリを使用した分析

カスタム クエリから始める最も簡単な方法は、クエリを記述し、ローカルの Azure DevOps リポジトリに保存することです。 必要に応じてカスタム クエリの詳細をカスタマイズできますが、少なくともルール ID が必要です。 独自の CodeQL クエリを記述する方法の詳細については、「CodeQL クエリを記述する」を参照してください。 複数のクエリを 1 つのクエリ スイートにバンドルしたり、他のユーザーによって発行されたパックを利用したりすることもできます。 詳細については、「CodeQL パックを発行して使用する」を参照してください。

カスタム構成ファイルの使用

カスタム構成ファイルは、コードに対する CodeQL の分析中に実行されるクエリを管理する方法です。 実行する追加のクエリまたはクエリ パックを指定し、既定の CodeQL クエリを変更または無効にすることができます。

特定のクエリを含めるには、クエリの名前と、リポジトリ内のクエリ ファイル (.ql) の場所へのパスを指定します。

特定のパックを含めるには、パック名を指定します。 構成ファイルで実行する任意の数の CodeQL クエリ パックを指定できます。

ヒント

構成ファイルの packs フィルターは、GitHub でホストされているリポジトリからのパックのダウンロードをサポートしていますが、queries フィルターはそうではありません。 パックが GitHub で非公開の場合は、AdvancedSecurity-Codeql-Init@1 タスクで GitHub のアクセス トークンを環境変数として提供し、変数名を GITHUB_TOKEN、トークンのスコープを read:packages とする必要があります。

構成ファイルの例を次に示します。

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

ヒント

構成ファイルの仕様では、AdvancedSecurity-Codeql-Init@1 タスクのパイプライン レベルの構成が無視され、それよりも優先されます。 includepaths / ignorepaths は無視されるか、または paths/paths-ignore が存在する場合、paths/paths-ignore の値で上書きされます。 querysuite は、queries または構成ファイルの packs で指定された値で上書きされます。

構成ファイルに関するより具体的なアドバイスと構成オプションについては、「コード スキャンの詳細セットアップのカスタマイズ」を参照してください。

構成ファイルを取得したら、CodeQL 分析を実行するパイプラインをカスタマイズして、新しいファイルを利用します。 構成ファイルを指すサンプル パイプラインを次に示します。

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)
 
- task: AdvancedSecurity-Codeql-Autobuild@1
  displayName: AutoBuild
 
- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

code scanning のトラブルシューティング

通常、CodeQL の実行でエラーが発生した場合、CodeQL CLI は、実行する各コマンドのステータスを終了コードとして報告します。 終了コードは、後続のコマンドや、CodeQL CLI に依存する他のツールに関する情報を提供します。 終了コードについて詳しくは、「終了コード」をご覧ください。

エラー: 'database finalize' CodeQL コマンド (32)

このエラーは、CodeQL データベースの作成の最終処理に関する問題を示しています。抽出エラーまたはビルド手順の不足が原因の可能性があります。

トラブルシューティングの手順:

1. コードが存在し、コンパイルされていることを確認する
   • コンパイル済み言語の場合、ビルド プロセスがコードをコンパイルしており、AdvancedSecurity-Codeql-Init タスクと AdvancedSecurity-Codeql-Analyze タスクの間で発生していることを確認します。 一般的なビルド コマンドと必要なフラグ (clean no-cache/no-daemon など) については、こちらの「ビルド コマンドの指定」をご覧ください。
   • インタープリター型言語の場合、プロジェクトで指定された言語のソース コードがあることを確認します。
2. 抽出エラーの確認
   • 抽出エラーが CodeQL データベースの正常性に影響を与えるすかどうかを確認します。
   • ログ ファイルで抽出エラーと警告を確認し、データベースの全体的な正常性を評価します。
3. 圧倒的なエラーの調査
   • ほとんどのファイルで抽出エラーが発生した場合、さらに調査して、不適切な抽出の根本原因を把握してください。

エラー: 自動ビルド スクリプト (1)

このエラーは、自動ビルド エラーについて説明し、コード スキャンのセットアップまたは構成に関する問題を示しています。

トラブルシューティングの手順:

1. ビルド手順の構成
   • AutoBuild ステップを削除し、代わりにコンパイル済み言語の特定のビルド ステップをパイプラインで構成します。
   • 「GitHub Advanced Security for Azure DevOps の構成」で説明されているセットアップ ガイドラインをご覧ください。

エラー: エージェント ツール キャッシュに CodeQL ディレクトリが見つからない

このエラーは、セルフホステッド エージェントの CodeQL のインストールに関する問題を示しています。

トラブルシューティングの手順:

1. 「GitHub Advanced Security for Azure DevOps の構成」で説明されているセットアップ ガイドラインまたは構成スクリプトをご覧ください。

エラー: 言語パイプライン変数が設定されていない

このエラーは、スキャンする言語を指定するパイプライン変数を設定せずに CodeQL を実行しようとすると発生します。

トラブルシューティングの手順:

1. 言語パイプライン変数の設定
   • 言語パイプライン変数が正しく構成されていることを確認します。 「GitHub Advanced Security for Azure DevOps の構成」で説明されているセットアップ ガイドラインをご覧ください。
   • サポートされている言語には、csharp、cpp、go、java、javascript、python、ruby、swift が含まれます。

結果を返さない CodeQL

このセクションでは、CodeQL 分析で結果が生成されない状況に関するガイダンスを提供します。

トラブルシューティングの手順:

1. 検出された脆弱性の確認
   • コードに脆弱性がない可能性を考慮に入れてください。 脆弱性が予想されるが検出されない場合、さらに確認を進めます。
2. クエリ スイートの構成の確認
   • 使用されているクエリ スイートを確認し、必要に応じてより包括的なスイートに切り替えることを検討してください。
   • または、カスタム クエリ スイートを作成して、カスタマイズされた分析を行うことができます。
3. 結果を表示するためのアクセス許可の調整
   • 分析結果にアクセスするための適切なアクセス許可 (共同作成者レベル以上) が付与されていることを確認します。 詳しくは、「高度なセキュリティ アクセス許可」をご覧ください。

コード スキャン タスクのアクセス許可

コード スキャン ビルド タスクは、パイプライン ID を使って Advanced Security REST API を呼び出します。 既定では、同じプロジェクト内のパイプラインは、CodeQL 分析を実行することによって生成された SARIF ファイルをアップロードするアクセス権を持ちます。 ビルド サービス アカウントからこれらのアクセス許可を削除する場合、またはカスタム セットアップ (たとえば、リポジトリとは異なるプロジェクトでホストされているパイプライン) がある場合は、これらのアクセス許可を手動で付与する必要があります。

トラブルシューティングの手順:

• パイプラインで使われるビルド サービス アカウントに Advanced Security: View alerts と Advanced Security: Manage and dismiss alerts アクセス許可を付与します。これは、プロジェクト スコープのパイプラインの場合は [Project Name] Build Service ([Organization Name]) で、コレクション スコープのパイプラインの場合は Project Collection Build Service ([Organization Name]) です。