PII-Shield 🛡️

Сателлит (sidecar) для очистки логов в Kubernetes без единой строчки кода. Предотвращает утечки данных (GDPR/SOC2), редактируя PII из логов до того, как они покинут под.

PII-Shield работает внутри процесса — CLI, sidecar или WASM. Никакого размещённого API или сервера, на который отправляются ваши данные, не существует.

«Не позволяйте PII отравить ваши ИИ-модели». PII-Shield гарантирует, что конфиденциальные данные никогда не попадут в ваш обучающий набор данных, избавляя вас от принудительного переобучения модели из-за требований GDPR.

[!WARNING] Обновляетесь до v2.0.0? Мы перевели распространение для конечных пользователей на установку через Helm и Distroless Native Sidecar. Kustomize больше не поддерживается как путь установки релизов для продакшн-пользователей, хотя в репозитории оператора по-прежнему сохраняется каркас Kustomize для локальной разработки и генерации манифестов. Доступ к /bin/sh внутри sidecar PII-Shield больше не поддерживается. Прочитайте руководство по миграции.

Две модели развёртывания

PII-Shield предлагает два различных способа интеграции в ваш стек:

1. Оператор Kubernetes (без кода): Наша флагманская модель развёртывания. Полностью автоматизированный оператор K8s, который внедряет высокозащищённый Distroless Sidecar в ваши поды для перехвата и очистки логов на лету.
2. Встроенный WASM (для ключевых интеграций): Для экстремальной производительности основной движок может быть встроен напрямую через WASM, обеспечивая задержку <1ms без сетевых переходов.

Статус проекта и дорожная карта

PII-Shield — это активно разрабатываемый инструмент безопасности с открытым исходным кодом, находящийся в фазе производственного упрочнения. Линейка релизов v2.x поставляет рабочие артефакты CLI, контейнера, Helm/оператора и WASM SDK. Основные пути редактирования готовы к контролируемым развёртываниям, в то время как некоторые режимы развёртывания Kubernetes и гарантии цепочки поставок всё ещё стабилизируются.

См. KNOWN_LIMITATIONS.md для текущих границ производственного упрочнения.

Почему PII-Shield?

Разработчики часто забывают маскировать конфиденциальные данные. Традиционные regex-фильтры в Fluentd/Logstash медленны, сложны в поддержке и потребляют дорогой CPU на агрегаторах логов.

PII-Shield находится прямо рядом с контейнером вашего приложения:

• Основной движок производственного уровня: Оптимизирован для sidecar Kubernetes с низким выделением памяти на горячих путях и детерминированным сопоставлением regex.
• Контекстно-зависимый анализ энтропии: Обнаруживает секреты с высокой энтропией даже без ключей (например, Error: ... 44saCk9...) путём анализа контекстных ключевых слов.
• Пользовательские regex-правила: Детерминированное редактирование структурированных данных (UUID, ID), которое переопределяет проверки энтропии для известных шаблонов.
• Регрессионное и fuzz-покрытие: Протестировано на стрессовых случаях, включая бинарный мусор, вложенность JSON и многоязычные логи.
• Детерминированное хеширование: Заменяет секреты уникальными хешами (например, [HIDDEN:a1b2c]), позволяя QA соотносить ошибки без просмотра исходных данных.
• Бесшовная интеграция: Не требует изменений в коде. Работает с любым языком (Node, Python, Java, Go).
• Поддержка белых списков: Явное разрешение безопасных шаблонов (например, git-хеши, системные ID) с помощью PII_SAFE_REGEX_LIST для предотвращения ложных срабатываний.

Управляете PII-Shield в десятках кластеров?

Мы создаём размещённый Control Plane с централизованным управлением правилами, оповещениями Slack и аналитикой редактирования.

Интеграции

Внутрипроцессная WASM-сборка PII-Shield поставляется в составе GuardSpine Code, open-source GitHub Action для управления кодом ИИ, который включает бинарник и указывает его в своём NOTICE.

Рекомендации по производительности

Хотя PII-Shield высоко оптимизирован, глубокая проверка сложных логов требует внимательного подхода к конфигурации.

• Текстовые логи: Чрезвычайно быстро (>100 тыс. строк/с).
• JSON-логи: Разбор с нулевым выделением памяти (без накладных расходов encoding/json). Сканер вручную разбирает JSON-структуры для обеспечения высокой пропускной способности (~7MB/s) без скачков памяти.
• Рекомендация: Использование безопасно при высокой пропускной способности. Мы используем защитные механизмы рекурсии для предотвращения переполнения стека на глубоко вложенных JSON.

Установка

Helm-чарт (оператор Kubernetes)

Официальный и рекомендуемый способ развёртывания PII-Shield в Kubernetes — через наш полностью автоматизированный оператор:

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, который автоматически внедряет высокозащищённые distroless sidecar в ваши поды без необходимости изменений в коде или Dockerfile.

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: Пользовательские regex-правила для детерминированного редактирования.
• PII_SAFE_REGEX_LIST: Regex-правила белого списка для игнорирования (совпадения возвращаются как есть).

Таблица чувствительности энтропии (порог по умолчанию: 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 (автоматическое внедрение sidecar) С установленным оператором PII-Shield защита приложения сводится к созданию 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"
# ...

Оператор автоматически внедрит pii-shield-agent с использованием шаблона Native Sidecar (K8s 1.28+) и безопасно замаскирует все логи!

📋 Бесплатно: Контрольный список аудита PII в логах Kubernetes из 25 пунктов — откуда происходит утечка PII из подов, какие пути логов обходят ваши фильтры и как проверить, что редактирование действительно работает. Получить контрольный список →

📦 Пакеты соответствия (GDPR/HIPAA/PCI) скоро появятся — получить ранний доступ →

💬 Используете PII-Shield? Расскажите нам о вашем развёртывании → — 2 минуты, и это определяет, что будет создано дальше.

Верификация

Этот проект верифицируется растущим набором тестов, призванным повысить уверенность перед производственным упрочнением:

1. Модульные тесты: Покрывают граничные случаи, многоязычную поддержку и целостность JSON с покрытием >85%.
2. Фаззинг: Нативный Go-фаззинг обеспечивает безопасность от сбоев при невалидных и случайных бинарных входных данных.
3. Smoke-тестирование: ./scripts/test-smoke.sh проверяет смешанные рабочие нагрузки и сообщает точность обнаружения.
4. Сквозное (E2E) тестирование: Набор operator/tests/run_e2e.sh выполняет полную проверку стека с использованием Minikube и Helm. Он собирает локальные образы, разворачивает оператор без cert-manager, развёртывает целевые Jobs и проверяет фактическое редактирование логов путём перехвата вывода sidecar.

Бенчмарки производительности

Чтобы сравнить сквозную пропускную способность 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

Это измеряет полный путь CLI от stdin до stdout. Для микробенчмарков только сканера выполните:

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

Интеграционные тесты оператора

Оператор держит быстрые модульные тесты отдельно от интеграционных тестов Kubernetes API. Обычные тесты оператора не запускают локальный API-сервер:

cd operator
go test ./...

Для запуска набора интеграционных тестов контроллера на основе envtest:

./scripts/test-operator-integration.sh

Эти тесты запускают локальный API-сервер Kubernetes и etcd через envtest, поэтому им требуется разрешение на привязку к 127.0.0.1. В ограниченных песочницах запускайте их в локальной оболочке, среде Docker или CI-раннере, допускающем привязку к localhost.

Поддержка

PII-Shield — это инфраструктура с открытым исходным кодом для логов, сохраняющих конфиденциальность. Если этот проект полезен вам или вашей организации, вы можете поддержать его развитие через GitHub Sponsors.

Проверка релизов

Рекомендации по проверке контрольных сумм релизов и digest образов задокументированы в docs/release-verification.md. Релизы с подписями и проверкой происхождения отслеживаются в рамках дорожной карты упрочнения цепочки поставок.

Лицензия

Распространяется под лицензией Apache 2.0. См. LICENSE для получения дополнительной информации.