PII-Shield 🛡️

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

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

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

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

두 가지 배포 모델

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

1. Kubernetes Operator (제로코드): 주력 배포 모델입니다. 파드에 고도로 안전한 Distroless 사이드카를 자동으로 주입하여 로그를 실시간으로 가로채고 정화하는 완전 자동화된 K8s Operator입니다.
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가 원본 데이터를 보지 않고도 오류를 상호 연관시킬 수 있게 합니다.
• 드롭인 방식: 코드 변경이 필요 없습니다. 모든 언어(Node, Python, Java, Go)와 호환됩니다.
• 화이트리스트 지원: PII_SAFE_REGEX_LIST를 사용하여 안전한 패턴(예: git 해시, 시스템 ID)을 명시적으로 허용하여 오탐(false positive)을 방지합니다.

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

중앙 집중식 규칙 관리, Slack 알림 및 삭제 분석 기능을 갖춘 호스팅 컨트롤 플레인을 구축 중입니다.

통합

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

성능 고려 사항

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

• 텍스트 로그: 매우 빠름(초당 10만 줄 이상).
• 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.3
# 또는 GitHub Container Registry(엔터프라이즈)에서:
docker pull ghcr.io/pii-shield/pii-shield:2.2.3

소스에서 빌드

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

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에 파이프하여 즉시 동작을 확인할 수 있습니다:

# 민감한 비밀번호가 포함된 로그 시뮬레이션
echo "Error: User password=MySecretPass123! failed login" | docker run -i --rm ghcr.io/pii-shield/pii-shield:2.2.3

# 출력: 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는 네이티브 사이드카 패턴(K8s 1.28+)을 사용하여 pii-shield-agent를 자동으로 주입하고 모든 로그를 안전하게 마스킹합니다!

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

📦 GDPR 컴플라이언스 팩 — 지금 이용 가능(얼리 액세스): 40개 이상의 테스트된 삭제 규칙, DPO용 문서, 감사 추적 템플릿. $149 → · HIPAA/PCI 대기자 명단 →

💬 PII-Shield를 사용 중이신가요? 배포 환경에 대해 알려주세요 → — 2분이면 충분하며, 향후 개발 방향을 결정하는 데 도움이 됩니다.

검증

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

1. 단위 테스트: 엣지 케이스, 다국어 지원 및 JSON 무결성을 85% 이상의 커버리지로 다룹니다.
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를 참조하세요.