stopgate 0.1.0__tar.gz

stopgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Kaila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stopgate-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: stopgate
+Version: 0.1.0
+Summary: Stop watching your agent. A local-first safety envelope that lets you run coding agents unattended.
+Author: Rohan Kaila
+License: MIT
+Project-URL: Homepage, https://github.com/Robomba/stopgate
+Project-URL: Source, https://github.com/Robomba/stopgate
+Keywords: ai,agent,security,guardrail,claude,prompt-injection,taint,dataflow
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Stopgate
+
+[![CI](https://github.com/Robomba/stopgate/actions/workflows/ci.yml/badge.svg)](https://github.com/Robomba/stopgate/actions/workflows/ci.yml)
+ ·  MIT  ·  zero runtime deps  ·  runs entirely on your machine
+
+### Stop watching your agent.
+
+You don't babysit your coding agent because it's dangerous. You babysit it because you can't tell the difference between it *reading a file* and it *reading your `.env` and POSTing it to an IP it found in a README.*
+
+Stopgate can. So you can go do something else.
+
+```bash
+pip install stopgate
+stopgate report
+```
+
+> The PyPI package is **`stopgate`** (plain `stopgate` is an unrelated project); the
+> command is just `stopgate`. For the bleeding edge:
+> `pip install "git+https://github.com/Robomba/stopgate.git"`.
+
+No config. It reads the logs your agent already wrote and tells you what it's been doing.
+
+```
+  This session — 8 agent actions:
+
+     1  file reads touched credentials  (/home/dev/app/.env)
+     3  network calls to 3 domains  (docs.example.com, collect.evil.example, api.github.com)
+     1  destructive commands                (no confirmation asked)
+     1  outbound payload carried a secret read earlier   <- this is the one
+     2  action(s) taken shortly after reading untrusted content
+```
+
+**Free. MIT. Runs entirely on your machine. Makes zero network calls of its own.**
+
+---
+
+## Why it's different
+
+Most guardrails you can `pip install` today match **keywords**. We published the benchmark showing that doesn't work: a bag-of-words classifier with no model at all scores **0.967** on the standard harm benchmark — and **0.493 (chance)** the moment the attacker stops using the obvious words. Keyword guardrails aren't detecting intent. They're detecting vocabulary. ([AICES paper](https://github.com/Robomba/ai-control-eval-suite) · [dataset](https://huggingface.co/datasets/Robomb/aices-minpair-control))
+
+Stopgate watches **where data came from and where it's going.** It tracks which tool results are untrusted (web/email/file/MCP), taints the session when the agent reads them, and fingerprints every secret it sees so it can spot that secret leaving the machine — **even base64-encoded.** *"The agent read `evil.com`, then tried to POST your `.env`"* is not a wording problem. You can't rephrase your way past a hash comparison.
+
+**This isn't a new idea, and I won't pretend it is.** Provenance/dataflow defenses for
+agents already exist in research: DeepMind's [CaMeL](https://arxiv.org/abs/2503.18813),
+[Invariant Labs](https://invariantlabs.ai/) (acquired into Snyk), Meta's
+[LlamaFirewall](https://arxiv.org/abs/2505.03574). Stopgate's contribution is **not** the
+concept — it's (1) a zero-config build you can install and run against your own Claude Code
+sessions today, and (2) an **open, minimal-pair controlled benchmark for agent actions** that
+measures the thing everyone hand-waves: how often a guardrail cries wolf. The benchmark is the
+new part; the gate is an honest implementation of a known idea. And to be precise about *how* it
+works: it's a **lexical** action layer (regex for `rm -rf`, `DROP TABLE`, `curl | bash`) **plus**
+a **non-lexical** provenance layer — not "dataflow instead of keywords," but both.
+
+---
+
+## Turn it on (live gating)
+
+Stopgate plugs into Claude Code as two hooks. **You need both.**
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "hooks": {
+    "PreToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "stopgate hook"  }] }],
+    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "stopgate watch" }] }]
+  }
+}
+```
+
+Why two? `PreToolUse` fires *before* a tool runs, so it never sees a **result** —
+no result, no secret bytes, nothing to fingerprint. `stopgate watch` (PostToolUse)
+is the only place a secret can actually be captured. **Without `watch`, Stopgate
+can only judge one action at a time and cross-call exfiltration is not detected.**
+With it, "read the `.env` at step 3, POST it to an unknown host at step 19" is
+caught — the payload at step 19 looks innocent on its own.
+
+### Modes
+
+| Mode | Behaviour | Use it when |
+|---|---|---|
+| `observe` | Scores and logs everything, **always allows**. Cannot stall an agent. | You're building trust, or the agent runs unattended and must never block. |
+| `enforce` *(default)* | A hard-stop surfaces to you as an **ask**. Everything else auto-approves. | You're at the keyboard. |
+| `enforce --headless` | A hard-stop **denies** instead of asking. | Nobody is there — an "ask" nobody answers is a hang, not a guardrail. |
+
+Set with `--mode`, or `$STOPGATE_MODE`, or a `~/.stopgate-mode` file.
+
+**Kill switch:** `echo observe > ~/.stopgate-mode` — instantly back to logging-only,
+no restart, no config edit.
+
+### What it never does
+
+Stopgate **never writes your secrets to disk.** Session state holds only rolling-hash
+fingerprints and salted hashes — enough to recognise those bytes trying to leave,
+not enough to reconstruct them. A stolen state file yields nothing. (State lives in
+`~/.cache/stopgate/sessions`, mode `0600`, expires after 7 days.)
+
+It also **fails open, on purpose**: if Stopgate itself errors, the tool call is
+allowed and the error is logged. A broken guardrail must never brick the agent it
+is watching. That is a deliberate trade-off, and it is the honest one to state:
+**Stopgate is a safety net, not a guarantee.** It can miss things. Do not use it as
+the only thing standing between an agent and something you cannot undo.
+
+## Our promises
+
+These are commitments, not features. They're the reason you can trust a security tool you didn't write.
+
+**1. We will never phone home.** Zero telemetry, zero analytics, no network calls of Stopgate's own — ever. A security tool that exfiltrates your data to prove nothing is exfiltrating your data is a joke. The code is MIT; verify it.
+
+**2. We publish our false-alarm rate every release.** Not our catch rate — anyone can catch everything by blocking everything. The number that matters is **how often we interrupt you for nothing**, and we print it whether it's good or bad. I haven't found another installable agent guardrail that publishes its false-alarm rate on a controlled set — if you know one, tell me and I'll link it.
+
+**3. Sixty seconds or we failed.** Install to first insight with no config file, no policy language, no account. If you have to *learn* Stopgate before it helps you, we built it wrong.
+
+**4. Some things always stop for a human.** Money moving, production, anything irreversible — those wake you up no matter what your policy says. No "trust level" will ever override that. If a tool offers to fully automate spending your money, close the tab.
+
+**5. We tell you what we can't do.** (See below — it stays in the README, permanently.)
+
+**6. We'll never ship an attack to sell the defense.** Our demos use dummy canaries and local sinks. We don't publish weapons.
+
+**7. Free, MIT, forever.** And the benchmark we grade ourselves with is public — run it against us, and against everyone else.
+
+---
+
+
+## ⚠ Disclaimer
+
+**Stopgate is best-effort and will make mistakes.** It can miss real attacks and flag safe
+actions. It is **not a guarantee of safety**, not a substitute for code review or OS
+sandboxing, and is provided **AS IS with no warranty** (MIT). Benchmark numbers come from a
+small, non-human-audited seed set and are indicative, not definitive. **You are responsible
+for what your agent does.** Full text: [DISCLAIMER.md](DISCLAIMER.md).
+
+## What Stopgate does NOT catch
+
+A security tool that overclaims is worse than none. Stopgate sees **actions, not thoughts.**
+
+- **A genuinely malicious model with a covert channel.** If the model is the adversary and hides intent in benign-looking actions, Stopgate can't read its mind.
+- **Anything outside the tool-call boundary.** If it doesn't go through a tool call Stopgate can see, Stopgate can't see it.
+- **The "acted after untrusted content" signal is a temporal-proximity heuristic, not true taint.** We can't see which datum actually influenced the model, so we flag high-risk actions within N steps of an untrusted read — with confidence that **decays** with distance and is **evadable** by simply spacing the action out past the window.
+- **Injection-provenance without secret egress.** A benign-*looking* action an agent runs because untrusted content told it to (no secret leaving) scores at **chance** in our own benchmark — Stopgate ties the keyword baseline there. Stopgate's real dataflow edge is secret-**egress**, not injection-provenance. We publish this miss (see `stopgate eval`).
+- **Transformed exfil.** Byte-matching catches naive/base64/hex copies of a secret; gzip, encryption, or having the model paraphrase the secret defeat it. A competent adversary can get data out. It raises the cost; it is not a wall.
+- **Anything not routed through the adapter** — a subprocess the agent spawns, network made from inside a tool's own code, or an MCP server talked to out-of-band — is invisible.
+- **Closed chat UIs** (ChatGPT / Claude web). There's no interception point.
+- **It is not a substitute for OS-level sandboxing.** Run untrusted agents in a container/VM. Stopgate is a layer on top, not a replacement.
+
+Stopgate **reduces babysitting; it does not eliminate risk.**
+
+---
+
+## Status
+
+**Shipped (local, verified):**
+- `stopgate report` — read-only, zero-config: what your agent has been doing.
+- `stopgate digest` — the session receipt: what was let through and *why it was safe*.
+- `stopgate learn` — writes an editable allow-policy from your own sessions (opt-in tuning).
+- `stopgate run` — unattended supervision: **auto-approve in-policy, hard-stop the irreversible.** Money, production, destructive, sign-in, install, and any secret leaving the machine always stop for a human — no policy can override that.
+- `stopgate hook` — the live Claude Code PreToolUse gate (returns allow / ask per tool call).
+
+**Next:** `stopgate eval` — the public precision benchmark (false alarms per 1,000 actions).
+
+
+## License
+
+MIT. Local-first. No network calls of its own.

stopgate-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Stopgate
+
+[![CI](https://github.com/Robomba/stopgate/actions/workflows/ci.yml/badge.svg)](https://github.com/Robomba/stopgate/actions/workflows/ci.yml)
+ ·  MIT  ·  zero runtime deps  ·  runs entirely on your machine
+
+### Stop watching your agent.
+
+You don't babysit your coding agent because it's dangerous. You babysit it because you can't tell the difference between it *reading a file* and it *reading your `.env` and POSTing it to an IP it found in a README.*
+
+Stopgate can. So you can go do something else.
+
+```bash
+pip install stopgate
+stopgate report
+```
+
+> The PyPI package is **`stopgate`** (plain `stopgate` is an unrelated project); the
+> command is just `stopgate`. For the bleeding edge:
+> `pip install "git+https://github.com/Robomba/stopgate.git"`.
+
+No config. It reads the logs your agent already wrote and tells you what it's been doing.
+
+```
+  This session — 8 agent actions:
+
+     1  file reads touched credentials  (/home/dev/app/.env)
+     3  network calls to 3 domains  (docs.example.com, collect.evil.example, api.github.com)
+     1  destructive commands                (no confirmation asked)
+     1  outbound payload carried a secret read earlier   <- this is the one
+     2  action(s) taken shortly after reading untrusted content
+```
+
+**Free. MIT. Runs entirely on your machine. Makes zero network calls of its own.**
+
+---
+
+## Why it's different
+
+Most guardrails you can `pip install` today match **keywords**. We published the benchmark showing that doesn't work: a bag-of-words classifier with no model at all scores **0.967** on the standard harm benchmark — and **0.493 (chance)** the moment the attacker stops using the obvious words. Keyword guardrails aren't detecting intent. They're detecting vocabulary. ([AICES paper](https://github.com/Robomba/ai-control-eval-suite) · [dataset](https://huggingface.co/datasets/Robomb/aices-minpair-control))
+
+Stopgate watches **where data came from and where it's going.** It tracks which tool results are untrusted (web/email/file/MCP), taints the session when the agent reads them, and fingerprints every secret it sees so it can spot that secret leaving the machine — **even base64-encoded.** *"The agent read `evil.com`, then tried to POST your `.env`"* is not a wording problem. You can't rephrase your way past a hash comparison.
+
+**This isn't a new idea, and I won't pretend it is.** Provenance/dataflow defenses for
+agents already exist in research: DeepMind's [CaMeL](https://arxiv.org/abs/2503.18813),
+[Invariant Labs](https://invariantlabs.ai/) (acquired into Snyk), Meta's
+[LlamaFirewall](https://arxiv.org/abs/2505.03574). Stopgate's contribution is **not** the
+concept — it's (1) a zero-config build you can install and run against your own Claude Code
+sessions today, and (2) an **open, minimal-pair controlled benchmark for agent actions** that
+measures the thing everyone hand-waves: how often a guardrail cries wolf. The benchmark is the
+new part; the gate is an honest implementation of a known idea. And to be precise about *how* it
+works: it's a **lexical** action layer (regex for `rm -rf`, `DROP TABLE`, `curl | bash`) **plus**
+a **non-lexical** provenance layer — not "dataflow instead of keywords," but both.
+
+---
+
+## Turn it on (live gating)
+
+Stopgate plugs into Claude Code as two hooks. **You need both.**
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "hooks": {
+    "PreToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "stopgate hook"  }] }],
+    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "stopgate watch" }] }]
+  }
+}
+```
+
+Why two? `PreToolUse` fires *before* a tool runs, so it never sees a **result** —
+no result, no secret bytes, nothing to fingerprint. `stopgate watch` (PostToolUse)
+is the only place a secret can actually be captured. **Without `watch`, Stopgate
+can only judge one action at a time and cross-call exfiltration is not detected.**
+With it, "read the `.env` at step 3, POST it to an unknown host at step 19" is
+caught — the payload at step 19 looks innocent on its own.
+
+### Modes
+
+| Mode | Behaviour | Use it when |
+|---|---|---|
+| `observe` | Scores and logs everything, **always allows**. Cannot stall an agent. | You're building trust, or the agent runs unattended and must never block. |
+| `enforce` *(default)* | A hard-stop surfaces to you as an **ask**. Everything else auto-approves. | You're at the keyboard. |
+| `enforce --headless` | A hard-stop **denies** instead of asking. | Nobody is there — an "ask" nobody answers is a hang, not a guardrail. |
+
+Set with `--mode`, or `$STOPGATE_MODE`, or a `~/.stopgate-mode` file.
+
+**Kill switch:** `echo observe > ~/.stopgate-mode` — instantly back to logging-only,
+no restart, no config edit.
+
+### What it never does
+
+Stopgate **never writes your secrets to disk.** Session state holds only rolling-hash
+fingerprints and salted hashes — enough to recognise those bytes trying to leave,
+not enough to reconstruct them. A stolen state file yields nothing. (State lives in
+`~/.cache/stopgate/sessions`, mode `0600`, expires after 7 days.)
+
+It also **fails open, on purpose**: if Stopgate itself errors, the tool call is
+allowed and the error is logged. A broken guardrail must never brick the agent it
+is watching. That is a deliberate trade-off, and it is the honest one to state:
+**Stopgate is a safety net, not a guarantee.** It can miss things. Do not use it as
+the only thing standing between an agent and something you cannot undo.
+
+## Our promises
+
+These are commitments, not features. They're the reason you can trust a security tool you didn't write.
+
+**1. We will never phone home.** Zero telemetry, zero analytics, no network calls of Stopgate's own — ever. A security tool that exfiltrates your data to prove nothing is exfiltrating your data is a joke. The code is MIT; verify it.
+
+**2. We publish our false-alarm rate every release.** Not our catch rate — anyone can catch everything by blocking everything. The number that matters is **how often we interrupt you for nothing**, and we print it whether it's good or bad. I haven't found another installable agent guardrail that publishes its false-alarm rate on a controlled set — if you know one, tell me and I'll link it.
+
+**3. Sixty seconds or we failed.** Install to first insight with no config file, no policy language, no account. If you have to *learn* Stopgate before it helps you, we built it wrong.
+
+**4. Some things always stop for a human.** Money moving, production, anything irreversible — those wake you up no matter what your policy says. No "trust level" will ever override that. If a tool offers to fully automate spending your money, close the tab.
+
+**5. We tell you what we can't do.** (See below — it stays in the README, permanently.)
+
+**6. We'll never ship an attack to sell the defense.** Our demos use dummy canaries and local sinks. We don't publish weapons.
+
+**7. Free, MIT, forever.** And the benchmark we grade ourselves with is public — run it against us, and against everyone else.
+
+---
+
+
+## ⚠ Disclaimer
+
+**Stopgate is best-effort and will make mistakes.** It can miss real attacks and flag safe
+actions. It is **not a guarantee of safety**, not a substitute for code review or OS
+sandboxing, and is provided **AS IS with no warranty** (MIT). Benchmark numbers come from a
+small, non-human-audited seed set and are indicative, not definitive. **You are responsible
+for what your agent does.** Full text: [DISCLAIMER.md](DISCLAIMER.md).
+
+## What Stopgate does NOT catch
+
+A security tool that overclaims is worse than none. Stopgate sees **actions, not thoughts.**
+
+- **A genuinely malicious model with a covert channel.** If the model is the adversary and hides intent in benign-looking actions, Stopgate can't read its mind.
+- **Anything outside the tool-call boundary.** If it doesn't go through a tool call Stopgate can see, Stopgate can't see it.
+- **The "acted after untrusted content" signal is a temporal-proximity heuristic, not true taint.** We can't see which datum actually influenced the model, so we flag high-risk actions within N steps of an untrusted read — with confidence that **decays** with distance and is **evadable** by simply spacing the action out past the window.
+- **Injection-provenance without secret egress.** A benign-*looking* action an agent runs because untrusted content told it to (no secret leaving) scores at **chance** in our own benchmark — Stopgate ties the keyword baseline there. Stopgate's real dataflow edge is secret-**egress**, not injection-provenance. We publish this miss (see `stopgate eval`).
+- **Transformed exfil.** Byte-matching catches naive/base64/hex copies of a secret; gzip, encryption, or having the model paraphrase the secret defeat it. A competent adversary can get data out. It raises the cost; it is not a wall.
+- **Anything not routed through the adapter** — a subprocess the agent spawns, network made from inside a tool's own code, or an MCP server talked to out-of-band — is invisible.
+- **Closed chat UIs** (ChatGPT / Claude web). There's no interception point.
+- **It is not a substitute for OS-level sandboxing.** Run untrusted agents in a container/VM. Stopgate is a layer on top, not a replacement.
+
+Stopgate **reduces babysitting; it does not eliminate risk.**
+
+---
+
+## Status
+
+**Shipped (local, verified):**
+- `stopgate report` — read-only, zero-config: what your agent has been doing.
+- `stopgate digest` — the session receipt: what was let through and *why it was safe*.
+- `stopgate learn` — writes an editable allow-policy from your own sessions (opt-in tuning).
+- `stopgate run` — unattended supervision: **auto-approve in-policy, hard-stop the irreversible.** Money, production, destructive, sign-in, install, and any secret leaving the machine always stop for a human — no policy can override that.
+- `stopgate hook` — the live Claude Code PreToolUse gate (returns allow / ask per tool call).
+
+**Next:** `stopgate eval` — the public precision benchmark (false alarms per 1,000 actions).
+
+
+## License
+
+MIT. Local-first. No network calls of its own.

stopgate-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stopgate"
+version = "0.1.0"
+description = "Stop watching your agent. A local-first safety envelope that lets you run coding agents unattended."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Rohan Kaila" }]
+keywords = ["ai", "agent", "security", "guardrail", "claude", "prompt-injection", "taint", "dataflow"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Environment :: Console",
+]
+# Deliberately ZERO runtime dependencies. Stopgate makes no network calls of its own
+# and pulls in nothing that could. Standard library only. (Promise #1.)
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Robomba/stopgate"
+Source = "https://github.com/Robomba/stopgate"
+
+[project.scripts]
+stopgate = "stopgate.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stopgate = ["data/*.jsonl"]

stopgate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stopgate-0.1.0/src/stopgate/__init__.py

@@ -0,0 +1,12 @@
+"""Stopgate — stop watching your agent.
+
+A local-first safety envelope for coding agents. Detection is by PROVENANCE and
+DATAFLOW, never keywords: every tool result is tagged trusted/untrusted, an
+untrusted read taints the session, high-risk actions near untrusted content
+escalate, and outbound bytes are matched (by rolling hash) against secrets read
+earlier in the session.
+
+Stopgate makes zero network calls of its own. Standard library only.
+"""
+
+__version__ = "0.1.0"