Java Security¶

This guide uses Beacon Java 1.3.4. Security has been embedded in the complete Agent JAR since 1.1.0. Keep the same -javaagent setup from the Java zero-code guide; there is no separate Security JAR to install or version.

Prepare the DataKit Logs pipeline using the Security receiver configuration. Verify delivery against records actually received.

Enable Security¶

Before enabling Security, download the complete Agent JAR from the 1.3.4 Release and name it beacon-javaagent.jar.

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 dependency inventories through OpenTelemetry Logs. Local CycloneDX files require explicit diagnostic output. Security is disabled by default. Findings are modeled runtime observations or candidate risks rather than confirmed vulnerabilities.

Findings and analysis¶

Java 1.3.0 introduced per-request occurrences and request-specific attack evidence. Java 1.3.3 uses schema v2: occurrence_id replaces evidence_id, online cumulative counts are removed, and empty evidence arrays can be omitted. See Findings and evidence for the Java 1.3.0 A/B/C example, v1 fields, v2 migration, status meanings, and delivery limits. Occurrence export, detailed evidence sampling, and OpenTelemetry trace sampling are independent.

SQL analysis is opt-in. Set BEACON_SECURITY_ANALYSIS_SQL_DIALECT=ansi only for compatible SQL; the default is unknown. The bounded lexical subset supports single-quoted strings, doubled quote escapes, quoted identifiers, decimal numbers, operators, parentheses, and comments. It is not a complete SQL parser or keyword detector. Backslash escapes, dollar quoting, backticks, bracket quoting, incomplete quotes, and tainted identifiers alone remain unknown. Fixed templates with separately bound values differ from untrusted SQL assembled before preparation; normal bound values do not create SQL-template findings.

Shell analysis supports simple POSIX scripts passed as a separate argument to sh, bash, dash, ksh, or zsh, including quotes, escapes, and control separators. Expansions, substitutions, redirections, compound syntax, Windows shells, and scripts reconstructed from Runtime.exec(String) remain unknown. Ordinary argv input is not classified as shell injection; application-specific argument risks remain possible.

Analysis is limited to 8,192 UTF-16 code units and 64 exact taint ranges. Unsupported inputs, imprecise ranges, and exhausted budgets retain uncertainty. There is no exploit replay, network probing, JDBC metadata lookup, or filesystem resolution. Java 1.3.4 has no network allowlist or filesystem-root policy; boundary-dependent SSRF, executable-selection, and path judgments remain unknown. Normalization does not establish safety. See the released analysis reference.

Configuration reference¶

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

Finding export policy¶

Findings classified as attack_evidence.status=no_evidence are not exported by default. unknown, suspected, and SBOM records remain eligible for export. Set BEACON_SECURITY_EXPORT_NO_EVIDENCE_ENABLED=true to restore the previous behavior. The switch controls OpenTelemetry Logs and evidence JSONL; internal detection, local finding snapshots, span summaries, and same-request evidence upgrades remain available. See the shared export policy.

Java also accepts -Dbeacon.security.export.no-evidence.enabled=true; put the JVM option before -jar.

Kubernetes¶

Put the complete released Agent JAR in the application image, or follow the version-pinned initContainer example. When using the public image, change the example image to ghcr.io/beacon-observability/beacon-java:1.3.4 and pin its digest for production. The init container copies the same JAR into an emptyDir; the application loads it with JAVA_TOOL_OPTIONS. Keep local output disabled for normal workloads.

Remove BEACON_SECURITY_ENABLED or set it to false to disable Security while leaving normal zero-code telemetry active.