응답 형식 - Starfort

성공적인 호출은 최상위 action과 콘텐츠 파트별 분석 결과인 input_results를 포함한 HTTP 200을 반환합니다. Starfort는 Guardian의 응답 본문을 그대로 반환합니다 — 래퍼나 필드 재구성이 없습니다.

action 모델

중간 상태는 정책 타입에 따라 다릅니다:

PII 정책은 PASS / MASK / BLOCK을 반환합니다.
Topic 정책은 PASS / CHECK / BLOCK을 반환하며, **CHECK**는 검토가 필요한 controversial 주제로 표시합니다.

API 호출자는 CHECK를 그대로 수신합니다 — CHECK를 PASS로 시행하는 Desktop Agent 및 Proxy Server와 달리 그렇습니다. 루트 action은 탐지된 모든 항목 중 가장 높은 심각도입니다: BLOCK > MASK > CHECK > PASS. Actions를 참고하세요.

최상위

필드	타입	설명
`action`	string	`PASS` \| `MASK` \| `BLOCK` — 모든 결과 중 가장 높은 심각도입니다.
`input_results`	array	검사된 콘텐츠 파트당 하나의 항목입니다. 검사된 것이 없으면 비어 있습니다.

각 input_results[] 항목:

필드	설명
`index`	`messages[].content` 내 콘텐츠 파트의 위치입니다.
`type`	`text`, `image`, `audio`, `video`, `document`, `archive`.
`identifier`	파일 파트의 경우 파일 이름. 그 외에는 `null`.
`action`	해당 파트의 action입니다.
`processed_content`	`MASK`일 때: 마스킹된 텍스트. `PASS`/`BLOCK`일 때: `null`.
`processed_content_type`	`processed_content`가 있을 때 그 MIME 타입입니다.
`results`	정책별 결과입니다(아래 참고).

MASK 예시 (PII)

{
  "action": "MASK",
  "input_results": [{
    "index": 0, "type": "text", "identifier": null, "action": "MASK",
    "processed_content": "제 번호는 [PHONE_NUMBER_1] 이고 이메일은 [EMAIL_1] 입니다.",
    "processed_content_type": "text",
    "results": [{
      "policy_name": "PII Masking Policy", "policy_type": "PII", "action": "MASK",
      "detected_items": [
        { "rule_type": "regex", "rule_id": 15, "rule_name": "phone_number:_korea_mobile_all_separators",
          "action": "MASK", "confidence": 1, "mask_word": "PHONE_NUMBER_1",
          "matched_text": "010-2543-2513", "alert_message": "휴대전화번호 감지됨" },
        { "rule_type": "regex", "rule_id": 18, "rule_name": "email:_email_address",
          "action": "MASK", "confidence": 1, "mask_word": "EMAIL_1",
          "matched_text": "jane@acme.co.kr", "alert_message": "이메일 주소 감지됨" }
      ]
    }]
  }]
}

마스킹 토큰 형식: [<MASK_WORD>_<n>], 발생 순서대로 번호가 매겨집니다([PHONE_NUMBER_1], [PHONE_NUMBER_2], …).

BLOCK 예시 (Topic)

{
  "action": "BLOCK",
  "input_results": [{
    "index": 0, "type": "text", "identifier": null, "action": "BLOCK",
    "processed_content": null, "processed_content_type": null,
    "results": [{
      "policy_name": "Topic Policy", "policy_type": "TOPIC", "action": "BLOCK",
      "detected_items": [
        { "rule_id": "WPN", "rule_name": "무기", "action": "BLOCK",
          "confidence": 1, "classification": "unsafe", "alert_message": "…" }
      ]
    }]
  }]
}

`detected_items` — PII vs. Topic

필드는 정책 타입에 따라 다릅니다:

필드	PII	Topic
`rule_type`	`ner` \| `regex` \| `keyword`	—
`rule_id`	정수	문자열 토픽 코드(예: `WPN`)
`rule_name`	규칙 이름	토픽 제목
`classification`	—	`safe`(→ PASS) \| `controversial`(→ CHECK) \| `unsafe`(→ BLOCK)
`mask_word`	존재함(MASK)	—
`matched_text`	일치한 구간	—
`action`, `confidence`, `alert_message`	예	예

최상위 action을 먼저 읽으세요. MASK일 때는 원본 대신 processed_content를 전달하세요. BLOCK일 때는 모델을 호출하지 마세요. Actions를 참고하세요.

`PASS`는 항상 “분석 완료, 아무것도 탐지되지 않음”을 의미합니다

results가 비어 있는 PASS는 결코 모호하지 않습니다: 이는 Guardian이 분석을 완료했고 아무것도 발견하지 못했음을 의미하며, 분석에 실패했다는 뜻이 아닙니다. Guardian이 분석할 수 없는 요청은 열화된 200이 아니라 HTTP 오류를 반환하므로(Guardian fail-closed), 실패가 깨끗한 결과로 오인될 수 없습니다. 오류 및 상태를 참고하세요.

​action 모델

​최상위

​MASK 예시 (PII)

​BLOCK 예시 (Topic)

​detected_items — PII vs. Topic

​PASS는 항상 “분석 완료, 아무것도 탐지되지 않음”을 의미합니다

action 모델

최상위

MASK 예시 (PII)

BLOCK 예시 (Topic)

`detected_items` — PII vs. Topic

`PASS`는 항상 “분석 완료, 아무것도 탐지되지 않음”을 의미합니다