PII-Shield 🛡️

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

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

같은 이름, 다른 프로젝트. 이것은 Microsoft 개발자 커뮤니티 블로그(2026년 5월, vikasgautam18/pii-shield)의 PII Shield 프라이버시 프록시가 아니며, piishield.ai 또는 piishield.com의 프롬프트 삭제 제품도 아니고, Intellirim의 PyPI pii-shield 패키지도 아닙니다. 저희 패키지는 PyPI의 pii-shield-wasi와 npm의 @aragossa/pii-shield-wasi이며, 문서에서는 이 프로젝트를 PII-Shield 사이드카라고 부릅니다.

"PII가 AI 모델을 오염시키도록 두지 마세요." PII-Shield는 민감한 데이터가 학습 데이터셋에 도달하지 않도록 보장하여 GDPR로 인한 모델 재학습을 피할 수 있게 해줍니다.

[!WARNING] v2.0.0으로 업그레이드하시나요? 최종 사용자 배포를 Helm 기반 설치와 Distroless 네이티브 사이드카로 이전했습니다. Kustomize는 더 이상 프로덕션 사용자를 위한 지원되는 릴리스 설치 경로가 아니지만, 운영자(operator) 저장소는 로컬 개발 및 매니페스트 생성을 위한 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 배포 모드와 공급망 보장은 아직 안정화 중입니다.

구성 요소	상태
핵심 스캐너	릴리스됨 / 통제된 배포
CLI 사이드카	릴리스됨 / 통제된 배포
Kubernetes operator	안정화 단계
WASM SDK	릴리스된 베타
Proxy-Wasm 게이트웨이 통합	계획된 R&D
Control Plane UI	계획된 R&D
eBPF 가로채기	실험적 R&D

현재 프로덕션 강화 경계에 대해서는 KNOWN_LIMITATIONS.md를 참조하세요.

PII-Shield를 사용하는 이유

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

PII-Shield는 애플리케이션 컨테이너 바로 옆에 위치합니다:

• 프로덕션 강화 핵심 엔진: 핫 패스에서 낮은 메모리 할당과 결정론적 정규식 매칭으로 Kubernetes 사이드카에 최적화되어 있습니다.
• 컨텍스트 인식 엔트로피 분석: 컨텍스트 키워드를 분석하여 키 없이도 고엔트로피 시크릿(예: Error: ... 44saCk9...)을 탐지합니다.
• 사용자 정의 정규식 규칙: 알려진 패턴에 대해 엔트로피 검사를 재정의하는 구조화된 데이터(UUID, ID)에 대한 결정론적 삭제를 제공합니다.
• 내장 시크릿 서명: 발급자 접두사가 붙은 자격 증명 — AWS 및 Google API 키, GitHub, Slack 및 Stripe 토큰, JWT, Bearer 자격 증명 및 PEM 개인 키 블록 — 은 형식에 따라 삭제되므로, 본문이 저엔트로피이거나 임계값이 높아진 경우에도 유효한 키가 잡힙니다.
• 형태 기반 전화번호: +가 있는 국제 번호, 북미 (555) 234-5678 형식, 그리고 전화 관련 키(phone, mobile, wa_id, ...) 아래의 숫자는 숫자만으로는 시크릿으로 점수화되지 않음에도 숨겨집니다.
• 키 기반 신원 번호: 신원 문서를 명명하는 키(idNumber, national_id, ssn, passport_number, tax_id, ...) 아래의 숫자는 숨겨지며, user_id 또는 order_id와 같은 레코드 ID는 숨겨지지 않습니다.
• 회귀 및 퍼즈 커버리지: 바이너리 가비지, JSON 중첩, 다국어 로그를 포함한 스트레스 케이스에 대해 테스트되었습니다.
• 결정론적 해싱: 시크릿을 고유한 해시(예: [HIDDEN:a1b2c])로 대체하여 QA가 원시 데이터를 보지 않고도 오류를 상관시킬 수 있습니다.
• 드롭인: 코드 변경이 필요하지 않습니다. 모든 언어(Node, Python, Java, Go)와 함께 작동합니다.
• 화이트리스트 지원: PII_SAFE_REGEX_LIST를 사용하여 안전한 패턴(예: git 해시, 시스템 ID)을 명시적으로 허용하여 오탐을 방지합니다.

수십 개의 클러스터에서 PII-Shield를 관리하시나요?

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

통합

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

성능 고려 사항

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

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

설치

Helm Chart (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

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

Docker

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 라이브러리

스캐너는 Go 프로그램 내부에서 실행될 수 있습니다. 예를 들어 각 레코드가 작성되기 전에 삭제하는 slog.Handler에서 사용할 수 있습니다. 표준 라이브러리만 필요합니다:

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)         // one line
cleanText := scanner.ScanAndRedactText(text) // several lines, line endings kept

이 패키지는 로드될 때 CLI와 동일한 PII_* 환경 변수를 읽습니다. v2.2.8 이전 릴리스는 모듈 경로를 /v2 없이 선언하므로 go get이 이를 거부합니다.

구성

환경 변수의 전체 목록은 CONFIGURATION.md를 참조하세요:

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

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

엔트로피	데이터 유형	예시
0.0 - 3.0	일반 단어, 반복	password, admin, 111111
3.0 - 3.6	CamelCase, 부분 해시	ProgramCampaignInstanceJob, 8f3a11b2c
3.6 - 4.5	경로, UUID, 약한 비밀번호	/opt/application/runtime, P@ssw0rd2026!
4.5 - 5.0	중간 토큰	E8s9d_2kL1
5.0+	고엔트로피 키	(SHA-256, API Keys)

빠른 시작

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.7

# 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를 자동으로 주입하고 모든 로그를 안전하게 마스킹합니다!

---

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