エージェントインストールガイド
概要
ここでは、Docker環境でContrastのNode.jsエージェントを使用する方法について紹介します。本項を参考にご利用の環境に合わせた方法で、DockerのNodeアプリケーションにContrastエージェントをインストールし、必要に応じてチーム内で共有してください。
本項では主に、Docker上のNodeアプリケーションにContrastエージェントを組み込み、Contrastでセキュリティデータを確認するための最も一般的な方法について説明します。
また、OWASP Juice ShopというサンプルのNodeアプリケーションに関する情報も記載しています。自分のアプリケーションで作業をする前に、このサンプルアプリケーションで手順を確認してみるのも良いでしょう。OWASP Juice Shopのサンプルコードへのリンクは本項の最後にあります。サンプルコードを使用して、Docker環境のOWASP Juice ShopにContrastエージェントをインストールしてアプリケーションを検査してみてください。
主な手順
アプリケーションのDockerfileを更新する
アプリケーションでContrastエージェントを有効にする
サポート対象のテクノロジ
作業を開始する前に、ご利用のNode.jsのツールや環境がContrastでサポートされていることを確認してください:Node.jsエージェントのサポート対象テクノロジ
本項は以下を前提としております:
- DevOpsの実践とDockerの仕組みに関してある程度の知識があること
- Contrast Node.jsエージェントがContrastサーバに接続するための情報があること:npmによるNode.jsエージェントのインストール
- Contrastエージェントをダウンロードして起動したことがあること
手順
まず、アプリケーションのDockerfileを編集します。
1. Contrast Node.jsエージェントを追加
ここでは、DockerイメージにContrastエージェントを追加して、基本の設定を行う方法について2つ紹介します。最適な方法をお選びください。
方法 1:アプリケーションに追加
開発中のアプリケーションにContrastエージェントを追加することが望ましいです。そうすれば、アプリケーションのpackage.jsonにエージェントが含まれるようになります。
- “npm install”コマンドを使用して、パイプラインやコンテナイメージにエージェントを組み込むことができます。
npm install @contrast/agent --no-optional
|
方法 2:Dockerfileに追加
方法1ではうまく行かない場合や、アプリケーションイメージをContrastエージェントがあるものとないもので分けたい場合は、コンテナのビルド時にContrastエージェントを追加できます。手順は、以下のとおりです。
- 同じ npm install コマンドを使って、既存のDockerfileにエージェントを追加します。
- または、新しいDockerfileにエージェントを追加してアプリケーションのイメージをベースイメージとして使用します。
2. Contrastエージェントの設定を指定
Contrastエージェントの設定を指定するために、さまざまな値を使用できます。設定する値には有効になる優先順位があります。各レベルは、上位のレベルが指定された場合に無効になります。優先順位は以下のとおりで、最も優先されるのが1です。
- 企業の基準(例、期限切れのライセンスは、assess.enableより優先)
- 環境変数の値
- YAML設定ファイルの値
- Contrast UIで指定した値
- デフォルトの値
優先順位の詳細については、以下を参照してください:
エージェントの設定の優先順位
設定する値を組み合わせて利用することをお勧めします。
- 共通の設定はYAMLファイルに保存してベースイメージに配置
- アプリケーション固有の設定に関する値は環境変数を使用
共通の設定
以下は、基本となる設定をYAMLファイルに指定する方法です。基本の設定として一般的ものをいくつか紹介します。必要に応じて編集してください。
- ログをコンソール出力にリダイレクト
- プロキシの設定(プロキシがある場合)
- エージェントのアクティビティを制限するパフォーマンスチューニングオプション
手順は、以下のとおりです。
- 基本の設定オプションを追加します。共通の固定の値となります。
api: |
- 次に、YAMLファイルを作成して、ベースイメージにコピーします。ここでは、YAMLファイルは、イメージ内のアプリケーションのベースディレクトリにある/app/contrast_security.yamlとしています。
- 編集したYAMLファイルをDockerfileにコピーします。
COPY WORKSPACE/contrast_security.yaml /app/contrast_security.yaml |
アプリケーション固有の設定
この方法によって、アプリケーションごとに追加のオプションを指定できます。アプリケーション固有の設定を指定するために、環境変数を使用します。
メモ:これらは、必要に応じてDockerfile内でENV命令を使用して指定するか、Docker runコマンドの実行時に -eオプションで指定することもできます。
- アプリケーションのメタデータ:アプリケーションに関連付けるユーザ定義のメタデータを指定
CONTRAST__APPLICATION__METADATA
- アプリケーション名:Contrastサーバに報告されるアプリケーションを指定
CONTRAST__APPLICATION__NAME
- アプリケーションのセッションメタデータ:ビルド番号、バージョン、ハッシュなどの情報でセッションの新規作成時に使用されるメタデータを指定(詳細は、Contrastドキュメントを参照)
CONTRAST__APPLICATION__SESSION_METADATA
- アプリケーショングループ:このアプリケーションを関連付けるアクセスグループをオンボード時に指定(注:アプリケーションのアクセスグループは、先にContrastで作成しておく必要あり)
CONTRAST__APPLICATION__GROUP
- サーバの環境:アプリケーションを実行する環境を指定、このオプションで有効な値:development、qa、production
CONTRAST__SERVER__ENVIRONMENT
3. Contrastエージェントを使用するよう起動コマンドを更新
Contrastを有効にするには、アプリケーションの起動時にContrastエージェントを組み込む必要があります。通常は、これはDockerfileのCMD文で行いますが、package.jsonに定義したnpmスクリプトを使用することもできます。
例えば、通常アプリケーションが以下で起動される場合は、
CMD [“node”, “app”]
|
Contrastを有効にするために以下のコマンドを使用できます。
CMD [“node”, “-r”, “@contrast/agent”, “app”]
|
4. アプリケーションでエージェントを有効にして起動
エージェントが起動されると、手順2で設定したURLとエージェントの認証情報を使ってContrastサーバへの接続を試みます。エージェントの認証情報を保護するために、Docker secretを利用して、デプロイ時に環境変数として渡すこともできます。以下は、Docker runコマンドの例です。
docker run -e CONTRAST__API_ -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value> -e CONTRAST__API__USER_NAME=<value> -e CONTRAST__SERVER__ENVIRONMENT=<value> image_with_contrast
|
Contrastが実行されていることは、コンテナのログに次のようなメッセージが表示されることで確認できます。
@contrast/agent 2.16.8 |
ソースコードのサンプル: OWASP Juice Shop
以下のGitHubのリポジトリにあるサンプルアプリケーションを参考にしてください。Docker環境のNode.jsアプリケーションにContrastエージェントを組み込むための手順や設定を理解するのに役立ちます。
https://github.com/Contrast-Security-OSS/contrastsecurity-node-docker-onboarding-guide-sample-project
FAQ
- Node.jsエージェントはアプリケーションのパフォーマンスにどの程度影響しますか?
アプリケーションで使用可能なCPUとメモリを増やす必要があります:Node.jsエージェントのシステム要件 - Node.jsエージェント使用時にアプリケーションの起動に影響はありますか?
Does the Node.js agent affect my application's performance? - Contrastログにある接続エラーはどのように処理すればよいですか?
Connectivity Issues with the Node Agent - 新しいバージョンのContrastエージェントは、古いバージョンのContrastサーバに対して動作しますか?また、その逆の場合は?
動作するかもしれませんが、推奨しません。常に両方を最新にしてください:Contrastエージェント