PII-Shield 🛡️

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

PII-Shield는 CLI, 사이드카 또는 WASM으로 프로세스 내(in-process)에서 실행됩니다. 호스팅 API가 없으며 데이터가 전송되는 서버도 없습니다.

"PII가 AI 모델을 오염시키지 마세요." PII-Shield는 민감한 데이터가 학습 데이터세트에 도달하지 않도록 보장하여 GDPR로 인한 모델 재학습 부담을 덜어줍니다.

[!WARNING] v2.0.0으로 업그레이드하시겠습니까? 최종 사용자 배포를 Helm 기반 설치 및 Distroless Native Sidecar로 전환했습니다. Kustomize는 더 이상 프로덕션 사용자를 위한 지원되는 릴리스 설치 경로가 아니지만, Operator 저장소는 로컬 개발 및 매니페스트 생성을 위해 Kustomize 스캐폴딩을 계속 유지합니다. PII-Shield 사이드카 내부의 /bin/sh 접근은 더 이상 지원되지 않습니다. 마이그레이션 가이드를 읽어보세요.

두 가지 배포 모델

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

1. Kubernetes Operator (제로코드): 당사의 대표 배포 모델입니다. 완전 자동화된 K8s Operator가 파드에 고도로 안전한 Distroless Sidecar를 주입하여 로그를 실시간으로 가로채고 정화합니다.
2. 프로세스 내 WASM (핵심 통합용): 극한의 성능을 위해 핵심 엔진을 WASM을 통해 직접 임베드할 수 있으며, 네트워크 홉 없이 <1ms 대기 시간을 제공합니다.

프로젝트 상태 및 로드맵

PII-Shield는 프로덕션 강화 단계에 있는 활발히 개발 중인 오픈소스 보안 도구입니다. v2.x 릴리스 라인은 사용 가능한 CLI, 컨테이너, Helm/Operator 및 WASM SDK 아티팩트를 제공합니다. 핵심 마스킹 경로는 통제된 배포에 대비되어 있으며, 일부 Kubernetes 배포 모드와 공급망 보증은 아직 안정화 중입니다.

현재 프로덕션 강화 범위는 KNOWN_LIMITATIONS.md를 참조하세요.

왜 PII-Shield인가?

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

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

• 프로덕션 강화 코어 엔진: 핫 경로에서 낮은 메모리 할당과 결정적 정규식 매칭을 갖춘 Kubernetes 사이드카에 최적화되어 있습니다.
• 컨텍스트 인지 엔트로피 분석: 컨텍스트 키워드를 분석하여 키 없이도 높은 엔트로피 비밀값(예: Error: ... 44saCk9...)을 탐지합니다.
• 사용자 정의 정규식 규칙: 알려진 패턴에 대한 엔트로피 검사를 대체하는 구조화된 데이터(UUID, ID)의 결정적 마스킹.
• 회귀 및 퍼즈 커버리지: 바이너리 쓰레기, JSON 중첩, 다국어 로그 등 스트레스 사례에 대해 테스트되었습니다.
• 결정적 해싱: 비밀값을 고유 해시(예: [HIDDEN:a1b2c])로 대체하여 QA가 원시 데이터를 보지 않고도 오류를 연관시킬 수 있게 합니다.
• 드롭인(Drop-in): 코드 변경이 필요 없습니다. 모든 언어(Node, Python, Java, Go)에서 작동합니다.
• 화이트리스트 지원: PII_SAFE_REGEX_LIST를 사용하여 안전한 패턴(예: git 해시, 시스템 ID)을 명시적으로 허용하여 오탐(false positive)을 방지합니다.

수십 개의 클러스터에서 PII-Shield를 관리하고 계신가요?

중앙 집중식 규칙 관리, Slack 알림, 마스킹 분석을 갖춘 호스팅 Control Plane을 구축 중입니다.

통합

PII-Shield의 프로세스 내 WASM 빌드는 오픈소스 AI 코드 거버넌스 GitHub Action인 GuardSpine Code 내부에 포함되어 있으며, 이 액션은 바이너리를 벤더링하고 NOTICE에 그 출처를 명시합니다.

성능 고려 사항

PII-Shield는 고도로 최적화되어 있지만, 복잡한 로그의 심층 검사에는 구성에 대한 세심한 주의가 필요합니다.

• 텍스트 로그: 매우 빠름(초당 100k줄 이상).
• JSON 로그: 제로 할당 파싱(encoding/json 오버헤드 없음). 스캐너는 메모리 급증 없이 높은 처리량(약 7MB/s)을 보장하기 위해 JSON 구조를 수동으로 파싱합니다.
• 권장 사항: 높은 처리량에서도 안전하게 사용할 수 있습니다. 깊게 중첩된 JSON에서 스택 오버플로를 방지하기 위해 재귀 안전장치를 사용합니다.

설치

Helm 차트 (Kubernetes Operator)

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

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

Docker

Docker Hub 또는 GHCR에서 최신 경량 이미지를 받으세요:

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

소스에서 빌드

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

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

구성

전체 환경 변수 목록은 CONFIGURATION.md를 참조하세요. 다음을 포함합니다:

• PII_SALT: 사용자 정의 HMAC 솔트(프로덕션에 필수).
• PII_ADAPTIVE_THRESHOLD: 동적 엔트로피 기준선 활성화.
• PII_DISABLE_BIGRAM_CHECK: 비영어 로그에 최적화.
• PII_CUSTOM_REGEX_LIST: 결정적 마스킹을 위한 사용자 정의 정규식 규칙.
• PII_SAFE_REGEX_LIST: 무시할 화이트리스트 정규식 규칙(일치 항목은 그대로 반환됨).

엔트로피 민감도 표 (기본 임계값: 3.6)

빠른 시작

1. 로컬 테스트 (CLI) 어떤 로그 출력이든 PII-Shield에 파이프하여 즉시 동작을 확인할 수 있습니다:

# Emulate a log with a sensitive password
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.0

# Output: Error: User password=[HIDDEN:8f3a11] failed login

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

정책 생성:

apiVersion: core.pii-shield.io/v1alpha1
kind: PiiPolicy
metadata:
  name: strict-policy
  namespace: default
spec:
  injectionMode: "file"

Deployment에 레이블 지정:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: secure-app
spec:
  template:
    metadata:
      labels:
        pii-shield.io/inject: "true"
      annotations:
        pii-shield.io/policy: "strict-policy"
# ...

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

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

📦 컴플라이언스 팩(GDPR/HIPAA/PCI) 출시 예정 — 조기 액세스 신청 →

💬 PII-Shield를 사용 중이신가요? 배포 사례를 알려주세요 → — 2분이면 되며, 다음에 구축될 기능을 결정하는 데 도움이 됩니다.

검증

이 프로젝트는 프로덕션 강화 전에 신뢰도를 높이기 위해 지속적으로 확장되는 테스트 스위트로 검증됩니다:

1. 단위 테스트: 85% 이상의 커버리지로 엣지 케이스, 다국어 지원, JSON 무결성을 다룹니다.
2. 퍼징: 네이티브 Go 퍼징을 통해 잘못된 입력과 무작위 바이너리 입력에 대한 크래시 안전성을 보장합니다.
3. 스모크 테스트: ./scripts/test-smoke.sh가 혼합 워크로드를 실행하고 탐지 정확도를 보고합니다.
4. 엔드투엔드(E2E) 테스트: operator/tests/run_e2e.sh 스위트는 Minikube와 Helm을 사용하여 전체 스택 검증을 수행합니다. 로컬 이미지를 빌드하고, cert-manager 없이 Operator를 프로비저닝하고, 대상 Job을 배포한 다음, 사이드카 출력을 가로채 실제 로그 마스킹을 검증합니다.

성능 벤치마크

현재 브랜치와 기준 ref 간의 엔드투엔드 CLI 처리량을 비교하려면:

./benchmark/run_benchmarks.sh

기본적으로 벤치마크는 HEAD를 origin/main과 비교하고, origin/main을 새로 고친 다음, 혼합 로그 코퍼스를 생성하고, 이전/신규 실행 순서를 번갈아 가며 중앙값, 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

Operator 통합 테스트

Operator는 빠른 단위 테스트를 Kubernetes API 통합 테스트와 분리하여 유지합니다. 일반 Operator 테스트는 로컬 API 서버를 시작하지 않습니다:

cd operator
go test ./...

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

./scripts/test-operator-integration.sh

이 테스트는 envtest를 통해 로컬 Kubernetes API 서버와 etcd를 시작하므로 127.0.0.1에 바인딩할 권한이 필요합니다. 제한된 샌드박스에서는 localhost 바인딩을 허용하는 로컬 셸, Docker 환경 또는 CI 러너에서 실행하세요.

지원

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

릴리스 검증

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

라이선스

Apache 2.0 라이선스로 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.