ai-agent-security-toolkit 0.4.1__tar.gz

ai_agent_security_toolkit-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dustin Arrington
+
+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.

ai_agent_security_toolkit-0.4.1/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: ai-agent-security-toolkit
+Version: 0.4.1
+Summary: Security toolkit for LLM agents: prompt-injection fuzzer, tool-call allowlist/sandbox, output validation + tamper-evident audit logging, and a STRIDE-for-agents threat-modeling template.
+Author: Dusty
+License: MIT
+Project-URL: Homepage, https://github.com/DustyStudy/ai-agent-security-toolkit
+Project-URL: Issues, https://github.com/DustyStudy/ai-agent-security-toolkit/issues
+Project-URL: Changelog, https://github.com/DustyStudy/ai-agent-security-toolkit/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/DustyStudy/ai-agent-security-toolkit/security/policy
+Keywords: llm,agents,prompt-injection,security,red-team,sandbox,audit,threat-modeling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.20
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == "mcp"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-jsonschema>=4.20; extra == "dev"
+Dynamic: license-file
+
+# ai-agent-security-toolkit
+
+[![CI](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/codeql.yml/badge.svg)](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/DustyStudy/ai-agent-security-toolkit/badge)](https://scorecard.dev/viewer/?uri=github.com/DustyStudy/ai-agent-security-toolkit)
+[![Release](https://img.shields.io/github/v/release/DustyStudy/ai-agent-security-toolkit)](https://github.com/DustyStudy/ai-agent-security-toolkit/releases)
+
+**Fuzz, contain, validate, and audit LLM agents.** Four pieces that fit together:
+
+| | Module | What it does |
+|---|---|---|
+| 1 | [`agentsec.fuzzer`](src/agentsec/fuzzer) | Prompt-injection test harness. 25 payloads x 10 obfuscations x 2 delivery modes = 500 cases, mechanically scored with canaries (no judge model). Emits JSON/Markdown and gates CI on attack-success rate. |
+| 2 | [`agentsec.sandbox`](src/agentsec/sandbox) | Deny-by-default tool allowlist for agent frameworks: per-argument validation, path confinement, SSRF checks on URL arguments, rate limits, human approval, and **taint tracking** that blocks side-effecting tools after untrusted content is read. Plus a no-shell subprocess runner. |
+| 3 | [`agentsec.middleware`](src/agentsec/middleware) | Output validation (secrets/PII, markdown-image exfiltration, XSS markup, JSON-schema, protected strings) and a **hash-chained, tamper-evident audit log** with secret redaction. |
+| 4 | [`agentsec.threatmodel`](src/agentsec/threatmodel) | **STRIDE-for-agents** threat catalog (25 threats mapped to the OWASP LLM Top 10 2025, the OWASP Top 10 for Agentic Applications 2026 and MITRE ATLAS) and a generator that turns a YAML system description into a threat model with data-flow diagram, threat register, and verification plan. |
+
+```mermaid
+flowchart LR
+  U[User / untrusted content] --> S[screen_input<br/>scan + taint + spotlight]
+  S --> M[(LLM)]
+  M -->|tool_use| G[ToolGuard<br/>allowlist + args + taint + approval]
+  G --> T[Tools]
+  T -->|results = untrusted| S
+  M -->|text| O[screen_output<br/>secrets, exfil links, markup]
+  O --> R[Response]
+  S -.-> A[(Audit log<br/>hash chain)]
+  G -.-> A
+  O -.-> A
+  F[Fuzzer] -. measures .-> S & G & O
+```
+
+**New here?** Take the [five-minute tour](docs/TOUR.md) (real output, no API key needed). **Deploying it?** Read the [production guide](docs/PRODUCTION.md).
+
+## Why this exists
+
+A prompt-injection filter will be bypassed; that is a property of the problem, not of any one filter. What you can control is **blast radius**: what the agent is *allowed* to do once its instructions have been hijacked, what leaves the system, and whether you can reconstruct what happened. This toolkit is built around that idea, and around **measuring** it rather than asserting it.
+
+### Simulator results (not a model benchmark)
+
+> **These numbers come from the built-in deterministic simulator, not from an LLM.** They show how the controls behave when the model obeys every injection. They are not a claim about the security of Claude, GPT, Gemini or any other model. See [Honest limitations](#honest-limitations).
+
+| Target | Attack-success rate | tool_misuse | exfiltration | prompt_leak | canary echo |
+|---|---:|---:|---:|---:|---:|
+| `builtin:naive` (obeys any injection) | **100%** | 100% | 100% | 100% | 100% |
+| `builtin:guarded-noscanner` (policy + output guard only) | **60%** | 0% | 0% | 0% | 100% |
+| `builtin:guarded` (+ heuristic scanner) | **34%** | 0% | 0% | 0% | 57% |
+
+Read it this way: tool policy and output validation reduce the *dangerous* outcomes (side effects, exfiltration, secret leaks) to zero **even when the model is fully compromised**. Merely getting the model to say something (canary echo) cannot be stopped by those layers, and the pattern-matching scanner only catches part of it. Base64, ROT13, homoglyphs, leetspeak and non-English variants slip past it, while zero-width and Unicode-tag smuggling are caught. [Full sample report](docs/sample-fuzz-report.md).
+
+**Against a real model:** the same matrix run against Llama 3.1 8B on a local GPU took the attack-success rate from 34.9% for the model alone to 0.2% behind the full stack, with no forbidden tool call, leak or exfiltration getting through. Method, scope and every number are in [docs/PROOF.md](docs/PROOF.md).
+
+## Install
+
+```bash
+pip install -e ".[dev]"          # from a clone
+pip install -e ".[anthropic]"    # optional: fuzz Claude models directly
+```
+
+Python 3.11+. Runtime dependencies: `PyYAML`, `jsonschema`.
+
+## 1. Fuzz an agent
+
+```bash
+# self-check against the built-in simulators
+agentsec fuzz --target builtin:guarded --md report.md --json report.json
+
+# your own agent, as a Python callable: def my_agent(prompt: str) -> str
+agentsec fuzz --target mypkg.agent:respond --max-asr 0.10
+
+# an HTTP endpoint fronting your agent
+agentsec fuzz --target https://staging.example.com/agent/chat
+
+# a Claude model directly (needs ANTHROPIC_API_KEY)
+agentsec fuzz --target anthropic:claude-sonnet-5-5 --max-cases 100
+
+# a local model through Ollama (no API key), bare and behind the toolkit's guards
+agentsec fuzz --target ollama:llama3.1:8b
+agentsec fuzz --target guarded:ollama:llama3.1:8b
+```
+
+Each case plants a random **canary** (split in two so a model that merely *quotes* the injection does not count), a **system-prompt secret**, and a set of **forbidden tools**. An attack succeeds if the response contains the canary or the secret, calls a forbidden tool, references the attacker domain in tool arguments, or renders a markdown/HTML image or link to the attacker domain. Results break down by goal, category, obfuscation, and delivery (payload typed by the user vs. hidden in a retrieved document).
+
+`--max-asr 0.05` makes the command exit `1` above 5%, so it can gate a release. Add `--categories tool_misuse,exfiltration,prompt_leak --max-asr 0` to gate specifically on containment.
+
+**CI reports.** `--sarif report.sarif` writes SARIF 2.1.0 for GitHub code scanning and `--junit report.xml` writes JUnit XML for any CI test UI. Successful attacks become findings (`error` for tool misuse, exfiltration and prompt leak; `warning` for instruction-following), each tagged with its OWASP LLM Top 10 (2025) id. Fuzz findings have no source location, so pass `--sarif-artifact path/to/agent.py` (repo-relative) to say which file the alerts attach to.
+
+```yaml
+# .github/workflows/agent-fuzz.yml (excerpt)
+permissions: {contents: read, security-events: write}
+steps:
+  - run: agentsec fuzz --target mypkg.agent:respond --max-asr 0.10 --quiet
+         --sarif agentsec.sarif --sarif-artifact src/mypkg/agent.py
+  - uses: github/codeql-action/upload-sarif@v4
+    if: always()
+    with: {sarif_file: agentsec.sarif}
+```
+
+Text taken from the target's output is bounded and stripped of control characters before it enters either format. The SARIF output is validated against the official 2.1.0 schema in the tests; it has not been uploaded to GitHub code scanning by this repo's CI.
+
+Targets may be `async def`: `agentsec fuzz --target mypkg.agent:respond` detects a coroutine function and runs it on one reused event loop, and `text_target` / `sync_target` do the same when you call the harness from Python.
+
+For richer targets, pass a callable that accepts an `AttackInput` and returns a `TargetResponse` (with `tool_calls`); see [`targets.py`](src/agentsec/fuzzer/targets.py).
+
+## 2. Constrain tool calls
+
+Policies are data, so they can be reviewed and diffed. Unknown keys are load-time errors and anything unlisted is denied. See [`examples/policy.yaml`](examples/policy.yaml).
+
+```python
+from agentsec.sandbox import Policy, ToolGuard, Session
+
+guard = ToolGuard(Policy.from_yaml("policy.yaml"), approver=ask_a_human)
+session = Session()
+
+# Wrap a function; the model's arguments are validated before it ever runs.
+search = guard.wrap("search_docs", search_docs, session)
+search(query="Q3 revenue")                       # allowed; result marks the session tainted
+guard.wrap("http_get", http_get, session)(       # ToolDenied: session read untrusted content
+    url="https://api.corp.example/x")            # and http_get has side effects
+```
+
+What the guard enforces:
+
+- **Default deny.** Tools and arguments not in the policy are refused; extra arguments are refused.
+- **Argument constraints.** Type, enum, regex (`pattern`, `deny_patterns`), length, numeric bounds.
+- **Paths** are resolved (symlinks and `..` included) and must sit under an allowed root.
+- **URLs** must match scheme and host allowlists, reject embedded credentials, and reject every non-global address (private, loopback, link-local, carrier-grade NAT) including the `169.254.169.254` and `100.100.100.200` metadata services and decimal/hex/octal/IPv4-mapped IP forms, plus `localhost` and `*.localhost` names. Any other hostname is only checked if `resolve_dns: true` is set, which rejects hostnames that resolve to non-public ranges. (This narrows DNS-rebinding exposure but does not eliminate it; pin the resolved address at connect time for a full fix.)
+- **Taint tracking.** Tools marked `returns_untrusted` taint the session; tools marked `side_effects` are then denied (or routed to approval) for the rest of that session. This breaks the "private data + untrusted content + outbound channel" combination without needing to detect the injection.
+- **Human approval** hook, per-tool and per-session call limits, and an audit trail of every request and decision.
+
+Drop-in helpers for the tool-calling wire formats: `run_anthropic_tool_uses` and `run_openai_tool_calls` turn model tool requests into results, with denials returned as error text the model can read. See the complete loop in [`examples/agent_loop.py`](examples/agent_loop.py).
+
+### Async, LangChain, LangGraph, MCP and subprocesses
+
+Each has its own section in [`docs/SANDBOX.md`](docs/SANDBOX.md), with the limits of what was tested.
+
+| Use | Entry point |
+|---|---|
+| `asyncio` applications (FastAPI, LangGraph) | `aauthorize`, `aexecute`, `awrap`, `arun_anthropic_tool_uses`, `arun_openai_tool_calls`. Same policy, taint, limit and audit behavior as the sync API. [`examples/async_agent_loop.py`](examples/async_agent_loop.py) |
+| LangChain and LangGraph tools | `agentsec.integrations.langchain.guard_tools([...], guard, session)` |
+| MCP servers | `agentsec.integrations.mcp.GuardedMCPClient`: allowlists and pins tool definitions, and drops poisoned or changed ones |
+| External commands | `SafeCommandRunner`: no shell, executable and option allowlists, scrubbed environment, timeout. It is **not** an OS sandbox |
+
+## 3. Validate output and keep an audit trail
+
+```python
+from agentsec.middleware import AgentMiddleware, AuditLogger, FileSink, InjectionScanner, OutputGuard
+
+audit = AuditLogger(FileSink("audit.jsonl"), actor="support-copilot")
+mw = AgentMiddleware(
+    guard=guard,
+    scanner=InjectionScanner(),
+    output_guard=OutputGuard.default(allowed_hosts=["corp.example"], protected=[SYSTEM_PROMPT_CANARY]),
+    audit=audit,
+)
+
+screen = mw.screen_input(ticket_text, source="ticket", untrusted=True, session=session)
+...
+result = mw.screen_output(model_text)      # redacts secrets/PII, strips external images, blocks XSS markup
+```
+
+```bash
+agentsec audit verify audit.jsonl           # exit 1 if any record was edited or removed
+```
+
+The audit log chains records with SHA-256. Editing or deleting a record in the middle breaks verification from that point. It does **not** stop someone with write access from truncating the tail or replacing the whole file; ship records to append-only storage (S3 Object Lock, CloudWatch Logs with a restrictive resource policy) and anchor `AuditLogger.checkpoint()` somewhere the agent host cannot write. Secrets and PII are redacted before hashing, and `log_content=False` stores only hashes and lengths of long fields.
+
+**SIEM feed (CEF).** Keep the hash-chained file as the evidence of record and stream a copy to your SIEM in ArcSight Common Event Format, which Splunk, Microsoft Sentinel, QRadar, Elastic and most syslog pipelines ingest:
+
+```python
+from agentsec.middleware import AuditLogger, CefSink, FileSink, TeeSink
+
+audit = AuditLogger(TeeSink(FileSink("audit.jsonl"), CefSink(send_to_syslog)))   # or format_cef(record) yourself
+```
+
+Every CEF value is escaped and bounded, so attacker-influenced text cannot forge a field or start a new event. A failing SIEM sink does not interrupt the agent or break the chain. Details are in the [production guide](docs/PRODUCTION.md#audit-trail). The CEF output has not been ingested by a specific SIEM product.
+
+## 4. Threat model an agent (STRIDE-for-agents)
+
+```bash
+agentsec threatmodel init -o system.yaml     # describe components, trust zones, data flows
+agentsec threatmodel render system.yaml -o THREATMODEL.md
+```
+
+The generator selects candidate threats by component type, draws the data-flow diagram with trust-boundary crossings, gives each row a triage hint (raised for components that ingest untrusted input, have side effects, or hold sensitive data), and links each threat to its mitigations, the toolkit control that implements it, and the fuzzer categories that test it. See the worked example: [`docs/threat-model/EXAMPLE-support-copilot.md`](docs/threat-model/EXAMPLE-support-copilot.md), the [method and blank template](docs/threat-model/README.md), and `agentsec threatmodel catalog`. Each threat is also mapped to the [OWASP Top 10 for Agentic Applications (2026)](https://genai.owasp.org/2025/12/09/owasp-top-10-for-agentic-applications-the-benchmark-for-agentic-security-in-the-age-of-autonomous-ai/) and to [MITRE ATLAS](https://github.com/mitre-atlas/atlas-data) techniques (content release 2026.09). `agentsec threatmodel crosswalk` prints the [framework crosswalk](docs/threat-model/frameworks.md), which lists the toolkit controls and fuzzer categories behind each entry.
+
+## Coverage against OWASP Top 10 for LLM Applications (2025)
+
+| Risk | Where this toolkit helps |
+|---|---|
+| LLM01 Prompt injection | Fuzzer (measure), scanner + spotlighting (reduce), taint policy (contain) |
+| LLM02 Sensitive information disclosure | Secret/PII redaction, protected-string tripwire, audit redaction |
+| LLM03 Supply chain | Threat catalog entries and mitigations (no runtime control here) |
+| LLM04 Data and model poisoning | Catalog + retrieval-time scanning |
+| LLM05 Improper output handling | `OutputGuard` validators: markup, exfil links, JSON schema |
+| LLM06 Excessive agency | Deny-by-default `Policy`, approval, taint, `SafeCommandRunner` |
+| LLM07 System prompt leakage | Fuzzer `prompt_leak` category, `ProtectedStringValidator` |
+| LLM08 Vector and embedding weaknesses | Catalog entries only |
+| LLM09 Misinformation | Out of scope |
+| LLM10 Unbounded consumption | Per-session call limits, subprocess timeouts and output caps |
+
+The catalog also covers all ten OWASP agentic risks; the [crosswalk](docs/threat-model/frameworks.md) shows which toolkit controls back each one. A mapping means a threat is an instance of, or contributes to, that entry, not that the entry is mitigated. NIST AI RMF and ISO/IEC 42001 are not mapped.
+
+## Honest limitations
+
+- **The built-in agents are simulators.** `NaiveAgent` deterministically obeys injections and understands common obfuscations; it exists so the harness, detectors and CI gate can be tested offline. The numbers above show how *these controls behave when the model is compromised*, not how any real model behaves. Run the fuzzer against your real agent for that. `AnthropicTarget` and `HttpTarget` are tested against fakes and a local server, and have not been run against a live endpoint by this repo's CI. `OllamaTarget` has been run against a real local model once, by hand ([docs/PROOF.md](docs/PROOF.md)); CI does not run a model.
+- **Canary-echo success is a proxy.** It measures whether the model followed an injected instruction, which is the necessary first step of every real attack, but not the impact of a real one.
+- **The corpus is a starting set** of well-known technique families, not an exhaustive or adaptive attacker. Extend it with your own payloads (`FuzzConfig(corpus=...)`).
+- **The scanner is a tripwire.** Its documented bypasses are asserted in the tests on purpose.
+- **Output validators are pattern-based** and will not catch data a model re-encodes.
+- **No OS-level isolation.** Use containers/microVMs for code execution, and IMDSv2 with hop limit 1 for cloud-hosted agents.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests && ruff format --check src tests
+mypy src
+pytest --cov=agentsec
+```
+
+CI runs lint, type-check and tests on Linux (Python 3.11 to 3.13) and Windows and macOS (3.11, 3.12), builds and checks the package, validates the example policy, re-generates the example threat model to confirm it is current, and runs the fuzzer as a regression check that the containment layers still hold at 0% for tool misuse, exfiltration and prompt leak. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## Project health
+
+The [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/DustyStudy/ai-agent-security-toolkit) badge reflects a young, solo-maintained project. Code-Review and Contributors need other people, and Maintained scores 0 for any repository under 90 days old. The checks about the code and supply chain (pinned dependencies, fuzzing, signed releases, token permissions, SAST, vulnerabilities) are the informative ones. `codeql-action` is left on its major tag deliberately, because GitHub gates some features on the tag.
+
+## License
+
+MIT

ai_agent_security_toolkit-0.4.1/README.md

@@ -0,0 +1,230 @@
+# ai-agent-security-toolkit
+
+[![CI](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/codeql.yml/badge.svg)](https://github.com/DustyStudy/ai-agent-security-toolkit/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/DustyStudy/ai-agent-security-toolkit/badge)](https://scorecard.dev/viewer/?uri=github.com/DustyStudy/ai-agent-security-toolkit)
+[![Release](https://img.shields.io/github/v/release/DustyStudy/ai-agent-security-toolkit)](https://github.com/DustyStudy/ai-agent-security-toolkit/releases)
+
+**Fuzz, contain, validate, and audit LLM agents.** Four pieces that fit together:
+
+| | Module | What it does |
+|---|---|---|
+| 1 | [`agentsec.fuzzer`](src/agentsec/fuzzer) | Prompt-injection test harness. 25 payloads x 10 obfuscations x 2 delivery modes = 500 cases, mechanically scored with canaries (no judge model). Emits JSON/Markdown and gates CI on attack-success rate. |
+| 2 | [`agentsec.sandbox`](src/agentsec/sandbox) | Deny-by-default tool allowlist for agent frameworks: per-argument validation, path confinement, SSRF checks on URL arguments, rate limits, human approval, and **taint tracking** that blocks side-effecting tools after untrusted content is read. Plus a no-shell subprocess runner. |
+| 3 | [`agentsec.middleware`](src/agentsec/middleware) | Output validation (secrets/PII, markdown-image exfiltration, XSS markup, JSON-schema, protected strings) and a **hash-chained, tamper-evident audit log** with secret redaction. |
+| 4 | [`agentsec.threatmodel`](src/agentsec/threatmodel) | **STRIDE-for-agents** threat catalog (25 threats mapped to the OWASP LLM Top 10 2025, the OWASP Top 10 for Agentic Applications 2026 and MITRE ATLAS) and a generator that turns a YAML system description into a threat model with data-flow diagram, threat register, and verification plan. |
+
+```mermaid
+flowchart LR
+  U[User / untrusted content] --> S[screen_input<br/>scan + taint + spotlight]
+  S --> M[(LLM)]
+  M -->|tool_use| G[ToolGuard<br/>allowlist + args + taint + approval]
+  G --> T[Tools]
+  T -->|results = untrusted| S
+  M -->|text| O[screen_output<br/>secrets, exfil links, markup]
+  O --> R[Response]
+  S -.-> A[(Audit log<br/>hash chain)]
+  G -.-> A
+  O -.-> A
+  F[Fuzzer] -. measures .-> S & G & O
+```
+
+**New here?** Take the [five-minute tour](docs/TOUR.md) (real output, no API key needed). **Deploying it?** Read the [production guide](docs/PRODUCTION.md).
+
+## Why this exists
+
+A prompt-injection filter will be bypassed; that is a property of the problem, not of any one filter. What you can control is **blast radius**: what the agent is *allowed* to do once its instructions have been hijacked, what leaves the system, and whether you can reconstruct what happened. This toolkit is built around that idea, and around **measuring** it rather than asserting it.
+
+### Simulator results (not a model benchmark)
+
+> **These numbers come from the built-in deterministic simulator, not from an LLM.** They show how the controls behave when the model obeys every injection. They are not a claim about the security of Claude, GPT, Gemini or any other model. See [Honest limitations](#honest-limitations).
+
+| Target | Attack-success rate | tool_misuse | exfiltration | prompt_leak | canary echo |
+|---|---:|---:|---:|---:|---:|
+| `builtin:naive` (obeys any injection) | **100%** | 100% | 100% | 100% | 100% |
+| `builtin:guarded-noscanner` (policy + output guard only) | **60%** | 0% | 0% | 0% | 100% |
+| `builtin:guarded` (+ heuristic scanner) | **34%** | 0% | 0% | 0% | 57% |
+
+Read it this way: tool policy and output validation reduce the *dangerous* outcomes (side effects, exfiltration, secret leaks) to zero **even when the model is fully compromised**. Merely getting the model to say something (canary echo) cannot be stopped by those layers, and the pattern-matching scanner only catches part of it. Base64, ROT13, homoglyphs, leetspeak and non-English variants slip past it, while zero-width and Unicode-tag smuggling are caught. [Full sample report](docs/sample-fuzz-report.md).
+
+**Against a real model:** the same matrix run against Llama 3.1 8B on a local GPU took the attack-success rate from 34.9% for the model alone to 0.2% behind the full stack, with no forbidden tool call, leak or exfiltration getting through. Method, scope and every number are in [docs/PROOF.md](docs/PROOF.md).
+
+## Install
+
+```bash
+pip install -e ".[dev]"          # from a clone
+pip install -e ".[anthropic]"    # optional: fuzz Claude models directly
+```
+
+Python 3.11+. Runtime dependencies: `PyYAML`, `jsonschema`.
+
+## 1. Fuzz an agent
+
+```bash
+# self-check against the built-in simulators
+agentsec fuzz --target builtin:guarded --md report.md --json report.json
+
+# your own agent, as a Python callable: def my_agent(prompt: str) -> str
+agentsec fuzz --target mypkg.agent:respond --max-asr 0.10
+
+# an HTTP endpoint fronting your agent
+agentsec fuzz --target https://staging.example.com/agent/chat
+
+# a Claude model directly (needs ANTHROPIC_API_KEY)
+agentsec fuzz --target anthropic:claude-sonnet-5-5 --max-cases 100
+
+# a local model through Ollama (no API key), bare and behind the toolkit's guards
+agentsec fuzz --target ollama:llama3.1:8b
+agentsec fuzz --target guarded:ollama:llama3.1:8b
+```
+
+Each case plants a random **canary** (split in two so a model that merely *quotes* the injection does not count), a **system-prompt secret**, and a set of **forbidden tools**. An attack succeeds if the response contains the canary or the secret, calls a forbidden tool, references the attacker domain in tool arguments, or renders a markdown/HTML image or link to the attacker domain. Results break down by goal, category, obfuscation, and delivery (payload typed by the user vs. hidden in a retrieved document).
+
+`--max-asr 0.05` makes the command exit `1` above 5%, so it can gate a release. Add `--categories tool_misuse,exfiltration,prompt_leak --max-asr 0` to gate specifically on containment.
+
+**CI reports.** `--sarif report.sarif` writes SARIF 2.1.0 for GitHub code scanning and `--junit report.xml` writes JUnit XML for any CI test UI. Successful attacks become findings (`error` for tool misuse, exfiltration and prompt leak; `warning` for instruction-following), each tagged with its OWASP LLM Top 10 (2025) id. Fuzz findings have no source location, so pass `--sarif-artifact path/to/agent.py` (repo-relative) to say which file the alerts attach to.
+
+```yaml
+# .github/workflows/agent-fuzz.yml (excerpt)
+permissions: {contents: read, security-events: write}
+steps:
+  - run: agentsec fuzz --target mypkg.agent:respond --max-asr 0.10 --quiet
+         --sarif agentsec.sarif --sarif-artifact src/mypkg/agent.py
+  - uses: github/codeql-action/upload-sarif@v4
+    if: always()
+    with: {sarif_file: agentsec.sarif}
+```
+
+Text taken from the target's output is bounded and stripped of control characters before it enters either format. The SARIF output is validated against the official 2.1.0 schema in the tests; it has not been uploaded to GitHub code scanning by this repo's CI.
+
+Targets may be `async def`: `agentsec fuzz --target mypkg.agent:respond` detects a coroutine function and runs it on one reused event loop, and `text_target` / `sync_target` do the same when you call the harness from Python.
+
+For richer targets, pass a callable that accepts an `AttackInput` and returns a `TargetResponse` (with `tool_calls`); see [`targets.py`](src/agentsec/fuzzer/targets.py).
+
+## 2. Constrain tool calls
+
+Policies are data, so they can be reviewed and diffed. Unknown keys are load-time errors and anything unlisted is denied. See [`examples/policy.yaml`](examples/policy.yaml).
+
+```python
+from agentsec.sandbox import Policy, ToolGuard, Session
+
+guard = ToolGuard(Policy.from_yaml("policy.yaml"), approver=ask_a_human)
+session = Session()
+
+# Wrap a function; the model's arguments are validated before it ever runs.
+search = guard.wrap("search_docs", search_docs, session)
+search(query="Q3 revenue")                       # allowed; result marks the session tainted
+guard.wrap("http_get", http_get, session)(       # ToolDenied: session read untrusted content
+    url="https://api.corp.example/x")            # and http_get has side effects
+```
+
+What the guard enforces:
+
+- **Default deny.** Tools and arguments not in the policy are refused; extra arguments are refused.
+- **Argument constraints.** Type, enum, regex (`pattern`, `deny_patterns`), length, numeric bounds.
+- **Paths** are resolved (symlinks and `..` included) and must sit under an allowed root.
+- **URLs** must match scheme and host allowlists, reject embedded credentials, and reject every non-global address (private, loopback, link-local, carrier-grade NAT) including the `169.254.169.254` and `100.100.100.200` metadata services and decimal/hex/octal/IPv4-mapped IP forms, plus `localhost` and `*.localhost` names. Any other hostname is only checked if `resolve_dns: true` is set, which rejects hostnames that resolve to non-public ranges. (This narrows DNS-rebinding exposure but does not eliminate it; pin the resolved address at connect time for a full fix.)
+- **Taint tracking.** Tools marked `returns_untrusted` taint the session; tools marked `side_effects` are then denied (or routed to approval) for the rest of that session. This breaks the "private data + untrusted content + outbound channel" combination without needing to detect the injection.
+- **Human approval** hook, per-tool and per-session call limits, and an audit trail of every request and decision.
+
+Drop-in helpers for the tool-calling wire formats: `run_anthropic_tool_uses` and `run_openai_tool_calls` turn model tool requests into results, with denials returned as error text the model can read. See the complete loop in [`examples/agent_loop.py`](examples/agent_loop.py).
+
+### Async, LangChain, LangGraph, MCP and subprocesses
+
+Each has its own section in [`docs/SANDBOX.md`](docs/SANDBOX.md), with the limits of what was tested.
+
+| Use | Entry point |
+|---|---|
+| `asyncio` applications (FastAPI, LangGraph) | `aauthorize`, `aexecute`, `awrap`, `arun_anthropic_tool_uses`, `arun_openai_tool_calls`. Same policy, taint, limit and audit behavior as the sync API. [`examples/async_agent_loop.py`](examples/async_agent_loop.py) |
+| LangChain and LangGraph tools | `agentsec.integrations.langchain.guard_tools([...], guard, session)` |
+| MCP servers | `agentsec.integrations.mcp.GuardedMCPClient`: allowlists and pins tool definitions, and drops poisoned or changed ones |
+| External commands | `SafeCommandRunner`: no shell, executable and option allowlists, scrubbed environment, timeout. It is **not** an OS sandbox |
+
+## 3. Validate output and keep an audit trail
+
+```python
+from agentsec.middleware import AgentMiddleware, AuditLogger, FileSink, InjectionScanner, OutputGuard
+
+audit = AuditLogger(FileSink("audit.jsonl"), actor="support-copilot")
+mw = AgentMiddleware(
+    guard=guard,
+    scanner=InjectionScanner(),
+    output_guard=OutputGuard.default(allowed_hosts=["corp.example"], protected=[SYSTEM_PROMPT_CANARY]),
+    audit=audit,
+)
+
+screen = mw.screen_input(ticket_text, source="ticket", untrusted=True, session=session)
+...
+result = mw.screen_output(model_text)      # redacts secrets/PII, strips external images, blocks XSS markup
+```
+
+```bash
+agentsec audit verify audit.jsonl           # exit 1 if any record was edited or removed
+```
+
+The audit log chains records with SHA-256. Editing or deleting a record in the middle breaks verification from that point. It does **not** stop someone with write access from truncating the tail or replacing the whole file; ship records to append-only storage (S3 Object Lock, CloudWatch Logs with a restrictive resource policy) and anchor `AuditLogger.checkpoint()` somewhere the agent host cannot write. Secrets and PII are redacted before hashing, and `log_content=False` stores only hashes and lengths of long fields.
+
+**SIEM feed (CEF).** Keep the hash-chained file as the evidence of record and stream a copy to your SIEM in ArcSight Common Event Format, which Splunk, Microsoft Sentinel, QRadar, Elastic and most syslog pipelines ingest:
+
+```python
+from agentsec.middleware import AuditLogger, CefSink, FileSink, TeeSink
+
+audit = AuditLogger(TeeSink(FileSink("audit.jsonl"), CefSink(send_to_syslog)))   # or format_cef(record) yourself
+```
+
+Every CEF value is escaped and bounded, so attacker-influenced text cannot forge a field or start a new event. A failing SIEM sink does not interrupt the agent or break the chain. Details are in the [production guide](docs/PRODUCTION.md#audit-trail). The CEF output has not been ingested by a specific SIEM product.
+
+## 4. Threat model an agent (STRIDE-for-agents)
+
+```bash
+agentsec threatmodel init -o system.yaml     # describe components, trust zones, data flows
+agentsec threatmodel render system.yaml -o THREATMODEL.md
+```
+
+The generator selects candidate threats by component type, draws the data-flow diagram with trust-boundary crossings, gives each row a triage hint (raised for components that ingest untrusted input, have side effects, or hold sensitive data), and links each threat to its mitigations, the toolkit control that implements it, and the fuzzer categories that test it. See the worked example: [`docs/threat-model/EXAMPLE-support-copilot.md`](docs/threat-model/EXAMPLE-support-copilot.md), the [method and blank template](docs/threat-model/README.md), and `agentsec threatmodel catalog`. Each threat is also mapped to the [OWASP Top 10 for Agentic Applications (2026)](https://genai.owasp.org/2025/12/09/owasp-top-10-for-agentic-applications-the-benchmark-for-agentic-security-in-the-age-of-autonomous-ai/) and to [MITRE ATLAS](https://github.com/mitre-atlas/atlas-data) techniques (content release 2026.09). `agentsec threatmodel crosswalk` prints the [framework crosswalk](docs/threat-model/frameworks.md), which lists the toolkit controls and fuzzer categories behind each entry.
+
+## Coverage against OWASP Top 10 for LLM Applications (2025)
+
+| Risk | Where this toolkit helps |
+|---|---|
+| LLM01 Prompt injection | Fuzzer (measure), scanner + spotlighting (reduce), taint policy (contain) |
+| LLM02 Sensitive information disclosure | Secret/PII redaction, protected-string tripwire, audit redaction |
+| LLM03 Supply chain | Threat catalog entries and mitigations (no runtime control here) |
+| LLM04 Data and model poisoning | Catalog + retrieval-time scanning |
+| LLM05 Improper output handling | `OutputGuard` validators: markup, exfil links, JSON schema |
+| LLM06 Excessive agency | Deny-by-default `Policy`, approval, taint, `SafeCommandRunner` |
+| LLM07 System prompt leakage | Fuzzer `prompt_leak` category, `ProtectedStringValidator` |
+| LLM08 Vector and embedding weaknesses | Catalog entries only |
+| LLM09 Misinformation | Out of scope |
+| LLM10 Unbounded consumption | Per-session call limits, subprocess timeouts and output caps |
+
+The catalog also covers all ten OWASP agentic risks; the [crosswalk](docs/threat-model/frameworks.md) shows which toolkit controls back each one. A mapping means a threat is an instance of, or contributes to, that entry, not that the entry is mitigated. NIST AI RMF and ISO/IEC 42001 are not mapped.
+
+## Honest limitations
+
+- **The built-in agents are simulators.** `NaiveAgent` deterministically obeys injections and understands common obfuscations; it exists so the harness, detectors and CI gate can be tested offline. The numbers above show how *these controls behave when the model is compromised*, not how any real model behaves. Run the fuzzer against your real agent for that. `AnthropicTarget` and `HttpTarget` are tested against fakes and a local server, and have not been run against a live endpoint by this repo's CI. `OllamaTarget` has been run against a real local model once, by hand ([docs/PROOF.md](docs/PROOF.md)); CI does not run a model.
+- **Canary-echo success is a proxy.** It measures whether the model followed an injected instruction, which is the necessary first step of every real attack, but not the impact of a real one.
+- **The corpus is a starting set** of well-known technique families, not an exhaustive or adaptive attacker. Extend it with your own payloads (`FuzzConfig(corpus=...)`).
+- **The scanner is a tripwire.** Its documented bypasses are asserted in the tests on purpose.
+- **Output validators are pattern-based** and will not catch data a model re-encodes.
+- **No OS-level isolation.** Use containers/microVMs for code execution, and IMDSv2 with hop limit 1 for cloud-hosted agents.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests && ruff format --check src tests
+mypy src
+pytest --cov=agentsec
+```
+
+CI runs lint, type-check and tests on Linux (Python 3.11 to 3.13) and Windows and macOS (3.11, 3.12), builds and checks the package, validates the example policy, re-generates the example threat model to confirm it is current, and runs the fuzzer as a regression check that the containment layers still hold at 0% for tool misuse, exfiltration and prompt leak. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## Project health
+
+The [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/DustyStudy/ai-agent-security-toolkit) badge reflects a young, solo-maintained project. Code-Review and Contributors need other people, and Maintained scores 0 for any repository under 90 days old. The checks about the code and supply chain (pinned dependencies, fuzzing, signed releases, token permissions, SAST, vulnerabilities) are the informative ones. `codeql-action` is left on its major tag deliberately, because GitHub gates some features on the tag.
+
+## License
+
+MIT

ai_agent_security_toolkit-0.4.1/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-agent-security-toolkit"
+version = "0.4.1"
+description = "Security toolkit for LLM agents: prompt-injection fuzzer, tool-call allowlist/sandbox, output validation + tamper-evident audit logging, and a STRIDE-for-agents threat-modeling template."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Dusty" }]
+keywords = ["llm", "agents", "prompt-injection", "security", "red-team", "sandbox", "audit", "threat-modeling"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "PyYAML>=6.0",
+    "jsonschema>=4.20",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40"]
+mcp = ["mcp>=2"]
+langchain = ["langchain-core>=0.3"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "types-PyYAML>=6.0",
+    "types-jsonschema>=4.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/DustyStudy/ai-agent-security-toolkit"
+Issues = "https://github.com/DustyStudy/ai-agent-security-toolkit/issues"
+Changelog = "https://github.com/DustyStudy/ai-agent-security-toolkit/blob/main/CHANGELOG.md"
+Security = "https://github.com/DustyStudy/ai-agent-security-toolkit/security/policy"
+
+[project.scripts]
+agentsec = "agentsec.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agentsec = ["py.typed", "threatmodel/data/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.coverage.run]
+source = ["agentsec"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S"]
+# Fuzz targets signal a broken invariant with `assert`.
+"fuzz/*" = ["S101"]
+# Deliberately-vulnerable simulator + attack corpus: fake credentials and
+# canary strings are the point of these files.
+"src/agentsec/fuzzer/mock_agents.py" = ["S105", "S106"]
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["agentsec"]
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+check_untyped_defs = true
+disallow_untyped_defs = true

ai_agent_security_toolkit-0.4.1/setup.cfg

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

ai_agent_security_toolkit-0.4.1/src/agentsec/__init__.py

@@ -0,0 +1,3 @@
+"""ai-agent-security-toolkit: fuzz, contain, validate and audit LLM agents."""
+
+__version__ = "0.4.1"