| **Code** | **Description** |
| --- | --- |
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |
| `3` | Network error |
| `4` | Authentication failed |
| `5` | Permission denied |
| `6` | Resource not found |
| `7` | Operation timeout |
| `8` | Rate limit exceeded |
| `9` | Internal server error |

### Usage Examples

```bash
# Basic scan
./tool --target example.com

# Scan with custom port
./tool --target example.com --port 8080

# Verbose output
./tool --target example.com -v

target: example.com
port: 443
timeout: 30
verbose: false

git clone https://github.com/example/tool.git
cd tool
pip install -r requirements.txt

모델에 도달하기 전에 검색된 컨텍스트를 스캔합니다:```python
res = shield.protect(user_prompt, my_llm, context=retrieved_docs)
if res.action == "block":
    ...   # a poisoned document was caught before the model saw it

로깅에 결정을 한 번 연결하면 모든 호출이 기록됩니다:```python
from reasongate import Shield, log_sink, file_sink

shield = Shield(audit_hook=log_sink)                    # -> "reasongate.audit" logger
shield = Shield(audit_hook=file_sink("audit.jsonl"))    # -> JSON-Lines, SIEM-ready

- Shield off, poisoned record: 레코드가 공격자에게 이메일로 전송되고 전송이 실행된다.
  이는 디스크에 기록되는 실제 부작용이다.
- Shield on, poisoned record: 간접 스캔이 모델이 호출되기 전에 페이로드를 잡아낸다. 부작용 없음.
- Shield on, clean record: 에이전트가 정상적으로 응답한다.
- Shield on, **reworded** attack: 페이로드가 평범한 업무 메모로 바꿔 표현되어 시그니처
  계층이 이를 *매칭하지 못한다* — 그런데도 부작용은 발생하지 않는다. 왜냐하면 액션
  게이트(아래)가 도구 호출을 차단하기 때문이다. 그 목적지(유출 주소, 계정)가 신뢰할 수
  없는 콘텐츠에서 인용된 것이며, 이는 어떤 재표현으로도 숨길 수 없다.

각 계층이 무엇을 하는지 분명히 하자. 시그니처 매칭에는 실제 한계가 있다. 주입을
재표현하여 더 이상 알려진 패턴과 매칭되지 않게 하면 규칙 코어는 이를 잡지 못한다 —
그래서 코어는 경계가 아니라 첫 번째 필터인 것이다. 네 번째 실행이 그 한계에 대한
정직한 답이다. 탐지가 개선된 척하지 않으며, 탐지는 여전히 재표현된 공격을 놓친다.
침해를 막는 것은 텍스트의 표현이 아니라 액션 뒤에 있는 데이터의 신뢰를 추론하는
*다른* 계층이다. 네 가지 조건 모두 CI 불변식으로 강제되므로 데모가 조용히 퇴행할 수
없다.

라이브 플레이그라운드도 있다: <https://reasongate-demo-nvgo.onrender.com>. 제로 의존성
코어를 실행하며 API 키가 필요 없고 서버 밖으로 데이터를 전송하지 않는다.

## 코어의 탐지기

- **정규화 / 난독화 해제.** 제로 폭 문자, 키릴 문자 동형이의어, 리트스피크(`1gn0re`),
  띄어쓰기 및 점으로 구분된 문자(`i.g.n.o.r.e`), base64 페이로드를 제거하여, 위장된
  알려진 표현이 패턴 계층이 매칭할 수 있는 형태로 정규화되도록 한다.
- **주입 / 탈옥 패턴.** 알려진 표현에 대한 규칙 계층.
- **간접 주입.** 검색된 문서와 도구 출력이 모델에 도달하기 전에 동일한 스캔을 실행한다.
- **출력 유출 및 카나리.** 나가는 방향에서 시크릿과 PII를 표시한다. 시스템 프롬프트에
  심어둔 카나리 토큰은 시스템 프롬프트 유출을 추측이 아니라 입증 가능하게 만든다.

정책 엔진은 이러한 신호들을 보정된 noisy-OR로 융합하므로, 여러 약한 신호가 합쳐져
차단에 이를 수 있지만 정상 프롬프트에서 나온 고립된 노이즈는 그렇게 되지 않는다.

## 액션 게이트 (에이전트 도구 호출)

탐지기는 "이 텍스트가 주입인가?"라고 묻는다 — 재표현으로 잃을 수 있는 질문이다. 액션
게이트는 표현과 무관한 다른 질문을 던진다: *이 액션을 생성한 데이터의 신뢰를 고려할 때,
이 액션이 진행되어도 되는가?* 이것은 간접 주입에 대한 능력 기반 방어로, 신뢰할 수 없는
콘텐츠, 민감한 능력, 그리고 빠져나갈 길이라는 "치명적 삼중주"를 깨뜨리며, 시그니처
계층이 놓치는 재표현된 공격을 잡아낸다.```python
from reasongate import ToolGate, ToolPolicy, Segment

gate = ToolGate([
    ToolPolicy("transfer_funds", sensitive=True, destination_args=("to_account",)),
    ToolPolicy("send_email",     sensitive=True, destination_args=("to",)),
])

record = Segment(text=retrieved_doc, source="crm", trust="untrusted")
decision = gate.authorize(
    {"name": "transfer_funds", "args": {"to_account": "9900", "amount": "$84,200"}},
    context=[record],
)
decision.allowed       # False — the destination account is quoted from untrusted content
print(decision.explain())

Authorization은 오염된 목적지를 세탁하지 않는다: `authorized=True`는 공동 존재(co-presence)를 해제하는데, 이는 주체가 그 행동을 요청했기 때문이다 — 그러나 신뢰할 수 없는 콘텐츠로부터 유래한 인자 값은 해제하지 않는데, 이는 주체가 그것을 선택하지 않았기 때문이다.

### 기존 에이전트에 연결하기```python
from reasongate.adapters.toolcalls import from_anthropic, refusal_result
from reasongate.catalog import infer_policies, describe

print(describe(infer_policies([t["name"] for t in tools])))   # draft policies, then correct them

for call in from_anthropic(response.content):
    decision = session.authorize(call)
    if not decision.allowed:
        results.append(refusal_result(call, decision))        # the model is told why
    else:
        results.append(run(call))

**이 패키지에는 모델 판정기가 포함되어 있지 않습니다.** 문장이 산문 정책과 충돌하는지 판단하려면 모델이 필요합니다. 설정하지 않으면 게이트는 허용 대신 *"평가되지 않음"* 을 반환합니다. 검사되지 않은 요청이 승인된 것처럼 보여서는 안 되기 때문입니다. 모델 판정기 자체도 인젝션 대상이며, 이는 권고 사항입니다. 논쟁의 여지가 없는 계층은 `ToolGate`로, 에이전트가 *할 수 있는* 행동을 제한합니다.

### AgentDojo에서 측정

이 게이트는 이 위협을 위해 만들어진 벤치마크에서 자체적인 수치를 갖게 되었습니다 ([AgentDojo](https://github.com/ethz-spylab/agentdojo): 에이전트가 읽는 데이터를 통해 공격받는 네 개의 도구 사용 에이전트 스위트). 루프에 모델이 없습니다. 벤치마크 자체의 정답 도구 시퀀스가 완전히 하이재킹된 에이전트로서 게이트를 통해 재생되고, AgentDojo 자체의 검사기가 결과를 채점합니다:

| | 공격 성공률 | 정상 트래픽에서의 유용성 |
|---|---:|---:|
| 게이트 없음 | 97.4% | 100% |
| 인자 오염만 | **12.6%** | 64.9% |
| 엄격 (동시 존재) | 3.4% | 41.2% |

루프에 모델이 있는 경우 (Claude Haiku 4.5, 뱅킹) 그림은 더욱 선명합니다. 모델이 스스로 모든 인젝션을 거부했으므로 게이트는 보안을 추가하지 못했고 유용성 12.5포인트를 비용으로 치렀습니다. 모델의 판단이 실패하는 경우에 대한 보험, 그 대가입니다. 두 열을 모두 읽으십시오. 게이트가 치르는 35포인트의 유용성은 에이전트가 상점에서 읽은 합법적인 목적지입니다. 지불하라는 청구서에 적힌 IBAN으로, 오염은 같은 파일에 있는 공격자의 IBAN과 구분할 수 없습니다. 단어를 보지 않기 때문입니다. 통과하는 것은 문서화된 세 가지 형태입니다: 읽기인 목표, 인용되지 않고 조회된 목적지, 그리고 목적지가 아닌 필드에 있는 피해. 방법, 스위트별 수치, 주의사항: [RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo).

이 계층 뒤의 추론 — 위협 모델, 텍스트 탐지가 구조적으로 불충분한 이유, 그리고 게이트의 보장 *과 비보장* — 은 [docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md)에 작성되어 있습니다. 여전히 놓치는 것, 실제 코퍼스에서 측정하고 인용한 것은 [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md)에 있습니다.

## 벤치마크

전체 방법론, 하네스, 부정적 결과는 [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md)에 있습니다. 함께 읽을 가치가 있는 세 가지 수치: 과잉 차단하는 것, 포착하는 것, 그리고 요청당 비용.

**과잉 방어.** 많은 가드가 *ignore*, *system*, *bypass* 같은 트리거 단어를 포함하기만 한 무해한 프롬프트를 과잉 차단합니다. [NotInject](https://huggingface.co/datasets/leolee99/NotInject) (339개의 무해하지만 트리거 단어가 많은 프롬프트)에서 규칙 코어는 **0.0% 오탐률**과 오프라인 100% 무해 정확도를 보입니다.

**알려진 패턴에 대한 회피 재현율.** 알려진 공격이 난독화되면 정규화가 대부분을 복구합니다:

| | 회피 하에서의 재현율 | FPR | F1 |
|---|---:|---:|---:|
| 정규식만 | 21.2% | 3.3% | 0.349 |
| 코어 (정규화 + 간접) | 78.1% | 6.7% | 0.871 |

이것은 *코어가 이미 알고 있는 패턴의 난독화 변형*에 대한 재현율입니다. 새로운 표현에 대한 재현율이 아닙니다. 그것은 위에서 언급한 0% 수치입니다.

**요청당 비용.** `eval/latency.py`로 측정 (호출 경로별 p50/p95, Apple M3 Pro):

| 입력 | p50 | p95 |
|---|---:|---:|
| 채팅 프롬프트 (60자) | 0.178 ms | 0.202 ms |
| 2 KB 문서, 정상 | 8.51 ms | 8.94 ms |
| 50 KB 문서, 정상 (입력 상한) | 211 ms | 216 ms |
| `ToolGate.authorize` (도구 호출, 크기 무관) | 0.020 ms | 0.021 ms |

하나의 프로세스가 초당 약 5,400개의 채팅 프롬프트를 처리하며 코어는 상태를 유지하지 않으므로 프로세스에 따라 확장됩니다. 배포 전에 알아둘 가치가 있는 부분: **입력 경로는 입력 길이에 선형입니다 — 정상 문서의 경우 KB당 약 4.2 ms, 패턴이 이미 일치한 경우 1.7 ms.** 채팅 크기에서는 모델 기반 가드 (ProtectAI deberta-v3, 약 116 ms)보다 약 650배 저렴합니다. 50 KB에서는 *더 나쁩니다*. 트랜스포머는 512 토큰에서 잘리지만 우리는 모든 것을 스캔하기 때문입니다. 교차점은 약 25 KB입니다 — 전체 문서를 게이트하면 그 비용을 치릅니다. 액션 게이트는 이 속성이 없습니다. 도구 인자와 세그먼트 신뢰를 읽지, 산문을 읽지 않으므로 어떤 크기에서도 무료입니다.

**ML 탐지기 (별도 애드온).** 임베딩 기반 분류기가 규칙 코어가 처리할 수 없는 자연스러운 표현의 공격을 처리합니다. 이것은 코어가 아닌 탐지기의 수치입니다:

| 설정 | 재현율 | FPR | F1 |
|---|---:|---:|---:|
| 홀드아웃 테스트 (약 5.5k, 결합 실제 데이터) | 96.1% | 0.3% | 0.978 |
| 5겹 교차 검증 | 95.5% ± 0.8 | 2.5% ± 1.3 | 0.963 ± 0.010 |
| 분포 외 (A+B 학습, 미학습 C 테스트) | 87.6% | 10.9% | 0.882 |

데이터: `deepset/prompt-injections`, `jackhhao/jailbreak-classification`, `xTRam1/safe-guard-prompt-injection`. 언급할 가치가 있는 하나의 부정적 결과: 합성 데이터로 학습된 초기 모델은 0.98 F1을 기록했지만, 절제 실험에서 구두점과 대소문자만으로 0.96에 도달했습니다 — 점수는 데이터 생성기의 인공물이었습니다. 설명 가능한 분류기가 그것을 드러냈습니다. 분포 외 하락 0.97에서 0.88이 실제 일반화 수치입니다: 저하되지만 붕괴하지는 않습니다.

이 중 어느 것이든 재현하십시오 — 각 스크립트가 실제로 필요로 하는 것에 따라 그룹화되어 있습니다. 0.2.0 이후로 학습된 모델은 애드온에 있고 규칙 코어 벤치마크만 이 저장소 단독으로 실행되기 때문입니다:```bash
# Offline, no key, no add-on — runs against this repo as-is:
python eval/public_bench.py     # over-defense on NotInject (339 benign)
python eval/adversarial.py      # evasion robustness of the rule core
python eval/latency.py          # cost per request: p50/p95/p99 and throughput

# Needs `pip install reasongate[eval]` and a VOYAGE_API_KEY (embeddings):
python eval/pipeline_real.py    # train/val/test with a validation-tuned threshold
python eval/validate.py         # leakage check, trivial baselines, 5-fold CV, 5x2cv

# Needs the enterprise add-on (the trained model moved there in 0.2.0):
python eval/ood_test.py         # out-of-distribution generalization
python eval/head_to_head.py     # vs ProtectAI deberta-v3

# Needs `pip install agentdojo` (Python 3.10+), no key — the action gate on AgentDojo:
python eval/agentdojo_gate.py   # ASR and utility, gate off / taint / strict