Docker環境でのNode.jsエージェント

エージェントインストールガイド

概要

ここでは、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エージェントをアプリケーションに追加
Contrastエージェントの設定ファイルを作成
Contrastエージェントを使用するよう起動コマンドを更新

アプリケーションでContrastエージェントを有効にする

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: 
  url: https://app.contrastsecurity.com
agent: 
  service: 
    enable: true
    logger: 
      path: /proc/1/fd/1
      level: INFO
    host: 127.0.0.1
    port: 30555
  logger: 
    path: /proc/1/fd/1
    level: INFO

次に、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
--------------------------------------
2020-07-20T19:05:14.407Z INFO contrast-service: BUILD {"progname": "Contrast Service", "version": "2.8.1", "buildTime": ""}
2020-07-20T19:05:14.407Z INFO Building timer for orphan request cleanup {"progname": "Contrast Service", "cleanupMs": 5000}
2020-07-20T19:05:14.408Z INFO Building timer for orphan app cleanup {"progname": "Contrast Service", "time": 5000}
2020-07-20T19:05:14.450Z INFO Creating New Application Server {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "clientId": "1", "pid": 1}
2020-07-20T19:05:14.450Z WARN Failed to initialize secure client, falling back to insecure client {"progname": "Contrast Service"}
2020-07-20T19:05:15.473Z INFO setting new server features for context{"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a"}
2020-07-20T19:05:15.474Z ERROR Error setting up CEF syslog {"progname": "Contrast Service", "err": "open /juice-shop/security.log: permission denied"}
2020-07-20T19:05:15.475Z INFO starting event scanner {"progname": "Contrast Service", "report": {}}
2020-07-20T19:05:15.486Z INFO Creating new application {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "appName": "juiceshop-guide", "language": "Node", "clientId": "1", "pid": 1}
2020-07-20T19:05:15.486Z INFO AppCreate: creating and initializing new application {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "server_name": "bc1bd6e5cd3a", "app_name": "juiceshop-guide", "app_lang": "Node", "client_id": "1", "pid": 1}
2020-07-20T19:05:15.921Z INFO setting new application settings {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "serverName": "bc1bd6e5cd3a", "appName": "juiceshop-guide", "language": "Node"}
2020-07-20T19:05:15.922Z INFO Setting session id on app context: {"progname": "Contrast Service", "uuid": "96299b72-f867-4354-b9c9-1eb23511cb8a", "clientid": "1", "appname": "juiceshop-guide", "applang": "Node", "apppath": "/juice-shop/package.json", "sessionid": "cd0b271e66974162bf5fcca8b32e37b1"}
Entering main at /juice-shop/app
info: All dependencies in ./package.json are satisfied (OK)
...

ソースコードのサンプル: 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エージェント

Docker環境でのNode.jsエージェント

エージェントインストールガイド

概要

主な手順

サポート対象のテクノロジ

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

手順

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

2. Contrastエージェントの設定を指定

3. Contrastエージェントを使用するよう起動コマンドを更新

4. アプリケーションでエージェントを有効にして起動

ソースコードのサンプル: OWASP Juice Shop

FAQ

この記事は役に立ちましたか？

<%= previousTitle %>

<%= nextTitle %>

この文書の目次

<%= heading %>

<%= block.name %>

よく閲覧される文書

カテゴリ

ナビゲーションメニュを切り替え

検索

エージェントインストールガイド

概要

主な手順

サポート対象のテクノロジ

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

手順

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

2. Contrastエージェントの設定を指定

3. Contrastエージェントを使用するよう起動コマンドを更新

4. アプリケーションでエージェントを有効にして起動

ソースコードのサンプル: OWASP Juice Shop

FAQ

この記事は役に立ちましたか？

<%= previousTitle %>

<%= nextTitle %>

この文書の目次

<%= heading %>

<%= block.name %>

よく閲覧される文書

カテゴリ

ナビゲーションメニュを切り替え

カテゴリ

カテゴリ