davidcarliez/coverAI 요청이 기기를 떠나기 전에 비밀 정보와 개인 식별 정보(PII)를 대체하는 로컬 개인정보 보호 프록시
대화를 끊지 않고 민감한 값을 LLM 요청에서 제외하세요.
설치 · 빠른 시작 · 정책 · 모니터링 · Pi / OMP · 보안
Cover는 Codex, Claude Code, Cursor, SDK 및 기타 HTTP 기반 AI 클라이언트를 위한 로컬 프라이버시 프록시입니다. 나가는 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 기능 |
|---|---|
| 정책 | allow, placeholder, pseudonymize, mask, redact, block 작업을 사용하는 선언적 규칙 |
| 현실적인 대체 값 | IP 주소, 호스트, 도메인, 이메일, 사용자 이름, 비밀번호, UUID, URL 및 별칭을 위한 결정적 생성기 |
| 문맥 인지 규칙 | admin 같은 짧은 비밀번호를 포함하여 JSON 키별 전체 값 보호, 정규식 및 내장 탐지기 선택자 지원 |
| 안정적인 식별자 | 설치 키 기반 HMAC 가명은 요청, 세션, 재시작을 걸쳐 일관되게 유지됩니다. |
| 매핑 안전성 | TTL과 용량 제한이 있는, 범위가 제한되고 세션별로 격리된 메모리 전용 되돌릴 수 있는 매핑 |
| 검사 | cover inspect는 LLM에 연결하지 않고 보호된 JSON을 미리 봅니다. |
| 진단 | cover doctor는 정책, 데몬 상태, 로컬 fail-closed 동작, Codex 라우팅을 확인합니다. |
| 모니터링 | 메타데이터 전용 감사 및 모니터링 보기, 그리고 캡처되거나 전달된 콘텐츠의 명시적 실시간 전용 검사 |
| 프록시 강화 | 기본 루프백 리스너, 본문 및 스트림 제한, 일반적인 안전 오류, fail-closed 파싱 |
| Codex 호환성 | Responses API 및 라우터 구성, 압축 검사, 안전한 SSE 복원, 불변 encrypted_content 필드 |
| 선택적 의미론적 검사 | 로컬 llama.cpp 탐지기가 정규식이 놓치는 자유 형식 텍스트를 검사할 수 있습니다. |
설치 프로그램은 Cover를 클론하고 Go로 빌드하여 ~/.local/bin/cover에 설치하고 선택한 클라이언트를 구성한 다음 프록시를 시작합니다.
curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash
요구 사항: git 및 go.mod에 명시된 Go 버전.
사전 빌드된 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
핵심 바이너리에는 cgo 의존성이 없습니다. 표준 Go 크로스 컴파일도 동작합니다:
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 또는 사용자 지정 업스트림을 입력하도록 요청합니다. 전체 구성은 configs/config.example.yaml에 문서화되어 있습니다.
| 명령 | 용도 |
|---|---|
cover install | 클라이언트, 셸 내보내기, 백그라운드 프록시 구성 |
cover init | 구성 파일 생성 |
cover start [--detach] | 포그라운드 또는 백그라운드로 Cover 시작 |
cover stop | 백그라운드 프로세스 중지 |
cover restart | 백그라운드에서 다시 시작 |
cover status [--json] | 프로세스, 리스너, 수정된 업스트림 상태 표시 |
cover version [--json] | 빌드 버전, 커밋, 날짜 표시 |
cover env | 구성된 클라이언트의 셸 내보내기 출력 |
cover test | 로컬 합성 편집(redaction) 및 복원 검사 실행 |
cover inspect request.json | Cover가 전달할 내용을 정확히 미리 보기 |
cover doctor [--json] | 구성, 프라이버시, 데몬, 라우팅 검사 실행 |
cover monitor | 최근 안전 메타데이터 표시 및 새 이벤트 추적 |
cover monitor --show-content | 민감한 실시간 변환 및 발신 JSON 표시 |
cover models pull | 선택적 로컬 탐지기 런타임 및 모델 다운로드 |
cover models status | 로컬 탐지기 설치 및 구성 보고 |
cover completion | 셸 완성 스크립트 생성 |
Cover를 중지해도 클라이언트 구성은 변경되지 않습니다. 여전히 Cover를 가리키는 클라이언트는 Cover가 다시 시작되거나 클라이언트가 직접 공급자 또는 라우터를 다시 가리키기 전까지 연결에 실패합니다.
내장 정규식 탐지는 AWS 및 GCP 키, GitHub, GitLab, Slack, Stripe, Anthropic 토큰, 개인 키 블록, JWT, 명시적 일반 비밀 할당, 이메일, SSN, 신용카드, 전화번호, IBAN을 다룹니다. 단순한 OpenAI sk-... 값은 의도적으로 전용 내장 범주가 아닙니다. 환경에 필요하다면 명시적 규칙을 정의하세요.
규칙은 ~/.config/cover/config.yaml의 rules 아래에 있습니다. 선택자는 정규식, 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>...) 그룹을 사용하면 정규식이 캡처된 값만 대체할 수 있습니다.
| 작업 | 결과 |
|---|---|
allow | 일치 항목을 기록하되 변경하지 않고 남겨 둡니다 |
placeholder | 짧은 되돌릴 수 있는 토큰으로 대체합니다 |
pseudonymize | 현실적이고 결정적인 값으로 대체합니다 |
mask | 첫 번째와 마지막 문자는 유지하고 중간을 마스킹합니다 |
redact | [REDACTED]로 대체합니다 |
block | 전체 요청을 로컬에서 거부합니다 |
가명 생성기: 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는 구성, 리스너 정책, 제한, 가명 키, 편집(redaction) 왕복, 업스트림 루프 보호, 데몬, fail-closed 동작, 감사 로그, 환경 라우팅, Codex 공급자, Codex 요청 압축을 검증합니다. 실시간 프로브는 로컬에서 거부되며 모델 토큰을 소비하지 않습니다.
cover monitor
cover monitor --follow=false -n 50
cover monitor --json
기본 모니터는 허용 목록에 포함된 메타데이터(시간, HTTP 상태, 변환 수, 바이트 수, 지연 시간, 범주, 일반 오류)만 표시합니다. 감사 로그에는 요청 또는 응답 본문, 일치 값, 매핑, 경로, 쿼리, 업스트림 자격 증명이 절대 포함되지 않습니다.
cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json
이 옵트인 보기에는 캡처된 각 원본과 대체 값, 그리고 업스트림 전송에 전달된 정확한 변환 JSON이 표시됩니다. 실시간 전용이며 감사 로그에는 절대 추가되지 않습니다. 캡처는 인증된 로컬 뷰어가 연결된 후 시작되고 연결이 끊기면 중지됩니다. 스트림은 루프백 전용이며, 설치 키에서 파생된 토큰을 사용하고, 느린 뷰어는 연결을 끊습니다.
[!WARNING] 이 터미널 출력은 민감합니다. 공유 터미널, 녹화된 세션, CI 로그 또는 지원 대화 기록에서는
--show-content를 사용하지 마세요.
Cover는 요청 메서드, 경로, 쿼리, 헤더를 구성된 업스트림으로 전달합니다. Cover는 인증 헤더를 다시 쓰지 않으므로 기존 공급자 인증도 계속 작동합니다.
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"로 바꾸세요.
Cover의 upstream이 실제 라우터 URL을 가리키도록 유지하세요. configs/codex-router.example.yaml을 시작점으로 사용하세요. Cover는 라우터의 일반 JSON 트래픽에서 동작하므로 선택한 모델은 OpenAI, Anthropic, Gemini, DeepSeek 또는 다른 모델일 수 있습니다.
Responses API encrypted_content 필드는 불투명하고 암호학적으로 검증됩니다. Cover는 요청 스캔과 응답 복원 중에 이를 변경하지 않고 유지합니다.
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1
Claude Code는 첫 번째 형식을 사용합니다. OpenAI 호환 SDK 및 클라이언트는 일반적으로 /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 및 다른 애플리케이션은 API 기본 URL 설정을 제공하는 경우 동일한 엔드포인트를 사용할 수 있습니다. cover doctor 또는 cover monitor로 라우팅을 확인하세요.
공식 하네스 확장은 프라이버시 엔진을 로컬 Go 프록시에 유지하면서 Pi 또는 Oh My Pi에서 Cover를 제어합니다:
pi install npm:cover-harness
# or
omp plugin install cover-harness
현재 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
정규식 및 키 인지 규칙은 모든 이름, 주소, 고객 ID 또는 내부 코드명을 식별할 수 없습니다. Cover는 추가 의미론적 탐지기로 작은 로컬 llama.cpp 모델을 실행할 수 있습니다.
cover models pull
cover models status
cover restart
기본 모델은 약 490MB Q4 GGUF 형식의 Qwen2.5-0.5B-Instruct입니다. Cover는 루프백에서 llama-server를 시작하고 호출별 및 전체 요청 예산을 적용합니다. 바이너리 누락, 시작 실패, 시간 초과, 탐지기 오류는 탐지기가 활성화된 경우 fail-closed로 처리됩니다. 반환된 스팬은 Cover가 수락하기 전에 입력에 그대로 존재해야 합니다.
지원되지 않는 플랫폼에서는 이 기능을 비활성화된 상태로 두세요. 제한, 일괄 처리, 동시성, 모델 경로는 configs/config.example.yaml의 detectors.llm_fallback 섹션을 참조하세요.
Cover는 실제로 프록시를 통과하는 JSON 본문의 일치하는 문자열 값만 보호합니다. 모든 민감한 값을 발견한다고 주장하지 않습니다.
데이터가 다음 위치에 나타나면 여전히 머신을 벗어날 수 있습니다:
allow 규칙이 적용되는 필드encrypted_content인라인 이미지 처리는 media.images: allow, warn, block으로 구성할 수 있습니다. Cover는 픽셀을 검사하지 않으며, 어떤 미디어 정책도 모든 가능한 인코딩을 인식할 수 없습니다.
Cover는 network.allow_remote: true가 명시적으로 구성되지 않는 한 루프백이 아닌 리스너를 거부합니다. Cover와 업스트림 라우터가 다른 호스트에서 실행되는 경우 TLS 또는 다른 신뢰할 수 있는 전송을 사용하고 별도의 네트워크 액세스 제어를 적용하세요. Cover 자체는 일반 프록시 트래픽을 인증하지 않습니다.
요청, 버퍼링된 응답, 전체 스트림, SSE 이벤트별 제한이 메모리 사용을 제한합니다. 크기가 초과된 요청은 HTTP 413을 반환하고, 크기가 초과된 버퍼링된 응답은 HTTP 502를 반환하며, 크기가 초과된 스트림은 종료됩니다.
취약점을 신고하기 전에 SECURITY.md를 읽으세요. 공개 이슈를 여는 대신 해당 문서에 설명된 비공개 신고 경로를 사용하세요.
CONTRIBUTING.mdCODE_OF_CONDUCT.md