agentproof-scan 0.1.2__tar.gz → 0.1.3__tar.gz

{agentproof_scan-0.1.2/agentproof_scan.egg-info → agentproof_scan-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproof-scan
-Version: 0.1.2
+Version: 0.1.3
 Summary: CLI security scanner: probes AI-agent HTTP endpoints for secret/prompt leakage, with CI-gating exit codes.
 Author: AgentProof
 License-Expression: Apache-2.0
@@ -52,6 +52,49 @@ you can read the code and reproduce every number yourself.
 
 ---
 
+## 📦 Prerequisites
+
+If this is your first command-line tool, **the hard part is installing Python, not
+installing this.** People get stuck there. That step isn't part of this tool, and it's
+a normal place to get stuck.
+
+**1. Check that you have Python 3.9 or newer.** One of these three works; which one
+tells you how Python was installed on your machine:
+
+```
+python  --version
+python3 --version
+py -3   --version
+```
+
+**2. Install, and put your key in a `.env` file** in the folder you'll run from.
+Every command below carries a label saying whether *we actually ran it*:
+
+| Shell | Commands | Source |
+|---|---|---|
+| bash / zsh | `pip install agentproof-scan`<br>`echo 'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env` | **VERIFIED** — 9 Linux-container cells (Python 3.9/3.11/3.13 × venv/system/pipx, live PyPI install) |
+| PowerShell 5.1 | `pip install agentproof-scan`<br>`'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' \| Out-File -Encoding utf8 .env` | **UNTESTED** — works or not, [open an issue](https://github.com/ghkfuddl1327-wq/agentproof/issues) |
+| pwsh 7 | `pip install agentproof-scan`<br>`'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env` | **UNTESTED** — same |
+| cmd.exe | `pip install agentproof-scan`<br>`echo GEMINI_API_KEY=PASTE_YOUR_KEY_HERE> .env` | **UNTESTED** — same |
+
+Get a free Gemini key at <https://aistudio.google.com/apikey>. `.env` is read from the
+directory you run in, and is gitignored — never commit it.
+
+**3. If something isn't found:**
+
+| Symptom | Try |
+|---|---|
+| `pip: command not found` | `python -m pip install agentproof-scan` |
+| `agentproof-scan: command not found` | `python -m agentproof_scan` (same tool, same flags) |
+
+> **On `.env` encoding.** `0.1.3` reads `.env` files written as UTF-8, UTF-8 with BOM,
+> and **UTF-16LE with BOM** (what PowerShell 5.1's `>` produces), and it strips stray
+> quotes that `cmd.exe` leaves around the *key name*. That is a claim about **bytes**,
+> tested byte-for-byte. It is **not** a claim that the tool passes on Windows — see
+> [Verification scope](#verification-scope).
+
+---
+
 ## 🚀 60-second Quick Start (no setup knowledge — just copy-paste)
 
 `agentproof-scan` ships with a built-in **victim demo**: an intentionally leaky agent
@@ -72,7 +115,13 @@ agentproof-scan --stability 5    # repeat 5× — more reliable (see note below)
 
 A JSON report prints. If the demo leaked, you'll see a `leak_count` of 1 or more.
 
-> ⚠️ **Seeing all zeros?** First check that `GEMINI_API_KEY` is actually set. A missing key would otherwise produce a misleading `0` — meaning *"the scan didn't run,"* not *"your agent is safe."* The scanner now stops loudly with a clear error when the key is missing, so all-zeros should be rare — but if you ever see it, verify the key first.
+> ⚠️ **A zero you can trust.** Up to `0.1.2` a scan that never reached your agent — bad
+> key, HTTP 500, timeout — still printed `leak_count: 0` and exited `0`. It read as
+> *"your agent is safe"* when it meant *"we couldn't ask."* From `0.1.3` the scanner
+> **refuses to report clean** unless every probe actually got an answer: it exits `1`
+> and prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` on stderr. A leak it *did*
+> find is still reported — a partial scan may not claim clean, but it may claim what it
+> found.
 
 > **Why `--stability 5`?** A single run is non-deterministic — a leaky agent can still answer "safely" on any one try, so a one-shot scan might read `0` by luck. Repeating (e.g. `--stability 5`) measures *how often* it leaks (`leak_rate`) and is the reliable way to read the verdict.
 
@@ -270,6 +319,91 @@ If your agent leaks a secret, `--fail-on-findings` exits non-zero and the check
 red. By default it fails on **leaked secrets only** (not softer prompt-disclosure
 signals); add `--fail-on any` to gate on those too. Scan only agents you own.
 
+**Exit codes** — three states, never two:
+
+| Code | Meaning | When |
+|---|---|---|
+| `0` | Clean | Every probe reached your agent, nothing leaked |
+| `1` | **The scan did not run** | Missing/placeholder key, HTTP error, timeout, bad flag. Never means "safe". Prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` to stderr |
+| `2` | Findings | The agent leaked (requires `--fail-on-findings`) |
+
+`1` and `2` are different on purpose: a build that fails because *nobody could ask the
+agent* must not be read as *the agent leaked*, and neither may be read as *safe*.
+
+> **This table was not true before `0.1.3`.** It was written as documentation of intent,
+> but the code never matched it: an invalid CLI flag exited `2` (argparse's default),
+> which a CI gate reads as *"your agent leaked a secret."* And a scan that never reached
+> the agent exited `0`, which reads as *"safe."* Both are fixed in `0.1.3`. Changing the
+> flag error from `2` to `1` is not a change to the contract — it is the first release in
+> which the contract is true. Every non-zero exit now also prints
+> `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` (`missing_env`, `placeholder_key`,
+> `http_status`, `timeout`, `nonzero_exit`, `missing_url`, `auth_missing_env`,
+> `usage_error`, …) so CI can tell *which* guard fired. The exit code is the contract;
+> the slug is the evidence.
+
+---
+
+## Verification scope
+
+All test data in this repository comes from **Linux containers**.
+
+**Verified** — 9 cells, live PyPI install (not local build):
+Python 3.9 / 3.11 / 3.13 × venv / system / pipx
+
+**Not verified:**
+
+| Environment | Status |
+|---|---|
+| Windows (PowerShell 5.1 / pwsh 7 / cmd) | Not verified. CI coverage planned. |
+| macOS | Not verified. CI coverage planned. |
+| Linux, installed on host (not container) | Not verified. |
+| GitHub Codespaces, as a new user | Not verified. We develop there; we have never walked the first-run path. |
+| Python installation itself (PATH, python.org / MS Store / pyenv) | **Cannot be covered by CI.** Runners ship with Python pre-installed. |
+
+The last row will not be closed by automation. If you hit friction installing
+Python itself, an issue is the only way that row changes.
+
+`0.1.3` handles UTF-16LE+BOM `.env` files (byte-level test).
+This is **not** a claim that the tool passes on Windows PowerShell 5.1.
+It is a claim about the bytes.
+
+---
+
+## If you don't have Python
+
+GitHub Codespaces gives you a Linux container in the browser.
+Requires only a GitHub account. No local Python installation.
+
+```bash
+pip install agentproof-scan
+```
+
+⚠ **Before you do this, read the next section.**
+Codespaces is not verified as a new-user path (see table above),
+and running this tool means putting a provider API key into a cloud VM.
+
+---
+
+## Handling your API key ⚠
+
+This tool needs a live provider key to call your agent.
+Wherever you run it, that key is exposed to that environment.
+
+- Use a **scoped, low-quota, disposable key**. Not your production key.
+- Set a hard spend cap before you start. Budget *alerts* are not caps.
+- **Revoke the key when you are done.**
+- In Codespaces: use a Codespaces secret, not a committed `.env`.
+  Never commit `.env`. It is gitignored — do not override that.
+- If you fork this repo, your fork's Codespace inherits nothing of ours.
+  Your key is yours to manage.
+
+A Codespaces secret arrives as an environment variable, and a real environment
+variable always beats a `.env` file — so the scanner runs with no `.env` at all.
+
+This tool detects leaks. It does not prevent them.
+Scoping, rate limits, and hard spend caps do that. See
+[What it catches — and what it doesn't](#what-it-catches--and-what-it-doesnt-plainly).
+
 ---
 
 ## ❓ Stuck? (no experience needed — your escape hatch)
@@ -293,7 +427,7 @@ Early work in progress. This tool grew out of red-team probing experiments and i
 **Known limitation:** a present-but-invalid key (wrong or expired) can still produce a `0` — detecting invalid keys from API-error responses is a planned follow-up.
 
 **Not yet in this release:** wider credential-type coverage (Stripe, Slack, JWT, PEM,
-SendGrid, Twilio, npm, …) is implemented and tested, but `0.1.2` ships only the six
+SendGrid, Twilio, npm, …) is implemented and tested, but `0.1.3` ships only the six
 families listed under [What it catches](#what-it-catches--and-what-it-doesnt-plainly).
 It lands in a later release rather than being advertised here before you can run it.
 
@@ -353,7 +487,7 @@ into a wall of text.
 ## What it catches — and what it doesn't (plainly)
 
 **It catches:** a set list of credential types, matched by their shape. As of
-`0.1.2` that's **six families** — OpenAI, Anthropic, Google, AWS, GitHub, and xAI.
+`0.1.3` that's **six families** — OpenAI, Anthropic, Google, AWS, GitHub, and xAI.
 Matching holds up whether the secret is in plain text or JSON, across different
 languages, and in the answer or the reasoning — for the types it knows.
 
@@ -363,7 +497,7 @@ and docs don't set off false alarms.
 
 **It doesn't catch:**
 - **Credential types outside those six** — Stripe, Slack, JWTs, PEM private keys,
-  SendGrid, Twilio, npm tokens and others are **not** matched in `0.1.2`. Broader
+  SendGrid, Twilio, npm tokens and others are **not** matched in `0.1.3`. Broader
   type coverage is built and tested but not yet released here (see Status).
 - **Secrets with no tell-tale prefix** — e.g. a database password buried in a
   `postgres://…` URL. A real limit of shape-matching.

{agentproof_scan-0.1.2 → agentproof_scan-0.1.3}/README.md

@@ -30,6 +30,49 @@ you can read the code and reproduce every number yourself.
 
 ---
 
+## 📦 Prerequisites
+
+If this is your first command-line tool, **the hard part is installing Python, not
+installing this.** People get stuck there. That step isn't part of this tool, and it's
+a normal place to get stuck.
+
+**1. Check that you have Python 3.9 or newer.** One of these three works; which one
+tells you how Python was installed on your machine:
+
+```
+python  --version
+python3 --version
+py -3   --version
+```
+
+**2. Install, and put your key in a `.env` file** in the folder you'll run from.
+Every command below carries a label saying whether *we actually ran it*:
+
+| Shell | Commands | Source |
+|---|---|---|
+| bash / zsh | `pip install agentproof-scan`<br>`echo 'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env` | **VERIFIED** — 9 Linux-container cells (Python 3.9/3.11/3.13 × venv/system/pipx, live PyPI install) |
+| PowerShell 5.1 | `pip install agentproof-scan`<br>`'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' \| Out-File -Encoding utf8 .env` | **UNTESTED** — works or not, [open an issue](https://github.com/ghkfuddl1327-wq/agentproof/issues) |
+| pwsh 7 | `pip install agentproof-scan`<br>`'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env` | **UNTESTED** — same |
+| cmd.exe | `pip install agentproof-scan`<br>`echo GEMINI_API_KEY=PASTE_YOUR_KEY_HERE> .env` | **UNTESTED** — same |
+
+Get a free Gemini key at <https://aistudio.google.com/apikey>. `.env` is read from the
+directory you run in, and is gitignored — never commit it.
+
+**3. If something isn't found:**
+
+| Symptom | Try |
+|---|---|
+| `pip: command not found` | `python -m pip install agentproof-scan` |
+| `agentproof-scan: command not found` | `python -m agentproof_scan` (same tool, same flags) |
+
+> **On `.env` encoding.** `0.1.3` reads `.env` files written as UTF-8, UTF-8 with BOM,
+> and **UTF-16LE with BOM** (what PowerShell 5.1's `>` produces), and it strips stray
+> quotes that `cmd.exe` leaves around the *key name*. That is a claim about **bytes**,
+> tested byte-for-byte. It is **not** a claim that the tool passes on Windows — see
+> [Verification scope](#verification-scope).
+
+---
+
 ## 🚀 60-second Quick Start (no setup knowledge — just copy-paste)
 
 `agentproof-scan` ships with a built-in **victim demo**: an intentionally leaky agent
@@ -50,7 +93,13 @@ agentproof-scan --stability 5    # repeat 5× — more reliable (see note below)
 
 A JSON report prints. If the demo leaked, you'll see a `leak_count` of 1 or more.
 
-> ⚠️ **Seeing all zeros?** First check that `GEMINI_API_KEY` is actually set. A missing key would otherwise produce a misleading `0` — meaning *"the scan didn't run,"* not *"your agent is safe."* The scanner now stops loudly with a clear error when the key is missing, so all-zeros should be rare — but if you ever see it, verify the key first.
+> ⚠️ **A zero you can trust.** Up to `0.1.2` a scan that never reached your agent — bad
+> key, HTTP 500, timeout — still printed `leak_count: 0` and exited `0`. It read as
+> *"your agent is safe"* when it meant *"we couldn't ask."* From `0.1.3` the scanner
+> **refuses to report clean** unless every probe actually got an answer: it exits `1`
+> and prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` on stderr. A leak it *did*
+> find is still reported — a partial scan may not claim clean, but it may claim what it
+> found.
 
 > **Why `--stability 5`?** A single run is non-deterministic — a leaky agent can still answer "safely" on any one try, so a one-shot scan might read `0` by luck. Repeating (e.g. `--stability 5`) measures *how often* it leaks (`leak_rate`) and is the reliable way to read the verdict.
 
@@ -248,6 +297,91 @@ If your agent leaks a secret, `--fail-on-findings` exits non-zero and the check
 red. By default it fails on **leaked secrets only** (not softer prompt-disclosure
 signals); add `--fail-on any` to gate on those too. Scan only agents you own.
 
+**Exit codes** — three states, never two:
+
+| Code | Meaning | When |
+|---|---|---|
+| `0` | Clean | Every probe reached your agent, nothing leaked |
+| `1` | **The scan did not run** | Missing/placeholder key, HTTP error, timeout, bad flag. Never means "safe". Prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` to stderr |
+| `2` | Findings | The agent leaked (requires `--fail-on-findings`) |
+
+`1` and `2` are different on purpose: a build that fails because *nobody could ask the
+agent* must not be read as *the agent leaked*, and neither may be read as *safe*.
+
+> **This table was not true before `0.1.3`.** It was written as documentation of intent,
+> but the code never matched it: an invalid CLI flag exited `2` (argparse's default),
+> which a CI gate reads as *"your agent leaked a secret."* And a scan that never reached
+> the agent exited `0`, which reads as *"safe."* Both are fixed in `0.1.3`. Changing the
+> flag error from `2` to `1` is not a change to the contract — it is the first release in
+> which the contract is true. Every non-zero exit now also prints
+> `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` (`missing_env`, `placeholder_key`,
+> `http_status`, `timeout`, `nonzero_exit`, `missing_url`, `auth_missing_env`,
+> `usage_error`, …) so CI can tell *which* guard fired. The exit code is the contract;
+> the slug is the evidence.
+
+---
+
+## Verification scope
+
+All test data in this repository comes from **Linux containers**.
+
+**Verified** — 9 cells, live PyPI install (not local build):
+Python 3.9 / 3.11 / 3.13 × venv / system / pipx
+
+**Not verified:**
+
+| Environment | Status |
+|---|---|
+| Windows (PowerShell 5.1 / pwsh 7 / cmd) | Not verified. CI coverage planned. |
+| macOS | Not verified. CI coverage planned. |
+| Linux, installed on host (not container) | Not verified. |
+| GitHub Codespaces, as a new user | Not verified. We develop there; we have never walked the first-run path. |
+| Python installation itself (PATH, python.org / MS Store / pyenv) | **Cannot be covered by CI.** Runners ship with Python pre-installed. |
+
+The last row will not be closed by automation. If you hit friction installing
+Python itself, an issue is the only way that row changes.
+
+`0.1.3` handles UTF-16LE+BOM `.env` files (byte-level test).
+This is **not** a claim that the tool passes on Windows PowerShell 5.1.
+It is a claim about the bytes.
+
+---
+
+## If you don't have Python
+
+GitHub Codespaces gives you a Linux container in the browser.
+Requires only a GitHub account. No local Python installation.
+
+```bash
+pip install agentproof-scan
+```
+
+⚠ **Before you do this, read the next section.**
+Codespaces is not verified as a new-user path (see table above),
+and running this tool means putting a provider API key into a cloud VM.
+
+---
+
+## Handling your API key ⚠
+
+This tool needs a live provider key to call your agent.
+Wherever you run it, that key is exposed to that environment.
+
+- Use a **scoped, low-quota, disposable key**. Not your production key.
+- Set a hard spend cap before you start. Budget *alerts* are not caps.
+- **Revoke the key when you are done.**
+- In Codespaces: use a Codespaces secret, not a committed `.env`.
+  Never commit `.env`. It is gitignored — do not override that.
+- If you fork this repo, your fork's Codespace inherits nothing of ours.
+  Your key is yours to manage.
+
+A Codespaces secret arrives as an environment variable, and a real environment
+variable always beats a `.env` file — so the scanner runs with no `.env` at all.
+
+This tool detects leaks. It does not prevent them.
+Scoping, rate limits, and hard spend caps do that. See
+[What it catches — and what it doesn't](#what-it-catches--and-what-it-doesnt-plainly).
+
 ---
 
 ## ❓ Stuck? (no experience needed — your escape hatch)
@@ -271,7 +405,7 @@ Early work in progress. This tool grew out of red-team probing experiments and i
 **Known limitation:** a present-but-invalid key (wrong or expired) can still produce a `0` — detecting invalid keys from API-error responses is a planned follow-up.
 
 **Not yet in this release:** wider credential-type coverage (Stripe, Slack, JWT, PEM,
-SendGrid, Twilio, npm, …) is implemented and tested, but `0.1.2` ships only the six
+SendGrid, Twilio, npm, …) is implemented and tested, but `0.1.3` ships only the six
 families listed under [What it catches](#what-it-catches--and-what-it-doesnt-plainly).
 It lands in a later release rather than being advertised here before you can run it.
 
@@ -331,7 +465,7 @@ into a wall of text.
 ## What it catches — and what it doesn't (plainly)
 
 **It catches:** a set list of credential types, matched by their shape. As of
-`0.1.2` that's **six families** — OpenAI, Anthropic, Google, AWS, GitHub, and xAI.
+`0.1.3` that's **six families** — OpenAI, Anthropic, Google, AWS, GitHub, and xAI.
 Matching holds up whether the secret is in plain text or JSON, across different
 languages, and in the answer or the reasoning — for the types it knows.
 
@@ -341,7 +475,7 @@ and docs don't set off false alarms.
 
 **It doesn't catch:**
 - **Credential types outside those six** — Stripe, Slack, JWTs, PEM private keys,
-  SendGrid, Twilio, npm tokens and others are **not** matched in `0.1.2`. Broader
+  SendGrid, Twilio, npm tokens and others are **not** matched in `0.1.3`. Broader
   type coverage is built and tested but not yet released here (see Status).
 - **Secrets with no tell-tale prefix** — e.g. a database password buried in a
   `postgres://…` URL. A real limit of shape-matching.

{agentproof_scan-0.1.2 → agentproof_scan-0.1.3}/agentproof_scan/__init__.py

@@ -3,4 +3,4 @@
 CLI 진입점은 콘솔 스크립트 `agentproof-scan`(= agentproof_scan.scan:main).
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

agentproof_scan-0.1.3/agentproof_scan/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m agentproof_scan` 진입점.
+
+콘솔 스크립트(`agentproof-scan`)가 PATH 에 안 잡히는 환경 — Windows 의 Scripts/ 디렉터리가
+PATH 에 없거나, pipx/venv 를 activate 하지 않은 경우 — 을 위한 탈출구다. 같은 main() 을 부른다.
+"""
+
+from .scan import main
+
+if __name__ == "__main__":
+    main()

agentproof_scan-0.1.3/agentproof_scan/adapters/__init__.py

@@ -0,0 +1,84 @@
+"""adapters — 스캐너가 다양한 타깃 에이전트를 동일 인터페이스로 검사하기 위한 어댑터 패키지.
+
+import 시 .env(KEY=VALUE)를 os.environ에 로드한다. 두 위치를 본다:
+  (1) 소스 트리 루트(개발 시 clone 루트) — 기존 동작 유지,
+  (2) 현재 작업 디렉터리 ./.env — pip 설치 후 사용자가 CLI 를 실행하는 곳.
+Claude Code의 Bash 셸은 사용자의 대화형 터미널 export를 상속하지 않으므로,
+키는 .env에 적어두면 어댑터가 환경변수로 읽어 쓴다(.env는 .gitignore 대상).
+설치판에서는 (1)이 site-packages 내부라 무의미 → (2)가 실제 동작 경로다.
+"""
+
+import os
+
+
+def _decode_dotenv(raw):
+    """.env 바이트를 텍스트로. 셸마다 디스크에 남기는 바이트가 다르다.
+
+    - bash/zsh      : UTF-8, LF
+    - pwsh 7        : UTF-8(BOM 없음), CRLF
+    - PowerShell 5.1: `>` 가 Out-File 이고 기본 인코딩이 Unicode = **UTF-16LE + BOM**
+    - cmd.exe       : UTF-8, CRLF
+
+    utf-8-sig 는 UTF-8 BOM 을 벗기고, 실패하면(0xff 0xfe 로 시작하는 UTF-16LE 등)
+    utf-16 으로 재시도한다(BOM 으로 바이트 순서 판별).
+
+    주장할 수 있는 것은 "이 바이트를 읽는다"이지 "PowerShell 5.1 을 통과한다"가 아니다.
+    실 Windows 의 PATH/pip/console-script 해석은 여전히 미검증이다.
+    """
+    try:
+        return raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        return raw.decode("utf-16")
+
+
+def _unwrap_whole_assignment(line):
+    """`'KEY=VALUE'` 처럼 **할당 전체**를 감싼 따옴표 짝만 벗긴다.
+
+    cmd.exe 는 `echo 'K=V' > .env` 의 작은따옴표를 특수문자가 아니라 리터럴로
+    파일에 남긴다. 그러면 키가 `'GEMINI_API_KEY`, 값이 `V'` 가 되어 둘 다 오염된다.
+
+    **값 안의 따옴표는 건드리지 않는다.** `KEY='v'` 는 값이 `'v'` 로 남는다.
+    """
+    if len(line) >= 2 and line[0] == line[-1] and line[0] in "\"'" and "=" in line:
+        return line[1:-1]
+    return line
+
+
+def _parse_dotenv(path):
+    if not os.path.isfile(path):
+        return
+    with open(path, "rb") as f:
+        text = _decode_dotenv(f.read())
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        line = _unwrap_whole_assignment(line)
+        key, _, value = line.partition("=")
+        # 키: 감싸는 따옴표를 벗긴다. 환경변수 이름에 따옴표가 들어갈 일은 없고,
+        #     오염되면 키가 영영 안 잡힌다(cmd.exe 경로).
+        key = key.strip().strip('"').strip("'").strip()
+        # 값: **절대 벗기지 않는다.** 값은 자격증명 리터럴이고 우리 탐지는 리터럴
+        #     매칭이다. 로더가 값을 변형하면 파일의 문자열과 메모리의 문자열이
+        #     달라지고, FP/FN 이 우리가 통제하지 못하는 지점에서 태어난다.
+        #     로더의 관용은 키 이름까지다 — 탐지 표면에는 닿지 않는다.
+        value = value.strip()
+        if not key:
+            continue
+        # 이미 환경에 있으면 덮어쓰지 않는다(실제 환경변수 우선).
+        os.environ.setdefault(key, value)
+
+
+def _load_dotenv():
+    # (1) 소스 트리 루트(= 이 파일에서 두 단계 위), (2) 현재 작업 디렉터리.
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    seen = set()
+    for path in (os.path.join(root, ".env"), os.path.join(os.getcwd(), ".env")):
+        rp = os.path.realpath(path)
+        if rp in seen:
+            continue
+        seen.add(rp)
+        _parse_dotenv(path)
+
+
+_load_dotenv()

agentproof_scan-0.1.3/agentproof_scan/adapters/base.py

@@ -0,0 +1,116 @@
+"""base.py — 스캐너가 의존하는 타깃 에이전트 추상 인터페이스."""
+
+from abc import ABC, abstractmethod
+
+
+class AgentCallError(Exception):
+    """에이전트 호출이 성공하지 못했음을 알리는 예외.
+
+    reason 슬러그는 stderr 안정 토큰(``AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>``)과
+    리포트의 abort_reason 필드를 동시에 먹인다. 슬러그와 필드명이 공개 계약이고,
+    사람이 읽는 산문은 아니다 — 산문은 번역·수정되며 CI 의 grep 을 다음 릴리스에 깬다.
+    """
+
+    SLUGS = (
+        "http_status",  # 2xx/3xx 아닌 응답
+        "parse_error",  # 2xx 지만 기대한 형태가 아님
+        "transport_error",  # 연결 실패·DNS·읽기 타임아웃
+        "timeout",  # 서브프로세스 타임아웃
+        "nonzero_exit",  # 서브프로세스 비정상 종료
+        "no_output",  # 서브프로세스가 아무것도 안 냄
+        "missing_env",  # preflight: 필수 키 없음
+        "placeholder_key",  # preflight: 문서의 플레이스홀더가 그대로 남음
+        "usage_error",  # CLI 인자가 잘못됨 (argparse) — 2 가 아니라 1 이다
+        "incomplete",  # 일부 프로브만 응답 (구체 사유 불명)
+    )
+
+    def __init__(self, message, reason="agent_call_failed", target=None):
+        super().__init__(message)
+        self.reason = reason
+        self.target = target
+
+
+class AgentConfigError(Exception):
+    """스캔을 시작할 수 없는 설정 오류. 프로브 실패(AgentCallError)와 **다른 타입**이다.
+
+    프로브 실패는 세고 넘어간다(다른 프로브는 유출을 찾을 수 있다). 설정 오류는
+    스캔 전체가 성립하지 않으므로 중단한다. 두 실패를 같은 타입으로 두면
+    "auth 헤더 형식이 틀렸다"가 "프로브 하나가 실패했다"로 집계된다.
+
+    reason 슬러그가 **어느 방어가 발화했는지**를 증언한다. 종료코드는 계약이고
+    슬러그는 증거다 — 서로 다른 방어가 같은 종료코드를 내므로, 코드로 방어의
+    신원을 확인하려 들면 안 된다.
+    """
+
+    SLUGS = (
+        "missing_url",  # --url 없음/빈 값
+        "missing_prompt_field",
+        "missing_response_field",
+        "auth_format",  # --auth-header 형식 오류
+        "auth_missing_env",  # 헤더가 참조하는 환경변수 미설정
+        "config_not_mapping",  # --agent-config 가 매핑이 아님
+        "config_error",  # 그 외 설정 오류
+    )
+
+    def __init__(self, message, reason="config_error"):
+        super().__init__(message)
+        self.reason = reason
+
+
+def ensure_ok(resp, target):
+    """HTTP 응답이 성공인지 확인한다. 아니면 AgentCallError 를 올린다.
+
+    A(generic_http)·B(gemini 계열) 전용 **편의 함수**이지 계약이 아니다.
+    초크포인트는 예외 타입이다 — 서브프로세스 경로(C·D)에는 응답 객체 자체가 없어
+    이 함수를 부를 수 없고, AgentCallError 를 직접 올린다.
+
+    누락돼 있던 raise_for_status() 그 자체다. 반드시 ``resp.json()``/``resp.text``
+    **앞**에서 불러야 한다. 뒤에서 부르면 오류 본문이 이미 스캔 대상 텍스트가 된 뒤다.
+    """
+    status = getattr(resp, "status_code", None)
+    if status is None or 200 <= status < 400:
+        return
+    raise AgentCallError(f"{target}: HTTP {status}", reason="http_status", target=target)
+
+
+class AgentAdapter(ABC):
+    """검사 대상 에이전트를 감싸는 어댑터 인터페이스.
+
+    스캐너(scan.py)는 구체 구현이 아니라 이 인터페이스에만 의존한다.
+
+    ── 계약 ──────────────────────────────────────────────────────────────────
+    ask() 는 **성공한 에이전트 응답만** 반환한다.
+    전송·인증·파싱·서브프로세스 실패는 AgentCallError 로 올린다.
+    실패를 텍스트로 반환하면 안 된다. ``returncode != 0`` 도 이 안이다.
+
+    이유: 실패를 문자열로 돌려주면 그 문자열이 스캔 대상이 된다. 오류 메시지엔
+    시크릿 모양이 없으므로 결함 0건이 나오고, 스캐너는 에이전트에 닿지도 못한 채
+    "안전"(exit 0)을 보고한다. 보안 도구의 거짓 GREEN 이다.
+
+        실패는 스캔 가능한 텍스트로 표현될 수 없다.
+
+    이 불변식은 실패의 *열거*보다 강하다. 새 실패 양식이 생겨도 예외 타입 하나만
+    지키면 스캐너가 알아서 거부한다.
+    """
+
+    @abstractmethod
+    def ask(self, user_input: str) -> str:
+        """user_input을 타깃에 보내고 **성공한** 응답 텍스트를 반환한다.
+
+        실패 시 AgentCallError 를 raise 한다. 실패 문자열을 return 하지 않는다.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_target_name(self) -> str:
+        """리포트에 기록할 타깃 식별자."""
+        raise NotImplementedError
+
+    def required_env_vars(self) -> list[str]:
+        """이 어댑터가 실제로 타깃에 도달하려면 필요한 환경변수 목록.
+
+        스캐너가 스캔 전 preflight 검사에 사용한다. 키가 없으면 "조용한 0"
+        (호출은 실패했는데 결함 0건이라 '안전'으로 오인) 대신 명확히 에러로
+        종료시키기 위함이다. 기본값: 없음.
+        """
+        return []

{agentproof_scan-0.1.2 → agentproof_scan-0.1.3}/agentproof_scan/adapters/external_starter.py

@@ -12,7 +12,7 @@ provider 파라미터로 백엔드 모델을 선택한다:
 import os
 import subprocess
 
-from .base import AgentAdapter
+from .base import AgentAdapter, AgentCallError
 from .simple_chatbot import CLEAN_DEFAULT_SYSTEM_PROMPT
 
 # 깨끗한(clean) 시스템 프롬프트 — simple_chatbot과 동일하게 시크릿이 없다.
@@ -110,17 +110,40 @@ class NgptAdapter(AgentAdapter):
         return cmd, env
 
     def ask(self, user_input: str) -> str:
+        # 실패는 절대 문자열로 돌려주지 않는다 — 돌려주면 그 문자열이 스캔되어
+        # "결함 0건 → 안전"이 된다. 서브프로세스엔 응답 객체가 없어 ensure_ok 를
+        # 쓸 수 없고, AgentCallError 를 직접 올린다.
         cmd, env = self._build_cmd_and_env(user_input)
         try:
             result = subprocess.run(
                 cmd, env=env, capture_output=True, text=True, timeout=120
             )
-        except subprocess.TimeoutExpired:
-            return "[ngpt timeout]"
-        # 응답 텍스트만 추출(앞뒤 공백/개행 제거). 실패 시 stderr를 함께 노출.
+        except subprocess.TimeoutExpired as e:
+            raise AgentCallError(
+                f"{self.target_name}: ngpt timed out",
+                reason="timeout",
+                target=self.target_name,
+            ) from e
+        except OSError as e:  # 바이너리 없음·실행 불가
+            raise AgentCallError(
+                f"{self.target_name}: cannot run ngpt ({type(e).__name__})",
+                reason="transport_error",
+                target=self.target_name,
+            ) from e
+
+        if result.returncode != 0:
+            raise AgentCallError(
+                f"{self.target_name}: ngpt exited {result.returncode}",
+                reason="nonzero_exit",
+                target=self.target_name,
+            )
         out = (result.stdout or "").strip()
         if not out:
-            return f"[ngpt no output] {(result.stderr or '').strip()}"
+            raise AgentCallError(
+                f"{self.target_name}: ngpt produced no output",
+                reason="no_output",
+                target=self.target_name,
+            )
         return out
 
     def get_target_name(self) -> str: