次の方法で共有

コード スキャンのトラブルシューティング

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

[前提条件]

カテゴリ 要求事項
アクセス許可 - リポジトリのすべてのアラートの概要を表示するには、リポジトリに対する「コントリビューター」権限が必要です。
- Advanced Security でアラートを解除するには、プロジェクト管理者の権限が必要です。
- Advanced Security でアクセス許可を管理するには、プロジェクト コレクション管理者グループのメンバーであること、またはAdvanced Security: 設定の管理のアクセス許可が許可に設定されている必要があります。

高度なセキュリティの権限の詳細については、「高度なセキュリティ権限の管理」を参照してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

結果を返さない CodeQL

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

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

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

CodeQL のタイムアウト

AdvancedSecurity-Codeql-Analyze@1 タスクにThis job was abandoned ... we lost contact with the agentが表示され、ホストされている Microsoft エージェントを使用している場合、タスクは有料のホステッド エージェントに対して組み込みの 6 時間のタイムアウトに達しています。 代わりに、セルフホステッド エージェントで分析を実行しようとする場合があります。

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

コード スキャン ビルド タスクは、パイプライン 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]) です。

意図しないリポジトリにコードスキャン結果を公開すること

あるリポジトリに格納されているパイプライン定義があり、GitHub Advanced Security によってスキャンされるソース コードが別のリポジトリにある場合、結果が処理され、正しくないリポジトリに送信され、ソース コード リポジトリではなくパイプライン定義を含むリポジトリに発行される可能性があります。

意図した結果ルーティングを有効にするには、パイプライン環境変数 advancedsecurity.publish.repository.infer: true を設定して、作業ディレクトリ内のリポジトリから発行するリポジトリを推測します。

trigger:
  - main

resources:
  repositories:
    # PipelineRepo: The repository containing the pipeline definition.
    # This is optional and only needed if you plan to reference files or scripts from this repo.
    - repository: PipelineRepo
      type: git
      name: DevOpsPipelineRepo
      ref: refs/heads/main
      trigger:
        - main
    # SourceRepo: The repository where scanning and publishing will occur.
    - repository: SourceRepo
      type: git
      name: code-to-analyze-repo
      ref: refs/heads/main
      trigger:
        - main

jobs:
  - job: "CodeQLScan"
    displayName: "CodeQL Scanning with Inferred Publishing"
    variables:
      # Enable repository inference
      advancedsecurity.publish.repository.infer: true
    steps:
      # Checkout the SourceRepo
      - checkout: SourceRepo

      # Initialize CodeQL
      - task: AdvancedSecurity-Codeql-Init@1
        displayName: "Initialize CodeQL"
        inputs:
          languages: "python,javascript" # Adjust based on repository languages

      # Perform CodeQL analysis
      - task: AdvancedSecurity-Codeql-Analyze@1
        displayName: "Analyze Code with CodeQL"

セルフホステッド エージェントへの CodeQL バンドルの手動インストール

GitHub で入手できるアーキテクチャのセットアップ スクリプトを使用して、CodeQL バンドルをエージェント ツール キャッシュにインストールします。 これらのスクリプトでは、 $AGENT_TOOLSDIRECTORY 環境変数をエージェント上のエージェント ツール ディレクトリの場所 (たとえば、 C:/agent/_work/_tool) に設定する必要があります。 または、次の手順を手動で実装することもできます。

  1. GitHub から最新の CodeQL リリース バンドルを選択します。
  2. バンドルをダウンロードし、エージェント ツール ディレクトリ (通常は _work/_tool の下にあります) 内のディレクトリ (./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/) に解凍します。 v2.16.0の現在のリリースを使用すると、フォルダー名は ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/ になります。 エージェント ツール ディレクトリの詳細は、こちらを参照してください。
  3. x64.complete という名前の空のファイルを ./CodeQL/0.0.0-[codeql-release-bundle-tag] フォルダーで作成します。 前の例を使用すると、x64.complete ファイルへのエンド ファイル パスは ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete になります。

コード スキャン アラートを発行するリポジトリを明示的に定義するにはどうすればよいですか?

  • パイプライン環境変数 advancedsecurity.publish.repository.infer: true を使用して、作業ディレクトリ内のリポジトリから発行するリポジトリを推測します。
  • 別のオプションとして、リポジトリを明示的にチェックアウトしない場合、またはエイリアスを使用してリポジトリをチェックアウトしない場合は、変数を使用します advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['YourRepositoryAlias']) ]

詳細については、 リリース ノートを参照してください。