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 管道发送安全发现和运行时软件清单。运行时 SBOM 在 Security 生命周期中默认开启；进程本地诊断文件仍保持关闭，除非显式启用。

安全发现表示有边界的已建模数据流观测或候选风险，并不确认应用存在漏洞。请先选择应用运行时对应的指南，并在扩大配置范围前验证已导出的 Logs 记录。

.NET 和 PHP 当前没有已发布的 Beacon Security 能力。

接入 DataKit¶

先按公共配置开启 DataKit OpenTelemetry 采集器，并完成对应语言的零代码安装。Security 通过 OTLP Logs 上报，在观测云「日志」中验证记录。以下示例假设应用与 DataKit 位于同一主机。

Java¶

Beacon Java 已将 Security 嵌入完整 Agent JAR。继续使用 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 使用同步模块 Hook 进行限定范围的源码转换，因此要求 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>`	设置诊断目录。