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는 동기 모듈 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>`	진단 디렉터리를 설정합니다.