ClickHouse HOLs
GitHub

Decryption with an audit trail for Langfuse fields (open-source stack)


Verified end to end on 2026-11-02 against Langfuse 4.56.0 (OSS, no licence key, from the langfuse-hols v4 stack), ClickHouse 26.8.22.13, OpenBao 2.7.2 and Keycloak 26.8.1. Fresh volumes; the decryption service ran on python:3.12.15-slim; Docker 29.9.2, Compose v5.6.1. 02 passed 7 checks and 03 passed 28. A fault injected on purpose (bob added to svc-a-readers) made 03 fail 5 checks, and it passed again once the fault was removed.

Regulated teams ask for three things around LLM traces: encrypt sensitive fields, let only authorised people see them in clear, and keep a record of who decrypted what, when and why. Langfuse stores whatever it receives and has no decryption or read-audit feature. Its audit log, an Enterprise feature, records create/update/delete only. So the record has to come from the decryption path. This lab builds that path from open-source parts and tests it.

Architecture

  app ── encrypt (OpenBao Transit, encrypt-only token) ──► Langfuse OSS  (stores enc:<key>:vault:v1:…)
                                                              │ public API (service's project key)
  user ── IdP login (Keycloak) ── POST /decrypt + reason ──► decrypt-service ──► audit ClickHouse
                                                              │  1. attempt row      (audit.decrypt_events,
                                                              │  2. OpenBao login     insert-only writer,
                                                              │     with the USER's JWT                select-only auditor)
                                                              │  3. transit/decrypt + X-Request-Id
                                                              ▼  4. outcome row
                                                           OpenBao ── audit file ──► read in place by ClickHouse file()

Prerequisites

Run

cd usecase/langfuse-decryption-audit
./01-up.sh               # .env with generated passwords, 4 containers, OpenBao/ClickHouse/Keycloak config
./02-encrypt-and-send.sh # the "app": encrypt with OpenBao, send 2 encrypted + 1 plaintext trace to Langfuse
./03-decrypt-checks.sh   # 9 request scenarios, a bypass, the trail, the reconciliation, immutability
./04-audit-report.sh     # the reviewer's queries (per user, refusals, reconciliation)
./99-down.sh [--purge]   # --purge also deletes the audit table, OpenBao's audit file, .env and .state

OpenBao runs in dev mode (in memory), so 01-up.sh applies its configuration on every run. Langfuse is not touched by 99-down.sh.

What the checks found (2026-11-02)

02-encrypt-and-send.sh: 7 PASS - The app's token encrypts with both keys and gets HTTP 403 when it tries to decrypt. - Langfuse's API returns enc:svc-a:vault:v1:… for the encrypted traces; Langfuse's ClickHouse holds 0 rows with their plaintext, and the plaintext control is found by the same query.

03-decrypt-checks.sh: 28 PASS

Request Result OpenBao's reason (in the service row)
alice (svc-a-readers) → A, with a reason 200, plaintext —
carol (svc-b-readers) → B, with a reason 200, plaintext —
alice → B 403 claim "groups" does not match any associated bound claim values
bob (no group) → A 403 "groups" claim not found in token
alice → A, no reason 400 (stopped by the service before OpenBao)
no token 401 —
alice's token edited to carol / svc-b-readers, signature kept 403 error verifying token signature
audit ClickHouse stopped 503, no plaintext OpenBao received 0 decrypt calls for that request
alice straight to OpenBao (bypass) plaintext she holds the right; no service row

Things worth knowing

Mapping to Azure (documented, not run)

Here On Azure
OpenBao Transit key per service Azure Key Vault key per service, decrypt / unwrapKey operations
OpenBao audit file Key Vault diagnostic logs (AuditEvent) to Log Analytics or a storage account
Keycloak Microsoft Entra ID; groups claim or app roles
the user's JWT → OpenBao role the service calls Key Vault with the user's token (on-behalf-of), so the caller identity in Key Vault's log is the user
audit ClickHouse + reconciliation the same table; Key Vault's logs exported and joined by request id

Not production

Files

File What
docker-compose.yml OpenBao, Keycloak, audit ClickHouse, decrypt-service
openbao/audit.hcl declarative file audit device
keycloak/realm-corp.json realm, groups, decrypt-portal client (groups claim, openbao audience)
decrypt-service/service.py the decryption service (stdlib)
clickhouse/schema.sql audit.decrypt_events with TTL
04-audit-report.sql reviewer queries, incl. the reconciliation over file()
01–04, 99, lib.sh setup, checks, report, teardown

Related: field encryption in the Python SDK's export hook is langfuse-hols labs/v4/langfuse-ee step 14.


2026-11-02에 처음부터 끝까지 검증했습니다. Langfuse 4.56.0(OSS, 라이선스 키 없음, langfuse-hols v4 스택), ClickHouse 26.8.22.13, OpenBao 2.7.2, Keycloak 26.8.1 기준입니다. 새 볼륨으로 실행했고, 복호화 서비스는 python:3.12.15-slim에서 돌렸습니다. Docker 29.9.2, Compose v5.6.1입니다. 02는 확인 7개, 03은 28개를 통과했습니다. 일부러 넣은 결함(bob을 svc-a-readers에 추가)에서 03은 5개가 실패했고, 결함을 되돌리자 다시 통과했습니다.

규제가 있는 조직은 LLM trace에 세 가지를 요구합니다. 민감 필드를 암호화할 것, 권한이 있는 사람만 평문을 볼 것, 그리고 누가 언제 무엇을 왜 복호화했는지 기록할 것입니다. Langfuse는 받은 값을 그대로 저장할 뿐 복호화 기능도 조회 감사 기능도 없습니다. Enterprise 기능인 감사 로그도 생성·수정·삭제만 기록합니다. 그래서 기록은 복호화 경로에서 남겨야 합니다. 이 실습은 그 경로를 오픈소스로 만들고 시험합니다.

구조

  앱 ── 암호화 (OpenBao Transit, 암호화 전용 토큰) ──► Langfuse OSS  (enc:<키>:vault:v1:… 저장)
                                                           │ public API (서비스의 프로젝트 키)
  사용자 ── IdP 로그인 (Keycloak) ── POST /decrypt + 사유 ──► decrypt-service ──► 감사 ClickHouse
                                                           │  1. attempt 행        (audit.decrypt_events,
                                                           │  2. 사용자 JWT로        쓰기 전용 writer,
                                                           │     OpenBao 로그인       읽기 전용 auditor)
                                                           │  3. transit/decrypt + X-Request-Id
                                                           ▼  4. 결과 행
                                                        OpenBao ── 감사 파일 ──► ClickHouse file()로 그 자리에서 읽음

사전 준비

실행

cd usecase/langfuse-decryption-audit
./01-up.sh               # 생성한 비밀번호로 .env, 컨테이너 4개, OpenBao·ClickHouse·Keycloak 설정
./02-encrypt-and-send.sh # "앱" 역할: OpenBao로 암호화, Langfuse에 암호화 trace 2개와 평문 대조 1개 전송
./03-decrypt-checks.sh   # 요청 시나리오 9개, 우회, 이력, 대조, 수정 불가 확인
./04-audit-report.sh     # 감사 담당 쿼리(사용자별, 거부, 대조)
./99-down.sh [--purge]   # --purge는 감사 테이블, OpenBao 감사 파일, .env, .state까지 삭제

OpenBao는 dev 모드(메모리)라 01-up.sh가 실행할 때마다 설정을 다시 넣습니다. 99-down.sh는 Langfuse를 건드리지 않습니다.

확인한 것 (2026-11-02)

02-encrypt-and-send.sh: 7개 PASS - 앱 토큰은 두 키로 암호화할 수 있고, 복호화를 시도하면 HTTP 403입니다. - Langfuse API는 암호화한 trace에 enc:svc-a:vault:v1:…를 돌려주고, Langfuse의 ClickHouse에서 그 평문을 가진 행은 0개입니다. 같은 쿼리가 평문 대조는 찾습니다.

03-decrypt-checks.sh: 28개 PASS

요청 결과 OpenBao의 거부 사유(서비스 행에 기록)
alice(svc-a-readers) → A, 사유 있음 200, 평문 —
carol(svc-b-readers) → B, 사유 있음 200, 평문 —
alice → B 403 claim "groups" does not match any associated bound claim values
bob(그룹 없음) → A 403 "groups" claim not found in token
alice → A, 사유 없음 400 (OpenBao 전에 서비스가 막음)
토큰 없음 401 —
alice 토큰을 carol / svc-b-readers로 고치고 서명은 그대로 403 error verifying token signature
감사 ClickHouse 중지 503, 평문 없음 그 요청으로 OpenBao 복호화 호출 0회
alice가 OpenBao로 직접(우회) 평문 권한은 있음, 서비스 행은 없음

알아 둘 것

Azure에 대응하면 (문서 기준, 실행하지 않음)

여기 Azure
서비스별 OpenBao Transit 키 서비스별 Azure Key Vault 키, decrypt / unwrapKey 연산
OpenBao 감사 파일 Key Vault 진단 로그(AuditEvent)를 Log Analytics나 스토리지로
Keycloak Microsoft Entra ID, groups claim 또는 앱 역할
사용자 JWT → OpenBao role 서비스가 사용자 토큰으로 Key Vault 호출(on-behalf-of), Key Vault 로그의 호출자가 사용자
감사 ClickHouse + 대조 같은 테이블, Key Vault 로그를 내보내 request id로 대조

운영용이 아닌 부분

파일

파일 내용
docker-compose.yml OpenBao, Keycloak, 감사 ClickHouse, decrypt-service
openbao/audit.hcl 선언형 파일 감사 장치
keycloak/realm-corp.json realm, 그룹, decrypt-portal client(groups claim, openbao audience)
decrypt-service/service.py 복호화 서비스(stdlib)
clickhouse/schema.sql TTL이 있는 audit.decrypt_events
04-audit-report.sql 감사 담당 쿼리, file() 위의 대조 포함
01–04, 99, lib.sh 설정, 확인, 보고서, 정리

관련: Python SDK의 export hook에서 하는 필드 암호화는 langfuse-hols labs/v4/langfuse-ee 14단계입니다.

Open this lab on GitHub →GitHub에서 이 실습 열기 →