Contrast Jenkinsプラグイン

Jenkinsは、アプリケーションのビルド、テスト、デプロイ、実行のプロセスを自動化する継続的インテグレーション(CI)ツールです。

ContrastのJenkinsプラグインを使用すると、このパイプラインにアプリケーションセキュリティゲートを追加できます。セキュリティゲートとして、脆弱なアプリケーションのJenkinsジョブを「FAILURE(失敗)」や「UNSTABLE(不安定)」などのビルド結果で失敗させる基準を指定できます。

ヒント

このプラグインのソースコードは、JenkinsプラグインのGithubリポジトリで参照できます。

互換性を保つために、次のバージョンを使用してください。

Jenkins

Contrast-Jenkinsプラグイン

Contrast

2.60.3

3.4

3.7.6

2.60.3

3.7

3.7.10

2.60.3

3.8

3.8.0

Jenkinsプラグインをインストールして使用するには:

  1. ContrastとJenkins間の接続を定義します。

  2. お使いの環境に合わせて、Jenkinsをどのように利用するかを決めます。

  3. ビルドを実行します。

接続

JenkinsでContrastへの接続を定義するには:

  1. Jenkinsのダッシュボードで、左のサイドバーのJenkinsの管理を選択します。

  2. システムの設定 を選択し、「Contrast Connections」のセクションを探してください。

  3. Contrast usernameの項目で、Contrastのユーザ名を入力します。ユーザ名は、通常Contrastのアカウントに使用するEメールアドレスです。

  4. Contrast APIキー、Contrast serviceキー、Contrast URLおよび組織IDを入力します。これらの情報はプロファイルで確認できます。

  5. Result of a vulnerable buildで、ドロップダウンメニューを使用して、アプリケーションが脆弱である場合にContrastからJenkinsジョブの結果をどのように返すかを選択します。指定できるオプションは、FAILURE(失敗)、UNSTABLE(不安定)、SUCCESS(成功)、NOT_BUILT(ビルドしない)およびAborted(停止)です。

  6. Jenkinsインスタンスがアプリケーションを見つけられないときにJeninsジョブを自動的に失敗させたい場合は、Apply this vulnerable build result to the job when Jenkins encounters an error with Contrast のボックスにチェックをします。

  7. アプリケーションがJenkinsのシステムレベルで脆弱であるかを判断するために、Contrastプラグインで使用する基準を定義できます。ジョブレベルの制御をシステムレベルの制御より優先したい場合は、Allow job level application vulnerability security controls to override those controls set here at the system levelの横にあるチェックボックスにチェックをします。インスタンス内のすべてのJenkinsジョブで基準の一貫性を持たせたい場合は、このボックスをオフのままにします。

    注記

    ジョブ結果ポリシー を使用してセキュリティ制御を設定している場合、こららのポリシーはジョブレベルまたはシステムレベルで設定されたポリシーより優先されます。

  8. Test Contrast connectionを選択して、プラグインがContrastに認証され、アプリケーションの脆弱性に関する情報を取得できることを確認します。

  9. Saveを選択します。

システムレベルで脆弱性のセキュリティ制御を定義

Jenkinsで接続を定義した後、フリースタイルのジョブを使用している場合は、システムレベルでContrastの脆弱性によるセキュリティ制御を設定することができます。もしくは、 ジョブレベルでセキュリティ制御を設定することもできますし、ジョブ結果ポリシーを使用してそれらのセキュリティ制御を優先させることもできます。

  1. Contrast Vulnerability Security Controlsで、ドロップダウンメニューから以前作成したConnectionを選択します。

  2. Number of Allowed Vulnerabilitiesを設定します。この数字は除外されるため、「5」に設定すると、6件以上の脆弱性がある場合にJenkinsが失敗します。このフィールドは必須です。

  3. ドロップダウンメニューのオプションからVulnerability Severityを選択します(これらは、Contrastの脆弱性の深刻度オプションと同じです)。プラグインでは、このフィールドに設定された深刻度以上の全ての脆弱性についてAPIコールのフィルターが設定されます。このフィールドは必須ではありませんが、選択すると結果を絞り込むことができます。

  4. ドロップダウンメニューからVulnerability Type (ルール名)を選択します。フィルタリングについて単一のルールを指定すると、プラグインではこのルールタイプの脆弱性の数がチェックされ、件数が比較されます。このフィールドは必須ではありませんが、選択すると結果を絞り込むことができます。

  5. Vulnerability Statusesのリストから選択します。Vulnerability Statusesは必須ではありませんが、役立つ場合があります。例えば、ConfirmedおよびReportedを選択すると、オープンステータスの脆弱性のみが返されます。脆弱性をステータスで絞り込まない場合は、空欄にしておきます。

    複数の条件を追加することはできますが、プラグインでは最初の条件を満たさなかった時点でジョブが失敗します。プラグインでは、最初に違反した脆弱性セキュリティ制御にビルド結果が設定されます。

ビルド後の処理としてセキュリティ制御を定義

Jenkinsのシステムレベルでセキュリティ制御を設定した後に、パイプラインの一部ではないフリースタイルジョブのセキュリティ制御をジョブレベルで追加することもできます。これを行うには:

  1. Jenkinsのジョブの定義時に、ビルド後の処理のセクションを探します。

  2. ドロップダウンメニューから、以前作成した接続を選択します。

  3. アプリケーションを選択します。このフィールドは必須です。

    • アプリケーションが計測済の場合は、Choose your applicationドロップダウンメニューからアプリケーションを選択します。

    • アプリケーションがまだ計測されていない場合は、Application NameおよびApplication Languageフィールドを使用して、アプリケーションを指定します。アプリケーションを計測するときに使用するのと同じアプリケーション名をJenkinsに指定する必要があります。アプリケーションの計測後、Contrastでのビルド後の処理ステップ中に、その同じ名前と言語が使用されます。

  4. システムレベルの脆弱性セキュリティ制御の上書きを許可するよう接続が設定されている場合は、Override Vulnerability Security Controls at the Jenkins system levelの横にあるチェックボックスをオンにすることで、その設定を上書きできます。

    これを行う場合は、このジョブのNumber of Allowed VulnerabilitiesVulnerability SeverityVulnerability Type、およびVulnerability Statusesも指定する必要があります。

  5. Query vulnerabilities byでオプションを選択して、脆弱性のクエリ方法を選択します。こうすると、そのジョブで検出された脆弱性のみが考慮されます。デフォルトでは、最初のオプション:appVersionTag, format: applicationId-buildNumberがプラグインで使用されます。

contrastAgentでダウンロード

contrastAgentという名前のパイプラインステップは、最新のContrastエージェントをダウンロードします。

パラメータ

必須項目

説明

profile

必須

Contrastとの通信に使用するContrast接続プロファイル

MyConnection

outputDirectory

必須

ダウンロードしたエージェントを配置する場所を定義

env.WORKSPACE

agentType

applicationIdが定義されていない場合は必須

アプリケーションに組み込んだエージェントのタイプ(大文字と小文字の区別なし)

オプション: Java、 .NET、 .NET_Core、 Node、 Ruby、 Python

Java

contrastAgentという名前のパイプラインステップを追加する例を次に示します。

  • node{
      stage('Download Latest Contrast Agent'){
        contrastAgent profile:'MyConnection', outputDirectory: env.WORKSPACE, agentType: 'Java'
      }
    }

Jenkinsのパイプラインで脆弱性のセキュリティ制御を定義

contrastAgentというパイプラインステップを使用してContrastエージェントをダウンロードし、アプリケーションにエージェントを組み込み、アプリケーションを実行します。contrastVerificationというパイプラインステップを使用すると、アプリケーションを検証し、セキュリティ制御のパラメータを設定できます。

contrastVerificationでアプリケーションを検証

contrastVerificationという名前のパイプラインステップを使用して、アプリケーションが脆弱かどうか検証できます。

パラメータ

必須項目

説明

profile

必須

profileを使用して、Contrastとの通信に使用する接続を指定します。

Contrast Connection

queryBy

必須

queryByを使用して、ビルドに関連する脆弱性にフィルタをかけます。オプション1、2、4の場合、この値は、アプリケーションの実行中にContrastエージェントに渡されたcontrast.override.appversionパラメータと一致する必要があります。

脆弱性をクエリする方法をオプション番号で指定します(デフォルトの値は1):

  1. appVersionTag, format: applicationId-${BUILD_NUMBER}

  2. appVersionTag, format: applicationId-${JOB_NAME}-${BUILD_NUMBER}

  3. startDate (これはビルドのタイムスタンプです。ビルド開始後に検出された脆弱性のみを調べます。)

  4. APPVERSIONTAG (これは、ジョブパラメータか環境変数です。独自のテキストを指定する場合は、このオプションを選択し、Jenkinsジョブ内の環境変数としてAPPVERSIONTAGをエクスポートしてください。JOB_NAMEBUILD_NUMBERの両方は、既にJenkinsの環境変数として利用可能です。)

1

applicationId

applicationNameagentTypeが定義されていない場合は必須

検証しようとしているアプリケーションまたはアプリケーションモジュールのID

cb3ea678-38c8-4487-ba94-692a117e7966

applicationName

applicationIdが定義されていない場合は必須

検証しようとしているアプリケーションの名前(大文字と小文字の区別なし)

MyApp

count

オプション

許容する脆弱性の総数、デフォルトは0

10

rule

オプション

デフォルトはAll

xss

severity

オプション

デフォルトはAll。その他のオプション:Critical、 High、 MediumLow

High

appVersionTag

オプション

Contrastエージェントのcontrast.override.appversionパラメータに渡された値

v1.2.3

contrastVerificationという名前でパイプラインステップを追加する方法の例をいくつか示します。

  • queryBy startDateを使用:

    contrastVerification applicationId: '1e6ad9c6-89d4-4f06-bdf6-92c569ec89de', count: 1, profile: 'new-profile', queryBy: 3, rule: 'cache-controls-missing', severity: 'High'
  • queryByのカスタムappVersionTagパラメータを使用:

    contrastVerification applicationId: '1e6ad9c6-89d4-4f06-bdf6-92c569ec89de', count: 1, profile: 'new-profile', queryBy: 4, appVersionTag: 'v1.2.3' rule: 'cache-controls-missing', severity: 'High'
  • applicationNameAgentTypeを使用してアプリケーションを定義:

    contrastVerification applicationName: 'MyApp', agentType: 'Java', count: 1, profile: 'new-profile', queryBy: 3, rule: 'cache-controls-missing', severity: 'High'
  • 事前設定またはオーバライドされている脆弱性のセキュリティ制御でアプリケーションを検証します。

    Contrastで脆弱性のセキュリティ制御が事前に設定されていることがわかっている場合は、プロファイルおよび、applicationIdか(applicationNameagentType)のいずれかを定義するだけで良いです。

    contrastVerification applicationId: '35ae7b89-1c76-414b-b317-c444ce27608b', profile: 'ContrastConnection'

ジョブ結果ポリシーを定義

ジョブ結果ポリシー(Contrast Jenkinsプラグインのバージョン3.3以降でサポート)は、Contrastプラグインを使用するJenkinsジョブにビルド結果を割り当てます。ジョブ結果ポリシーにより、設定した基準に基づいて、ジョブのビルド結果に失敗(FAILURE)、 不安定(UNSTABLE)、成功(SUCCESS)などのステータスが付けられます。

Contrastでジョブ結果ポリシーを定義するには、組織の管理者である必要があります。

ジョブ結果ポリシーを定義するには:

  1. Contrast UIで組織の設定を選択し、左のナビゲーションでインテグレーションを選択します。

  2. Jenkinsの行で、ジョブ結果ポリシーを追加を選択します。

    JenkinsOverview.png
  3. ジョブ結果ポリシーの名前を定義します(必須)。

  4. アプリケーションで、ポリシーを適用するアプリケーションを指定します。アプリケーションは、アプリケーションの名前や重要度、またはタグで指定できます。アプリケーション名で選択する場合、個々のアプリケーションやマージされたアプリケーションを選択できます。

  5. 脆弱性プロパティでは、ポリシーの対象とする脆弱性の制限や環境などを定義します。環境脆弱性ステータス最初に検知された脆弱性を使用して、ポリシーの対象とする脆弱性を絞り込みます。 脆弱性ルールを使用して、ジョブ結果のステータス変更のトリガーとなるルール(特定の深刻度)とその数をしきい値として指定します。

    • 環境: ポリシーを適用する環境を選択します(複数選択可)。

      例えば、テスト(QA)環境にある脆弱性が本番環境で発生してしまうのを防ぐには、QAを選択します。 (ただし、この場合、開発環境の脆弱性は考慮されません。それらの脆弱性を対象とするには、開発環境も選択します。または、すべての環境の脆弱性を対象とする場合は、全ての環境を選択します。)

    • 脆弱性ステータス: どのステータスを対象とするかを選択します(複数選択可)。脆弱性のステータスは、Contrastで決定されます。

      ヒント

      ほとんどの場合、報告済確認済疑わしいなどのオープン中のステータスのみを選択します(問題無し、 修復済修正完了などのクローズのステータスではなく)。そうすれば、既に開発者が対応した脆弱性によって、Jenkinsのジョブが失敗したり不安定になることがありません。

    • 最初に検知された脆弱性: 脆弱性が最初に検知された時間に基づいて、ポリシーの対象とする脆弱性の時間範囲を設定します。

      開始終了フィールドを使用して、時間範囲の開始と終了を設定します。時間範囲の開始に、ジョブ開始時か、Contrastステップを実行する前の所定の日数、またはアプリケーションをオンボードした日を選択します。 時間範囲の終了に、Contrastステップを実行する前の所定の日数か、JenkinsでContrastステップを実行するまで、または特定の期間のオプションを選択します。カスタマイズを選択して、いずれかのフィールドに特定の日付を選択することもできます。

      脆弱性がこの時間範囲外で最初に検出された場合、その脆弱性はポリシーの対象にはなりません。

      ヒント

      開発者に一定期間(例えば、1週間)内に脆弱性を修正させるためには、7日以上前に検出された脆弱性のみをポリシー違反とさせるよう、ポリシーを定義します。これを行うには、開始アプリケーションのオンボード時を、終了過去7日間を設定します。

    • 脆弱性ルール: このセクションを使用して、ポリシーで許可する脆弱性の件数、種類および深刻度によるしきい値を設定します。

      ルールごとに、深刻度Assessルールを選択したら、許容する脆弱性数を選択します。別のルールを追加をクリックすれば、複数のルールを登録できます。

      許容される脆弱性数は、この深刻度の脆弱性を、このビルドに影響を与えずに許容する脆弱性の数を決定します。「0」に設定すると、1つの脆弱性でビルド結果のステータスが変更されます。「10」に設定した場合は、指定した種類の脆弱性が11件検出されるまで、ビルド結果のステータスは変わりません。特定のルールや深刻度に対して、許容される脆弱性数を空欄のままにすると、そのルールや深刻度の全ての脆弱性が許容されます。

      例えば、全てのルールと1件の脆弱性を設定した場合、1つの脆弱性がポリシーのトリガーとなります。また、別のルールを追加して、このポリシーを5つの重大な脆弱性のルールと2つのクロスサイトスクリプティングの脆弱性に制限することもできます。

    • 脆弱性にフィルターをかける時にプラグインの"Query vulnerabilites by"で選択したオプションを適用しますの横のチェックボックスにチェックをします。Contrast Assessのビルド後の処理またはパイプラインステップを使用して、Jenkinsジョブの脆弱性をクエリするよう定義できます。例えば、AppVersionTagや、脆弱性が最後に検出された日などを使用できます。このチェックボックスを選択すると、ジョブ結果ポリシーの評価時にこのクエリが含まれるようになります。

    以下は、ジョブ結果ポリシーの可能なルールと設定で、これらの条件が満たされた場合にJenkinsでの結果ステータスを変更する例です。

    VulnPropertiesJenkins.png

    この例では、次のような脆弱性がポリシー違反の対象となります。

    • QA環境として指定されたサーバで検出された全ての脆弱性

    • ステータスが報告済、 確認済疑わしい全ての脆弱性

    • アプリケーションのオンボード時からJenkinsでContrastステップが実行されるまでの間に初めて検出された全ての脆弱性

    次のいずれかのうち少なくとも1つが発生すると、ポリシー違反となり、結果ステータスが変更されます。

    • 重大な脆弱性が1つ以上ある

    • SQLインジェクションを除く全てのルールで、または注意の深刻度の脆弱性が合計で4つ以上ある

    注記

    脆弱性は1回だけカウントされ、最も具体性が高い設定(例、特定の脆弱性ルール)が、最も具体性が低い設定(全てのルール)より優先されます。ルールの種類と深刻度の両方で脆弱性の制限が設定されている場合、その脆弱性はルールの種類の数としてカウントされますが、深刻度の脆弱性としてカウントされません。従って、この例では、重大な脆弱性は深刻度の脆弱性数としてカウントされますが、および注意の深刻度は全てのルールとしてまとめられます。

  6. ポリシー結果で、ポリシーの結果を選択します。選択した基準に一致するジョブをContrastで失敗(FAILURE)、 不安定(UNSTABLE)または成功(SUCCESS)のステータスにします。複数のジョブ結果ポリシーが指定されているアプリケーションには、違反しているすべてのポリシーで最も重大な結果が適用されます。

  7. このジョブ結果ポリシーを有効化の横にあるチェックボックスをオフにすると、個々のポリシーを削除しなくても、JenkinsジョブにContrastのポリシーが適用されるのを一時停止できます。

Jenkinsでのビルドの実行

初めてビルドを実行するには:

  1. Jenkinsで、実行するジョブまたはプロジェクトを選択します。

  2. 左側のメニューで、Build Nowを選択します。

  3. 詳細を見るには、ログ出力を表示します。

  4. フリースタイルのジョブを使用している場合は、タスクからのデータを表示できます。実行を選択して、左側のメニューでVulnerability Reportを選択します。

    重要

    ジョブまたはプロジェクトの概要でグラフを見ることもできます。ただし、Contrastパイプラインステップを使用した場合、または1つ以上の選択されたアプリケーションがジョブ結果ポリシーで上書きされている場合は、グラフが表示されません。