Security¶

Beacon Security is an optional capability inside each language's normal zero-code package. It is disabled by default and does not introduce a second agent, wrapper command, or release lifecycle.

Language	Runtime scope	Deployment
Java	The complete Java Agent	One Agent JAR
Python	Standard-GIL CPython 3.11–3.14	The existing `beacon` command
Node.js	Node.js 22.22.3+ or 24.11.1+	The existing package with ESM preload

When enabled, Security sends findings and runtime software inventory through the application's OpenTelemetry Logs pipeline. Runtime SBOM collection is on by default within the enabled Security lifecycle. Process-local diagnostic files remain off unless explicitly enabled.

Findings describe bounded modeled-flow observations or candidate risks. They are not confirmation that an application is vulnerable. Start with the guide for the application's runtime and validate the exported Logs records before rolling the configuration out broadly.

.NET and PHP do not currently have a released Beacon Security capability.

Connect to DataKit¶

Enable the DataKit OpenTelemetry input using Common configuration, then install the agent for your language. Security exports OTLP Logs; verify the records in Logs in Guance. These examples assume that the application and DataKit run on the same host.

Java¶

Beacon Java embeds Security in the complete Agent JAR. Keep the same -javaagent setup from the Java zero-code guide; there is no separate Security JAR to install or version.

Enable 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

The Agent exports findings and runtime CycloneDX SBOM records through OpenTelemetry Logs. Security is disabled by default. Findings are modeled runtime observations or candidate risks rather than confirmed vulnerabilities.

Java configuration reference¶

Environment variable	Default	Purpose
`BEACON_SECURITY_ENABLED`	`false`	Enables the Security lifecycle and runtime observation.
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Collects runtime SBOM while Security is enabled.
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	Enables process-local diagnostic snapshots.
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	Sets the diagnostic snapshot directory.
`BEACON_SECURITY_EVIDENCE_FILE`	Unset	Sets an optional diagnostic JSONL file.

Normal OpenTelemetry variables configure resource identity, transport, and authentication. Local output is for diagnosis only and is not durable or cluster-wide delivery.

Python¶

Beacon Python includes Security in the beacon-otel wheel. It supports standard-GIL CPython 3.11 through 3.14 and uses the existing beacon command; there is no separate Security distribution.

Enable 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 contains Python module prefixes, not file paths. Without it, the enabled lifecycle can export the runtime SBOM but does not transform application modules or produce modeled-flow findings.

Python configuration reference¶

Environment variable	Default	Purpose
`BEACON_SECURITY_ENABLED`	`false`	Enables the Security lifecycle and runtime SBOM.
`BEACON_SECURITY_PYTHON_INCLUDE`	Empty	Selects application module prefixes for finding collection.
`BEACON_SECURITY_PYTHON_EXCLUDE`	Empty	Excludes module prefixes and takes precedence over include.
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Collects runtime SBOM while Security is enabled.
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	Enables process-local diagnostic files.
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	Sets the diagnostic directory.
`BEACON_SECURITY_EVIDENCE_FILE`	Unset	Sets an optional diagnostic JSONL file.

Findings and SBOM records use the OpenTelemetry Logs pipeline. Local output is diagnostic evidence and remains off by default.

Node.js¶

Beacon Node.js includes Security in @beacon-observability/nodejs. Applications normally install only that complete package. Security requires Node.js 22.22.3+ or 24.11.1+ because it uses synchronous module hooks for scoped source transformation.

Enable Node.js Security¶

Use the ESM --import preload. The CommonJS --require preload still starts normal telemetry and profiling but cannot activate Security transformation.

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 selects application source roots. Package dependencies, Node.js built-ins, and explicitly excluded roots are not transformed.

Node.js configuration reference¶

Environment variable	Default	Purpose
`BEACON_SECURITY_ENABLED`	`false`	Enables the Security lifecycle and runtime SBOM.
`BEACON_SECURITY_NODE_INCLUDE`	Empty	Selects application source roots for finding collection.
`BEACON_SECURITY_NODE_EXCLUDE`	Empty	Excludes source roots and takes precedence over include.
`BEACON_SECURITY_SBOM_ENABLED`	`true`	Collects runtime SBOM while Security is enabled.
`BEACON_SECURITY_LOCAL_OUTPUT_ENABLED`	`false`	Enables process-local diagnostic files.
`BEACON_SECURITY_OUTPUT`	`./beacon-security-output/<instance-id>`	Sets the diagnostic directory.