エージェントインストールガイド
概要
ここでは、Docker環境でContrastのJavaエージェントを使用する方法について紹介します。本項を参考にご利用の環境に合わせた方法で、DockerのJavaアプリケーションにContrastエージェントをインストールし、必要に応じてチーム内で共有してください。
本項では主に、Docker上のJavaアプリケーションにContrastエージェントを組み込み、Contrastでセキュリティデータを確認するための最も一般的な方法について説明します。
また、PetClinicというサンプルのJavaアプリケーションに関する情報も記載しています。自分のアプリケーションで作業をする前に、このサンプルアプリケーションで手順を確認してみるのも良いでしょう。PetClinicのサンプルコードへのリンクは本項の最後にあります。サンプルコードを使用して、Docker環境のPetClinicにContrastエージェントをインストールしてアプリケーションを検査してみてください。
主な手順
アプリケーションのDockerfileを更新する
アプリケーションでContrastエージェントを有効にする
サポート対象のテクノロジ
作業を開始する前に、ご利用のJavaのツールや環境がContrastでサポートされていることを確認してください: Javaエージェントのサポート対象テクノロジ
本項は以下を前提としております:
- DevOpsの実践とDockerの仕組みに関してある程度の知識があること
- Contrast JavaエージェントがContrastサーバに接続するための必要な情報があること:Javaエージェントのインストール
- Contrast Javaエージェントをダウンロードして起動したことがあること
手順
まず、アプリケーションのDockerfileを編集します。
1. Contrast Javaエージェントを追加
ここでは、DockerイメージにContrastエージェントを追加して、基本の設定を行う方法について2つ紹介します。最適な方法をお選びください。
方法 1:ベースイメージに追加
この方法では、エージェントの更新はベースイメージの更新に依存します。手順は以下のとおりです。
- Contrastエージェントと基本の設定を、有効化せずにDockerベースイメージに追加します。
- イメージを1箇所変更し、このベースイメージを使用する全てのアプリケーションでContrastを利用可能にします。
- アプリケーションのDockerイメージまたはコンテナでContrastを有効にします。
ベースイメージのDockerfileの設定例:
FROM BASE_IMAGE |
Contrastエージェントの場所には、/opt/contrastを推奨しますが変更も可能です。必要に応じて、社内リポジトリからエージェントをダウンロードするようにURLを変更することもできます。
エージェントの特定のバージョンを指定してビルド時にMavenリポジトリからダウンロードできます。
docker build --build-arg CONTRAST_AGENT_VERSION=<addVersionHere> -t image_with_contrast:tag .
|
方法 2:アプリケーションイメージに追加
この方法では、チームではどのバージョンのContrastエージェントでも使用できるようになり、自動更新されるのを避けることができます。手順は、以下のとおりです。
- 上述のADD命令をアプリケーションのDockerイメージに直接追加します。
2. エージェントの設定を指定
Contrastエージェントの設定は、さまざまな値を使用して指定できます。設定する値には有効になる優先順位があります。各レベルは、上位のレベルが指定された場合に無効になります。優先順位は次のとおりで、最も優先されるのが1です:
-
-
- 企業の基準(例、期限切れのライセンスはassess.enableより優先)
- システムプロパティの値
- 環境変数の値
- YAML設定ファイルの値
- Contrast UIで指定した値
- デフォルトの値
-
優先順位の詳細については、以下を参照してください:
エージェントの設定の優先順位
設定する値を組み合わせて利用することをお勧めします:
-
-
- 共通の設定はYAMLファイルに保存してベースイメージに配置
- アプリケーション固有の設定に関する値はJavaのシステムプロパティを使用
-
共通の設定
以下は、基本となる設定をYAMLファイルに指定する方法です。基本の設定として一般的なものをいくつか紹介します。必要に応じて編集してください。
- ログをコンソール出力にリダイレクト
- プロキシの設定(プロキシがある場合)
- エージェントのアクティビティを制限するパフォーマンスチューニングオプション
設定をするには:
- 以下のように設定オプションと値を追加します。
api: |
- 次に、YAMLファイルを作成して、ベースイメージにコピーします。
- 次の行をDockerfileに追加して、編集したYAMLファイルをベースイメージのDockerfileにコピーします。
COPY WORKSPACE/contrast_security.yaml /opt/contrast/contrast_security.yaml |
アプリケーション固有の設定
アプリケーションごとに追加のオプションを指定できます。アプリケーション固有の設定を指定するために、Javaのシステムプロパティを使用します。
- アプリケーションのメタデータ: アプリケーションに関連付けるユーザ定義のメタデータを指定
-Dcontrast.application.metadata
- アプリケーション名:Contrastサーバに報告されるアプリケーション名を指定
-Dcontrast.agent.java.standalone_app_name
- アプリケーションのセッションメタデータ:ビルド番号、バージョン、ハッシュなどの情報でセッションの新規作成時に使用されるメタデータを指定(詳細は、Contrastドキュメントを参照)
-Dcontrast.application.session_metadata
- アプリケーションのグループ:このアプリケーションを関連付けるアクセスグループをオンボード時に指定(注:アプリケーションのアクセスグループは先にContrastで作成しておく必要あり)
-Dcontrast.application.group
- サーバの環境:アプリケーションを実行する環境を指定、有効な値:development、 qa、 production
-Dcontrast.server.environment
3. JVM引数を更新してエージェントをロード
Javaアプリケーションにプロファイラをロードするために、アプリケーションに -javaagent オプションを渡す必要があります。これをJAVA_TOOL_OPTIONS
環境変数で指定します。Contrastで共通のJVM引数をベースイメージ内の別の環境変数にあらかじめセットしておけば、アプリケーションチームはその変数をJAVA_TOOL_OPTIONS
で使用できます。
ベースイメージのDockerfile
ENV CONTRAST_OPTS "-javaagent:/opt/contrast/contrast.jar \ |
アプリケーションイメージのDockerfile
ENV JAVA_TOOL_OPTIONS $CONTRAST_OPTS \ |
4. アプリケーションでエージェントを有効にする
エージェントがContrastサーバにデータを送信するには、APIのURLとエージェントの認証情報が必要です。エージェントの認証情報を保護するために、Docker secretを利用してデプロイ時に環境変数として渡すこともできます。以下は、docker run コマンドの例です:
docker run -e CONTRAST__API__URL=https://app.contrastsecurity.com -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value> |
Contrastが実行されているかを確認するには、コンテナのログをチェックしてください。次のようなメッセージが表示されているはずです:
2020-05-28 22:36:29,910 [main STDOUT] INFO - Copyright: 2019 Contrast Security, Inc |
ソースコードのサンプル:PetClinic
以下のGitHubリポジトリにあるサンプルアプリケーションを参考にしてください。Docker環境のJavaアプリケーションにContrastエージェントを組み込むための手順や設定を理解するのに役立ちます。
https://github.com/TimFranklin/docker-java-petclinic
FAQ
- Contrast Javaエージェントは、アプリケーションのパフォーマンスにどの程度影響しますか?
Java Agent Effects on Application Performance(Assess)
- Javaで実行する場合に、アプリケーションの起動に影響ありますか?
Java Agent Effects on Startup Performance
- Contrastログに表示されるSSL接続エラーを解決するにはどうすればよいですか?
JavaエージェントがContrast UIに接続できない:javax.net.ssl.SSLHandshakeException
- 新しいバージョンのエージェントは、古いバージョンのContrastサーバに対して動作しますか?また、その逆の場合は?
動作するかもしれませんが推奨しません。常に両方を最新にしてください。(参:エージェントのインストール)