Security¶

Beacon Security は、各言語の既存のゼロコードパッケージに含まれる任意機能です。既定では無効で、別の Agent、ラッパーコマンド、独立したバージョン管理は追加されません。

言語	ランタイムの対象範囲	デプロイ方法
Java	完全版 Java Agent	単一の Agent JAR
Python	標準 GIL の CPython 3.11–3.14	既存の `beacon` コマンド
Node.js	Node.js 22.22.3+ または 24.11.1+	既存パッケージと ESM プリロード

有効にすると、Security はアプリケーションの既存の OpenTelemetry Logs パイプラインを使い、セキュリティ検出結果とランタイムのソフトウェア一覧を送信します。Security のライフサイクルではランタイム SBOM が既定で有効になります。プロセスローカルの診断ファイルは、明示的に有効にするまで無効のままです。

セキュリティ検出結果は、モデル化された範囲内でのデータフロー観測やリスク候補を示し、脆弱性の存在を確定するものではありません。まずアプリケーションのランタイムに対応するガイドを選び、設定範囲を広げる前にエクスポートされた Logs レコードを確認してください。

.NET と PHP には、現在リリース済みの Beacon Security 機能はありません。

DataKit への接続¶

共通設定に従って DataKit OpenTelemetry コレクターを有効にし、対象言語のゼロコードインストールを完了してください。Security は OTLP Logs で送信します。Guance の「ログ」でレコードを確認してください。以下は、アプリケーションと DataKit が同じホストにあることを前提とします。

Java¶

Beacon Java の完全版 Agent JAR には Security が組み込まれています。Java ゼロコードガイドと同じ -javaagent 設定を引き続き使用してください。別の Security JAR をインストール、管理する必要はありません。

Java Security の有効化¶

export BEACON_SECURITY_ENABLED=true
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
java -javaagent:./beacon-javaagent.jar -jar orders.jar

Agent は OpenTelemetry Logs でセキュリティ検出結果とランタイム CycloneDX SBOM をエクスポートします。Security は既定では無効です。検出結果はモデル化されたランタイム観測やリスク候補を示し、確認済みの脆弱性を意味しません。

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

環境変数	既定値	用途
`BEACON_SECURITY_ENABLED`	`false`	Security のライフサイクルとランタイム観測を有効にします。
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Security が有効なときにランタイム SBOM を収集します。
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	プロセスローカルの診断スナップショットを有効にします。
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	診断スナップショットのディレクトリを指定します。
`BEACON_SECURITY_EVIDENCE_FILE`	未設定	任意の診断 JSONL ファイルを指定します。

標準の OpenTelemetry 変数でリソースの識別、転送、認証を設定します。ローカル出力は診断用であり、永続化やクラスターレベルの配信の仕組みではありません。

Python¶

Beacon Python は beacon-otel wheel に Security を含みます。標準 GIL の CPython 3.11 から 3.14 に対応し、既存の beacon コマンドをそのまま使用します。別の Security パッケージは不要です。

Python Security の有効化¶

export BEACON_SECURITY_ENABLED=true
export BEACON_SECURITY_PYTHON_INCLUDE=orders
export OTEL_SERVICE_NAME=orders
export OTEL_RESOURCE_ATTRIBUTES=service.namespace=shop
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
beacon uvicorn orders.asgi:application --host 0.0.0.0 --port 8000

BEACON_SECURITY_PYTHON_INCLUDE には、ファイルシステムのパスではなく Python モジュールのプレフィックスを指定します。未設定の場合、有効なライフサイクルからランタイム SBOM はエクスポートできますが、アプリケーションモジュールの変換や、モデル化されたデータフローの検出結果は生成されません。

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

環境変数	既定値	用途
`BEACON_SECURITY_ENABLED`	`false`	Security のライフサイクルとランタイム SBOM を有効にします。
`BEACON_SECURITY_PYTHON_INCLUDE`	空	セキュリティ検出の収集対象となるアプリケーションモジュールのプレフィックスを選択します。
`BEACON_SECURITY_PYTHON_EXCLUDE`	空	除外するモジュールプレフィックス。include より優先されます。
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Security が有効なときにランタイム SBOM を収集します。
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	プロセスローカルの診断ファイルを有効にします。
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	診断ディレクトリを指定します。
`BEACON_SECURITY_EVIDENCE_FILE`	未設定	任意の診断 JSONL ファイルを指定します。

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

Node.js¶

Beacon Node.js は @beacon-observability/nodejs に Security を含みます。通常はこの完全版パッケージをインストールするだけで利用できます。Security は同期モジュールフックによって限定された範囲のソース変換を行うため、Node.js 22.22.3+ または 24.11.1+ が必要です。

Node.js Security の有効化¶

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

npm install @beacon-observability/nodejs

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 の組み込みモジュール、明示的に除外したルートは変換されません。

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

環境変数	既定値	用途
`BEACON_SECURITY_ENABLED`	`false`	Security のライフサイクルとランタイム SBOM を有効にします。
`BEACON_SECURITY_NODE_INCLUDE`	空	セキュリティ検出の収集対象となるアプリケーションのソースルートを選択します。
`BEACON_SECURITY_NODE_EXCLUDE`	空	除外するソースルート。include より優先されます。
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Security が有効なときにランタイム SBOM を収集します。
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	プロセスローカルの診断ファイルを有効にします。
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	診断ディレクトリを指定します。