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

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

概要

ここでは、Docker環境でContrastのRubyエージェントを使用する方法について紹介します。本項を参考にご利用の環境に合わせた方法で、DockerのRubyアプリケーションにContrastエージェントをインストールし、必要に応じてチーム内で共有してください。

本項では主に、Docker上のRubyアプリケーションにContrastエージェントを組み込み、Contrastでセキュリティデータを確認するための最も一般的な方法について説明します。

また、RailsGoatというサンプルのRubyアプリケーションに関する情報も記載しています。自分のアプリケーションで作業をする前に、このサンプルアプリケーションで手順を確認してみるのも良いでしょう。RailsGoatのサンプルコードへのリンクは本項の最後にあります。サンプルコードを使用して、Docker環境のRailsGoatにContrastエージェントをインストールしてアプリケーションを検査してみてください。

主な手順

アプリケーションのDockerfileを更新する：

1. Contrast Rubyエージェントを追加
2. Contrast Rubyエージェントの設定を指定
3. 環境の認証資格情報を追加 

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

4. コンテナ化したアプリケーションでContrastを有効にして実行・動作を確認

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

作業を開始する前に、ご利用のRubyのツールや環境がContrastでサポートされていることを確認してください：Rubyエージェントのサポート対象テクノロジ

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

• DevOps実践とDockerの仕組みに関してある程度の知識があること
• Rubyのgemリポジトリへアクセスできること
• Contrast RubyエージェントがContrastサーバに接続するための情報があること

手順

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

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

ここでは、DockerイメージにContrastエージェントを追加して、基本の設定を行う方法について2つ紹介します。最適な方法をお選びください。

方法 1：Dockerfileに追加

この方法では、ContrastエージェントをアプリケーションのDockerfileに追加します。手順は、以下のとおりです。 

• アプリケーションのDockerイメージの最後にContrastエージェントを追加
• Contrastの設定値を追加

最新のRuby gemのエージェントを追加できます。

RUN bundle add contrast-agent

もしくは、特定のバージョンを対象とすることもできます。 

RUN bundle add contrast-agent -v 3.12.1

例： Dockerfileの設定

FROM ruby:2.6.5
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
RUN mkdir /myapp
WORKDIR /myapp
ADD Gemfile /myapp/Gemfile
ADD Gemfile.lock /myapp/Gemfile.lock
RUN bundle install
ADD . /myapp
RUN bundle add contrast-agent -v 3.12.1

方法 2：Gemfileに追加

この方法では、ContrastエージェントをソースGemfileに追加します。手順は、以下のとおりです。

• ContrastエージェントをアプリケーションのGemfileに追加します。必要に応じて、エージェントのバージョンを指定します。もしくは、gem listに直接追加するか、オプショングループとして追加します。
• Contrastの設定値を追加します。

Gemfileの例：Contrast Rubyエージェントをすべての環境で実行する場合のコマンド

gem "contrast-agent", "3.12.1"

Gemfileの例：Contrast Rubyエージェントを特定の環境で実行する場合のコマンド

gem 'contrast-agent', require: !!ENV['CONTRAST__ENABLE'] != "production"

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

Contrastエージェントの設定を指定するために、さまざまな値を使用できます。設定する値には有効になる優先順位があります。各レベルは、上位のレベルが指定された場合に無効になります。優先順位は以下のとおりで、最も優先されるのが1です。

1. 企業の基準(例、期限切れのライセンスは、assess.enableより優先)
2. 環境変数の値
3. YAML設定ファイルの値
4. Contrast UIで指定した値
5. デフォルトの値

優先順位の詳細については、以下を参照してください：
エージェントの設定の優先順位

設定する値を組み合わせて利用することをお勧めします。

• 共通の設定はYAMLファイルに保存してベースイメージに配置
• 認証情報やアプリケーション固有の設定は環境変数を使用

共通の設定

以下は、基本となる設定をYAMLファイルに指定する方法です。ベースイメージに追加して、必要に応じて環境変数で上書きすることもできます。

手順は、以下のとおりです。

1. サービスとログの基本的な設定を追加します。

agent:
  logger:
    path: /proc/1/fd/1
    level: ERROR
    # Set to `true` for the agent to tag logs
    # with \"!AM!\" for the metrics tool.
    # metrics: true
  security_logger:
    path: /proc/1/fd/1
    level: ERROR
  service:
    host: localhost
    port: 30555
    logger:
      path: /proc/1/fd/1
      level: ERROR

2. 編集したYAMLファイルをベースイメージのDockerfileにコピーします。

コンテナ内の以下のいずれかの場所にコピーします：

• <approot>/contrast_security.yaml
• <approot>/config/contrast_security.yaml
• /etc/contrast_security.yaml
  

COPY WORKSPACE/contrast_security.yaml approot/contrast_security.yaml

アプリケーション固有の設定

アプリケーション固有の設定には、アプリケーションのコンテナで環境変数を指定します。以下は、一般的によく使用される設定オプションです。注：アンダースコアは2つ付けてください。

詳細は、Contrastドキュメントを参照：Rubyエージェントの設定

• アプリケーション名： Contrastサーバに報告されるアプリケーション名を指定
  CONTRAST__APPLICATION__NAME
• アプリケーショングループ： このアプリケーションを関連付けるアクセスグループをオンボード時に指定(注：アプリケーションのアクセスグループは、先にContrastで作成しておく必要あり)
  CONTRAST__APPLICATION__GROUP
• アプリケーションのタグ：アプリケーションにタグを指定
  CONTRAST__APPLICATION__TAGS
• サーバ名： Contrastに報告されるサーバ名を指定
  CONTRAST__SERVER__NAME
• サーバの環境： アプリケーションを実行する環境をして、このオプションで有効な値：development、qa、production
  CONTRAST__SERVER__ENVIRONMENT
• サーバのタグ： サーバ名にタグを追加
  CONTRAST__SERVER__TAG

3. 環境の認証資格情報を追加

RubyエージェントがContrastサーバにデータを送信するには、APIのURLとサーバに対するエージェントの認証情報が必要です。 このデータは機密情報となりますので、取り扱いにはご注意ください。

CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast
CONTRAST__API__API_KEY={Your API KEY}
CONTRAST__API__SERVICE_KEY={Your Service key}
CONTRAST__API__USER_NAME={Your agent user}

APIの値(エージェントキー)は、Contrast UIで取得するか、RubyエージェントのYAMLファイルをダウンロードすることで取得できます。

詳細は、Contrastのドキュメントを参照：エージェントキーの検索

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

これで、Contrastを有効にしてアプリケーションイメージを実行できます。アプリケーションの起動時にContrastエージェントが組み込まれて解析が始まり、Contrastサーバに脆弱性が報告されます。

Contrastが実行されているかを確認するには、コンテナのログをチェックしてください。次のようなメッセージが表示されるはずです。

web_1  | !!! Contrast - working directory: /myapp
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:58.085+0000","v":0,"msg":"Framework detected. Enabling support.","framework":"Rails"}
web_1  | Puma starting in single mode...
web_1  | * Version 4.2.1 (ruby 2.6.5-p114), codename: Distant Airhorns
web_1  | * Min threads: 0, max threads: 16
web_1  | * Environment: development
web_1  | * Listening on tcp://0.0.0.0:3000
web_1  | Use Ctrl-C to stop
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Current rule settings:"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Assess Rule mode set","rule":"redos","mode":true}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":50,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"Field 'user': Value must not be blank"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.279+0000","v":0,"msg":"CONTRAST-SERVICE -- Version: 2.9.2 PID: 20 WorkingDir: /myapp"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.280+0000","v":0,"msg":"Current rule settings:"}
web_1  | {"name":"Contrast Agent","hostname":"d93cca918965","pid":1,"level":30,"time":"2020-07-09T14:02:59.280+0000","v":0,"msg":"Assess Rule mode set","rule":"redos","mode":false}

既知の問題

contrast_security.yaml fileファイルを使用しないでエージェントの設定をする場合、以下のようなエラーメッセージがログに出力されることがあります。

web_1  | !!! Contrast - valid configuration file could not be found at any of the search paths

これは無視しても問題ありません。 

ソースコードのサンプル: RailsGoat

以下のGitHubのリポジトリにあるサンプルアプリケーションを参考にしてください。Docker環境のRubyアプリケーションにContrastエージェントを組み込むための手順や設定を理解するのに役立ちます。
https://github.com/Contrast-Security-OSS/railsgoat 

FAQ

1. Contrast Rubyエージェントをテストスイートで実行するにはどうすればよいですか？
2. Rubyエージェントのログを取得するにはどうすればよいですか？
3. Rubyエージェント固有の設定は他にありますか？
4. 新しいバージョンのエージェントは、古いバージョンのContrastサーバに対して動作しますか？また、その逆の場合は？
   動作するかもしれませんが、推奨しません。常に両方を最新にしてください。参考：Contrastエージェント