Cover

Не допускайте попадания чувствительных значений в запросы к LLM, не нарушая диалог.

Установка · Быстрый старт · Политики · Мониторинг · Pi / OMP · Безопасность

Cover — это локальный прокси конфиденциальности для Codex, Claude Code, Cursor, SDK и других HTTP-клиентов на базе ИИ. Он сканирует исходящий JSON, заменяет совпавшие значения локально и восстанавливает обратимые замены в JSON- и потоковых ответах. LLM получает защищённые значения, а агент может продолжать использовать исходные.

Cover работает как прозрачный обратный прокси с заменой на основе политик, детерминированными псевдонимами, эксплуатационными проверками, поддержкой Codex и строгой обработкой сбоев. Он создан, чтобы оставаться локальным, наблюдаемым и явно указывать на то, что не может проверить.

flowchart LR
    A["Agent"] -->|"JSON request"| C["Cover<br/>detect · transform · enforce"]
    C -->|"protected request"| L["LLM or router"]
    L -->|"JSON or SSE response"| C
    C -->|"restored response"| A

Возможности

Установка

Установщик клонирует Cover, собирает его с помощью Go, устанавливает в ~/.local/bin/cover, настраивает выбранные клиенты и запускает прокси.

curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

Требования: git и версия Go, указанная в go.mod.

Готовые архивы для Linux, macOS и Windows и их контрольные суммы доступны на GitHub Releases.

Для неинтерактивной установки:

COVER_AGENTS=openai,claude \
  curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

git clone https://github.com/DavidCarliez/cover.git
cd cover
go build -o cover ./cmd/cover
install -m 0755 cover ~/.local/bin/cover

GOOS=linux GOARCH=arm64 go build -o cover-linux-arm64 ./cmd/cover
GOOS=windows GOARCH=amd64 go build -o cover.exe ./cmd/cover

Быстрый старт

cover init             # write ~/.config/cover/config.yaml
cover start --detach   # run in the background
cover doctor           # verify the local setup
cover test             # local redaction round trip, no network call
cover monitor          # watch privacy-safe request metadata

cover init запрашивает OpenAI, Anthropic или пользовательский upstream. Полная конфигурация описана в configs/config.example.yaml.

Справочник команд

Остановка Cover не меняет конфигурацию клиентов. Клиент, всё ещё указывающий на Cover, не сможет подключиться, пока Cover не будет перезапущен или клиент не будет направлен обратно на своего прямого провайдера или роутер.

Политики конфиденциальности

Встроенное обнаружение на основе регулярных выражений охватывает ключи AWS и GCP, токены GitHub, GitLab, Slack, Stripe и Anthropic, блоки приватных ключей, JWT, явные присваивания секретов общего вида, email-адреса, SSN, кредитные карты, номера телефонов и IBAN. Голое значение sk-... от OpenAI намеренно не является отдельной встроенной категорией. Определите явное правило, если вашему окружению оно нужно.

Правила находятся в разделе rules файла ~/.config/cover/config.yaml. Селектором может быть регулярное выражение, детектор builtin_* или список ключей JSON-объекта.

rules:
  password_fields:
    keys: [password, passwd, pwd, passphrase, user_password, database_password]
    category: password
    action: pseudonymize
    generator: password
    priority: 220

  ipv4_addresses:
    detector: builtin_ipv4
    category: ip_address
    action: pseudonymize
    generator: ipv4
    priority: 100

  customer_name:
    pattern: '(?i)\bNIKE\b'
    category: customer
    action: pseudonymize
    generator: alias
    priority: 80

  forbidden_secret:
    pattern: '(?i)secret\s*[:=]\s*(?P<value>[^\s,;]+)'
    action: block
    priority: 200

Селекторы ключей защищают полные строковые значения. Например, {"password":"admin"} защищён, но несвязанный {"username":"admin"} не считается паролем. Именованные группы (?P<value>...) позволяют регулярному выражению заменять только захваченное значение.

Генераторы псевдонимов: ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url и alias.

Правила проверяются при запуске. Недопустимые селекторы, выражения, действия, генераторы или группы захвата не позволяют Cover запуститься. Ошибки детекторов, исчерпание отображений, повреждённый JSON, сжатые тела и явные блокировки не приводят к пересылке исходного запроса.

Стабильные псевдонимы и обратимые отображения

Cover создаёт ~/.config/cover/pseudonym.key с правами доступа только для владельца. HMAC-SHA-256 создаёт одинаковый псевдоним для одного и того же исходного значения во всех сеансах и перезапусках. Разные установки создают разные псевдонимы.

Ключ не позволяет восстановить исходные значения. Для восстановления используются ограниченные отображения, хранящиеся только в памяти процесса. Отображения разделяются по X-Cover-Session, истекают после настроенного TTL и удаляются по завершении изолированного запроса. Делайте резервную копию ключа, только если непрерывность стабильных псевдонимов важна.

Проверка, диагностика и мониторинг

Предпросмотр без отправки

cover inspect request.json
cover inspect request.json --session demo

Отчёт содержит преобразованный запрос, совпавшие правила, категории, действия, предупреждения и состояние блокировки. Он не отправляет сетевых запросов и не выводит обратимое отображение.

Проверка установки

cover doctor
cover doctor --json

Doctor проверяет конфигурацию, политику прослушивателя, лимиты, ключ псевдонимов, цикл редактирования и восстановления, защиту от зацикливания на upstream, демон, поведение fail-closed, журнал аудита, маршрутизацию окружения, провайдера Codex и сжатие запросов Codex. Его проверочный запрос отклоняется локально и не тратит токены модели.

Безопасный мониторинг по умолчанию

cover monitor
cover monitor --follow=false -n 50
cover monitor --json

Монитор по умолчанию показывает только разрешённые метаданные: время, HTTP-статус, количество преобразований, размеры в байтах, задержку, категории и общие ошибки. Журналы аудита никогда не содержат тела запросов и ответов, совпавшие значения, отображения, пути, параметры запроса или учётные данные upstream.

Явный просмотр чувствительных данных в реальном времени

cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json

Этот просмотр доступен только при явном включении: он показывает каждое перехваченное исходное и заменённое значение, а затем точный преобразованный JSON, переданный в upstream. Он работает только в реальном времени и никогда не попадает в журнал аудита. Захват начинается после подключения аутентифицированного локального зрителя и останавливается при его отключении. Поток работает только через loopback, использует токен, полученный из ключа установки, и отключает медленных зрителей.

[!WARNING] Этот вывод терминала содержит чувствительные данные. Не используйте --show-content в общих терминалах, записанных сеансах, журналах CI или стенограммах обращений в поддержку.

Подключение клиентов

Cover пересылает методы запросов, пути, параметры запроса и заголовки настроенному upstream. Существующая аутентификация провайдера продолжает работать, поскольку Cover не переписывает заголовки аутентификации.

Codex и Codex Router

Codex использует Responses API. Добавьте провайдера уровня пользователя в ~/.codex/config.toml и отключите сжатие запросов, чтобы Cover мог проверять тело:

model_provider = "cover"

[model_providers.cover]
name = "Cover"
base_url = "http://127.0.0.1:8317"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
enable_request_compression = false

Эти ключи соответствуют официальной справочной документации Codex по конфигурации. Если [features] уже существует, добавьте параметр в эту таблицу. Для роутера, который читает токен из окружения, замените requires_openai_auth на env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Оставьте upstream Cover направленным на реальный URL роутера. Используйте configs/codex-router.example.yaml в качестве отправной точки. Выбранной моделью может быть OpenAI, Anthropic, Gemini, DeepSeek или другая модель, поскольку Cover работает с общим JSON-трафиком роутера.

Поля encrypted_content Responses API непрозрачны и криптографически проверяемы. Cover оставляет их без изменений при сканировании запросов и восстановлении ответов.

Claude Code, SDK и другие клиенты

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1

Claude Code использует первую форму. SDK и клиенты, совместимые с OpenAI, обычно используют форму /v1. Установщик может сохранить эти настройки, а cover env выводит экспорты для клиентов, выбранных при установке.

Конструкторы SDK могут задавать тот же базовый URL напрямую:

client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key=os.environ["OPENAI_API_KEY"])
client = anthropic.Anthropic(base_url="http://127.0.0.1:8317", api_key=os.environ["ANTHROPIC_API_KEY"])

Cursor и другие приложения могут использовать тот же конечный адрес, если они предоставляют настройку базового URL API. Подтвердите маршрутизацию с помощью cover doctor или cover monitor.

Pi и Oh My Pi

Официальное расширение harness управляет Cover из Pi или Oh My Pi, сохраняя механизм конфиденциальности в локальном Go-прокси:

pi install npm:cover-harness
# or
omp plugin install cover-harness

Настройте только тех провайдеров, которые должны проходить через текущий upstream Cover:

/cover providers openai-codex,deepseek=/
/cover on
/cover doctor

Провайдеры семейства OpenAI по умолчанию используют путь прокси /v1. =/ выбирает корень прокси для транспортов, таких как DeepSeek, которые добавляют собственный путь запроса. Для обычной работы используйте /cover status, /cover start, /cover stop и /cover monitor. /cover off восстанавливает прямую маршрутизацию к провайдеру.

Защита работает в режиме fail-closed: пока она включена, настроенные провайдеры остаются направленными на Cover, даже когда его демон недоступен, поэтому запросы отклоняются локально, а не в обход прокси. Состояние расширения хранится локально и конфиденциально в ~/.config/cover/harness.json.

Тот же пакет доступен в каталоге пакетов Pi. Пользователи OMP также могут добавить этот репозиторий как маркетплейс:

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-harness@cover

Дополнительный локальный LLM-детектор

Правила на основе регулярных выражений и ключей не могут распознать каждое имя, адрес, идентификатор клиента или внутреннее кодовое имя. Cover может запускать небольшую локальную модель llama.cpp как дополнительный семантический детектор.

cover models pull
cover models status
cover restart

Модель по умолчанию — Qwen2.5-0.5B-Instruct в виде GGUF Q4 объёмом около 490 МБ. Cover запускает llama-server на loopback и обеспечивает лимиты бюджета на каждый вызов и на общий объём запросов. Отсутствующие бинарные файлы, сбои запуска, тайм-ауты и ошибки детектора приводят к отказу (fail closed), когда детектор включён. Возвращённые фрагменты должны встречаться в исходном тексте дословно, прежде чем Cover их примет.

Оставьте эту функцию отключённой на неподдерживаемых платформах. См. раздел detectors.llm_fallback в configs/config.example.yaml для получения информации о лимитах, пакетной обработке, параллелизме и путях к моделям.

Границы безопасности

Cover защищает совпадающие строковые значения в JSON-телах, которые действительно проходят через прокси. Он не заявляет, что обнаруживает каждое чувствительное значение.

Данные всё ещё могут покинуть машину, если они появляются в:

• значении, которое не распознаёт ни один включённый детектор или правило;
• поле, покрытом правилом allow;
• HTTP-заголовках, путях URL или строках запроса;
• пикселях изображений, двоичных медиафайлах или неподдерживаемых кодировках;
• нестроковых JSON-значениях;
• структурных полях протокола, таких как model, role, type, IDs и имена инструментов или функций;
• непрозрачных encrypted_content, которые должны оставаться неизменными для безопасности протокола;
• трафике клиента, который обходит Cover.

Обработка встроенных изображений настраивается с помощью media.images: allow, warn или block. Cover не проверяет пиксели, и ни одна политика медиа не может распознать все возможные кодировки.

Cover отклоняет прослушиватели не на loopback, если явно не настроено network.allow_remote: true. Если Cover и его upstream-роутер работают на разных хостах, используйте TLS или другой доверенный транспорт и примените отдельные средства контроля сетевого доступа. Cover сам не аутентифицирует обычный прокси-трафик.

Лимиты запроса, буферизованного ответа, общего потока и каждого SSE-события ограничивают использование памяти. Чрезмерно большие запросы возвращают HTTP 413, чрезмерно большие буферизованные ответы — HTTP 502, а слишком большие потоки завершаются.

Прочтите SECURITY.md перед сообщением об уязвимости. Пожалуйста, используйте описанный там приватный канал сообщений, а не открывайте публичный issue.

Проект

• Разработка и тесты: CONTRIBUTING.md
• Поведение: CODE_OF_CONDUCT.md
• Лицензия: Apache License 2.0