設定
YAML設定ファイルについて説明します。コンテナイメージでは既定で
/etc/kestrelynx/config.ymlを使用します。未知のYAMLフィールドはエラーになるようになってます。
コメント付きの完全な例は
config.example.ymlに
あります。
スケジュール
| 設定項目 | 既定値 | 説明 |
|---|---|---|
schedule.daily_at |
空 | HH:MM形式のローカル時刻。空の場合は起動時点から24時間ごとに実行します。 |
schedule.run_on_start |
true |
KestreLynxの起動直後に1回スキャンします。 |
daily_atで使用するタイムゾーンは、コンテナのTZ環境変数で指定します。
スキャン
| 設定項目 | 既定値 | 説明 |
|---|---|---|
scan.severity |
[HIGH, CRITICAL] |
分析と通知の対象にするTrivyの深刻度です。 |
指定できる値はUNKNOWN、LOW、MEDIUM、HIGH、CRITICALです。
通知先
少なくとも1つの通知先が必要です。
| 設定項目 | 既定値 | 説明 |
|---|---|---|
notify.slack_webhook_url |
空 | Slack Incoming WebhookのURLです。チャンネルへの通知に対応します。 |
notify.slack_bot_token |
空 | chat:write権限を持つSlack Bot Tokenです。slack_channelと一緒に設定すると、スレッド投稿と前回レポートへのリンクを利用できます。 |
notify.slack_channel |
空 | Botで通知するSlackチャンネルIDです。 |
notify.generic_webhook_url |
空 | 構造化JSONを受け取るエンドポイントです。 |
notify.language |
en |
Slack通知とPR本文の言語です。enかjaを指定し、それ以外は設定エラーです。汎用WebhookのJSONは英語のままです。 |
notify.notify_on_clean |
false |
脆弱性がない場合にも通知します。 |
slack_webhook_urlとBot Tokenの組み合わせを同時には設定できません。
汎用Webhookは、どちらのSlack通知方式とも併用できます。
スレッドの位置とフッターの読み方は、スレッドのレポートを参照してください。
日本語のSlack通知は、次のように設定します。
翻訳する定型文と英語のまま残る内容は、通知の言語を参照してください。
通知モード
| 設定項目 | 既定値 | 説明 |
|---|---|---|
notify.mode |
diff |
diffは変化を通知し、fullはスキャンごとに現在の全項目を通知します。 |
notify.full_report_day |
monday |
diffモードで完全なレポートを送る曜日です。neverで無効化します。 |
差分として扱う変化はパッケージの変化、送信する条件はスキャン通知の送信条件を参照してください。
状態管理とDocker
| 設定項目 | 既定値 | 説明 |
|---|---|---|
docker.socket |
/var/run/docker.sock |
Dockerソケットのパスです。 |
state.path |
/var/lib/kestrelynx/state.json |
スキャン履歴と差分計算に使用するファイルです。 |
脅威情報フィードのキャッシュは、state.pathと同じディレクトリ内のintelディレクトリに保存します。
既定のパスは/var/lib/kestrelynx/intelです。
state.pathを含むディレクトリの永続化はセットアップ手順、履歴の扱いは履歴の継続を参照してください。
修正計画と修正PR
機能の入口は修正計画の案内、有効化は有効化の手順を参照してください。
有効化設定
| 設定項目 | 既定値 | 説明 |
|---|---|---|
remediation.enabled |
false |
修正計画を有効にします。 |
remediation.pull_requests.enabled |
false |
修正PRを有効にします。修正計画の有効化とGitHub tokenが必要です。 |
各設定で行う処理は計画とPRの実行範囲を参照してください。
GitHubアクセス
| 設定項目 | 既定値 | 形式・必須条件 |
|---|---|---|
remediation.github.token |
空 | 空白・制御文字を含まないGitHub tokenで、PRを有効にする場合は必須です。 |
| 用途 | 必要な権限 |
|---|---|
| 公開リポジトリの計画 | tokenなしで匿名の読み取りが可能 |
| 非公開リポジトリの計画 | 対象リポジトリに限定したfine-grained tokenのContents: Read |
| PRの作成・管理 | 対象リポジトリに限定したfine-grained tokenのContentsとPull requests: Read and write |
設定ファイルは所有者だけが読めるようにしてください。 tokenの送付先は認証情報の送付範囲を参照してください。
保存先
| 設定項目 | 既定値 | 形式・説明 |
|---|---|---|
remediation.storage_dir |
/var/lib/kestrelynx/remediation |
計画、配信記録、PR記録、ツールキャッシュを保存する絶対パスのディレクトリです。 |
state.pathを変えても、この保存先は変わりません。
内容は保存ファイルを参照してください。
イメージレジストリの認証
| 設定項目 | 既定値 | 説明 |
|---|---|---|
remediation.registries |
[] |
非公開イメージの候補選定と比較スキャンに使う、ホストごとの認証設定です。 |
| フィールド | 既定値・必須条件 | 形式・検証条件 |
|---|---|---|
host |
必須 | イメージ参照に書くホスト名またはIPv4アドレスと任意のポートで、scheme・パス・ユーザー情報は含めません。ポートは1〜65535です。 |
username |
必須 | 空白・制御文字・:を含まない、空でない文字列です。 |
password |
必須 | 空白・制御文字を含まない、空でないパスワードまたはアクセストークンです。 |
token_hosts |
[] |
認証情報を送ってよい追加のtoken serviceのホスト一覧で、各値の形式はhostと同じです。 |
- ホスト名は大文字・小文字を区別せず、
docker.io・index.docker.io・registry-1.docker.ioは同じホストとして扱う - 正規化後に同じ
hostとなる認証設定は重複して指定できない - Docker Hubの認証には
host: docker.ioとtoken_hosts: [auth.docker.io]を指定する
送付先とリダイレクトの制限は認証情報の送付範囲、設定手順は非公開イメージの認証を参照してください。
ソースの対応付け
| 設定項目 | 既定値 | 説明 |
|---|---|---|
remediation.mappings |
[] |
稼働中のComposeワークロードとGitHub上のソースファイルを対応付けます。 |
各項目にworkload、repository、base_branchと、ちょうど1種類のソースを設定します。
| 対応付け内のフィールド | 必須条件・形式 |
|---|---|
workload |
必須で、稼働中ワークロードのComposeラベルと一致するcompose/<project>/<service>です。 |
repository |
必須で、owner/name形式のGitHubリポジトリです。 |
base_branch |
必須で、ソースの取得元とPRの宛先に使う有効なGitブランチ名です。 |
compose.path / compose.service |
Composeの対応付けで必須の、リポジトリ相対のComposeファイルとサービス名です。 |
dockerfile.path |
Dockerfileの対応付けで必須の、リポジトリ相対のDockerfileです。 |
dockerfile.target |
任意のビルド対象ステージで、省略すると最後のステージを使います。英字で始まる128バイト以内の英数字・_・.・-です。 |
dependencies.directory |
依存ファイルの対応付けで必須のディレクトリで、.はリポジトリのルートです。 |
- パスはリポジトリ内の正規化したパスとし、先頭の
/、./、..、バックスラッシュを使わない - 同じワークロードには、ソースの種類ごとに1件ずつ、別の項目で対応付ける
- 共有する依存ディレクトリやDockerfileには同じbase branchを指定する
- 同じリポジトリの同じComposeファイルのサービスを複数のワークロードに対応付けない
- リポジトリ名の重複判定では大文字・小文字を区別しない
Composeのbuildからの特定と明示したDockerfileとの照合はベースイメージの特定、入力の対応範囲は対応する入力形式を参照してください。
処理の上限
次の設定はremediation.limits配下に指定します。
| 設定項目 | 既定値 | 単位・指定範囲 |
|---|---|---|
candidate_scans_per_cycle |
10 |
1サイクルの候補イメージのスキャン数で、正の整数です。 |
baseline_rescans_per_cycle |
10 |
比較条件をそろえるための1サイクルの比較元の再スキャン数で、正の整数です。 |
registry_requests_per_cycle |
200 |
token交換を含む1サイクルのイメージレジストリへのHTTP要求数で、正の整数です。 |
tag_pages_per_repository |
20 |
イメージリポジトリごとのタグ一覧取得の要求数で、対象系列を探索する要求も含む正の整数です。 |
cycle_timeout |
30m |
計画、依存更新、PR処理の期限で、正の期間です。通常の稼働イメージのスキャンは含みません。 |
new_prs_per_cycle |
3 |
PR有効時の1サイクルの新規PR数で、正の整数です。 |
open_prs |
10 |
PR有効時の設定したリポジトリ全体で開いているKestreLynxのPR数で、正の整数です。 |
dependency_jobs_per_cycle |
3 |
1サイクルで試みる依存更新の単位数で、正の整数です。パッケージ数やコンテナ数ではありません。 |
job_timeout |
6m |
各作業用コンテナの作成・実行・結果回収の期限で、1m〜60m30sです。 |
上限による結果は理由コード、PRの扱いはPRの管理、実行期限と後処理は作業用コンテナの実行を参照してください。
作業用イメージの取得先
| 設定項目 | 既定値 | 形式・検証条件 |
|---|---|---|
remediation.worker.registry |
空 | Docker Hubミラーのhost[:port][/path]を小文字で指定します。空の場合はDocker Hubを使います。 |
- scheme・タグ・digest・
//・..を含めない - パスには小文字英数字と区切りの
.・_・-を使う - ミラーには指定したホストとパスの下に、公式イメージと同じ内容の
library/node・library/pythonを配置する
固定と取得不能時の扱いは公式イメージの固定、系列は対応する実行環境、通信先は作業用イメージの取得を参照してください。
ツールの公開後待機時間
| 設定項目 | 既定値 | 形式・指定範囲 |
|---|---|---|
remediation.worker.tool_versions.min_release_age |
72h |
npm・pnpm・uvの公開から使用までの最小待機時間で、72hや30mのような正の期間です。0や負の値は指定できません。 |
判定はツール公開後の待機、取得時の検査はツールの取得と照合を参照してください。
ツールキャッシュの容量
| 設定項目 | 既定値 | 形式・指定範囲 |
|---|---|---|
remediation.worker.tool_versions.cache_max_size |
1GiB |
npm・pnpm・uvのキャッシュ容量の上限です。整数のバイト数、または整数にB・KiB・MiB・GiBを付け、最低128MiBを指定します。 |
再利用時の検査と容量不足時の扱いはツールキャッシュの再利用を参照してください。
作業プログラムの配置先
| 設定項目 | 既定値 | 形式・適用範囲 |
|---|---|---|
remediation.worker.program_dir |
空 | 空または絶対パスで、開発用の作業プログラムを置くディレクトリです。通常の配布版では指定不要です。 |
作業用コンテナに渡す際の検査はコンテナへの入力を参照してください。
起動時の検証
次の組み合わせは起動時にエラーになります。
remediation.enabledを有効にせず、PRだけを有効にした場合remediation.github.tokenなしでPRを有効にした場合kubernetes.enabled: trueで修正計画を有効にした場合
機能が無効でも、tokenの形式、保存先、対応付け、処理上限、レジストリ認証、作業用コンテナの設定を検証します。 この設定の検証だけで、リモートのリポジトリやイメージにアクセスできることは確認しません。
稼働時の使用状況
稼働時の使用状況は実験的な機能です。
| 設定項目 | 既定値 | 説明 |
|---|---|---|
runtime.enabled |
false |
Sensorの証拠を読み、使用状況を通知に反映します。Sensorを置かない場合は無効のままにします。 |
runtime.mute_unfixable_not_in_use |
false |
修正版がなく7日以上使用が確認されない所見のうち、条件を満たすものをSlackで通知オフにします。runtime.enabled: trueのときだけ有効です。優先度は変えず、汎用Webhookには全件残します。 |
runtime.evidence_dir |
/var/lib/kestrelynx-runtime |
Sensorの証拠ボリュームをマウントした絶対パスです。Sensorの--evidence-dirと一致させます。 |
runtime.enabled: falseでは、証拠ディレクトリを開かず、通知に稼働時の情報を追加しません。
エコシステム名のラベルとWebhookのエコシステム関連フィールドは、この設定に関係なく適用されます。
runtime.enabled: trueとkubernetes.enabled: trueの併用は設定エラーです。
稼働時の使用状況はDockerだけで利用できます。
有効時は、本体がDocker APIのGET /containers/jsonに加えて
GET /containers/{id}/jsonも使用します。io.kestrelynx.runtime.exclude=trueの
ラベルを持つコンテナは使用状況の判定から外します。値は小文字のtrueだけが該当します。
Sensorの導入手順、観測の判定方法、通知オフの条件と通知の再開、権限は稼働時の使用状況に記載しています。
Kubernetes
| 設定項目 | 既定値 | 説明 |
|---|---|---|
kubernetes.enabled |
false |
Dockerホストの代わりにKubernetesクラスタをスキャンします。 |
kubernetes.api_server |
空 | Kubernetes APIサーバのURLです。空の場合はKUBERNETES_SERVICE_HOSTとKUBERNETES_SERVICE_PORTを使用します。空でない値はhttps://で始まる必要があります。 |
kubernetes.token_file |
空 | ServiceAccountのトークンファイルです。空の場合は/var/run/secrets/kubernetes.io/serviceaccount/tokenを使用します。 |
kubernetes.ca_file |
空 | PEM形式のクラスタCAバンドルです。空の場合は/var/run/secrets/kubernetes.io/serviceaccount/ca.crtを使用します。 |
kubernetes.tls_server_name |
空 | APIサーバのTLS証明書の検証に使用するサーバ名を上書きします。空の場合は上書きしません。 |
kubernetes.namespaces |
[] |
スキャン対象のnamespaceです。空または省略した場合は、すべてのnamespaceを対象にします。 |
docker.socketに値（空文字列""を含みます）を設定した状態でkubernetes.enabled: trueを設定すると、
起動に失敗します。キーを省略するか値をnullにした場合は、この排他条件に該当しません。
空のdocker:セクションは受け付けます。Kubernetesを有効にする場合は、docker:セクション全体を削除してください。
クラスタ内では、api_server、token_file、ca_fileを空のままにすると、
Podに注入されたAPIサーバのアドレスと、マウントされたServiceAccountのトークンおよび
CAを使用できます。Kubernetesが有効な場合、api_serverが空で、APIサーバの環境変数の
いずれかが欠けていると起動に失敗します。CAバンドルは実行時に読み取り可能で、
有効なPEM証明書を含む必要があります。安全でない接続へのフォールバックはありません。
各namespaceはDNS-1123ラベルである必要があります。使用できる文字は小文字の英数字と ハイフンで、長さは1〜63バイト、先頭と末尾は英数字にします。namespaceを指定した場合、 Pod、ReplicaSet、Jobの一覧はnamespaceごとに個別に取得します。Nodeの一覧は 引き続きクラスタ全体から取得します。
環境
| 設定項目 | 既定値 | 説明 |
|---|---|---|
environment.name |
空 | このインスタンスのスキャン履歴に付ける任意の名前です。空の場合は、名前のない既定の環境になります。 |
空でない名前はDNS-1123ラベルである必要があります。使用できる文字は小文字の英数字と ハイフンで、長さは1〜63バイト、先頭と末尾は英数字にします。値は正規化しません。 大文字、ドット、アンダースコア、空白文字は受け付けません。
名前を設定すると、Slackのヘッダーには[name]として、汎用Webhookのペイロードでは
environmentオブジェクトのnameとして表示します。このオブジェクトには、
有効なadapterに基づくkindが常に含まれ、値はdockerまたはkubernetesです。
環境種別は設定できません。名前が空の場合、Webhookではnameを省略します。
この名前はスキャン履歴に付けるラベルであり、ホストを識別するものではありません。 ホスト名やIPアドレスから生成することもありません。状態ファイルを保持していれば、 ホストの再構築や移行の前後で同じ名前を使い続けても問題ありません。名前を追加、変更、 削除しても、履歴のリセット、初回検出日の変更、既存の検出項目の再通知は行いません。
悪用情報に基づく優先順位付け
| 設定項目 | 既定値 | 説明 |
|---|---|---|
triage.enabled |
true |
CISA KEVとEPSSによる優先順位付けを有効にします。 |
triage.act_now_epss |
0.10 |
CVEをact nowに分類するEPSS確率の下限です。 |
triage.watch_epss |
0.01 |
CVEを少なくともwatchに分類するEPSS確率の下限です。 |
triage.kev_url |
空 | CISA KEVフィードのURLを、ローカルミラーなどへ変更します。 |
triage.epss_url |
空 | EPSSフィードのURLを、ローカルミラーなどへ変更します。 |
triage.discussion_links |
true |
act-now CVEに関するHacker Newsの議論を検索します。 |
通信先と送信内容は外向きの通信を参照してください。
しきい値は次の条件を満たす必要があります。