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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproof-scan
-Version: 0.1.2
+Version: 0.1.4
 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,59 @@ 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.**
+
+```
+pip install agentproof-scan
+```
+`pip: command not found` → `python -m pip install agentproof-scan`. On Windows without
+Python, `py -m pip install agentproof-scan` triggers the Python Install Manager to fetch
+Python for you. [VERIFIED: `py -m ...` installed Python 3.14.6 on Windows, owner, 2026-07-11.]
+
+**3. Put your key in a `.env` file, with an editor — not a shell command.**
+
+Open a new file called `.env` in the folder you'll run from, and put one line in it:
+
+```
+GEMINI_API_KEY=your-real-key-here
+```
+
+Save it. Get a free key at <https://aistudio.google.com/apikey>. `.env` is auto-loaded from
+the directory you run in and is gitignored — never commit it.
+
+> **Why an editor and not `echo '...' > .env`?** A shell command puts your key on the
+> command line, and the shell saves that line to its **history** in plaintext
+> (`~/.bash_history`, PowerShell's `ConsoleHost_history.txt`). A tool that detects leaked
+> credentials should not teach you to write one to a file nobody thinks to check. An editor
+> avoids the history entirely. (If you do use the shell, this tool does **not** scan shell
+> history — that's on you to clear.)
+
+> **On `.env` encoding.** The loader reads `.env` written as UTF-8, UTF-8 with BOM, and
+> **UTF-16LE with BOM** (what PowerShell 5.1's `>` produces — [VERIFIED on a real PowerShell
+> 5.1 file, owner, 2026-07-11]), and strips stray quotes `cmd.exe` leaves around the *key
+> name*. **Don't quote the value** — `KEY="abc"` keeps the quotes literally.
+
+**4. If the command isn't found:** `agentproof-scan: command not found` →
+`python -m agentproof_scan` (Windows: `py -m agentproof_scan`) — same tool, same flags,
+works when the console script isn't on PATH. [VERIFIED on Windows, owner, 2026-07-11.]
+
+---
+
 ## 🚀 60-second Quick Start (no setup knowledge — just copy-paste)
 
 `agentproof-scan` ships with a built-in **victim demo**: an intentionally leaky agent
@@ -62,19 +115,38 @@ backed by Google Gemini. You only need a free Gemini key to try it.
 pip install agentproof-scan
 
 # 2. Get a FREE Gemini key → https://aistudio.google.com/apikey
-#    save it to a .env file in the folder you run from (auto-loaded, kept out of git):
-echo 'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env
+#    Then create a file named .env in this folder (with an editor, not the shell —
+#    see Prerequisites) containing one line:
+#        GEMINI_API_KEY=your-real-key-here
 
 # 3. Scan the built-in vulnerable demo agent
-agentproof-scan                  # same as: agentproof-scan --target victim
-agentproof-scan --stability 5    # repeat 5× — more reliable (see note below)
+agentproof-scan                  # one pass = 15 probes = 15 API calls
+agentproof-scan --stability 2    # 2 passes = 30 calls — more reliable (see notes)
 ```
 
 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.
-
-> **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.
+> ⚠️ **On a free Gemini key, watch the request count.** Each pass sends **15 probes** = 15
+> API calls; `--stability N` multiplies that (`--stability 5` = 75 calls, `--stability 10`
+> = 150). The free tier has a per-minute quota, and hitting it is **not** a tool failure —
+> the scanner exits `1` with `reason=rate_limit` and tells you to wait or lower
+> `--stability`. Start with `--stability 2`; raise it once you know your quota headroom.
+
+> ⚠️ **A zero you can trust.** A scan that never reached your agent, or was cut off
+> partway (bad key, HTTP 500, timeout, rate limit), must not read as *"safe."* The scanner
+> **refuses to report clean** unless every probe actually got an answer: otherwise it exits
+> `1` and prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` on stderr (`rate_limit`,
+> `auth_failed`, `http_status`, `incomplete_scan`, …). A leak it *did* find is still
+> reported and, under `--fail-on-findings`, still exits `2` — **a partial scan may not
+> claim clean, but it may claim what it found.** (Earlier versions, up to `0.1.3`, could
+> print `leak_count: 0` and exit `0` here — that's the bug `0.1.4` closes.)
+
+> **Why repeat with `--stability`?** 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
+> measures *how often* it leaks (`leak_rate`) and is the reliable way to read the verdict.
+> A probe that never got an answer shows `leak_rate: null` (**not** `0.0`) — "not asked" is
+> not "didn't leak." ⚠ Each repeat costs `15 × N` API calls; on a free key start at
+> `--stability 2` (see the request-count note above).
 
 ---
 
@@ -87,7 +159,7 @@ Two fields matter:
 
 **Analogy:** `leak` = the guard handed over the vault key. `prompt_disclosure` = the guard didn't hand over the key, but read the security manual aloud. Both are bad; the first is worse.
 
-**`leak_rate`** (in repeat/stability mode) = how often a probe pulled a leak. For example `4/10 (0.4)` = 4 of 10 tries leaked. A flaky leak is still a leak — repetition shows how *reliably* an agent fails.
+**`leak_rate`** (in repeat/stability mode) = how often a probe pulled a leak, over the runs that **got an answer**. For example `4/10 (0.4)` = 4 of 10 answered tries leaked. A flaky leak is still a leak — repetition shows how *reliably* an agent fails. A probe that never got an answer (rate-limited, timed out) shows `leak_rate: null`, not `0.0` — the report separates *"didn't leak"* from *"wasn't asked."*
 
 **Which secrets it recognizes:** the scanner looks for key shapes from major providers — OpenAI (including modern `sk-proj-` / `sk-svcacct-` / `sk-admin-` keys and the legacy `sk-` format), Anthropic, Google, AWS, GitHub, and xAI.
 
@@ -167,9 +239,10 @@ agentproof-scan \
 **Needs auth?** Pass a header — but put only the **name** of an environment variable
 in the flag, never the key itself:
 
+Add the key to your `.env` (with an editor — same reason as the Quick Start: keep it out
+of shell history) as `MY_AGENT_KEY=your-real-key`, then reference it **by name**:
+
 ```bash
-# key lives in .env (gitignored); the flag references it by name
-echo 'MY_AGENT_KEY=sk-your-real-key' >> .env
 agentproof-scan --url https://my-agent.example.com/chat \
   --prompt-field message --response-field reply \
   --auth-header "Authorization=Bearer {MY_AGENT_KEY}"
@@ -260,16 +333,103 @@ jobs:
 
 *(Also at [`examples/ci/agentproof.yml`](https://github.com/ghkfuddl1327-wq/agentproof/blob/main/examples/ci/agentproof.yml) — copy it, don't clone the repo.)*
 
-**Don't drop the `AGENT_URL` guard.** An unset secret is an empty string, and an
-empty `--url` makes the scanner fall back to its **bundled demo agent** — which
-leaks on purpose. Without the guard your build goes red over a planted fake secret
-while your real agent is never scanned. Forked pull requests get no secrets at all,
-so they always take this path.
+**Keep the `AGENT_URL` guard anyway.** An unset secret is an empty string, and the
+guard turns that into a clear "secret not set" failure. Since `0.1.3` an empty `--url`
+already exits `1` on its own (`reason=missing_url`) rather than scanning anything — so
+a missing `AGENT_URL` fails the build as *"the scan did not run,"* not as *"your agent
+leaked."* The guard just makes that reason obvious in the log. Forked pull requests get
+no secrets, so they hit this path — and a `1` there is correct: nothing was scanned,
+and nothing is claimed clean.
 
 If your agent leaks a secret, `--fail-on-findings` exits non-zero and the check goes
 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.4` 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)
@@ -290,10 +450,13 @@ If any step is confusing, paste this into an AI assistant and follow along:
 
 Early work in progress. This tool grew out of red-team probing experiments and is expanding toward broader pre-deployment credential-exposure detection. The detection rule and the cross-model numbers are still being validated — **expect changes**, and if you can break something we marked as working, please open an issue.
 
-**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.
+**Invalid keys, since `0.1.3`:** a present-but-invalid key (wrong or expired) no longer
+produces a misleading `0`. The provider returns an HTTP error, the scanner treats that
+as *the scan did not run* — exit `1`, `reason=http_status` — and refuses to report clean.
+Earlier versions did report `0` here; that was the bug `0.1.3` closes.
 
 **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.4` 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 +516,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.4` 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 +526,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.4`. 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.4}/README.md

@@ -30,6 +30,59 @@ 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.**
+
+```
+pip install agentproof-scan
+```
+`pip: command not found` → `python -m pip install agentproof-scan`. On Windows without
+Python, `py -m pip install agentproof-scan` triggers the Python Install Manager to fetch
+Python for you. [VERIFIED: `py -m ...` installed Python 3.14.6 on Windows, owner, 2026-07-11.]
+
+**3. Put your key in a `.env` file, with an editor — not a shell command.**
+
+Open a new file called `.env` in the folder you'll run from, and put one line in it:
+
+```
+GEMINI_API_KEY=your-real-key-here
+```
+
+Save it. Get a free key at <https://aistudio.google.com/apikey>. `.env` is auto-loaded from
+the directory you run in and is gitignored — never commit it.
+
+> **Why an editor and not `echo '...' > .env`?** A shell command puts your key on the
+> command line, and the shell saves that line to its **history** in plaintext
+> (`~/.bash_history`, PowerShell's `ConsoleHost_history.txt`). A tool that detects leaked
+> credentials should not teach you to write one to a file nobody thinks to check. An editor
+> avoids the history entirely. (If you do use the shell, this tool does **not** scan shell
+> history — that's on you to clear.)
+
+> **On `.env` encoding.** The loader reads `.env` written as UTF-8, UTF-8 with BOM, and
+> **UTF-16LE with BOM** (what PowerShell 5.1's `>` produces — [VERIFIED on a real PowerShell
+> 5.1 file, owner, 2026-07-11]), and strips stray quotes `cmd.exe` leaves around the *key
+> name*. **Don't quote the value** — `KEY="abc"` keeps the quotes literally.
+
+**4. If the command isn't found:** `agentproof-scan: command not found` →
+`python -m agentproof_scan` (Windows: `py -m agentproof_scan`) — same tool, same flags,
+works when the console script isn't on PATH. [VERIFIED on Windows, owner, 2026-07-11.]
+
+---
+
 ## 🚀 60-second Quick Start (no setup knowledge — just copy-paste)
 
 `agentproof-scan` ships with a built-in **victim demo**: an intentionally leaky agent
@@ -40,19 +93,38 @@ backed by Google Gemini. You only need a free Gemini key to try it.
 pip install agentproof-scan
 
 # 2. Get a FREE Gemini key → https://aistudio.google.com/apikey
-#    save it to a .env file in the folder you run from (auto-loaded, kept out of git):
-echo 'GEMINI_API_KEY=PASTE_YOUR_KEY_HERE' > .env
+#    Then create a file named .env in this folder (with an editor, not the shell —
+#    see Prerequisites) containing one line:
+#        GEMINI_API_KEY=your-real-key-here
 
 # 3. Scan the built-in vulnerable demo agent
-agentproof-scan                  # same as: agentproof-scan --target victim
-agentproof-scan --stability 5    # repeat 5× — more reliable (see note below)
+agentproof-scan                  # one pass = 15 probes = 15 API calls
+agentproof-scan --stability 2    # 2 passes = 30 calls — more reliable (see notes)
 ```
 
 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.
-
-> **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.
+> ⚠️ **On a free Gemini key, watch the request count.** Each pass sends **15 probes** = 15
+> API calls; `--stability N` multiplies that (`--stability 5` = 75 calls, `--stability 10`
+> = 150). The free tier has a per-minute quota, and hitting it is **not** a tool failure —
+> the scanner exits `1` with `reason=rate_limit` and tells you to wait or lower
+> `--stability`. Start with `--stability 2`; raise it once you know your quota headroom.
+
+> ⚠️ **A zero you can trust.** A scan that never reached your agent, or was cut off
+> partway (bad key, HTTP 500, timeout, rate limit), must not read as *"safe."* The scanner
+> **refuses to report clean** unless every probe actually got an answer: otherwise it exits
+> `1` and prints `AGENTPROOF_SCAN_DID_NOT_RUN reason=<slug>` on stderr (`rate_limit`,
+> `auth_failed`, `http_status`, `incomplete_scan`, …). A leak it *did* find is still
+> reported and, under `--fail-on-findings`, still exits `2` — **a partial scan may not
+> claim clean, but it may claim what it found.** (Earlier versions, up to `0.1.3`, could
+> print `leak_count: 0` and exit `0` here — that's the bug `0.1.4` closes.)
+
+> **Why repeat with `--stability`?** 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
+> measures *how often* it leaks (`leak_rate`) and is the reliable way to read the verdict.
+> A probe that never got an answer shows `leak_rate: null` (**not** `0.0`) — "not asked" is
+> not "didn't leak." ⚠ Each repeat costs `15 × N` API calls; on a free key start at
+> `--stability 2` (see the request-count note above).
 
 ---
 
@@ -65,7 +137,7 @@ Two fields matter:
 
 **Analogy:** `leak` = the guard handed over the vault key. `prompt_disclosure` = the guard didn't hand over the key, but read the security manual aloud. Both are bad; the first is worse.
 
-**`leak_rate`** (in repeat/stability mode) = how often a probe pulled a leak. For example `4/10 (0.4)` = 4 of 10 tries leaked. A flaky leak is still a leak — repetition shows how *reliably* an agent fails.
+**`leak_rate`** (in repeat/stability mode) = how often a probe pulled a leak, over the runs that **got an answer**. For example `4/10 (0.4)` = 4 of 10 answered tries leaked. A flaky leak is still a leak — repetition shows how *reliably* an agent fails. A probe that never got an answer (rate-limited, timed out) shows `leak_rate: null`, not `0.0` — the report separates *"didn't leak"* from *"wasn't asked."*
 
 **Which secrets it recognizes:** the scanner looks for key shapes from major providers — OpenAI (including modern `sk-proj-` / `sk-svcacct-` / `sk-admin-` keys and the legacy `sk-` format), Anthropic, Google, AWS, GitHub, and xAI.
 
@@ -145,9 +217,10 @@ agentproof-scan \
 **Needs auth?** Pass a header — but put only the **name** of an environment variable
 in the flag, never the key itself:
 
+Add the key to your `.env` (with an editor — same reason as the Quick Start: keep it out
+of shell history) as `MY_AGENT_KEY=your-real-key`, then reference it **by name**:
+
 ```bash
-# key lives in .env (gitignored); the flag references it by name
-echo 'MY_AGENT_KEY=sk-your-real-key' >> .env
 agentproof-scan --url https://my-agent.example.com/chat \
   --prompt-field message --response-field reply \
   --auth-header "Authorization=Bearer {MY_AGENT_KEY}"
@@ -238,16 +311,103 @@ jobs:
 
 *(Also at [`examples/ci/agentproof.yml`](https://github.com/ghkfuddl1327-wq/agentproof/blob/main/examples/ci/agentproof.yml) — copy it, don't clone the repo.)*
 
-**Don't drop the `AGENT_URL` guard.** An unset secret is an empty string, and an
-empty `--url` makes the scanner fall back to its **bundled demo agent** — which
-leaks on purpose. Without the guard your build goes red over a planted fake secret
-while your real agent is never scanned. Forked pull requests get no secrets at all,
-so they always take this path.
+**Keep the `AGENT_URL` guard anyway.** An unset secret is an empty string, and the
+guard turns that into a clear "secret not set" failure. Since `0.1.3` an empty `--url`
+already exits `1` on its own (`reason=missing_url`) rather than scanning anything — so
+a missing `AGENT_URL` fails the build as *"the scan did not run,"* not as *"your agent
+leaked."* The guard just makes that reason obvious in the log. Forked pull requests get
+no secrets, so they hit this path — and a `1` there is correct: nothing was scanned,
+and nothing is claimed clean.
 
 If your agent leaks a secret, `--fail-on-findings` exits non-zero and the check goes
 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.4` 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)
@@ -268,10 +428,13 @@ If any step is confusing, paste this into an AI assistant and follow along:
 
 Early work in progress. This tool grew out of red-team probing experiments and is expanding toward broader pre-deployment credential-exposure detection. The detection rule and the cross-model numbers are still being validated — **expect changes**, and if you can break something we marked as working, please open an issue.
 
-**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.
+**Invalid keys, since `0.1.3`:** a present-but-invalid key (wrong or expired) no longer
+produces a misleading `0`. The provider returns an HTTP error, the scanner treats that
+as *the scan did not run* — exit `1`, `reason=http_status` — and refuses to report clean.
+Earlier versions did report `0` here; that was the bug `0.1.3` closes.
 
 **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.4` 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 +494,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.4` 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 +504,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.4`. 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.4}/agentproof_scan/__init__.py

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

agentproof_scan-0.1.4/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.4/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()