Node.js Security¶

Beacon Node.js 2.0.1 には、@beacon-observability/nodejs のセキュリティがすでに含まれています。通常、アプリケーションはこの完全なパッケージをインストールするだけで済みます。セキュリティでは、スコープ指定されたソース変換に同期モジュールフックを使用するため、Node.js 22.22.3 以降または 24.11.1 以降が必要です。

まず、Security 受信側の設定に従って DataKit ログパイプラインを準備します。受信側の検証は、実際に受信した記録に基づいて行う必要があります。

セキュリティを有効にする¶

ESM の --import プリロードが必須です。CommonJS の --require プリロードでは通常のテレメトリと Profile は起動できますが、Security のソース変換は有効になりません。

npm install @beacon-observability/nodejs@2.0.1

export NODE_OPTIONS="--import @beacon-observability/nodejs/register"
export BEACON_SECURITY_ENABLED=true
export BEACON_SECURITY_NODE_INCLUDE=/srv/app
export OTEL_SERVICE_NAME=orders
export OTEL_RESOURCE_ATTRIBUTES=service.namespace=shop
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
node /srv/app/server.mjs

BEACON_SECURITY_NODE_INCLUDE でアプリケーションのソースルートを選択します。依存パッケージ、Node.js の組み込みモジュール、明示的に除外したルートは変換されません。

セキュリティの発見と分析¶

リクエストごとのロギングとリクエストレベルの攻撃証拠は 1.3.0 以降で利用可能であり、スキーマ v2 は 2.0.0 以降で利用可能です。このページでは 2.0.1 を使用し、リクエストレコードを occurrence_id で識別します。詳細な証拠のサンプリングは、リクエストレコードのエクスポートやトレースサンプリングとは独立しています。空の証拠配列は省略でき、サンプリング自体は切り捨てを表しません。オンライン読み込みの累積発生数はありません。コンシューマは、重複排除後に受信したオカレンスを集約する必要があります。 unknown、no_evidence、suspected、証拠のアップグレードと配信制限については、セキュリティ検出結果と証拠を参照してください。どのステータスであっても悪用の成功を保証するものではありません。

SQL 解析のデフォルトは unknown です。互換性のある SQL に対してのみ BEACON_SECURITY_ANALYSIS_SQL_DIALECT=ansi を設定し、引用符で囲まれた文字列と識別子、二重引用符のエスケープ、数値、単純な演算子、およびコメントの制限された字句サブセットを有効にします。これは完全なパーサーではありません。他の方言、バックスラッシュまたはドル引用符、サポートされていない構文、不正確なテイント、および 8,192 を超える UTF-16 コード単位または 64 のテイントマーカーを含む入力は、unknown のままです。準備されたステートメントを個別に処理する必要がある前に、テンプレートのバインド値と信頼できないテンプレートの結合を修正しました。

シェル解析は、単純な POSIX sh、bash、dash、ksh、zsh コマンド、引用符、エスケープ、および制御区切り文字をサポートします。展開、リダイレクト、複合構文、およびその他のシェルは unknown を維持します。通常の argv は、固定ターゲットのパス/クエリ入力からの独立した観測値です。ネットワーク許可リストまたはファイルシステムのルートディレクトリポリシーは実装されておらず、関連する境界判断は依然として unknown です。正規化はセキュリティを意味するものではありません。バイト文字列は、既知のテキスト方言に対して解析されません。詳細については、固定バージョンの分析リファレンスを参照してください。

攻撃証拠を発見せずにエクスポートする¶

2.0.1 は、デフォルトでは、no_evidence の結果を OpenTelemetry ログおよび証拠の JSONL にエクスポートしません。 BEACON_SECURITY_EXPORT_NO_EVIDENCE_ENABLED=true を設定してエクスポートを再開します。 unknown、suspected は引き続きエクスポートでき、SBOM は影響を受けません。フィルタリングはキューに参加する前に行われ、エクスポート損失としてカウントされません。内部検出、同じリクエストの重複排除、証拠のアップグレードは引き続き実行されます。ローカル検出スナップショットとスパン概要には、エクスポートされていない観測値が保存されます。 no_evidence は安全性を示すものではなく、エクスポートされたイベントがないことはリスクが検出されなかったことを証明するものではありません。

パラメータリファレンス¶

環境変数	既定値	用途
`BEACON_SECURITY_ENABLED`	`false`	Security のライフサイクルとランタイム SBOM を有効にします。
`BEACON_SECURITY_NODE_INCLUDE`	空	セキュリティ検出の収集対象となるアプリケーションのソースルートを選択します。
`BEACON_SECURITY_NODE_EXCLUDE`	空	除外するソースルート。include より優先されます。
`BEACON_SECURITY_FINDINGS_SAMPLE_SECONDS`	`300`	各検出の完全な証拠のサンプリング間隔 (秒)。
`BEACON_SECURITY_ANALYSIS_SQL_DIALECT`	`unknown`	`ansi` は、サポートされている SQL レキシックスのサブセットを有効にします。
`BEACON_SECURITY_EXPORT_NO_EVIDENCE_ENABLED`	`false`	`no_evidence` イベントもエクスポートします。
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Security が有効なときにランタイム SBOM を収集します。
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	プロセスローカルの診断ファイルを有効にします。
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	診断ディレクトリを指定します。

セキュリティ検出結果と SBOM レコードは OpenTelemetry Logs パイプラインで送信されます。ローカル出力は診断用であり、既定では無効のままにしてください。

Kubernetes¶

アプリケーションイメージ内の完全なパッケージをインストールし、固定バージョンの Deployment サンプルを参照してください。通常のアプリケーションコンテナでは、ESM のプリロードと環境変数を設定するだけでよく、セキュリティサイドカーや初期化コンテナは必要ありません。

通常のゼロコードテレメトリを保持しながらセキュリティをオフにするには、BEACON_SECURITY_ENABLED を削除するか、false に設定します。