Docker環境でのJavaエージェント

概要

ここでは、Docker環境でContrastのJavaエージェントを使用する方法について紹介します。また、Docker環境のサンプルアプリケーションについても本項の最後に記載しています。自分のアプリケーションで作業をする前に、サンプルアプリケーションを利用して手順を確認してみてください。

Docker環境でのContrastエージェントの設定方法は様々なため、サンプルコードなどをお試し頂き、本項を参考にしてご利用の環境に適した導入方法をご確認ください。

主な手順

アプリケーションのDockerfileを編集

DockerイメージにContrast Javaエージェントを追加
DockerイメージにContrast Javaエージェントの設定を追加
DockerイメージでContrast Javaエージェントを有効にする変数を定義

アプリケーションを起動

Contrastを有効にしてDockerイメージを作成・コンテナを起動

本項は以下を前提としております：

利用するJavaの環境がContrastのサポート対象であること：Javaエージェントのサポート対象テクノロジ
DevOpsの実践とDockerの仕組みに関してある程度の知識があること
Contrast JavaエージェントがContrastサーバに接続するための必要な情報があること：Javaエージェントの設定
Contrast Javaエージェントをダウンロードして起動したことがあること

手順

まず、アプリケーションのDockerfileを編集します。

1. Contrast Javaエージェントを追加

DockerイメージにContrastエージェントをダウンロードするために、以下の記述をDockerfileに追加します。

Dockerfileの記述：

FROM BASE_IMAGE
ARG CONTRAST_AGENT_VERSION
ADD https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/$CONTRAST_AGENT_VERSION/contrast-agent-$CONTRAST_AGENT_VERSION.jar /opt/contrast/contrast.jar

Contrastエージェントの場所には、/opt/contrastを推奨しますが変更も可能です。必要に応じて、社内リポジトリからエージェントをダウンロードするようにURLを変更することもできます。

Contrastエージェントのバージョンは、以下のコマンドを実行して、Dockerイメージのビルド時に指定します。指定したバージョンのContrastエージェントが、Mavenリポジトリからダウンロードされます。

docker build --build-arg CONTRAST_AGENT_VERSION=<addVersionHere> -t image_with_contrast:tag .

2. DockerイメージでJavaエージェントのプロパティを設定

Contrastエージェントのプロパティは、環境変数、YAML設定ファイル(contrast_security.yaml)、またはコマンドライン引数で設定できます。エージェントの設定には、有効になる優先順位があります。

Contrastエージェントのプロパティを設定するには、Contrast UIのエージェントの追加画面よりYAML設定ファイル(contrast_security.yaml)をダウンロードし、アプリケーションのディレクトリに配置します。
以下の設定は任意ですが、推奨プロパティです。必要に応じて、<NEEDS_TO_BE_SET>の箇所を置き換えてcontrast_security.yamlに追加してください。各プロパティの詳細については、YAMLテンプレートを参照してください。

api:
  proxy:
      enable: <NEEDS_TO_BE_SET>
      url: <NEEDS_TO_BE_SET>
agent:
   java:
      standalone_app_name: <NEEDS_TO_BE_SET>
  logger:
      path: ./contrast_agent.log
      level: ERROR
server:
   name: < NEEDS_TO_BE_SET>

メモ：

Contrast UIからダウンロードしたYAML設定ファイルには、Contrastで認証するためのエージェントキー(APIの値)がデフォルトで含まれます。認証情報の保護などのためにエージェントキーをYAML設定ファイルに含めない場合には、手順4で記載しているように、エージェントキーをコンテナの起動時に指定することもできます。

次に、以下の行をDockerfileに追加して、編集したYAMLファイルをベースイメージのDockerfileにコピーします。

COPY ./contrast_security.yaml /opt/contrast/contrast_security.yaml

3. DockerイメージでJavaエージェントを有効にする

アプリケーションでJavaエージェントを有効にするために、アプリケーションに-javaagentフラグを渡す必要があります。これを行うには、JAVA_TOOL_OPTIONS環境変数を指定します。以下の行をDockerfileに追加すると、コンテナの起動時にJavaエージェントが有効になります。

ENV JAVA_TOOL_OPTIONS "-javaagent:/opt/contrast/contrast.jar \
-Dcontrast.config.path=/opt/contrast/contrast_security.yaml"

4. Dockerイメージを作成しコンテナを起動する

Dockerイメージ作成

Javaエージェントを有効にしたDockerイメージの作成は、通常のビルド手順と同様で以下のコマンドを実行します。<addVersionHere>の箇所を、ダウンロードするJavaエージェントのバージョンに置き換えます。ダウンロード可能なエージェントのバージョンは、Mavenリポジトリで確認できます。

docker build --build-arg CONTRAST_AGENT_VERSION=<addVersionHere> -t image_with_contrast:tag .

以下は、イメージ作成のコマンドの実行例です。

docker build --build-arg CONTRAST_AGENT_VERSION=3.8.5.20294 -t image_with_contrast:tag .

コンテナ起動

作成したイメージからコンテナを起動します。Contrastエージェントの設定方法に応じて、以下のコマンドのいずれかを実行します。

Contrastのエージェントキーをcontrast_security.yamlに設定している場合は、以下を実行します。

docker run image_with_contrast:tag

Contrastのエージェントキーをcontrast_security.yamlに設定していない場合は、以下を実行します。<value>の箇所を、ご利用の組織のエージェントキーに置き換えてください。

docker run -e CONTRAST__API__API_KEY=<value> \
-e CONTRAST__API__SERVICE_KEY=<value> \
-e CONTRAST__API__URL=<value> \
-e CONTRAST__API__USER_NAME=<value> \
image_with_contrast:tag

実行の確認

コンテナを起動したら、コンテナのログでContrastが実行されているかを確認できます。次のようなメッセージが表示されているはずです。

2020-05-28 22:36:29,910 [main STDOUT] INFO - Copyright: 2019 Contrast Security, Inc
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contact: support@contrastsecurity.com
2020-05-28 22:36:29,910 [main STDOUT] INFO - License: Commercial
2020-05-28 22:36:29,910 [main STDOUT] INFO - NOTICE: This Software and the patented inventions embodied within may only be used as part of
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security's commercial offerings. Even though it is made available through public
2020-05-28 22:36:29,910 [main STDOUT] INFO - repositories, use of this Software is subject to the applicable End User Licensing Agreement
2020-05-28 22:36:29,910 [main STDOUT] INFO - found at https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed between
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security and the End User. The Software may not be reverse engineered, modified,
2020-05-28 22:36:29,910 [main STDOUT] INFO - repackaged, sold, redistributed or otherwise used in a way not consistent with the End User
2020-05-28 22:36:29,910 [main STDOUT] INFO - License Agreement.
[Contrast] Thu May 28 22:36:30 EDT 2020 Effective instructions: Assess=false, Protect=true
[Contrast] Thu May 28 22:36:30 EDT 2020 String Supporter has been disabled
[Contrast] Thu May 28 22:36:30 EDT 2020 Logging security messages to /Users/usernamehere/.contrast/security.log
[Contrast] Thu May 28 22:36:31 EDT 2020 Starting JVM [1862ms]

Docker articles:

概要