agent-sleuth 0.0.1__tar.gz

agent_sleuth-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+# Build
+dist/
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+
+# Test / lint caches
+.pytest_cache/
+.ruff_cache/

agent_sleuth-0.0.1/AGENT_SLEUTH_ARCHITECTURE.MD

@@ -0,0 +1,512 @@
+# Agent Sleuth — Architecture & Design Document
+
+**Status:** Authoritative design spec for implementation. Read this fully before writing code.
+**Audience:** The engineer/agent building this repo (you).
+**Last updated:** June 2026
+
+---
+
+## 0. TL;DR (read this, then read the rest)
+
+Agent Sleuth is an **in-process information-flow-control (IFC) library for LLM agents**. It prevents untrusted data (web page contents, email bodies, tool outputs, retrieved documents) from triggering **consequential actions** (sending email, writing files, posting to external services) inside an agent.
+
+The one-sentence README, which everything must serve:
+
+> **Prevents untrusted data from triggering consequential actions in your agent.**
+
+The core mechanism is **value-level provenance lineage tracked at the tool-I/O boundary** — *not* taint-tracking through the model's forward pass. When an untrusted tool returns data, we fingerprint the specific values in it. When a later consequential ("sink") tool call's arguments contain those fingerprinted values — verbatim or via structured field tracking — we have a **deterministic, classifier-free provenance edge**: "this string in `send_email.to` is byte-for-byte a value the untrusted web page returned." A small policy then fires: untrusted-origin value reaching a non-allowlisted external sink → **block or confirm**.
+
+Integration is **three lines of code** and **zero changes to the developer's agent**:
+
+```python
+from agent_sleuth import Sleuth
+
+agent = Sleuth(
+    agent=your_existing_agent,
+    untrusted=["read_email", "fetch_url", "search_web"],
+    consequential=["send_email", "write_file", "post_slack"],
+    mode="audit",  # → "enforce" once they trust it
+)
+result = agent.run("summarize my emails and send a report to my boss")
+print(agent.report())
+```
+
+The moat is **not the technology** — the research already proved the mechanism works. The moat is **making IFC adoptable by a developer who is not a security researcher**: sensible defaults, drop-in install, audit-mode-first, and a caught-attack log that is genuinely readable and shareable.
+
+---
+
+## 1. Why this design exists — the technical core
+
+### 1.1 The wall that kills the naive idea
+
+The obvious framing is "lightweight drop-in taint-tracking for agents." It does not work, and it's important to understand *why* before building, because the failure dictates the entire architecture.
+
+Classical taint analysis (Denning's IFC, TaintDroid) is **sound** because it propagates labels through **deterministic, discrete operations** — assignment, concatenation, arithmetic — where you know exactly which inputs flowed into which outputs.
+
+An LLM is the opposite: it is a **giant mixing function**. The moment untrusted text enters the context window, *everything* the model emits afterward is potentially a function of it. There is no principled way to say token 12 of the output is tainted but token 13 isn't. Naive taint propagation through the planner collapses to **"everything downstream of one web fetch is High-taint,"** no consequential action can ever fire, and the agent becomes useless. This is **taint explosion / over-tainting**, and it is the reason you cannot bolt a tracker onto a normal agent loop.
+
+This is also why the heavyweight academic systems are heavy. **Neither CaMeL nor FIDES actually taint-tracks through the LLM:**
+
+- **CaMeL** has a privileged model emit a *program*; the tracked data flow then happens in a Python interpreter (deterministic ops), and untrusted data never re-enters the privileged model's reasoning. This forces a program-synthesis rewrite of the agent.
+- **FIDES** hides untrusted values in variables and only lets a *quarantined* LLM peek via constrained decoding — output clamped to a bool or typed value, bounding the channel to a few bits. This forces quarantine-plus-policy infrastructure.
+
+Both buy soundness by **moving the security-relevant flow out of the LLM and into deterministic code.** That is exactly the heaviness Agent Sleuth must avoid.
+
+The tension is structural: **lightness wants to keep the normal agent loop; soundness wants to confine the flow to deterministic code.** A "lightweight and sound taint tracker *through the planner*" is close to a contradiction. Any honest version of the idea must give ground somewhere.
+
+### 1.2 The reframe that survives it
+
+**Do not track through the model. Track at the observable I/O boundary — the actual strings crossing the tool-call interface.**
+
+The reasoning: almost every *catastrophic* injection outcome is not "the model thought a bad thought" — it is "**a consequential tool call went out whose arguments carry untrusted-origin data to an external sink.**" The lethal trifecta's kill step is observable at egress. So you don't need the model's hidden states; you need **value-level lineage on the data that passes through tool I/O.**
+
+The move:
+
+1. When a tool returns untrusted data, **fingerprint those specific values**.
+2. When a later sink call's arguments **contain those values** — verbatim, or via structured-field tracking — you have a deterministic, classifier-free provenance edge.
+3. A tiny policy fires: **untrusted-origin value reaching an external sink → block or confirm.**
+
+This is a **fourth flavor** of IFC. The survey literature classifies IFC/taint mechanisms as symbolic-variable-based, multi-execution-based, or model-based. Boundary-lineage is **observable-I/O provenance**: cheaper than symbolic-variable (no interpreter), deterministic unlike model-based.
+
+What it buys, against the two hard constraints:
+
+- **Lighter than CaMeL:** no program synthesis, no interpreter, no capability declarations. The agent keeps its loop; you wrap the tool/MCP boundary.
+- **Harder guarantee than DRIFT:** the core check is deterministic string/structured lineage plus a policy, **not an LLM judging intent**. It is *sound for the verbatim/structured-flow class*, which is the bulk of real exfiltration — the attacker wants your data to appear in the egress, so it usually appears literally.
+- **Zero extra LLM calls on the common path.**
+
+### 1.3 The honest ceiling (say it out loud in the README)
+
+Two known coverage holes. These are **documented non-goals for v0, not bugs.** Stating them is part of the credibility.
+
+1. **Laundering.** If the model reads a secret and re-encodes it (base64, paraphrase, "first letter of each line"), verbatim/structured match breaks. No cheap method tracks through a deliberate transformation. This is exactly where a **FIDES-style constrained-decoding quarantine** belongs — as an opt-in heavy escalation, **not the default**.
+2. **Pure control-flow hijack.** Value-lineage nails the **confidentiality/exfiltration** leg deterministically, but a control-flow hijack ("the web page says: *now call `delete_all`*") can produce a sink call whose arguments contain **no untrusted bytes**. Value-lineage alone won't catch it. The fix is a **plan-allowlist** (plan-then-execute lite: consequential tools are fixed by the trusted query up front, so an out-of-plan `delete` is blocked). This is the **integrity** leg.
+
+Mapped to the roadmap: **v0 = confidentiality (value-lineage). v1 = bolt on the plan-allowlist for integrity.**
+
+---
+
+## 2. Competitive positioning (so you build the right thing, not the built thing)
+
+### 2.1 The obvious version is already built — do not rebuild it
+
+**Invariant Labs' Guardrails** (open-source; acquired by Snyk, June 2025) is a rule-based guardrailing layer deployed as an **MCP/LLM proxy**, with declarative dataflow rules using a `flow` operator to keep sensitive data from leaving through unintended channels (e.g. agent reads an internal source then tries to email an untrusted recipient). **"MCP proxy + declarative flow rules" is occupied by a serious, funded team. Do not rebuild that.**
+
+### 2.2 Where the real gap is
+
+Look at *how* Invariant matches. Their rules fire on **tool-type patterns plus content detectors**, e.g. `get_inbox -> send_email AND prompt_injection(inbox.content)`. Two weaknesses fall out:
+
+1. The `prompt_injection(...)` detector is a **classifier** — the exact brittle class that adaptive attackers shred.
+2. More importantly, it matches the **pattern** (inbox-then-email), **not the lineage**. The rule fires whether or not the email argument *actually contains* the inbox data, and you must **hand-write a rule per tool pair**. (This is the "policy generation is manual and brittle" problem — Invariant has it too.)
+
+So the unoccupied sliver is **not another proxy**. It's the **primitive underneath**: automatic, classifier-free, value-level provenance, so that:
+
+- (a) the guarantee is a **deterministic lineage match** instead of a prompt-injection classifier, and
+- (b) the rules **largely write themselves** — tag sources once, ship a default trifecta policy, instead of authoring N tool-pair rules.
+
+That is an **engine, not a prompt.** It could even slot **under** Invariant as a better detector rather than competing with their platform.
+
+### 2.3 CaMeL / FIDES / DRIFT are not the competitors people think
+
+- **CaMeL** is a research repo that reproduces AgentDojo numbers. As of early 2026 there is no readily-available public CaMeL that a developer can `pip install` and drop into their own agent. **A research repo that reproduces a benchmark is not a product.**
+- **FIDES** is "coming soon to Microsoft Agent Framework" — an open RFC, not shipped, and framework-locked to Microsoft. Not LangChain, not CrewAI, not a raw agent.
+- The space is **crowded with papers and benchmarks**, and **nearly empty of things a developer can pip install and use on an existing agent in five minutes.** Those are different axes. The entire thesis lives on the second one.
+
+The recurring, cited #1 limitation of CaMeL is **its reliance on users to define security policies.** That sounds hard in research framing; in product framing it is a **sensible-defaults problem** (see §6). Researchers are bad at exactly the thing this product is good at.
+
+The analogy: React/Vercel, Supabase/Postgres. The underlying tech was never the moat. **The moat was making it usable.**
+
+### 2.4 The bet, stated plainly
+
+- Microsoft will ship FIDES-in-framework eventually. The bet is that it's (a) locked to their framework, (b) slow, (c) bad at DX, and (d) you can own LangChain/CrewAI/raw-agent users first. Real, winnable, **and** a real risk. Name it.
+- **The moat is speed and developer love, not technology.** The day it stops being easier-to-use than the alternative, it's over.
+
+---
+
+## 3. Architecture decision: in-process library, not a proxy
+
+**Agent Sleuth is an in-process library. The proxy is a later, optional wrapper.**
+
+A proxy only sees the **tool-call boundary**. An in-process library sees the **entire execution graph**:
+
+- The full message history as it builds.
+- The LLM's intermediate reasoning (chain of thought).
+- Tool call arguments **before** they are dispatched.
+- Tool outputs **before** they enter the context window.
+- The causal chain between all of the above.
+
+That difference is the difference between CaMeL (in-process, can *enforce*) and a firewall (boundary-only, can only *observe*). The academic systems that actually work are all in-process. **The library is the core; it is what lets you enforce IFC rather than merely observe it.**
+
+> Note on the layering: being in-process gives you *access* to the full graph. The *enforcement primitive* you actually rely on is value-lineage at tool I/O (§1.2). The richer in-process visibility (CoT, message history) is available for future precision (e.g. confirming a value transited the model) and for the observability trace, but v0 enforcement does not depend on parsing the model's hidden state.
+
+The **MCP proxy** is a product you can build **later** as a thin wrapper around the same core engine — for users who aren't on a supported in-process framework. The core taint/lineage engine must be **framework-agnostic from day one** so both the in-process handlers and a future proxy share it.
+
+---
+
+## 4. System components
+
+The system decomposes into a **framework-agnostic core engine** and **framework adapters**. The core never imports LangChain (or any agent framework). Adapters translate framework callbacks into core calls.
+
+```
+agent_sleuth/
+├── core/
+│   ├── values.py        # TaintedValue, Trust
+│   ├── fingerprint.py   # value fingerprinting + extractables (emails/URLs/tokens/IDs)
+│   ├── store.py         # provenance store (lineage), run-level + value-level taint
+│   ├── policy.py        # IFCPolicy, defaults, sink/source classification, allowlist
+│   ├── lineage.py       # the matching engine: does a sink arg carry untrusted-origin values?
+│   ├── trace.py         # "why blocked" provenance-chain rendering
+│   └── errors.py        # TaintViolationError, etc.
+├── adapters/
+│   ├── langchain.py     # IFCCallbackHandler (BaseCallbackHandler)
+│   ├── decorator.py     # @tracked_tool for raw/custom agents
+│   └── mcp_proxy.py     # (LATER) thin MCP/LLM proxy shim around core
+├── runtime.py           # Sleuth — the public, developer-facing wrapper
+├── config.py            # config loading (YAML), defaults
+└── __init__.py          # exports: Sleuth, tracked_tool, Trust, IFCPolicy
+```
+
+> Naming: prior design sketches used `agentifc` / `IFCRuntime`. The product is **Agent Sleuth**; the public class is **`Sleuth`**. Treat `IFCRuntime` as the legacy alias if you keep one. Pick one and be consistent — `Sleuth` is preferred.
+
+### 4.1 `core/values.py` — the atom
+
+Every piece of data the system tracks is a labeled value.
+
+```python
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+class Trust(Enum):
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+
+@dataclass
+class TaintedValue:
+    value: Any
+    trust: Trust
+    source: str       # which tool produced this
+    trace_id: str     # tracks lineage across hops
+    created_at: float
+
+    def is_tainted(self) -> bool:
+        return self.trust == Trust.UNTRUSTED
+```
+
+This is the atom; everything in the runtime is a `TaintedValue` or derived from one.
+
+### 4.2 `core/fingerprint.py` — turning tool outputs into trackable values
+
+This is the heart of the **value-level** approach and the thing that distinguishes Sleuth from Invariant. On every tool return, you must extract the **specific values** worth tracking, not just label the whole blob.
+
+Strategy:
+
+- **Structured returns (JSON / dict / list):** track **per field**. Each leaf value gets a fingerprint keyed to its source + field path.
+- **Free text:** index by **exact substrings** and, crucially, **high-value extractables** pulled with regex — emails, URLs, tokens/API keys, phone numbers, IDs, account numbers. These structured identifiers are the usual exfil payload, so you get most of the value cheaply without trying to fingerprint every n-gram.
+- **Fingerprint** = a normalized, content-addressed key for a value (e.g. a hash of the normalized string), so lineage matching is a cheap set/substring membership test, not an LLM call.
+
+Output: a set of `(fingerprint, TaintedValue)` records appended to the provenance store.
+
+> Design intent: matching must be **deterministic and classifier-free**. No model is asked "is this an injection?" The question is only "did this exact untrusted-origin value appear in a sink argument?"
+
+### 4.3 `core/store.py` — the provenance store
+
+Holds labels and lineage across tool calls **within a single agent run**. The LLM's context window is stateful; the label store must match that statefulness.
+
+Two levels of granularity, both implemented:
+
+1. **Value-level lineage (primary, the wedge):** a content-addressed store mapping `fingerprint → {source, trust, field_path, trace_id, created_at}`. Used by the lineage engine to answer "does this sink argument contain untrusted-origin values, and from where?"
+2. **Run-level taint (coarse fallback / conservative mode):** a single `_run_taint_level`. Once *any* untrusted data enters the run, the whole run is considered tainted. This is conservative-but-correct (how FIDES handles it) and is the **simplest possible enforcement** — useful as a strict mode and as the bootstrap implementation, but on its own it produces too many false positives for general use (it would block "summarize this page and email it **to me**"). Value-level lineage + the destination allowlist (§4.4) is what makes the product usable.
+
+```python
+class TaintStore:
+    def __init__(self):
+        self._store: dict[str, TaintedValue] = {}
+        self._run_taint_level = Trust.TRUSTED
+
+    def label(self, key: str, value: Any, trust: Trust, source: str): ...
+    def get(self, key: str) -> "TaintedValue | None": ...
+    def get_run_trust(self) -> Trust: ...
+    def is_run_tainted(self) -> bool: ...
+    def reset(self): ...     # fresh taint state per run
+```
+
+`reset()` is called at the start of every `run()` — taint does not bleed across independent agent invocations.
+
+### 4.4 `core/policy.py` — the policy
+
+```python
+@dataclass
+class IFCPolicy:
+    untrusted_sources: list[str]        # tools whose outputs are untrusted
+    consequential_actions: list[str]    # tools that must not run on tainted/untrusted egress
+    destination_allowlist: list[str]    # trusted egress (user's own channels)
+    mode: str = "audit"                 # "audit" | "enforce" | "confirm"
+
+    def is_untrusted_source(self, tool_name: str) -> bool: ...   # exact or prefix match
+    def is_consequential(self, tool_name: str) -> bool: ...      # exact or prefix match
+
+    @classmethod
+    def from_defaults(cls, mode="audit") -> "IFCPolicy": ...
+```
+
+**Destination allowlist** is essential. A consequential call to a **trusted destination** (the user's own email, the user's own Slack) is *not* a violation even with tainted inputs. This is what kills the dominant false positive: *"summarize this page and email it to me."* The user's own channels = trusted egress.
+
+**Defaults from tool-name conventions** (the thing that makes config trivial):
+
+- Untrusted sources: any tool whose name contains `read`, `fetch`, `search`, `get`, `browse`, `retrieve`, `load`.
+- Consequential actions: any tool whose name contains `send`, `write`, `delete`, `post`, `update`, `create`, `execute`, `run`.
+
+Developers override as needed; **most people never touch the defaults.**
+
+### 4.5 `core/lineage.py` — the matching engine
+
+Given a pending sink call (tool name + arguments) and the provenance store, decide whether the call carries untrusted-origin values to a non-allowlisted destination.
+
+Algorithm (v0):
+
+1. If the tool is not consequential → allow.
+2. Extract the **destination field** from the sink args (e.g. `send_email.to`, `http_post.url`, `write_file.path`). If destination ∈ allowlist → allow.
+3. For each value in the sink args, test **value-lineage**: does it contain (verbatim substring, or structured-field equality) any **untrusted-origin fingerprint** from the store?
+4. If yes → **violation**, carrying the lineage chain (which source, which step, which field).
+5. If no untrusted-origin value is present but run-level strict mode is on → optionally violation (strict mode only).
+
+The output of a violation must include the **full lineage chain** for the trace (§4.7).
+
+### 4.6 `adapters/langchain.py` — the interception layer
+
+LangChain is the **first** adapter. Integration is a `BaseCallbackHandler` the developer passes in — **zero changes to their agent.**
+
+```python
+class IFCCallbackHandler(BaseCallbackHandler):
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        # ingress: if consequential AND lineage/run says tainted → record + (enforce) raise
+        ...
+    def on_tool_end(self, output, **kwargs):
+        # egress: fingerprint + label the output (untrusted if source is untrusted)
+        ...
+    def on_llm_start(self, messages, **kwargs):
+        # (optional) audit what's entering the context window
+        ...
+    def on_agent_action(self, action, **kwargs):
+        # (optional) block a consequential action if tainted, pre-dispatch
+        ...
+```
+
+The ingress check on `on_tool_start` builds the violation record and, **only in enforce mode**, raises `TaintViolationError` to halt the call. In audit mode it logs and lets the call proceed.
+
+The egress hook on `on_tool_end` fingerprints and labels the output, marking it untrusted if the producing tool is an untrusted source.
+
+> **Stability hazard:** the LangChain callback API changes. Pin to the stable callback interface, test against multiple LangChain versions, and keep the core engine framework-agnostic so adding CrewAI / Google ADK / raw agents never requires rewriting the engine.
+
+### 4.7 `core/trace.py` — the "why blocked" provenance trace
+
+This is **not a nice-to-have. It is the marketing.** (See §8.) On every violation, render the lineage chain from source to sink in a form that is genuinely readable and shareable:
+
+```
+BLOCKED: send_email() called with tainted inputs
+  Taint source: fetch_url() at step 2
+  Injected value detected in argument: to="attacker@evil.com"
+  Lineage: fetch_url (step 2, untrusted) → value "attacker@evil.com" → send_email.to (step 5)
+  Action: blocked, user notified
+```
+
+Invest in this output more than almost anything else in v0. A screenshot of a caught attack is the entire early growth strategy.
+
+### 4.8 `runtime.py` — `Sleuth`, the public API
+
+The single thing the developer imports. Constructs policy (from explicit lists or defaults), owns the store and handler, resets per run, exposes `violations` and `report()`.
+
+```python
+class Sleuth:
+    def __init__(self, agent, untrusted=None, consequential=None,
+                 destinations=None, mode="audit"):
+        self.policy = (IFCPolicy.from_defaults(mode=mode)
+                       if untrusted is None and consequential is None
+                       else IFCPolicy(untrusted_sources=untrusted or [],
+                                      consequential_actions=consequential or [],
+                                      destination_allowlist=destinations or [],
+                                      mode=mode))
+        self.store = TaintStore()
+        self.handler = IFCCallbackHandler(self.policy, self.store)
+        self.agent = agent
+
+    def run(self, query, **kwargs):
+        self.store.reset()
+        try:
+            return self.agent.run(query, callbacks=[self.handler], **kwargs)
+        except TaintViolationError as e:
+            return str(e)
+
+    @property
+    def violations(self) -> list[dict]: ...
+    def report(self) -> str: ...   # human-readable summary, "✓ none" or enumerated violations
+```
+
+---
+
+## 5. The default policy: the lethal trifecta
+
+Ship with **one default deterministic policy that works at zero config**:
+
+> **Untrusted-origin value reaching a non-allowlisted external sink → block-or-confirm.**
+
+This encodes the lethal trifecta kill step (untrusted input + sensitive data + external egress). It is overridable, but it must do something useful out of the box with no policy file. A working trifecta default shipping out of the box is what answers the "policy generation is manual and brittle" complaint.
+
+---
+
+## 6. Configuration, defaults, and the three friction points
+
+The product lives or dies on these three. Each has a designed fix; implement the fix, don't just expose the knob.
+
+**Friction 1 — who defines untrusted/consequential?**
+For a simple agent it's obvious; for a 20-tool agent it isn't. If config is hard to write, you're abandoned at setup.
+→ **Fix:** sensible name-based defaults (§4.4). Developer overrides as needed. Most never touch them.
+
+**Friction 2 — false positives kill adoption.**
+If you block a legitimate action, developers turn it off. Full stop. (This is the CaMeL-too-aggressive failure DRIFT was reacting to.)
+→ **Fix:** **ship in audit mode by default.** Logs everything, blocks nothing. Developer runs it a week, sees what *would* have been blocked, gains confidence, switches to enforce. This is exactly how Snyk and Datadog Security get adopted. The destination allowlist (§4.4) is the other half of false-positive control.
+
+**Friction 3 — the LangChain callback API is not stable.**
+If your library breaks on a LangChain update, you get uninstalled.
+→ **Fix:** pin to the stable callback interface, test against multiple versions, framework-agnostic core from day one.
+
+**Modes:**
+- `audit` (default): detect + log + render trace; never block.
+- `enforce`: raise `TaintViolationError` and halt the offending sink call.
+- `confirm`: surface the violation to a human/callback for an allow/deny decision before dispatch (the "block-or-confirm" branch of the default policy).
+
+---
+
+## 7. Roadmap — what each version does and does **not** do
+
+### v0 — Confidentiality / exfiltration (ship in days, demo-able, benchmark-able)
+
+The weekend-to-two-weeks slice. **In scope:**
+
+1. **Thin interceptor** — `@tracked_tool` decorator over tool functions *and* the LangChain `IFCCallbackHandler`, both seeing every tool input and output.
+2. **Content-addressed provenance store** — on each tool return, record value-fingerprints → `{source, trust label}`. Structured returns tracked per-field; free text indexed by exact substrings + high-value extractables (emails, URLs, tokens, IDs via regex).
+3. **Consequential sinks** — a small set (`send_email`, `http_post`, `write_file`, …) each with a **destination field**, plus a **destination allowlist** (user's own channels = trusted egress).
+4. **Default deterministic policy** — the lethal trifecta (§5): untrusted-origin value → non-allowlisted external sink → block-or-confirm. Works with zero config.
+5. **"Why blocked" provenance trace** (§4.7) — the lineage chain from source to sink; doubles as observability and the blog/marketing demo.
+
+**v0 explicitly does NOT do:**
+- It does **not** defend against **laundering** (base64/paraphrase/transform of a secret). Documented non-goal.
+- It does **not** defend against **pure control-flow hijack** (sink call whose arguments carry no untrusted bytes). That's v1.
+- It does **not** track taint through the model's hidden states. By design.
+- It does **not** try to be a platform, a proxy, or an enterprise product.
+
+**v0 honest envelope (put this in the README and any benchmark report):**
+> Sound on the verbatim/structured-exfil class. Zero extra LLM calls on the common path. Drop-in. Laundering and control-flow hijack explicitly out of scope for v0.
+
+### v1 — Integrity / control-flow
+
+- **Plan-allowlist (plan-then-execute lite):** consequential tools are fixed by the **trusted query** up front, so an out-of-plan `delete_all` injected by a web page is blocked even though its arguments carry no untrusted bytes. This closes the control-flow-hijack hole.
+- More granular taint (move beyond run-level strict mode where needed; richer per-value transitive lineage).
+- Additional framework adapters: **CrewAI**, **Google ADK**, raw-agent decorator hardening.
+
+### v2+ — Heavier guarantees & reach (opt-in, not default)
+
+- **FIDES-style constrained-decoding quarantine** as an **opt-in heavy escalation** for the laundering class. Never the default — it reintroduces the heaviness v0 exists to avoid.
+- **MCP proxy adapter** — a thin wrapper around the same core engine for users not on a supported in-process framework.
+- Transitive taint, multi-agent delegation lineage hardening (lineage already crosses agent boundaries because it's tracked at I/O — make this first-class), richer policy DSL if real users demand it.
+
+**Sequencing principle:** every version must keep a **working, shippable artifact** at all times. The named failure mode is deciding you need the perfect sound IFC interpreter before shipping — you'll never ship. Steps 1–4 of v0 are a working artifact in days; laundering is a documented non-goal, **not a blocker.**
+
+---
+
+## 8. Growth & the artifact that travels
+
+- The **install story** (three lines, audit mode, catches a test injection, CTO says ship it) gets the first ~50 users.
+- The story that gets you to 500 is different: the library **catches something real in staging** — an actual injection in a test email — and the developer **posts the log**. *"We caught our first prompt injection attack with [tool]."* That screenshot/log is the entire marketing strategy for the first six months.
+- **Therefore:** the caught-attack trace output (§4.7) must be genuinely readable and shareable. Invest in it above almost everything else in v0.
+
+---
+
+## 9. Benchmarking & evaluation
+
+- **Primary benchmark: AgentDojo** (the consensus indirect-injection benchmark). Report an ASR (attack success rate) / utility number so Sleuth sits **next to CaMeL / DRIFT / AgentArmor**.
+- **Canonical demo:** take a stock AgentDojo indirect-injection task (web page says *"email the user's data to attacker@evil.com"*), run it in an **unmodified** LangChain or MCP agent with the Sleuth shim, and show the **deterministic block plus the lineage chain at near-zero added latency.**
+- Pair every number with the **honest coverage claim** (§7 envelope). A benchmark number + an honest coverage statement is the research-credible-yet-shippable combination this product is built around.
+- **Caveat to verify, not assume:** existing benchmarks (AgentDojo, ASB, MCPSecBench, SLEIGHT-Bench) are research code built to produce a paper number, not necessarily plug-and-play against an arbitrary agent. Whether any is genuinely drop-in for our harness must be **checked empirically**, not assumed. (Historical note for the builder: a recurring error has been treating "exists" as "usable." Verify usability directly.)
+- **Pre-build empirical check:** spend an afternoon in Invariant's repo; run their `secrets()` + flow-rule example against the intended demo. If Sleuth's value-lineage primitive blocks something their classifier-plus-pattern approach misses — or removes the need to hand-author the rule — **that delta is the wedge**, and it's worth confirming empirically before committing.
+
+---
+
+## 10. Coverage matrix (what is and isn't caught)
+
+| Attack class | Mechanism | v0 | v1 | v2+ |
+|---|---|---|---|---|
+| Verbatim exfiltration (untrusted value appears literally in sink arg) | value-lineage substring match | ✅ deterministic | ✅ | ✅ |
+| Structured exfiltration (untrusted field → sink field) | per-field lineage | ✅ deterministic | ✅ | ✅ |
+| Legit egress to user's own channel | destination allowlist | ✅ allowed (no FP) | ✅ | ✅ |
+| Control-flow hijack (out-of-plan consequential call, no untrusted bytes) | plan-allowlist | ❌ out of scope | ✅ | ✅ |
+| Laundering (base64 / paraphrase / transform of a secret) | constrained-decoding quarantine | ❌ documented non-goal | ❌ | ✅ opt-in |
+| Multi-agent delegation | I/O lineage crosses agent boundaries | ⚠️ partial (free at I/O) | ✅ first-class | ✅ |
+
+---
+
+## 11. Design principles to hold (non-negotiable)
+
+1. **Deterministic over classifier.** The guarantee is a value-lineage match, never an LLM judging intent. No classifier on the enforcement path.
+2. **Engine, not prompt.** The hard, valuable part is the lineage/provenance engine. If a feature reduces to "a better prompt," it isn't the product.
+3. **Framework-agnostic core from day one.** `core/` never imports an agent framework. Adapters translate. This is what makes the proxy and new frameworks cheap later.
+4. **Audit-mode-first.** Default to observe, never block, until the developer opts into enforce. False positives are existential.
+5. **Zero extra LLM calls on the common path.** Latency and cost must be near-zero, or developers turn it off.
+6. **Sensible defaults; trivial config.** The three-line config must cover the 80% case. Name-based source/sink heuristics + a working trifecta default.
+7. **Ship the slice; document the gaps.** Laundering and control-flow hijack are *documented non-goals* for v0, not reasons to delay. Always keep a working artifact.
+8. **The trace is a feature.** Readable, shareable, caught-attack output is core, not polish.
+
+---
+
+## 12. Open decisions for the implementer to resolve
+
+These are deliberately left open; resolve them early and record the choice in the repo.
+
+- **Package/class naming:** `agent_sleuth` + `Sleuth` (preferred) vs legacy `agentifc` / `IFCRuntime`. Pick one.
+- **Fingerprint representation:** raw normalized string vs hash; how aggressively to normalize (whitespace, case, punctuation) without enabling trivial evasion or inflating false matches.
+- **Free-text extractable set:** exact regex inventory for emails/URLs/tokens/IDs/phone numbers — and how short a substring is allowed to count as a "value" (too short → false matches; too long → misses).
+- **Destination-field resolution:** how to identify the destination/sink field per tool generically (config map vs heuristic vs adapter-supplied schema).
+- **`confirm` mode UX:** how a human/callback approves or denies a pending sink call, in-process.
+- **Run boundary semantics:** confirm `reset()` per top-level `run()` is the right taint scope for nested/streaming/async agents.
+- **Async + streaming:** LangChain async callbacks and streamed tool outputs need first-class handling, not an afterthought.
+
+---
+
+## 13. First implementation milestone (definition of done for v0)
+
+A developer can:
+
+1. `pip install agent_sleuth`.
+2. Wrap an existing LangChain agent in three lines.
+3. Run a stock AgentDojo indirect-injection task in **audit** mode and see a rendered lineage trace of the would-be exfiltration.
+4. Switch to **enforce** mode and watch the same task get **deterministically blocked**, with the source→sink lineage chain printed, at near-zero added latency.
+5. Get an AgentDojo ASR/utility number alongside the honest coverage envelope.
+
+When that loop works end-to-end on an **unmodified** agent, v0 is done.
+
+> **Scope note — trifecta vs. lists vs. prose-negation (added after design review).**
+>
+> **v0 = the lethal-trifecta detector.** The deterministic value-lineage primitive:
+> "untrusted-origin value reached a consequential sink." Ships in audit mode (log +
+> "why blocked" trace) with at most a *trivial implicit* trusted-destination notion —
+> destinations appearing verbatim in the trusted query, extracted by the same
+> deterministic regexes used for fingerprinting (no LLM, no config). v0 deliberately
+> does **not** ship the configurable destination logic. Consequence: v0's enforce mode
+> over-flags (every untrusted→sink fires, including legitimate "email it to me"), which
+> is acceptable because audit is the default. The clean "block the attack, allow the
+> named recipient" enforce/benchmark demo therefore lands in v1, not v0.
+>
+> **v1 = the configurable allow/denylist + integrity leg.** Explicit developer-supplied
+> allowlist and denylist, deny-over-allow precedence, confirm-mode routing for
+> prose-extracted candidates, and the destination-field registry — i.e. everything that
+> makes enforce mode usable instead of blunt. The plan-allowlist (control-flow/integrity
+> leg) ships here too.
+>
+> **Deferred (open problem, not scheduled): negative trust expressed in prose.**
+> "Do NOT email bob@company.com" cannot be honored by deterministic extraction — regex
+> sees the address and can't read the "NOT," and parsing the negation would require an
+> LLM on the enforcement path, which is forbidden. This is a known limitation, not a bug.
+> Workaround for now: negative/authoritative trust lives in **structured config** (a
+> denylist entry), which deterministically overrides any prose-extracted or allowlisted
+> destination (deny > allow > prose-extracted). Revisit only if structured config proves
+> insufficient in practice; do not attempt prose-negation parsing as a default path.

agent_sleuth-0.0.1/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install for development
+pip install -e '.[dev,langchain,config]'
+
+# Run all tests
+pytest
+
+# Run a single test file
+pytest tests/test_e2e.py
+
+# Run a single test by name
+pytest tests/test_e2e.py::test_decorator_enforce_blocks
+
+# Lint
+ruff check agent_sleuth/ tests/
+
+# Run the AgentDojo benchmark
+PYTHONPATH=. python benchmarks/agentdojo/run.py
+
+# Run the quickstart example
+PYTHONPATH=. python examples/quickstart.py
+```
+
+## Architecture
+
+Agent Sleuth is an **in-process IFC (information-flow-control) library** that prevents untrusted tool outputs (web pages, emails, retrieved docs) from reaching consequential sinks (send_email, write_file, post_slack) inside an LLM agent. The mechanism is **value-level provenance lineage tracked at the tool I/O boundary** — not taint-tracking through the model's forward pass.
+
+### Why boundary-lineage, not taint-through-LLM
+
+Classical taint analysis collapses to "everything downstream of one web fetch is tainted" when applied to an LLM (taint explosion). Agent Sleuth avoids this by tracking only the **specific values** that cross the tool boundary: fingerprinting untrusted tool outputs and checking whether those exact values appear verbatim or as structured fields in later sink call arguments. This is deterministic and classifier-free.
+
+### Data flow
+
+1. **Untrusted tool returns** → `Engine.on_tool_result()` → `fingerprint.extract_values()` extracts specific strings/emails/URLs/tokens from the output → stored in `TaintStore` with source + trust label.
+2. **Consequential tool called** → `Engine.on_tool_call()` → `lineage.check()` tests whether any sink argument contains an untrusted-origin fingerprint → returns a `Violation` or `None`.
+3. On violation: **audit** logs it, **enforce** raises `TaintViolationError`, **confirm** routes to a callback.
+
+### Module map
+
+```
+agent_sleuth/
+├── core/
+│   ├── values.py       # TaintedValue + Trust enum — the tracked atom
+│   ├── fingerprint.py  # extract_values(): per-field structured + regex extractables
+│   ├── store.py        # TaintStore: content-addressed fingerprint → TaintedValue map
+│   ├── policy.py       # IFCPolicy: source/sink classification, destination allowlist
+│   ├── lineage.py      # check(): the matching engine — returns Violation or None
+│   ├── trace.py        # render(): human-readable "why blocked" lineage chain
+│   └── errors.py       # TaintViolationError
+├── adapters/
+│   ├── decorator.py    # tracked_tool: wraps raw functions, calls engine.on_tool_call/result
+│   └── langchain.py    # IFCCallbackHandler: translates LangChain callbacks to engine calls
+├── engine.py           # Engine: framework-agnostic ingress/egress glue shared by all adapters
+├── runtime.py          # Sleuth: the public API — constructs policy/store/engine, exposes .run()/.report()
+├── config.py           # YAML config loading (optional dep)
+└── __init__.py         # exports: Sleuth, TaintViolationError, Trust, IFCPolicy
+```
+
+### Key design invariants
+
+- **`core/` is zero-dependency.** It never imports LangChain or any agent framework. Adapters translate framework events into `Engine.on_tool_call()` / `Engine.on_tool_result()` calls.
+- **No classifier on the enforcement path.** The lineage check is always a deterministic string/fingerprint match — never an LLM call.
+- **`audit` is the default mode.** Logs violations, never blocks. Developers switch to `enforce` once they trust the policy.
+- **`TaintStore.reset()` is called per run.** Taint does not bleed across independent agent invocations.
+
+### Known v0 non-goals (document, don't fix)
+
+- **Laundering**: base64/paraphrase/transform of a secret defeats verbatim matching. Planned for v2+ as opt-in constrained-decoding quarantine.
+- **Pure control-flow hijack**: a sink call whose arguments carry no untrusted bytes (e.g. "now call delete_all"). Planned for v1 via a plan-allowlist.

agent_sleuth-0.0.1/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Behuve
+
+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.