既存のMavenプロジェクトでのJavaエージェントのインストール

Contrastエージェントには、Contrastサーバと通信するための設定が必要です。エージェントキーを取得してください。

Contrast設定ファイルを作成し、任意のテキストエディタで開きます。Contrast設定ファイルはYAMLファイルです。ここには、API認証情報が含まれるため、ホームディレクトリなど自分だけがアクセスできる場所に作成してください。わかりやすいファイル名(例えば.contrast.yml)を選択してください。

ファイルを作成し、任意のテキストエディタで開きます。

以下の内容を貼り付けます。

api:
  url: <contrast_url>
  api_key: <your_api_key>
  user_name: <agent_user_name>
  service_key: <agent_user_service_key>

<contrast_url>、<your_api_key>、<agent_user_name>、<agent_user_service_key>を前述の手順で取得したContrast URL、APIキー、ユーザ名、サービスキーに置き換えてファイルを保存します。

コマンドプロンプトを開き、以下のコマンドを実行してexamplesリポジトリをクローンします。

$ git clone https://github.com/Contrast-Security-OSS/contrast-java-examples.git
Cloning into 'contrast-java-examples'...
remote: Enumerating objects: 12, done.
remote: Counting objects: 100% (12/12), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 12 (delta 1), reused 9 (delta 1), pack-reused 0
Unpacking objects: 100% (12/12), done.

サンプルのmaven-cargoのルートを作業ディレクトリにします。

cd contrast-java-examples/maven-cargo

次に、統合テストを実行して、すべてが正常に機能することを確認します。maven-cargo-pluginによってJettyサーバがポート8080で起動し、EchoServletITの統合テストでJettyサーバにHTTPリクエストを送信することでEchoServletを検証します。最後に、maven-cargo-pluginがJettyサーバをシャットダウンします。

$ ./mvnw clean verify
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.contrastsecurity.examples:contrast-maven-cargo >---------
[INFO] Building Contrast Maven Cargo Example 1.0
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
    ... omitting some output ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.467 s
[INFO] Finished at: 2019-03-21T22:57:22-04:00
[INFO] ------------------------------------------------------------------------

これが機能しない場合は、Java 8が正しくインストールされていることを確認してください。

$ java -version
java version "1.8.0_131"
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode)

Javaインストールについて何らかの修正が必要だった場合は、再度テストを実行してみてください。それでも機能しない場合は、この問題の詳細を記載して問題を報告してください。

次の手順で、Maven Dependency Pluginを使用して、エージェントをプロジェクトのビルドディレクトリにダウンロードします。

プロジェクトPOM (pom.xml)のproperties要素に以下を追加します。

<contrast.version>3.6.3.8220</contrast.version>

バージョン番号とビルド番号は、Maven CentralにリリースされているContrast Javaエージェントのどのバージョンにも置き換えることができます。

プロジェクトPOM (pom.xml)のbuild.plugins要素に以下を追加します。

<plugin>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.1.1</version>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals>
        <goal>copy</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>com.contrastsecurity</groupId>
            <artifactId>contrast-agent</artifactId>
            <version>${contrast.version}</version>
          </artifactItem>
        </artifactItems>
        <stripVersion>true</stripVersion>
      </configuration>
    </execution>
  </executions>
</plugin>

Jettyの起動時にContrastを組み込むように既存のMaven Cargoプラグインを設定します。以下のconfiguration要素をstart-app-before-IT executionにコピーします。

<configuration>
  <configuration>
    <properties>
      <cargo.jvmargs>
        -javaagent:${project.build.directory}/dependency/contrast-agent.jar
        -Dcontrast.config.path=${user.home}/.contrast.yml
        -Dcontrast.agent.java.standalone_app_name=maven-cargo-how-to
       </cargo.jvmargs>
    </properties>
   </configuration>
</configuration>

-Dcontrast.config.pathの値を、ステップ2で作成した設定ファイルのパスと一致するよう変更します。

テストを再実行します。アプリケーションコンテナが初期化されると、Contrastが起動されたことを示す出力が表示されます。

$ ./mvnw clean verify
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.contrastsecurity.examples:contrast-maven-cargo >---------
[INFO] Building Contrast Maven Cargo Example 1.0
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
    ... omitting some output ...
[INFO] [talledLocalContainer] [Contrast] Thu Mar 21 23:20:40 EDT 2019 Starting Contrast (build 3.6.2.BACKGROUND) Pat. 8,458,789 B2
    ... omitting more output...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  16.644 s
[INFO] Finished at: 2019-03-21T22:57:22-04:00
[INFO] ------------------------------------------------------------------------

総合テスト中に、Contrastエージェントが脆弱なサーブレットを検出し、Contrastサーバに報告します。報告された脆弱性を参照するには、Contrast UIで脆弱性のページにアクセスし、アプリケーション名のmaven-cargo-how-toでフィルターをかけます。