エージェントインストールガイド
概要
ここでは、Docker環境でContrastの.NET Coreエージェントを使用する方法について紹介します。本項を参考にご利用の環境に合わせた方法で、Dockerの.NET CoreアプリケーションにContrastエージェントをインストールし、必要に応じてチーム内で共有してください。
本項では主に、Docker上の.NET CoreアプリケーションにContrastエージェントを組み込み、Contrastでセキュリティデータを確認するための最も一般的な方法について説明します。
また、eShopOnWebというサンプルの.NET Coreアプリケーションに関する情報も記載しています。自分のアプリケーションで作業をする前に、このサンプルアプリケーションで手順を確認してみるのも良いでしょう。eShopOnWebのサンプルコードへのリンクは本項の最後にあります。サンプルコードを使用して、Docker環境のeShopOnWebにContrastエージェントをインストールしてアプリケーションを検査してみてください。
主な手順
アプリケーションのDockerfileを更新する
アプリケーションでContrastエージェントを有効にする
サポート対象のテクノロジ
作業を開始する前に、ご利用の.NET Coreのツールや環境がContrastでサポートされていることを確認してください：.NET Coreのサポート対象テクノロジ
本項は以下を前提としております：
- DevOpsの実践とDockerの仕組みに関してある程度の知識があること
- Contrast .NET CoreエージェントがContrastサーバに接続するための必要な情報があること： .NET Coreエージェントの設定
- Contrast .NET Coreエージェントをダウンロードして起動したことがあること
手順
まず、アプリケーションのDockerfileを編集します。
1) Contrast .NET Coreエージェントを追加
ここでは、DockerイメージにContrastエージェントを追加して、基本の設定を行う方法について2つ紹介します。最適な方法をお選びください。
方法 1：ベースイメージに追加
- Contrastエージェントと基本の設定を、有効化せずにDockerベースイメージへ追加します
- ENVを一箇所更新して、 このイメージを使用するアプリケーションでContrastを利用可能にします
- アプリケーションのDockerイメージまたはコンテナでContrastを有効にします
例：ベースイメージのDockerfileの設定
FROM mcr.microsoft.com/azure-functions/dotnet:3.0 AS base
# Add contrast sensor package
FROM ubuntu:bionic AS contrast
RUN set -xe \
&& apt-get update \
&& apt-get install -y curl unzip \
&& curl -v -L https://www.nuget.org/api/v2/package/Contrast.SensorsNetCore -o /tmp/contrast.sensorsnetcore.nupkg \
&& unzip /tmp/contrast.sensorsnetcore.nupkg -d /tmp/contrast \
&& rm /tmp/contrast.sensorsnetcore.nupkg
FROM base AS final
WORKDIR /home/site/wwwroot
COPY --from=publish /app/publish .
COPY --from=contrast /tmp/contrast /opt/contrast
方法 2：アプリケーションイメージに追加
この方法の場合、チームではどのバージョンのContrastエージェントでも使用できるようになり、自動更新されるのを避けることができます。手順は、以下のとおりです。
- Contrast UIからContrastエージェントをダウンロードします。
- 手順はContrastのドキュメントを参照：.NET Coreエージェントの手動インストール
- ダウンロードしたzipアーカイブ(例えば、Contrast.NET.Core_1.5.11.zip)を、アプリケーションのプロジェクト内のディレクトリに展開します。
- Contrastエージェントとエージェントの設定をアプリケーションのDockerイメージに直接追加します。
COPY Contrast.NET.Core_1.5.11 /app/Contrast.NET.Core.1.5.11
2) Contrastエージェントの設定を指定
Contrastエージェントの設定を指定するために、さまざまな値を使用できます。設定する値には有効になる優先順位があります。各レベルは、上位のレベルが指定された場合に無効になります。優先順位は以下のとおりで、最も優先されるのが1です。
- 企業の基準(例、期限切れのライセンスは、assess.enableより優先)
- 環境変数の値
- YAML設定ファイルの値
- Contrast UIで指定した値
- デフォルトの値
優先順位の詳細については、以下を参照してください：
エージェントの設定の優先順位
設定する値を組み合わせて利用することをお勧めします。
- 共通の設定はYAMLファイルに保存してベースイメージに配置e
- アプリケーション固有の設定に関する値は環境変数を使用
共通の設定
YAMLファイルには、次のような共通の設定値を指定できます。.NET Coreエージェントには、全ての設定オプションを環境変数で指定できるため、このファイルは必須ではありません。
Contrastの設定で、すべてのアプリケーションに共通する値をこのファイルに定義するのがよいでしょう。詳細はこちら：.NET Coreエージェントの設定
環境変数 CONTRAST_CONFIG_PATH を使用して、YAMLファイルの場所を指定することもできます。
- 以下のように設定オプションと値を追加します。
agent:
logger:
path: /var/tmp
level: WARN
- 次に、YAMLファイルを作成して、ベースイメージにコピーします。ここでは、YAMLファイルは「PATH/TO/AGENT/contrast_security.yaml」として保存されていると仮定します。このパスはご利用の環境の設定ファイルへのパスに置き換えてください。
- 次の行をDockerfileに追加して、編集したYAMLファイルをベースイメージのDockerfileにコピーします。
COPY WORKSPACE/contrast_security.yaml PATH/TO/AGENT/contrast_security.yaml
アプリケーション固有の設定
アプリケーション固有の設定を指定するために、アプリケーションのコンテナ内の環境変数を使用します。以下は、一般的によく使用される設定オプションです。その他のオプションについては、Contrastのドキュメントを参照：.NET Coreエージェントの設定
- アプリケーション名：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) プロファイル変数および自分の環境の認証情報を追加
.NET Coreエージェントの設定を完了するには、アプリケーションに次の環境変数を渡す必要があります。CORECLR_ 変数はエージェントをロードし、CONTRAST_ 変数はContrastサーバに対するエージェントの認証用です。
CORECLR_PROFILER_PATH_64={path to the ContrastProfiler.so} Examples: /app/contrast/runtimes/linux-x64/native/ContrastProfiler.so
/opt/contrast/contentFiles/any/netstandard2.0/contrast/runtimes/linux-x64/native/ContrastProfiler.so (If following the Nuget example from Option one when adding the agent)
CORECLR_ENABLE_PROFILING=1
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で取得するか、.NET CoreエージェントのYAMLファイルをダウンロードすることで取得できます。詳細は、Contrastのドキュメントを参照：エージェントキーの検索
API_KEY、SERVICE_KEY、USER_NAMEは機密データとなりますので、取り扱いにはご注意ください。
4) アプリケーションでエージェントを有効にして起動
これで、Contrastを有効にしてアプリケーションイメージを実行できます。アプリケーションの起動時にContrastエージェントが組み込まれて解析が始まり、Contrastサーバに脆弱性が報告されます。
Contrastが実行されているかを確認するには、コンテナのログをチェックしてください。次のようなメッセージが表示されるはずです。
ソースコードのサンプル: eShopOnWeb
以下のGitHubのリポジトリにあるサンプルアプリケーションを参考にしてください。Docker環境の.NET CoreアプリケーションにContrastエージェントを組み込むための手順や設定を理解するのに役立ちます。
https://github.com/Contrast-Security-OSS/eShopOnWeb
<%= heading %>