ContextCloak

LLM, 에이전트, 외부 API로 텍스트를 보내기 전에 민감한 값을 가리고, 필요한 경우 같은 세션에서 다시 되돌리는 마스킹 API/SDK입니다.

ContextCloak는 LLM이 아닙니다. 외부 처리 단계 앞에 놓이는 보호 레이어입니다.

핵심 흐름

원본 문장
  -> ContextCloak가 민감정보 탐지
  -> 외부로 보낼 문장 생성
  -> 외부 처리 결과에 남은 임시 값
  -> 같은 세션에서 원문 맥락으로 되돌리기

예를 들어 API 키, 이메일, 전화번호, 내부 IP 같은 값은 외부로 보낼 문장에서 [REDACTED_*] 형태의 임시 값으로 바뀝니다. 원본값과 임시 값의 연결 정보는 복원을 위해 세션에서 관리하며, 로그에는 원본값을 남기지 않도록 설계되어 있습니다.

0. 사전 요구사항

아래 명령어는 Windows PowerShell 기준입니다. macOS/Linux는 uv 공식 설치 문서를 참고해 동일한 uv/git 명령을 셸에 맞게 실행하세요.

• Python 3.11 이상
• uv (Windows PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex")
• git

git clone https://github.com/Kyuhan1230/contextCloak.git
cd contextCloak

빠른 시작

1. 설치

uv sync

테이블(CSV/TSV/Parquet) 마스킹, 웹 UI "테이블" 탭, CLI masks·protect 명령까지 쓰려면 pandas/pyarrow가 필요한 table extra를 함께 설치하세요.

uv sync --extra table

AI 작업용 테이블 복사본 만들기

자동 감시나 원본 파일의 자동 변환은 하지 않습니다. 필요할 때 사용자가 직접 protect를 실행하면 원본 옆에 별도의 마스킹 복사본을 만듭니다.

# data/는 그대로 두고 data-masked/ 생성
uv run contextcloak protect .\data

# 출력 이름을 직접 지정
uv run contextcloak protect .\records.csv --output .\records-for-ai.csv

# 가장 안전한 방식: 원본은 AI workspace 밖에 두고 복사본만 안으로 생성
uv run contextcloak protect C:\private-data --output .\data-masked

• 입력은 CSV, TSV, Parquet 파일 또는 이 파일들을 담은 디렉터리입니다.
• 원본은 수정·이동하지 않으며, 이미 존재하는 출력은 덮어쓰지 않습니다.
• 디렉터리에서는 지원 테이블만 처리하고 다른 파일은 복사하지 않습니다.
• 출력에는 ContextCloak 복원용 매핑을 남기지 않습니다. 원본이 기준 데이터입니다.
• AI 도구에는 원본 data/가 아니라 생성된 data-masked/만 제공하세요.

가능하면 원본 폴더 자체를 AI workspace 밖에 두는 것이 가장 강한 경계입니다. protected_paths hook은 실수 방지를 돕지만 운영체제의 파일 권한을 대신하지 않습니다.

복원이 필요한 업무는 기존 Web UI, /v1/mask/table API 또는 SDK의 세션 기반 흐름을 사용해야 합니다.

NER(개체명 인식) 탐지까지 쓰려면 torch/transformers가 필요한 ner extra를 설치하세요. 기본(uv sync)만으로는 정규식 탐지만 동작합니다.

uv sync --extra ner

2. API 서버 실행

uv run contextcloak-server

또는 직접 uvicorn으로 실행할 수 있습니다.

uv run python -m uvicorn contextcloak.server.run:app --host 127.0.0.1 --port 18080

상태 확인:

curl http://127.0.0.1:18080/health

예상 응답:

{"status":"ok"}

3. 웹 UI 열기

브라우저에서 아래 주소를 엽니다.

http://127.0.0.1:18080/ui

웹 UI에서 확인할 수 있는 것:

• 원본 문장에서 민감한 값이 어떻게 가려지는지
• 외부로 보낼 문장에 원본값이 빠지는지
• 같은 세션에서 가린 값을 다시 되돌릴 수 있는지
• 현재 탐지 방식이 정규식인지 정규식 + NER인지
• 다크/라이트/시스템 테마 전환

배지에 마우스를 올리면 현재 로컬 API와 탐지 모드 설명이 표시됩니다.

웹 UI는 same-origin ContextCloak API만 호출합니다. 실제 외부 LLM이나 SaaS로 입력을 전송하지 않습니다.

SDK 사용 예시

Windows 콘솔에서 한글 출력이 깨진다면 PowerShell에서 아래처럼 환경변수를 지정한 뒤 실행하세요.

$env:PYTHONIOENCODING="utf-8"
uv run python script.py

from contextcloak import ContextCloak

agent = ContextCloak(base_url="http://127.0.0.1:18080")
session = agent.session(ttl_seconds=3600)  # session_id를 생략하면 서버가 자동 생성

masked = session.mask_text('api_key="sk-12345678901234567890"')
print(masked.masked_text)

external_response = "분석 결과: [REDACTED_CREDENTIALS] 값이 설정되어 있습니다."
restored = session.unmask_text(external_response)
print(restored)

session.close()
agent.close()

예상 출력:

api_key="[REDACTED_CREDENTIALS]"
분석 결과: sk-12345678901234567890 값이 설정되어 있습니다.

HTTP API

주요 endpoint:

GET    /health
POST   /v1/sessions
POST   /v1/mask/text
POST   /v1/unmask/text
DELETE /v1/sessions/{session_id}
GET    /ui
GET    /ui/status
POST   /ui/external-response

마스킹 요청:

POST /v1/mask/text
Content-Type: application/json

{
  "session_id": "analysis-001",
  "text": "admin email is hong.gildong@corp.example and host is 10.23.17.44"
}

응답 예시:

{
  "masked_text": "admin email is [REDACTED_PII_EMAIL] and host is [REDACTED_INFRA]",
  "session_id": "analysis-001",
  "detected_categories": ["PII_EMAIL", "INFRA"],
  "placeholder_counts": {"PII_EMAIL": 1, "INFRA": 1},
  "strategies_applied": {"PII_EMAIL": "reversible", "INFRA": "reversible"},
  "restorable": true
}

복원 요청:

POST /v1/unmask/text
Content-Type: application/json

{
  "session_id": "analysis-001",
  "text": "review [REDACTED_PII_EMAIL] and [REDACTED_INFRA]"
}

탐지 방식

ContextCloak는 정규식 기반 탐지를 기본으로 사용합니다. 설정과 모델 상태에 따라 NER가 함께 활성화될 수 있습니다.

웹 UI의 탐지 배지는 아래처럼 표시됩니다.

탐지: 정규식
탐지: 정규식 + NER

GET /ui/status는 웹 UI가 표시할 탐지 모드 상태를 반환합니다.

{
  "detection_mode": "탐지: 정규식 + NER",
  "ner_requested": true,
  "ner_config_enabled": true,
  "ner_model_exists": true,
  "ner_active": true,
  "detail": "정해진 패턴과 NER(개체명 인식)를 사용해 민감정보 후보를 찾습니다."
}

마스킹 전략

룰과 요청 옵션에 따라 표시 방식을 조정할 수 있습니다.

strategy	예시 입력	예시 출력	용도
reversible	api_key="sk-..."	api_key="[REDACTED_CREDENTIALS]"	같은 세션에서 복원해야 하는 값
partial	10.23.17.44	10.x.xx.xxx	일부 형태만 보여도 되는 값
pseudonym	James Bond	PERSON_001	사람/서비스/업무 객체 alias
passthrough	TI-101	TI-101	정책상 그대로 통과하는 값

요청 예시:

masked = session.mask_text(
    "operator James Bond connected from 10.23.17.44",
    options={
        "category_strategies": {
            "PERSON": "pseudonym",
            "INFRA": "partial",
        }
    },
)

print(masked.masked_text)

테이블 마스킹 전략

CSV/DataFrame/Parquet 테이블은 컬럼 dtype과 샘플 값을 기준으로 전략을 추론하고, credential 형식은 일부 행을 놓치지 않도록 전체 non-null 값을 검사합니다.

strategy	적용 대상	동작
standard_scale	숫자 컬럼	평균과 표준편차로 변환하고 같은 세션에서 복원
pseudonym	문자열 컬럼	PERSON_001 같은 session-local alias로 치환
partial	IP 등 일부 형식을 유지할 값	일부 구조만 남기고 값 치환
date_shift	datetime dtype, ISO date/datetime 문자열	-371일 이동해 요일을 유지하고 같은 세션에서 복원
passthrough	bool 또는 명시적으로 통과시킨 컬럼	값을 변경하지 않음

date_shift의 이동값은 -371일, 즉 53 * 7일입니다. 따라서 날짜는 달라지지만 요일 특성은 유지됩니다. CSV의 ISO YYYY-MM-DD 날짜 문자열과 Parquet의 datetime 컬럼에 자동 적용되며, 컬럼 override로 passthrough를 지정하면 이동하지 않습니다.

서버 설정

환경 변수	기본값	설명
CONTEXTCLOAK_HOST	127.0.0.1	API 서버 bind host
CONTEXTCLOAK_PORT	18080	API 서버 port
CONTEXTCLOAK_BASE_URL	http://127.0.0.1:18080	SDK가 호출할 API 서버 URL
CONTEXTCLOAK_CONFIG_DIR	기본 config 경로	룰/프로젝트 설정 디렉터리
CONTEXTCLOAK_PROJECTS_ROOT	~/Projects	projects.yaml의 프로젝트 상위 디렉터리
CONTEXTCLOAK_PROJECT	없음	사용할 project 이름
CONTEXTCLOAK_USE_NER	true	NER 사용 요청 여부
CONTEXTCLOAK_VAULT_PATH	logs/contextcloak-vault.sqlite	SQLite session 복원 매핑 저장소

예시:

$env:CONTEXTCLOAK_USE_NER="false"
uv run contextcloak-server

SQLite Vault 예시:

$env:CONTEXTCLOAK_VAULT_PATH="C:\ContextCloak\vault.sqlite"
uv run contextcloak-server

SQLite Vault 파일에는 복원에 필요한 원본 민감값이 저장됩니다. 운영 환경에서는 파일 권한, 디스크 암호화, 백업 정책, 보관 기간을 별도로 통제해야 합니다.

운영 주의점

• 마스킹은 유출 위험을 낮추는 보호 레이어이지, 전체 보안 통제를 대체하지 않습니다.
• 복원은 같은 세션의 연결 정보에 의존합니다. 세션 ID와 TTL을 업무 단위에 맞게 분리하세요.
• 외부 LLM/API에는 원본값이 아니라 마스킹된 문장만 전달하는 구조로 호출 코드를 작성해야 합니다.
• 운영 환경에서는 인증, 접근 제어, 감사 정책, 영속 Vault 저장소를 별도로 설계해야 합니다.
• 민감 원본값을 로그에 남기지 않는 정책을 유지해야 합니다.

현재 지원 범위

영역	상태
텍스트 마스킹/복원 API	지원
Python SDK	지원
세션 기반 복원	지원
웹 UI	지원
정규식 탐지	지원
NER 탐지	설정/모델 상태에 따라 지원 (uv sync --extra ner 필요)
DataFrame/CSV/TSV/Parquet 로컬 마스킹 서비스	제공 (uv sync --extra table 필요)
CSV/TSV/Parquet 수동 보호 복사본 CLI	지원 (contextcloak protect)
원본 폴더 자동 감시·자동 변환	지원하지 않음 (명시적 실행 원칙)
원격 Parquet 업로드 API	예정
인증/권한	운영 배포 전 추가 필요

secureAgent 호환성

기존 secureagent import, CLI, 환경변수는 호환을 위해 유지합니다. 런타임 구현 기준은 contextcloak.*이며, 새 코드에서는 contextcloak import와 CONTEXTCLOAK_* 환경변수를 사용하세요.

아키텍처

제품 본선은 Python SDK가 HTTP API를 호출하고, API가 서비스·탐지·Vault 계층을 조합하는 구조입니다.

Python SDK
  -> HTTP API
  -> masking/session services
  -> detector, policy, table transformer
  -> SQLite Vault

사용자 명시 실행
  -> protect CLI
  -> 원본 유지 + 별도 마스킹 복사본

• SDK는 Vault를 직접 생성하거나 읽지 않습니다.
• core는 탐지와 마스킹 규칙을, services는 유스케이스 조합을 담당합니다.
• api와 server는 HTTP 계약과 실행 환경을 담당합니다.
• proxy와 mitm은 호환·진단 경로이며 기본 SDK/API 흐름이 아닙니다.
• DataFrame/Parquet 처리는 로컬 서비스와 Web UI에서 제공하며 현재 HTTP SDK 공개 API에는 포함하지 않습니다.
• protect는 별도 복사본만 만들고 복원 metadata를 즉시 폐기하는 로컬 일회성 흐름입니다.

모듈 문서

구현과 함께 유지해야 하는 계약은 각 모듈 README에 둡니다.

영역	문서
패키지 구조와 공개 API	contextcloak/README.md
설정과 탐지 룰	config/README.md
Web UI	contextcloak/webui/README.md
테이블 마스킹	contextcloak/table/README.md
Claude Code hooks	contextcloak/hooks/README.md
Vault	contextcloak/vault/README.md
MITM 진단 경로	contextcloak/mitm/README.md
운영·검증 스크립트	scripts/README.md

개발

테스트 실행:

uv run pytest

웹 UI 관련 테스트만 실행:

uv run pytest tests/test_web_ui.py

탐지 품질 리포트:

uv run python scripts\evaluate_detection_quality.py

Privacy Filter 모델 설치와 로컬 로드 검증 (uv sync --extra ner 먼저 필요):

uv run python scripts\setup_privacy_filter_model.py
uv run python scripts\setup_privacy_filter_model.py --skip-download
uv run pytest -q tests/test_privacy_filter_local_model.py