Show HN: PII-Shield – JSON 무결성을 갖춘 로그 정제 사이드카 (Go, Entropy)

Kubernetes용 제로 코드 로그 정제 사이드카.
파드가 떠나기 전에 로그에서 개인 식별 정보(PII)를 마스킹하여 데이터 유출을 방지합니다 (GDPR/SOC2).

PII-Shield는 인프로세스로 실행됩니다 — CLI, 사이드카 또는 WASM. 호스팅되는 API도 없고 데이터를 전송하는 서버도 없습니다.

같은 이름이지만 다른 프로젝트입니다. 이 제품은 Microsoft 개발자 커뮤니티 블로그의 PII Shield 프라이버시 프록시(2026년 5월, vikasgautam18/pii-shield)가 아니며, piishield.ai나 piishield.com의 프롬프트 마스킹 제품도 아니고, pii-shield 패키지도 아닙니다.

Intellirim이 PyPI에 올린 패키지입니다. 저희 패키지는 PyPI에서 pii-shield-wasi이고 npm에서는 @aragossa/pii-shield-wasi입니다. 본문에서는 이 프로젝트를 PII-Shield 사이드카라고 부릅니다.

"개인 식별 정보(PII)가 AI 모델을 오염시키도록 두지 마세요." PII-Shield는 민감한 데이터가 학습 데이터셋에 도달하는 것을 막아, GDPR로 인한 모델 재학습의 위험으로부터 보호합니다.

경고

v2.0.0으로 업그레이드하시나요?
저희는 최종 사용자 배포를 Helm 기반 설치 및 Distroless Native Sidecar로 옮겼습니다. Kustomize는 더 이상 프로덕션 사용자를 위한 지원되는 릴리스 설치 경로가 아니지만, 오퍼레이터 저장소에는 로컬 개발 및 매니페스트 생성을 위해 여전히 Kustomize 스캐폴딩이 남아 있습니다. /bin/sh

PII-Shield 사이드카 내부에서의 접근은 더 이상 지원되지 않습니다. 마이그레이션 가이드를 읽어보세요.

PII-Shield는 사용자의 스택에 통합할 수 있는 두 가지 뚜렷한 방법을 제공합니다:

Kubernetes Operator (제로 코드): 저희의 주력 배포 모델입니다. 파드에 고도로 안전한 Distroless 사이드카를 주입하여 로그를 실시간으로 가로채고 정제하는 완전히 자동화된 K8s Operator입니다.
In-Process WASM (핵심 통합용): 극한의 성능을 위해 핵심 엔진은 WASM을 통해 직접 임베딩될 수 있으며, 네트워크 허브 없이 <1ms 지연 시간을 제공합니다.

PII-Shield는 프로덕션 강화 단계에 있는 활발하게 개발되는 오픈소스 보안 도구입니다. v2.x 릴리스 라인은 사용 가능한 CLI, 컨테이너, Helm/operator, WASM SDK 아티팩트를 제공합니다. 핵심 마스킹(redaction) 경로는 통제된 배포를 위해 준비되었으며, 일부 Kubernetes 배포 모드와 공급망 보장 기능은 여전히 안정화되고 있습니다.

개발자들은 민감한 데이터를 마스킹하는 것을 종종 잊습니다. Fluentd/Logstash의 전통적인 정규 표현식 필터는 느리고, 유지 관리가 어려우며, 로그 집계기(log aggregators)에서 값비싼 CPU를 소모합니다.

PII-Shield는 앱 컨테이너 바로 옆에 위치합니다:

프로덕션 강화 핵심 엔진 (Production-hardening Core Engine): 핫 패스(hot paths)에서 낮은 메모리 할당과 결정론적 정규 표현식 매칭을 위해 최적화된 Kubernetes 사이드카(sidecars)용 엔진입니다. 문맥 인식 엔트로피 분석 (Context-Aware Entropy Analysis): 키가 없더라도 높은 엔트로피의 비밀 정보(예: Error: ... 44saCk9...)를 문맥 키워드를 분석하여 감지합니다. 사용자 정의 정규 표현식 규칙 (Custom Regex Rules): 구조화된 데이터(UUID, ID)에 대한 결정론적 마스킹을 제공하며, 알려진 패턴에 대해 엔트로피 검사를 무시합니다. 내장 비밀 서명 (Built-in Secret Signatures): 발급자 접두사(Issuer-prefixed)가 붙은 자격 증명 — AWS 및 Google API 키, GitHub, Slack 및 Stripe 토큰, JWT, Bearer 자격 증명, PEM 개인 키 블록 — 은 형식에 따라 마스킹됩니다. 따라서 유효한 키는 본문이 낮은 엔트로피이거나 임계값이 높아진 경우에도 포착됩니다. 모양 기반 전화번호 (Telephone Numbers by Shape): 국제 번호의 + 기호나 북미 형태인 (555) 234-5678과 같은 형식, 그리고 전화 관련 키(phone, mobile, wa_id, ...) 아래의 숫자는 오직 숫자만으로는 비밀 정보로 점수화되지 않더라도 숨겨집니다. 키 기반 신원 번호 (Identity Numbers by Key): 신분증을 명시하는 키(idNumber, national_id, ssn, passport_number, tax_id, ...) 아래의 숫자는 숨겨지며, user_id나 order_id와 같은 레코드 ID도 마찬가지입니다.

회귀 및 퍼즈 커버리지: 바이너리 쓰레기, JSON 중첩 구조, 다국어 로그를 포함한 스트레스 케이스에 대해 테스트되었습니다.결정론적 해싱 (Deterministic Hashing): 비밀 정보를 고유한 해시(예: [HIDDEN:a1b2c])로 대체하여 QA가 원본 데이터 없이도 오류 간의 상관관계를 파악할 수 있게 합니다.드롭인 방식 (Drop-in): 코드 변경이 필요 없습니다. 모든 언어(Node, Python, Java, Go)에서 작동합니다.화이트리스트 지원 (Whitelist Support): PII_SAFE_REGEX_LIST를 사용하여 안전한 패턴(예: git 해시, 시스템 ID)을 명시적으로 허용함으로써 오탐지(false positives)를 방지합니다.

우리는 중앙 집중식 규칙 관리, Slack 알림 및 마스킹 분석 기능을 갖춘 호스팅형 Control Plane을 구축하고 있습니다.

PII-Shield의 인프로세스 WASM 빌드는 오픈 소스 AI 코드 거버넌스 GitHub Action인 GuardSpine Code 내에 포함되어 바이너리를 배포하고 NOTICE 파일에서 크레딧을 제공합니다.

PII-Shield는 고도로 최적화되었지만, 복잡한 로그의 깊은 검사는 설정에 대한 세심한 주의를 필요로 합니다.

텍스트 로그: 매우 빠릅니다 (>100k lines/s). JSON 로그: 할당(allocation)이 없는 파싱 (encoding/json 오버헤드 없음). 스캐너는 높은 처리량(~7MB/s)을 유지하면서 메모리 급증 없이 JSON 구조를 수동으로 파싱합니다. 권장 사항: 고처리량 사용에 안전합니다. 깊게 중첩된 JSON에서 스택 오버플로우를 방지하기 위해 재귀 보호 장치(recursion safeguards)를 사용합니다.

Kubernetes에서 PII-Shield를 배포하는 공식적이고 권장되는 방법은 완전히 자동화된 Operator를 이용하는 것입니다:

helm repo add pii-shield https://pii-shield.github.io/pii-shield/
helm repo update
helm install pii-shield-operator pii-shield/pii-shield-operator -n operator-system --create-namespace

이 명령어는 PII-Shield Operator를 배포하며, 코드나 Dockerfile 변경 없이 Pod에 고도로 안전한 distroless 사이드카를 자동으로 주입합니다.

Docker Hub 또는 GHCR에서 최신 경량 이미지를 가져오세요:

docker pull thelisdeep/pii-shield:2.2.7
# OR from GitHub Container Registry (Enterprise):
docker pull ghcr.io/pii-shield/pii-shield:2.2.7

소스 코드에서 바이너리를 직접 빌드할 수도 있습니다:

go build -o pii-shield ./cmd/cleaner

스캐너는 Go 프로그램 내부에서 실행될 수 있으며, 예를 들어 slog.Handler 내에서 각 레코드를 기록되기 전에 마스킹(redacts)할 수 있습니다. 표준 라이브러리만 필요합니다:

go get github.com/pii-shield/pii-shield/v2/pkg/scanner

import "github.com/pii-shield/pii-shield/v2/pkg/scanner"
clean := scanner.ScanAndRedact(line) // 한 줄 처리
cleanText := scanner.ScanAndRedactText(text) // 여러 줄 처리, 줄 바꿈 문자 유지

이 패키지는 CLI가 로드할 때와 동일한 PII_* 환경 변수를 읽습니다. v2.2.8 이전 릴리스는 모듈 경로에 /v2를 선언하지 않았기 때문에 go get 명령어가 이를 거부합니다.

전체 환경 변수 목록은 CONFIGURATION.md를 참조하십시오. 여기에는 다음이 포함됩니다:

PII_SALT
: 사용자 지정 HMAC salt (운영 환경에서 필수).
PII_ADAPTIVE_THRESHOLD
: 동적 엔트로피 기준선 활성화.
PII_DISABLE_BIGRAM_CHECK
: 비영어권 로그 최적화.
PII_CUSTOM_REGEX_LIST
: 결정론적 마스킹을 위한 사용자 지정 정규식(regex) 규칙.
PII_SAFE_REGEX_LIST
: 무시할 화이트리스트 정규식 규칙 (일치하는 내용은 원본 그대로 반환됨).

• 로컬 테스트 (CLI): PII-Shield를 통해 모든 로그 출력을 파이프하여 즉시 작동하는 것을 확인할 수 있습니다:

# 민감한 비밀번호가 포함된 로그 에뮬레이션
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.7
# 출력: Error: User password=[HIDDEN:8f3a11] failed login

• Kubernetes (자동 사이드카 주입): PII-Shield Operator가 설치되어 있으면, PiiPolicy를 생성하고 Pod에 레이블을 지정하는 것만으로 애플리케이션 보호가 가능합니다.

정책 생성:

apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
...

Deployment 레이블 지정:

apiVersion: apps/v1
kind: Deployment
metadata:
...

Operator는 네이티브 사이드카 패턴(K8s 1.28+)을 사용하여 pii-shield-agent를 자동으로 주입하고 모든 로그를 안전하게 마스킹합니다!

📋 무료: 25개 항목 Kubernetes 로그 PII 감사 체크리스트 — 파드에서 PII가 유출되는 경로, 필터링을 우회하는 로그 경로, 그리고 마스킹이 실제로 작동하는지 확인하는 방법 등을 다룹니다. 체크리스트 받기 →

📦 GDPR 준수 팩 — 지금 이용 가능 (얼리 액세스): 테스트된 40개 이상의 마스킹 규칙, DPO(Data Protection Officer) 준비 문서, 감사 추적 템플릿 등이 포함되어 있습니다. $149 → · HIPAA/PCI는 대기 목록에 등록하세요 →

💬 PII-Shield를 사용하고 계신가요? 배포 현황을 알려주세요 → — 2분이면 다음 개발 방향을 결정하는 데 도움이 됩니다.

이 프로젝트는 프로덕션 강화 전에 신뢰도를 높이기 위한 성장하는 테스트 스위트로 검증되었습니다:

단위 테스트 (Unit Tests): 엣지 케이스, 다국어 지원, JSON 무결성을 포함하여 85% 이상의 커버리지를 제공합니다.퍼징 (Fuzzing): 네이티브 Go 퍼징은 유효하지 않거나 임의의 바이너리 입력에 대한 충돌 안전성을 보장합니다.스모크 테스트 (Smoke Testing):./scripts/test-smoke.sh
컨테이너를 통해 1000줄 분량의 혼합 워크로드 코퍼스를 엔드투엔드로 실행하고 탐지 정확도를 보고합니다. 비밀 정보는 그 값이 출력에서 누락되고 마스킹 표시가 대신 자리했을 때만 포착된 것으로 간주되며, 안전한 라인은 변경되지 않고 돌아와야 합니다. 이 테스트는 오탐(false positive)이나 미탐(false negative)이 발생하거나 컨테이너가 0이 아닌 값으로 종료되거나 주어진 줄 수와 다른 줄 수를 반환할 경우 실패합니다. 산문 형태의 키 없는 비밀 정보는 알려진 격차로 별도 추적됩니다. 이는 엔트로피에 의존하기 때문입니다: 고정된 코퍼스는 이를 허용하지 않지만, 새로운 임의 코퍼스(--fuzz)는 두 개를 허용합니다.엔드투엔드 (E2E) 테스트: operator/tests/run_e2e.sh
스위트는 Minikube와 Helm을 사용하여 전체 스택 검증을 수행합니다. 로컬 이미지를 빌드하고 cert-manager 없이 Operator를 프로비저닝하며, 대상 Job을 배포하고 사이드카 출력을 가로채어 실제 로그 마스킹을 검증합니다.

위의 스위트(suite)는 스캐너를 증명할 뿐, 사용자의 설치 환경을 증명하지는 않습니다. 마스킹된 스트림을 신뢰하기 전에, 사용자가 제어하는 값을 심고 수집기(collector) 측에서 해당 값이 나타나는지 확인하십시오:

• 합성 카드 번호, 가짜 이메일 주소, 그리고 사용자가 제어하는 파드(pod)의 테스트 계정 번호를 포함한 로그 라인을 기록하고,
  grep -c를 사용하여 각 값에 대해 로그가 도달하는 횟수를 확인합니다. 그 개수는 0이어야 합니다. - 고정된 PII_SALT와 함께 수천 개의 프로덕션 형태의 라인을 CLI로 실행하고, diff를 읽어 살아남은 값과 그대로 두었어야 할 값을 찾습니다. - PII_ENTITY_TYPE_LABELS=true로 반복하여 어떤 감지기(detector)가 작동했는지 확인합니다: entropy로 보고된 카드가 아닌 card로 보고된 것은 여전히 숨겨져 있지만, Luhn 알고리즘 경로는 이를 감지하지 못했습니다. - PII_METRICS_ENABLED=true를 사용하면 piishield_redaction_events_total을 type별로 관찰합니다. 배포 후 감소했다는 것은 상위 스트림(upstream) 어딘가에서 형식이 변경되었다는 의미입니다. - 값을 마스킹으로부터 보호하는 모든 규칙 다음에, 심었던 값 검사를 다시 실행하십시오.

스캐너가 설계상 포착할 수 없는 것들, 예를 들어 자유 텍스트에 있는 이름 등은 KNOWN_LIMITATIONS.md에 나열되어 있습니다. 결제 로그의 전후 비교를 포함한 전체 워크스루는 은행 로그 가이드(banking logs guide)에 있습니다.

현재 브랜치와 기준 레퍼런스 간의 종단 간(end-to-end) CLI 처리량 비교를 하려면:

./benchmark/run_benchmarks.sh

기본적으로, 벤치마크는 HEAD를 origin/main과 비교하고, origin/main을 새로 고치며, 혼합된 로그 코퍼스(log corpus)를 생성하고, 오래된/새로운 실행 순서를 번갈아 가며, 중앙값(median), p95, 최소/최대, 그리고 MiB/s를 보고합니다:

BASE_REF=origin/main RUNS=9 LINES=500000 ./benchmark/run_benchmarks.sh

이것은 전체 stdin-to-stdout CLI 경로를 측정합니다. 스캐너 전용 마이크로 벤치마크의 경우, 다음을 실행하십시오:

go test -bench=. -benchmem ./pkg/scanner

오퍼레이터는 빠른 단위 테스트(unit tests)와 Kubernetes API 통합 테스트를 분리하여 유지합니다. 일반적인 오퍼레이터 테스트는 로컬 API 서버를 시작하지 않습니다:

cd operator
go test ./...

envtest 기반 컨트롤러 통합 스위트를 실행하려면:

./scripts/test-operator-integration.sh

스크립트는 make -C operator test-integration을 호출합니다.

이 명령어는 첫 사용 시 operator/go.mod에 명시된 Kubernetes 버전에 대한 envtest 바이너리를 다운로드합니다. CI 환경에서는 푸시할 때마다 동일한 타겟을 실행합니다. 이 테스트들은 envtest를 통해 로컬 Kubernetes API 서버와 etcd를 시작하므로, 127.0.0.1에 바인딩할 권한이 필요합니다. 제한된 샌드박스 환경에서는 로컬 셸(shell), Docker 환경 또는 localhost 바인딩을 허용하는 CI 러너에서 실행하십시오.

PII-Shield는 개인정보 보호가 적용된 로그를 위한 오픈 소스 인프라입니다. 이 프로젝트가 귀하 또는 귀하의 조직에 유용하다면, GitHub Sponsors를 통해 개발 지원을 할 수 있습니다.

릴리스 체크섬 및 이미지 다이제스트(image-digest) 검증 지침은 docs/release-verification.md에 문서화되어 있습니다. 서명 및 출처(provenance)-백업 릴리스는 공급망 강화 로드맵의 일부로 추적됩니다.

Apache 2.0 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE를 참조하십시오.