query-sanitizer-mcp
query-sanitizer-mcp
프롬프트와 외부 LLM 사이에 위치하여 데이터가 기기를 떠나기 전에 민감한 정보를 자동으로 삭제하는 경량 MCP 미들웨어입니다.
[Your Prompt] → sanitize_query() → [Safe Prompt] → External LLM → [Response] → restore_response() → [You]v0.3.0 — 4단계 DLP 파이프라인: 정규식 → GLiNER NER → LLM 정제 → 사후 스캔 확인. 100% 오픈 소스, 100% 로컬 환경에서 실행됩니다. M4 MacBook 및 Google Colab T4에서 테스트되었습니다.
목적
내부 컨텍스트를 Claude, ChatGPT 또는 기타 클라우드 LLM에 붙여넣을 때마다 다음과 같은 정보가 유출될 위험이 있습니다:
직원 이름, 이메일, 전화번호
내부 프로젝트 코드명
인프라 세부 정보 (IP, 호스트 이름, DB 이름)
API 키 및 자격 증명
회사 이름, 거래 규모, 법적 참조
이 MCP 서버는 해당 텍스트를 가로채어 민감한 토큰을 유형별 자리 표시자([ORG_NAME_1], [PII_NAME_1] 등)로 대체하고, 응답에서 이를 복원합니다. 따라서 사용자는 자연스러운 텍스트를 보게 되며, 클라우드 LLM은 실제 값을 절대 볼 수 없습니다.
Related MCP server: ai-security-gateway-mcp
도구
도구 | 설명 |
| 3단계 삭제. 안전한 텍스트 + |
| 자리 표시자를 원래 값으로 교체. |
| LLM 응답에서 생성되거나 유출되었을 수 있는 데이터를 스캔. |
| 최근 삭제 기록 표시. |
탐지 파이프라인
1단계 — 정규식 사전 통과 (항상 실행, 모델 불필요)
구조화된 토큰을 위한 결정론적 패턴입니다. 로컬 모델이 오프라인일 때도 실행됩니다.
패턴 | 카테고리 | 차단 여부 |
AWS 액세스 키 ( | CREDENTIAL | 예 — 차단됨 |
GitHub 토큰 ( | CREDENTIAL | 예 |
JWT ( | CREDENTIAL | 예 |
Slack 토큰 ( | CREDENTIAL | 예 |
| CREDENTIAL | 예 |
URL 내 비밀번호 ( | CREDENTIAL | 예 |
이메일 주소 | PII_NAME | 아니요 — 복원됨 |
전화번호 | PII_NAME | 아니요 |
SSN ( | PII_ID | 아니요 |
직원/배지 ID ( | PII_ID | 아니요 |
RFC 1918 사설 IP | INFRA | 아니요 |
달러 금액 | FINANCIAL | 아니요 |
설정 정의 엔티티 (조직명, 직원, 코드명, 도메인) | 다양함 | 아니요 |
2단계 — LLM 정제 (문맥 기반, 최선 노력)
문맥 내에서 사용되는 조직명, 프로젝트 코드명, GEO_INTERNAL 참조, LEGAL 용어, INTERNAL_URL 패턴 등 의미론적 이해가 필요한 엔티티를 포착합니다. 로컬 모델을 사용할 수 없는 경우, 명확한 경고와 함께 1단계 출력 결과가 반환됩니다.
3단계 — 사후 스캔 신뢰도 확인
삭제된 텍스트에 대해 높은 신뢰도의 정규식 패턴을 실행하여 LLM이 놓쳤을 수 있는 잠재적 데이터(예: 모델이 포착하지 못한 JWT)를 플래그 지정합니다. 보고서에 경고로 표시됩니다.
설정
옵션 A — M4 MacBook (권장)
스택: Ollama 0.19+ (MLX 백엔드, M4에서 약 50 tok/s) + GLiNER NER (MPS, 호출당 약 80ms)
# 1. Install Ollama and pull the recommended model
brew install ollama
ollama pull qwen2.5:3b # 2GB, fast + strong instruction following
ollama serve # Ollama 0.19+ uses MLX automatically on Apple Silicon
# 2. Clone and install with NER layer
git clone https://github.com/vidoluco/query-sanitizer-mcp
cd query-sanitizer-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[nlp]" # fastmcp + gliner (GLiNER NER layer)Claude Code에 추가 (~/.claude/settings.json):
{
"mcpServers": {
"query-sanitizer": {
"command": "/path/to/query-sanitizer-mcp/.venv/bin/python",
"args": ["/path/to/query-sanitizer-mcp/server.py"],
"env": {
"SANITIZER_MODEL_NAME": "qwen2.5:3b",
"SANITIZER_GLINER_MODEL": "urchade/gliner_medium-v2.1"
}
}
}
}M4용 대체 LLM 모델 (모두 Ollama 경유):
모델 | 크기 | M4 속도 | 용도 |
| 2 GB | ~50 tok/s | 기본 — 빠르고 정확함 |
| 3 GB | ~40 tok/s | 강력한 추론 |
| 2 GB | ~45 tok/s | 광범위한 일반 용도 |
| 5 GB | ~30 tok/s | 더 높은 정확도, 더 많은 RAM 필요 |
옵션 B — Google Colab T4
스택: HuggingFace transformers (Ollama 불필요) + GLiNER (CUDA)
# Cell 1 — install
!pip install "query-sanitizer-mcp[colab]" -q
# fastmcp + gliner + transformers + torch + accelerate
# Cell 2 — configure
import os
os.environ["SANITIZER_BACKEND"] = "hf"
os.environ["SANITIZER_HF_MODEL"] = "Qwen/Qwen2.5-3B-Instruct" # ~6GB, fits T4 16GB
os.environ["SANITIZER_GLINER_MODEL"] = "urchade/gliner_medium-v2.1"
os.environ["SANITIZER_LEDGER_DIR"] = "/content/sanitizer-ledger"
# Cell 3 — use directly (no MCP client needed in Colab)
import sys; sys.path.insert(0, ".")
from server import sanitize_query, restore_response, scan_response
result = sanitize_query("Send report to jane.doe@acme.com re: Project Phoenix")
print(result)첫 실행 시
Qwen2.5-3B-Instruct(~6 GB)와gliner_medium-v2.1(~500 MB)을 Colab 캐시로 다운로드합니다. 이후 실행은 즉시 이루어집니다.
최소 설정 (정규식 전용, 모델 불필요)
의존성 없는 운영(순수 정규식, Ollama 및 GLiNER 미사용)을 원할 경우:
pip install fastmcp
SANITIZER_MODEL_RETRIES=0 python server.py자격 증명, 이메일, SSN, 사설 IP 및 금융 금액은 정규식만으로 포착됩니다. 사람, 조직명, 프로젝트 코드명은 GLiNER 또는 LLM 계층이 필요합니다.
구성
.sanitizer-ledger/config.json을 생성하거나 python scripts/ledger.py init-config를 실행하세요:
{
"org_names": ["Acme Corp", "Acme"],
"org_domains": ["acme-internal.net"],
"project_codenames": ["Phoenix", "Titan"],
"known_employees": ["Jane Smith", "Marcus Webb"],
"internal_ip_ranges": ["10.0.0.0/8"],
"custom_patterns": [
{"pattern": "JIRA-\\d{4,}", "category": "PROJECT_NAME", "description": "Jira tickets"}
],
"always_allow": ["Google Cloud", "Kubernetes", "BigQuery", "Terraform", "Docker"]
}설정으로 정의된 엔티티(org_names, known_employees 등)는 정규식 사전 통과(결정론적 매칭용)와 LLM 시스템 프롬프트(문맥 변형용) 모두에 연결됩니다. 변경 사항은 다음 sanitize_query 호출 시 적용되며 서버 재시작은 필요하지 않습니다.
환경 변수
변수 | 기본값 | 설명 |
|
| 로컬 모델 엔드포인트 |
|
| 모델 이름 |
|
| 모델 실패 시 재시도 횟수 (2s, 4s 백오프) |
|
| 기록 디렉토리 경로 |
|
|
|
Ledger CLI
python scripts/ledger.py list [N] # recent N entries
python scripts/ledger.py lookup <san_id> # full mapping for one entry
python scripts/ledger.py restore <san_id> <text> # restore from CLI
python scripts/ledger.py stats # aggregate stats by category and source
python scripts/ledger.py purge --older-than 30d # enforce retention policy
python scripts/ledger.py init-config # create starter config.json삭제 카테고리
카테고리 | 예시 | 심각도 |
| API 키, 토큰, 비밀번호 | 치명적 — 차단됨, 절대 복원 안 됨 |
| 인트라넷 URL, 스테이징 엔드포인트 | 치명적 |
| 이름, 이메일, 전화번호 | 높음 |
| SSN, 직원 ID, 배지 번호 | 높음 |
| 회사/자회사 이름 | 높음 |
| 계약 조건, 사건 번호 | 높음 |
| 내부 코드명 | 중간 |
| IP, 호스트 이름, DB 이름 | 중간 |
| 수익, 거래 규모, 예산 | 중간 |
| 사무실 위치, 건물 이름 | 낮음 |
보안 모델
자격 증명은 절대 저장되지 않음 — 원본 값 대신
[BLOCKED]가 기록됨Fail-safe, not fail-open — 모델을 사용할 수 없는 경우 정규식 폴백이 트리거되며, 일반 텍스트가 그대로 통과되지 않음
로컬 추론 전용 — 삭제 단계를 위해 외부 API로 전송되는 데이터 없음
개인정보 보호 모드 (
SANITIZER_LEDGER_STORE_ORIGINALS=false) — 원본이 디스크에 전혀 기록되지 않음; 복원은 메모리 내 캐시를 통해 동일한 서버 세션 내에서만 작동
예시
전체 세션 추적은 examples/를 참조하세요:
01_api_key_leak.md— 정규식 사전 통과에 의해 차단된 AWS 자격 증명02_employee_pii.md— 이름, 이메일, 직원 ID가 포함된 HR 프롬프트 + 복원03_internal_infra.md— Ollama 오프라인 상태에서의 인프라 디버깅 (정규식 폴백)
기여
이슈를 열거나 PR을 보내주세요.
향후 계획 아이디어:
[ ] 탐지된 패턴에서 설정 항목 자동 제안
[ ] Claude Code 훅 통합 (프롬프트 전 자동 삭제)
[ ] 신뢰도 임계값 설정
[ ] 일괄/대량 삭제 모드
[ ] 코드 블록 스캔 (인라인 비밀값, import 경로)
[ ] 저장 시 기록 암호화
[ ] 기록 검토를 위한 웹 UI
라이선스
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Detect and redact PII and secrets before text reaches an LLM, with reversible placeholders.
Find and redact leaked secrets, wallet keys and PII before an AI agent sends text.
Detect and redact PII and secrets (API keys, tokens) in text, HTML or PDF before it reaches an LLM.
Scan prompts for injection attacks, redact PII, and audit LLM SDK usage from any MCP client
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceSecurity middleware for LLM apps and AI agent pipelines. Detects prompt injection attacks (22 signatures, 7 languages) and anonymizes PII (17 entity types). Deterministic, sub-25ms, GDPR Art.30 compliant.-
- AlicenseAqualityDmaintenanceScans prompts for PII and masks or redacts sensitive data locally before sending to an LLM, supporting multiple anonymization modes.1MIT
- FlicenseAqualityDmaintenanceA data-loss-prevention (DLP) layer for AI agents that intercepts document reads, scans for sensitive data, and redacts or blocks it before it reaches the model, with audit logging.1-
- AlicenseAqualityBmaintenanceEnables safe interaction with cloud LLMs by redacting sensitive entities into reversible placeholders, enforcing deterministic egress policies with human approval, and rehydrating responses so real data never leaves the process.4MIT