# 한국형 문서보안 필터 API
**Korean Documents DLP** — 기업 내부 문서와 데이터에서 기밀 정보 유출을 사전에 탐지·차단하는 AI 모델이에요. 6단계 등급(PUBLIC ~ CLASSIFIED)과 11가지 유형(계약·재무·M&A·HR·법무 등) 으로 자동 분류해요.
- **모델 ID**: `dlp`
- **라이브 버전**: `dlp-2026.05`
- **정확도** (1,541건 별도 평가 묶음): 등급 정확도 91.0% · 중요정보 차단 99.7% · 잘못 등급 올림 0.2%
- **2단계 자동 보강**: 빠른 분류기(약 10ms) → 신뢰도 부족 시 깊은 추론기(약 5s) 자동 호출
## 핵심 기능
- 계약서·재무자료·전략문서·코드 등 기밀 데이터 탐지
- 내부 정책 기반 민감도 분류 (Confidential / Internal / Public)
- 문맥 기반 "영업비밀 / 내부 의사결정 정보" 식별
- 파일 업로드·외부 전송 시 실시간 차단
- 사용자 행동 기반 유출 리스크 탐지
## 특징
- 단순 키워드가 아닌 "의미 기반" 기밀 판단
- 기업별 맞춤 정책 적용 가능 (대시보드 → 설정 → 필터 정책)
- 빠른 분류기 + 깊은 추론기 결합 (정확도와 속도 균형)
- SaaS·이메일·메신저·문서 시스템과 연동 가능
- 사내 보안 및 컴플라이언스 강화에 최적화
## 1. 빠른 호출
```bash
curl -X POST https://api.corepin.ai/v1/dlp/classify \
-H "Authorization: Bearer $COREPIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "본 인수합병은 공시 전 사내 보고용 자료로 외부 공유를 금합니다."
}'
```
응답:
```json
{
"grade": "TRADE_SECRET",
"grade_ko": "영업비밀",
"types": ["M_AND_A"],
"types_ko": ["인수합병"],
"tier_used": "t2_1",
"escalated": false,
"confidence": 0.973,
"grade_probs": {"PUBLIC": 0.001, "INTERNAL": 0.005, ...},
"meta": {
"model_id": "dlp",
"model_version": "dlp-2026.05",
"processing_time_ms": 12.4,
"request_id": "...",
"quota_remaining": 99997
}
}
```
## 2. 엔드포인트
| Method | Path | 인증 | 설명 |
|---|---|:-:|---|
| GET | `/v1/dlp/version` | – | 모델 버전·릴리스 노트 |
| GET | `/v1/dlp/grades` | – | 6등급 카탈로그 (한글 설명) |
| GET | `/v1/dlp/types` | – | 11 유형 카탈로그 |
| POST | `/v1/dlp/classify` | ✓ | 단건 등급·유형 분류 (자동 단계 전환) |
| POST | `/v1/dlp/batch` | ✓ | 일괄 분류 (1-100 문서, 메일 첨부·업로드 점검용) |
| GET | `/v1/dlp/history` | ✓ | 본문 미저장 분류 이력 |
| GET | `/v1/dlp/audit` | ✓ | 본문 저장 감사 로그 (audit 모드 활성화 후의 요청만) |
### 2.1 POST `/v1/dlp/classify`
**Request**:
```json
{
"text": "분류할 문서 텍스트 (1 ~ 32,768자)",
"force_t3": false,
"allow_escalate": true,
"return_text": false,
"apply_policy": false
}
```
`force_t3` (기본 false) — 빠른 분류기의 신뢰도와 무관하게 깊은 추론기를 강제 호출. 정확도 우선 케이스에 사용.
`allow_escalate` (기본 true) — false 면 빠른 분류기 결과만 사용 (응답 시간 우선).
`return_text` (기본 false) — 입력 본문을 응답에 echo 할지 여부. 운영 트래픽에서는 false 권장.
`apply_policy` (기본 false) — true 시 조직·테넌트의 DLP 정책 (차단 등급 / 차단 유형) 을 적용해 응답
`meta.policy_applied=true` 와 `meta.policy_decision` (`"block"` / `"allow"`) 을 반환. 정책 우선순위는
[tenants 문서 §3](/docs/tenants#3-정책-resolve-순서-호출-시점) 참조. 분류 자체는 정책 영향 없이 수행되며,
판정만 정책에 따라 달라져요.
**Response 필드**:
- `grade` — 6등급 중 하나 (라벨, 영문 식별자)
- `grade_ko` — 한글 등급명
- `types` — 검출된 유형 라벨 배열 (0~N개)
- `types_ko` — 한글 유형명 배열
- `tier_used` — `"t2_1"` (빠른 분류기) 또는 `"t3"` (깊은 추론기)
- `escalated` — 깊은 추론기까지 갔는지 여부
- `confidence` — 최종 등급 신뢰도 [0,1]
- `grade_probs` — 등급별 확률 분포 (빠른 분류기) · 깊은 추론기 결과만 반환된 경우 `null`
- `t2_1_grade` — 깊은 추론기로 보강된 경우 원래 빠른 분류기의 등급 (참고용)
- `meta.policy_applied` — 요청에 `apply_policy=true` 를 보냈는지 (false 면 항상 false)
- `meta.policy_decision` — `"block"` 또는 `"allow"` (apply_policy=true 일 때만 채워짐, 그 외 `null`)
### 2.2 POST `/v1/dlp/batch`
메일 첨부 일괄 점검·업로드 폴더 사전 검사용. 1-100 문서를 한 번에 분류.
**Request**:
```json
{
"texts": ["문서1", "문서2", "..."],
"force_t3": false,
"allow_escalate": true,
"return_text": false,
"apply_policy": false
}
```
- `texts` (필수) — 분류할 문서 텍스트 배열 (1-100). 각 항목 1-32,768자.
- `force_t3` (기본 false) — 모든 문서 강제 2단계 추론. 정확도 우선.
- `allow_escalate` (기본 true) — false 면 모든 문서 1단계 분류기만. 응답 시간 우선.
- `return_text` (기본 false) — 응답에 입력 본문 echo 여부.
- `apply_policy` (기본 false) — true 시 조직·테넌트의 DLP 차단 정책을 배치 전체에 동일 적용.
각 항목 응답에 `meta.policy_applied=true` 와 `meta.policy_decision` (`"block"` / `"allow"`)
채워져요. 정책 1회 resolve 후 항목마다 판정만 fan-out.
**Response**: `results` 배열 + 공통 `meta`. 각 항목은 단건 `classify` 응답과 동일 구조 (`grade`, `tier_used`, `escalated`, `confidence`, `t2_1_grade`, `meta.policy_*`).
배치 N 개는 RPM·월 한도 모두 N 건으로 차감.
### 2.3 GET `/v1/dlp/history`
본문 미저장 분류 이력. 본문은 저장되지 않으며, 결과(등급·유형·tier·신뢰도)와 길이만 반환해요.
```bash
curl "https://api.corepin.ai/v1/dlp/history?limit=50" \
-H "Authorization: Bearer $COREPIN_API_KEY"
```
응답 필드: `ts`, `request_id`, `text_length`, `summary.{grade, types, tier_used, escalated, confidence}`.
### 2.4 GET `/v1/dlp/audit`
본문 저장 감사 로그. **대시보드 → 설정** 에서 DLP 감사 모드를 `metadata` 또는 `full` 로 켠 이후의 요청만 적재돼요. `level=full` 인 경우에만 `input_text` 가 채워져요.
```bash
curl "https://api.corepin.ai/v1/dlp/audit?limit=50" \
-H "Authorization: Bearer $COREPIN_API_KEY"
```
쿼리 파라미터: `from_ts`, `to_ts` (unix epoch sec) · `blocked_only` (true/false) · `limit` (1 - 500, 기본 50) · `offset`. 응답 envelope은 `/v1/pii/audit` 와 동일 (`items[]` 의 `output` 만 DLP 응답 형태).
## 3. 6등급
낮은 등급(상)부터 높은 등급(하):
| 라벨 | 한글명 | 설명 |
|---|---|---|
| `PUBLIC` | 공개 | 외부 공개 가능. 마케팅 자료, 공식 보도자료 등 |
| `INTERNAL` | 사내 | 사내 한정. 일반 업무 자료 |
| `CONFIDENTIAL` | 대외비 | 제한된 인원 공유. 일반 사업 자료 |
| `RESTRICTED` | 제한 | 승인된 인원만. 인사·고객 정보 |
| `TRADE_SECRET` | 영업비밀 | 사내 핵심 비밀. M&A·R&D·전략 |
| `CLASSIFIED` | 기밀 | 최고 등급. 국가 기밀 또는 그에 준하는 정보 |
`GET /v1/dlp/grades` 에서 한글 설명까지 받아볼 수 있어요.
## 4. 11 유형
| 라벨 | 한글명 |
|---|---|
| `CONTRACT` | 계약서 |
| `FINANCIAL` | 재무 |
| `M_AND_A` | 인수합병 |
| `HR` | 인사 |
| `LEGAL` | 법무 |
| `RND_IP` | 연구·지식재산 |
| `STRATEGY` | 전략 |
| `CUSTOMER` | 고객 |
| `SECURITY` | 보안 |
| `PROCUREMENT` | 구매·조달 |
| `PUBLIC_CLASSIFIED` | 공개·기밀혼합 |
한 문서에 0~N 개 유형이 부착될 수 있어요.
## 5. 자동 보강 동작
문서가 들어오면 빠른 분류기(약 10ms)가 먼저 분류해요. 신뢰도가 임계값 미만이면 자동으로 깊은 추론기(약 5s)가 호출돼요. 통계상 약 85% 가 빠른 분류기 단독 처리, 15% 만 깊은 추론기까지 가요.
| 케이스 | 동작 |
|---|---|
| `confidence ≥ 0.85` | 빠른 분류기 결과 그대로 반환. `escalated=false` |
| `confidence < 0.85` | 깊은 추론기 호출. `tier_used="t3"`, `escalated=true`, `t2_1_grade` 에 원래 등급 보존 |
| `force_t3=true` | 빠른 분류기의 신뢰도와 무관하게 깊은 추론기 호출 |
| `allow_escalate=false` | 빠른 분류기 결과 강제 사용. 응답 시간 우선 케이스 |
## 6. N2SF (국가 망 보안체계) 매핑
국정원 N2SF의 정보 등급 분류 기준에 맞춰 6 등급을 정렬해뒀어요. 가이드라인의 `대외비` 가 우리 모델의 `CONFIDENTIAL`, `영업비밀` 이 `TRADE_SECRET`, `기밀` 이 `CLASSIFIED` 와 1:1 대응돼요. 사내 ISMS와의 연동은 `grade` 필드를 그대로 매핑해 사용하시면 돼요.
## 7. 변경 이력
- **dlp-2026.05** — 빠른 분류기. 한국 금융·기업 사내 문서 합성 셋(600 - 1,700자). 등급 정확도 91.0% · 중요정보 차단 99.7% · 잘못 등급 올림 0.2%.
- **깊은 추론기** — 빠른 분류기 신뢰도 부족 시만 호출. 등급 정확도 98.9% · 중요정보 차단 99.9%.
## 7.5 단가
- 무료: 60회/분 · 1,000회/월 · 카드 등록 불필요
- 유료: **₩50/호출** (T-3 자동 보강 추가 요금 없음, 텍스트 길이 무관 단일가)
- 연간 대량 계약 할인 가능 — <support@corepin.ai>
- 전체 요금 비교는 [`/pricing`](/pricing) 또는 [`/docs/billing`](/docs/billing)
## 8. 코드 예제
### Python
```python
import requests, os
r = requests.post(
"https://api.corepin.ai/v1/dlp/classify",
headers={"Authorization": f"Bearer {os.environ['COREPIN_API_KEY']}"},
json={"text": "본 인수합병은 공시 전 사내 보고용 자료입니다."},
timeout=30,
)
r.raise_for_status()
out = r.json()
print(out["grade_ko"], "/", out["types_ko"])
# 영업비밀 / ['인수합병']
```
### JavaScript / TypeScript
```ts
const r = await fetch(`${BASE}/v1/dlp/classify`, {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.COREPIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ text }),
});
const { grade, grade_ko, types, types_ko, tier_used, confidence } = await r.json();
```