agentlatch-security 0.4.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/MANIFEST.in +1 -0
  2. {agentlatch_security-0.4.0/src/agentlatch_security.egg-info → agentlatch_security-0.5.0}/PKG-INFO +331 -103
  3. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/README.md +328 -100
  4. agentlatch_security-0.5.0/docs/GATES.md +86 -0
  5. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/pyproject.toml +3 -3
  6. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/__init__.py +1 -1
  7. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/action_summary.py +3 -6
  8. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/agent_code.py +19 -2
  9. agentlatch_security-0.5.0/src/agent_latch/catalog.py +430 -0
  10. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/cli.py +53 -5
  11. agentlatch_security-0.5.0/src/agent_latch/endpoints.py +155 -0
  12. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/findings.py +3 -1
  13. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/gates/alr04.py +4 -1
  14. agentlatch_security-0.5.0/src/agent_latch/memory.py +113 -0
  15. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/owasp.py +13 -0
  16. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/prompts.py +44 -2
  17. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/report.py +13 -3
  18. agentlatch_security-0.5.0/src/agent_latch/resilience.py +196 -0
  19. agentlatch_security-0.5.0/src/agent_latch/rogue.py +237 -0
  20. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/rules.py +4 -3
  21. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/cli.py +168 -0
  22. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/__init__.py +77 -0
  23. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/anchor.py +143 -0
  24. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/canonical.py +17 -0
  25. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/chain.py +262 -0
  26. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/report.py +281 -0
  27. agentlatch_security-0.5.0/src/agent_latch/runtime/ledger/verify.py +449 -0
  28. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/results.py +213 -16
  29. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/trace.py +31 -1
  30. agentlatch_security-0.5.0/src/agent_latch/sandbox.py +222 -0
  31. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/suppress.py +2 -1
  32. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/taint.py +95 -13
  33. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0/src/agentlatch_security.egg-info}/PKG-INFO +331 -103
  34. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agentlatch_security.egg-info/SOURCES.txt +14 -0
  35. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agentlatch_security.egg-info/requires.txt +2 -2
  36. agentlatch_security-0.5.0/tests/test_ledger.py +495 -0
  37. agentlatch_security-0.5.0/tests/test_runtime_results.py +288 -0
  38. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/test_scanner.py +378 -11
  39. agentlatch_security-0.4.0/tests/test_runtime_results.py +0 -101
  40. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/LICENSE +0 -0
  41. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/setup.cfg +0 -0
  42. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/astutil.py +0 -0
  43. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/gates/__init__.py +0 -0
  44. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/manifest.py +0 -0
  45. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/oversight.py +0 -0
  46. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/__init__.py +0 -0
  47. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/demo.py +0 -0
  48. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/demo_server.py +0 -0
  49. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/events.py +0 -0
  50. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/importer.py +0 -0
  51. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/middleware.py +0 -0
  52. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/normalizer.py +0 -0
  53. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/payloads.py +0 -0
  54. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/proxy.py +0 -0
  55. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/redact.py +0 -0
  56. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/runtime/sqlite_store.py +0 -0
  57. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agent_latch/yamlload.py +0 -0
  58. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agentlatch_security.egg-info/dependency_links.txt +0 -0
  59. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agentlatch_security.egg-info/entry_points.txt +0 -0
  60. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/src/agentlatch_security.egg-info/top_level.txt +0 -0
  61. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/runtime_fixtures/alr04_expected_column.txt +0 -0
  62. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/runtime_fixtures/alr04_normalized_events.json +0 -0
  63. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/runtime_fixtures/fake_server.py +0 -0
  64. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/runtime_fixtures/normalized-sample.json +0 -0
  65. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/test_alr04.py +0 -0
  66. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/test_runtime.py +0 -0
  67. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/test_runtime_importer.py +0 -0
  68. {agentlatch_security-0.4.0 → agentlatch_security-0.5.0}/tests/test_runtime_middleware.py +0 -0
@@ -1,2 +1,3 @@
1
1
  # The sdist ships the tests, so it must also ship the data they read.
2
2
  graft tests/runtime_fixtures
3
+ include docs/GATES.md
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentlatch-security
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: Local-first AI agent security scanner: checks agent code, tool manifests, and prompts for prompt injection, over-privileged tools, and secrets.
5
5
  Author: AgentLatch contributors
6
6
  License-Expression: MIT
@@ -26,12 +26,12 @@ Requires-Dist: rich<15,>=13.9
26
26
  Requires-Dist: rich-argparse<2,>=1.5
27
27
  Requires-Dist: PyYAML<7,>=6
28
28
  Provides-Extra: dev
29
- Requires-Dist: pytest<9,>=8; extra == "dev"
29
+ Requires-Dist: pytest<10,>=9; extra == "dev"
30
30
  Requires-Dist: ruff<1,>=0.8; extra == "dev"
31
31
  Provides-Extra: audit
32
32
  Requires-Dist: pip-audit<3,>=2.10; extra == "audit"
33
33
  Provides-Extra: runtime
34
- Requires-Dist: fastmcp==4.1.0; extra == "runtime"
34
+ Requires-Dist: fastmcp==4.1.4; extra == "runtime"
35
35
  Dynamic: license-file
36
36
 
37
37
  <p align="center">
@@ -57,11 +57,38 @@ Dynamic: license-file
57
57
 
58
58
  > **Project status: early proof of concept.** AgentLatch is not a complete vulnerability scanner, runtime protection system, security score, or certification. A clean scan means only that the enabled checks did not report a finding. The runtime proxy records traffic and runs one preview gate, ALR04, on MCP tool definitions. It reports findings and does not block calls.
59
59
 
60
+ ## What AgentLatch does so far
61
+
62
+ AgentLatch checks an AI agent at three points, and you can use each on its own:
63
+
64
+ 1. **Static scan:** reads an agent project's code, prompts and manifests before anything runs, and reports risky patterns with the file and line.
65
+ 2. **Runtime monitor (preview):** sits between an agent and its MCP server, records the tool traffic with secrets masked, and flags tool definitions that contain instruction-like content.
66
+ 3. **Tamper-evident ledger (preview):** seals that record in a hash chain, so an edited, deleted or rebuilt log shows up when you verify it.
67
+
68
+ Everything runs on your machine and nothing is uploaded. The only network use is the opt-in `--dependencies` audit. AgentLatch reports findings and never blocks a tool call, and a clean result is not a security guarantee.
69
+
70
+ ![What stays on your machine: project files flow through the AgentLatch scanner to reports and CI, all locally. An optional dependency audit, off by default, sends only package names and versions to an advisory service.](docs/assets/diagrams/local-boundary.svg)
71
+
72
+ Every section below follows the same four steps: what it does, **Run it** (copy-paste), **See the result** (the command that shows the output), and **Go deeper** (links).
73
+
74
+ | I want to… | Go to |
75
+ |---|---|
76
+ | Scan an agent project on my laptop | [1. Static scan](#1-static-scan-local) |
77
+ | Fail a pull request on risky changes | [2. Static scan in CI](#2-static-scan-in-ci-github-actions-and-pre-commit) |
78
+ | See what my agent asks its MCP tools to do | [3. Runtime monitor](#3-runtime-monitor-for-mcp-preview) |
79
+ | Prove the runtime log was not edited | [4. Tamper-evident ledger](#4-tamper-evident-ledger-preview) |
80
+ | Hook up Claude, ChatGPT or Cursor | [5. Connect your app](#5-connect-claude-chatgpt-or-cursor) |
81
+
60
82
  ## Contents
61
83
 
62
- - [Quick start: scan an agent project](#quick-start-scan-an-agent-project)
84
+ - [What AgentLatch does so far](#what-agentlatch-does-so-far)
85
+ - [Install once](#install-once)
86
+ - [1. Static scan (local)](#1-static-scan-local)
87
+ - [2. Static scan in CI (GitHub Actions and pre-commit)](#2-static-scan-in-ci-github-actions-and-pre-commit)
88
+ - [3. Runtime monitor for MCP (preview)](#3-runtime-monitor-for-mcp-preview)
89
+ - [4. Tamper-evident ledger (preview)](#4-tamper-evident-ledger-preview)
90
+ - [5. Connect Claude, ChatGPT or Cursor](#5-connect-claude-chatgpt-or-cursor)
63
91
  - [How it works](#how-it-works)
64
- - [Runtime monitoring for MCP (preview)](#runtime-monitoring-for-mcp-preview)
65
92
  - [What the scanner checks today](#what-the-scanner-checks-today)
66
93
  - [OWASP Agentic Top 10 coverage](#owasp-agentic-top-10-coverage)
67
94
  - [Documentation](#documentation)
@@ -73,31 +100,47 @@ Dynamic: license-file
73
100
  - [Roadmap](#roadmap)
74
101
  - [Contributing and security reports](#contributing-and-security-reports)
75
102
 
76
- ## Quick start: scan an agent project
103
+ ## Install once
77
104
 
78
- Requires Python 3.11+. Install AgentLatch from PyPI with [pipx](https://pipx.pypa.io), which keeps it in its own environment (Windows and other options: see [Getting started](https://github.com/AgentLatch/agent-latch/blob/main/docs/getting-started.md#install)):
105
+ Requires Python 3.11+. [pipx](https://pipx.pypa.io) keeps AgentLatch in its own environment (Windows and other options: [Getting started](https://github.com/AgentLatch/agent-latch/blob/main/docs/getting-started.md#install)).
79
106
 
80
107
  ```sh
81
108
  pipx install agentlatch-security
82
109
  ```
83
110
 
84
- Or install it into a virtual environment with pip:
111
+ Sections 3 to 5 use the runtime proxy, which needs the `runtime` extra (it adds FastMCP). Install this instead if you want everything:
112
+
113
+ ```sh
114
+ pipx install "agentlatch-security[runtime]"
115
+ ```
116
+
117
+ Or use a virtual environment:
85
118
 
86
119
  ```sh
87
120
  python3 -m venv .venv && source .venv/bin/activate
88
- python -m pip install agentlatch-security
121
+ python -m pip install "agentlatch-security[runtime]"
122
+ ```
123
+
124
+ Check it:
125
+
126
+ ```sh
127
+ agent-latch -V
89
128
  ```
90
129
 
91
130
  On PyPI, AgentLatch is published as `agentlatch-security`. It installs the `agent-latch` and `agent-latch-runtime` commands. The PyPI package named `agentlatch` is a separate project.
92
131
 
93
- Scan an agent project:
132
+ ## 1. Static scan (local)
133
+
134
+ **What it does:** reads the files of an agent project (Python code, prompts, YAML, manifests) and reports risky patterns. It never imports or runs the code it checks. No configuration or manifest is needed: every folder and text file is scanned.
135
+
136
+ ![The scan, end to end: source files are parsed and never run, checked by static rules and taint analysis, mapped to OWASP Agentic categories ASI01 to ASI10, and reported as text, JSON or SARIF.](docs/assets/diagrams/scan-flow.svg)
137
+
138
+ **Run it:**
94
139
 
95
140
  ```sh
96
141
  agent-latch scan /path/to/my-agent
97
142
  ```
98
143
 
99
- No configuration or agent manifest is needed: every folder and text file is scanned. Suppressions inside the scanned project (`.agent-latch-ignore`, inline ignore comments) are not applied unless you add `--project-ignores`, so a project you scan cannot hide its own findings.
100
-
101
144
  Try it on the deliberately insecure example in this repository:
102
145
 
103
146
  ```sh
@@ -105,11 +148,7 @@ git clone https://github.com/AgentLatch/agent-latch.git
105
148
  agent-latch scan agent-latch/examples/vulnerable-agent
106
149
  ```
107
150
 
108
- Watch the demo: scanning the example and failing CI with `--fail-on high`.
109
-
110
- [![AgentLatch demo video: scanning a vulnerable AI agent](https://raw.githubusercontent.com/AgentLatch/agent-latch/main/docs/assets/demo-video-thumbnail.png)](https://youtu.be/4FrRWlApDpo)
111
-
112
- More ways to run it:
151
+ Common options:
113
152
 
114
153
  ```sh
115
154
  agent-latch scan --config agent-manifest.yaml # also audit a manifest's declared tools (optional)
@@ -122,101 +161,136 @@ agent-latch scan . --format sarif --output results.sarif
122
161
  agent-latch --interactive # guided mode
123
162
  ```
124
163
 
125
- Block risky changes automatically with the [pre-commit hook](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md#pre-commit-hook) or the GitHub Action ([setup guide](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md#github-actions), [Marketplace listing](https://github.com/marketplace/actions/agentlatch-scan)):
164
+ Suppressions written inside the scanned project (`.agent-latch-ignore`, inline ignore comments) are not applied unless you add `--project-ignores`, so a project you scan cannot hide its own findings.
165
+
166
+ **See the result:** the terminal shows each finding with its rule, file and line, and OWASP mapping. This is real output for the example above (shortened):
167
+
168
+ ```text
169
+ Findings: 12
170
+
171
+ [HIGH] MAN001 (ALR09) High-risk tool without human approval
172
+ agent-manifest.yaml:29:1
173
+ Tool 'run_shell' can perform high-impact actions with no approval gate declared. ...
174
+ Gate: ALR09 Human approval for sensitive actions
175
+ OWASP Agentic: ASI02 Tool Misuse and Exploitation; ASI05 Unexpected Code Execution (RCE); ...
176
+ ```
177
+
178
+ ```sh
179
+ agent-latch scan . --plain # plain text, for logs and pipes
180
+ agent-latch scan . --format json # machine-readable
181
+ agent-latch scan . --format sarif --output results.sarif # for code scanning and SARIF viewers
182
+ echo $? # 0 passed, 1 findings at or above --fail-on, 2 error
183
+ ```
184
+
185
+ What the rules look for: how one piece of untrusted text can travel from a web page to a shell command. Each red marker is a shipped rule (`AG003`, `AG004`, `PY002`), and breaking any one link stops the chain.
186
+
187
+ ![How one bad input becomes an action: untrusted web content reaches an LLM agent, then a tool call with no approval gate, then a shell call. AgentLatch flags AG003, AG004 and PY002.](docs/assets/diagrams/attack-chain.svg)
188
+
189
+ [![AgentLatch demo video: scanning a vulnerable AI agent](https://raw.githubusercontent.com/AgentLatch/agent-latch/main/docs/assets/demo-video-thumbnail.png)](https://youtu.be/4FrRWlApDpo)
190
+
191
+ **Go deeper:** [Getting started](https://github.com/AgentLatch/agent-latch/blob/main/docs/getting-started.md) (ignores, output formats, exit codes) · [Rule reference](https://github.com/AgentLatch/agent-latch/blob/main/docs/RULES.md) · [Agent manifest](https://github.com/AgentLatch/agent-latch/blob/main/docs/agent-manifest.md)
192
+
193
+ ## 2. Static scan in CI (GitHub Actions and pre-commit)
194
+
195
+ **What it does:** runs the same scan on every pull request, or before every commit, and fails the check when a finding meets your threshold.
196
+
197
+ **Run it, GitHub Actions:** save this as `.github/workflows/agent-latch.yml` ([Marketplace listing](https://github.com/marketplace/actions/agentlatch-scan)):
126
198
 
127
199
  ```yaml
128
- - uses: AgentLatch/agent-latch@v0.4.0
129
- with:
130
- fail-on: high
131
- # min-severity: medium # optional: hide low and info findings
132
- # project-ignores: "true" # apply your repo's .agent-latch-ignore (see the note below)
200
+ name: agent-latch
201
+ on: [push, pull_request]
202
+
203
+ permissions:
204
+ contents: read
205
+ security-events: write # needed to upload results to code scanning
206
+
207
+ jobs:
208
+ scan:
209
+ runs-on: ubuntu-latest
210
+ steps:
211
+ - uses: actions/checkout@v4
212
+ - uses: AgentLatch/agent-latch@v0.5.0
213
+ with:
214
+ fail-on: high
215
+ # min-severity: medium # optional: hide low and info findings
216
+ # project-ignores: "true" # apply your repo's .agent-latch-ignore (a pull request can edit it)
133
217
  ```
134
218
 
135
- > **Upgrading from v0.1.0:** the project's own `.agent-latch-ignore`, `pyproject.toml` excludes, and inline ignore comments are no longer applied by default. If your repository relies on them, add `project-ignores: "true"` to the Action or `--project-ignores` on the command line. See the [v0.2.0 release notes](https://github.com/AgentLatch/agent-latch/blob/main/docs/release-notes/v0.2.0.md).
219
+ **Run it, pre-commit:** add this to `.pre-commit-config.yaml`, then run `pre-commit install`:
136
220
 
137
- ## How it works
221
+ ```yaml
222
+ repos:
223
+ - repo: https://github.com/AgentLatch/agent-latch
224
+ rev: v0.5.0
225
+ hooks:
226
+ - id: agent-latch
227
+ ```
138
228
 
139
- AgentLatch looks at an agent at two different times. The scanner reads the project's files before anything runs. The runtime proxy watches the agent's MCP tool traffic while it runs. Both stay on your machine.
229
+ **See the result:**
140
230
 
141
- ```mermaid
142
- flowchart LR
143
- subgraph before["Before you run: static scanner"]
144
- code["Python agent code<br/>prompts, YAML, manifests"] --> scan["agent-latch scan"]
145
- scan --> report["Findings<br/>terminal · JSON · SARIF<br/>mapped to OWASP ASI01–ASI10"]
146
- end
147
- subgraph during["While it runs: runtime proxy (preview)"]
148
- agent["AI agent<br/>CrewAI · Claude Desktop · Cursor · ..."] --> proxy["agent-latch-runtime proxy"]
149
- proxy --> server["MCP server"]
150
- proxy --> logs["Masked logs<br/>trace.jsonl · payloads.jsonl"]
151
- logs --> importer["agent-latch-runtime import-logs"]
152
- importer --> events["One event per message<br/>events.csv · normalized.jsonl<br/>optional --database (local SQLite)"]
153
- end
231
+ - **Actions:** open the run's log and its **job summary** (a findings table), or the repository's **Security → Code scanning** tab and the pull request's checks. The job exposes the outputs `sarif-file`, `finding-count` and `exit-code`.
232
+ - **pre-commit:** the commit is blocked on a high or critical finding. Check the whole repo at any time with:
233
+
234
+ ```sh
235
+ pre-commit run agent-latch --all-files
154
236
  ```
155
237
 
156
- The scanner never imports or runs the code it checks. The proxy passes every MCP message through unchanged and never blocks anything.
238
+ > **Upgrading from v0.1.0:** the project's own `.agent-latch-ignore`, `pyproject.toml` excludes, and inline ignore comments are no longer applied by default. If your repository relies on them, add `project-ignores: "true"` to the Action or `--project-ignores` on the command line. See the [v0.2.0 release notes](https://github.com/AgentLatch/agent-latch/blob/main/docs/release-notes/v0.2.0.md).
157
239
 
158
- ## Runtime monitoring for MCP (preview)
240
+ **Go deeper:** [pre-commit and CI](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md) (all inputs and outputs, other CI systems, choosing a threshold)
159
241
 
160
- `agent-latch-runtime` records what an AI agent asks its MCP tools to do and what comes back, so you can review an agent's tool use after a run. It is a **preview and monitor only**. It records every message and runs ALR04, which reports a finding when a tool definition contains instruction-like content. It does not block calls. After a run, `agent-latch --runtime-result` prints those findings in the same table as a scan, including a local tool's file and line when the project defines that tool. The report lists findings only.
242
+ ## 3. Runtime monitor for MCP (preview)
161
243
 
162
- ### Try it in one command
244
+ **What it does:** `agent-latch-runtime` sits between an AI agent and an MCP server and records what the agent asks its tools to do and what comes back. It is a **preview and monitor only**: it never blocks a call. It runs ALR04, which reports a finding when a tool definition contains instruction-like content. Secrets are masked in every file.
163
245
 
164
- Install with the `runtime` extra, which adds FastMCP:
246
+ ![Runtime monitor: the agent talks to the MCP server through the agent-latch-runtime proxy, which passes every message through unchanged and writes masked logs. import-logs joins them into events and findings, and agent-latch --runtime-result prints the report.](docs/assets/diagrams/runtime-monitor.svg)
247
+
248
+ **Run it:** try it with a bundled synthetic server, no setup:
165
249
 
166
250
  ```sh
167
- pipx install "agentlatch-security[runtime]" # or: python -m pip install "agentlatch-security[runtime]"
168
251
  agent-latch-runtime demo
169
252
  ```
170
253
 
171
- `demo` starts a bundled synthetic MCP server behind the real proxy, lists its tools, calls three of them (one returns a fake credential, one fails), gets a prompt, then imports the logs. This is real output:
254
+ `demo` starts the synthetic server behind the real proxy, makes a few tool calls (one returns a fake credential, one fails), then imports the logs. This is real output:
172
255
 
173
256
  ![Output of agent-latch-runtime demo: ten MCP events, from tools/list to prompts/get, each joined with its payload](https://raw.githubusercontent.com/AgentLatch/agent-latch/main/docs/assets/runtime-demo.svg)
174
257
 
175
- The files land in `runtime-logs/demo/` (git-ignored). The fake credential appears only as `[REDACTED]` in every one of them.
176
-
177
- ### Watch a real agent
178
-
179
- Put the proxy in front of any MCP server, then follow its logs from a second terminal:
258
+ Watch a real agent. Put the proxy in front of any MCP server, then follow its logs from a second terminal:
180
259
 
181
260
  ```sh
182
261
  # Terminal 1: the agent's MCP traffic goes through the proxy.
183
262
  agent-latch-runtime proxy --trace runtime-logs/trace.jsonl --payloads runtime-logs/payloads.jsonl \
184
263
  -- npx -y @modelcontextprotocol/server-github
264
+ ```
185
265
 
186
- # Terminal 2: one line per message, plus events.csv and normalized.jsonl in runtime-logs/.
266
+ ```sh
267
+ # Terminal 2: one line per message, plus events.csv and gate-results.csv in runtime-logs/.
187
268
  agent-latch-runtime import-logs
188
269
  ```
189
270
 
190
- Run both from the same folder, in the environment where AgentLatch is installed. `mcp-server/.venv` does not provide `agent-latch-runtime`.
271
+ Run both from the same folder, in the environment where AgentLatch is installed. `mcp-server/.venv` does not provide `agent-latch-runtime`. To also keep a queryable local copy, add `--database runtime-logs/runtime.db` to `import-logs` (SQLite, nothing is uploaded).
191
272
 
192
- To also keep a queryable copy, name a local SQLite file. That flag is the choice of store. Leave it off and nothing is written except the CSV and JSONL files. Nothing is uploaded.
273
+ **See the result:**
193
274
 
194
275
  ```sh
195
- agent-latch-runtime import-logs --database runtime-logs/runtime.db
276
+ agent-latch . --runtime-result runtime-logs/gate-results.csv
196
277
  ```
197
278
 
198
- SQLite is the first store. The importer calls it through a small `EventStore` interface, so a later destination can be selected the same way without becoming part of the default install. Details: [Store events in SQLite](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md#store-events-in-sqlite).
279
+ This prints the gate findings in the same table as a scan, with the local tool's file and line when the project defines it (add `--plain` for text). Real output, shortened:
199
280
 
200
- ```mermaid
201
- sequenceDiagram
202
- participant A as AI agent
203
- participant P as agent-latch-runtime proxy
204
- participant S as MCP server
205
- participant I as import-logs
206
- A->>P: tools/call (arguments)
207
- P->>S: forwarded unchanged
208
- S-->>P: result
209
- P-->>A: returned unchanged
210
- P->>P: write masked trace + payload records
211
- I->>P: tail the log files (read-only)
212
- I->>I: join request, payload and response into one event
281
+ ```text
282
+ Runtime findings · 3
283
+
284
+ HIGH ALR04-003 mcp-server/tools/alr04_fixture_tools.py:14
285
+ concealment
286
+ Tool definition contains above-threshold injection indicators; no exploit confirmed.
287
+ Evidence: instruction_to_conceal_from_user @ $/description
288
+ OWASP: ASI01 Agent Goal Hijack; ASI02 Tool Misuse and Exploitation; ...
213
289
  ```
214
290
 
215
- Step-by-step guides with expected output at each step:
291
+ The report lists findings only. Nothing was blocked. Add `--fail-on high` to exit `1` on a high finding, and `--min-severity` to hide lower ones.
216
292
 
217
- - [Connect an app](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md#connect-an-app) (Claude Code, Claude Desktop, Cursor, or any MCP config)
218
- - [Live run with a CrewAI agent, plus 20 test scenarios](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md#part-4-watch-a-live-agent-run-with-agentlatch) (normal calls, errors, fake secrets, SSRF attempts, injection-shaped input)
219
- - [Claude Desktop on Windows with the MCP server in WSL](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md#4b-claude-desktop-on-windows-with-the-gateway-in-wsl)
293
+ **Go deeper:** [Runtime proxy guide](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md) (limits, SQLite store, HTTP mode) · [Live run with a CrewAI agent, plus 20 test scenarios](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md#part-4-watch-a-live-agent-run-with-agentlatch)
220
294
 
221
295
  ### What the proxy records
222
296
 
@@ -231,46 +305,196 @@ The **trace** keeps argument names, sizes, SHA-256 hashes and a short secret-mas
231
305
 
232
306
  **Not recorded yet:** `resources/list` and `resources/read`, `initialize`, `sampling/createMessage`, notifications (including `tools/list_changed`), image, audio and embedded-resource content in tool results, and a failed `prompts/get`. These pass through the proxy unchanged with no record. The proxy also never sees the user's chat with the model, an app's built-in tools, or servers not routed through it. Details: [docs/runtime.md](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md#limits).
233
307
 
308
+ ## 4. Tamper-evident ledger (preview)
309
+
310
+ **What it does:** a log the agent can rewrite is not evidence. `--ledger FILE` seals every trace record into a local hash chain, and one short digest per batch (an *anchor*) is published somewhere the agent cannot write. An edit, a deletion or a full rebuild then shows up when you verify. It is off unless you ask for it, uses only the standard library, makes no network call, and is never in the request path.
311
+
312
+ ![Tamper-evident ledger: each trace line is sealed into a numbered block that holds its hash and the previous block's digest, the newest digest is published as an anchor the agent cannot write, and verify returns intact, unanchored, tampered, deleted, rewritten or missing.](docs/assets/diagrams/ledger.svg)
313
+
314
+ **Run it:**
315
+
316
+ ```sh
317
+ # 1. Record with a ledger (the ledger needs a trace file beside it)
318
+ agent-latch-runtime proxy --trace runtime-logs/trace.jsonl \
319
+ --ledger runtime-logs/trace.ledger.jsonl -- npx -y @modelcontextprotocol/server-github
320
+ ```
321
+
322
+ ```sh
323
+ # 2. Publish an anchor to a place the agent cannot write (a mounted drive, another host, ...)
324
+ agent-latch-runtime anchor --ledger runtime-logs/trace.ledger.jsonl --to /mnt/audit/anchors.jsonl
325
+ ```
326
+
327
+ ```sh
328
+ # 3. Verify, any time
329
+ agent-latch-runtime verify runtime-logs/trace.ledger.jsonl # finds trace.jsonl beside it
330
+ agent-latch-runtime verify runtime-logs/trace.ledger.jsonl --anchor /mnt/audit/anchors.jsonl
331
+ agent-latch-runtime verify runtime-logs # every ledger in a folder
332
+ agent-latch-runtime verify runtime-logs --all # ... and its subfolders, archives included
333
+ ```
334
+
335
+ **See the result:** `verify` prints one verdict (`intact`, `unanchored`, `tampered`, `deleted`, `rewritten` or `missing`) and exits `1` when the trail cannot be trusted. For the full picture, put the ledger in the runtime report:
336
+
337
+ ```sh
338
+ agent-latch . --runtime-result runtime-logs/gate-results.csv \
339
+ --ledger runtime-logs/trace.ledger.jsonl --anchor /mnt/audit/anchors.jsonl
340
+ ```
341
+
342
+ The verdict leads the report, followed by a table with one row per record. Problem records are always listed, and `--ledger-rows N` sets how many intact ones to show (`0` for all). Real output for a ledger with one edited record, one gap and one out-of-order block (shortened):
343
+
344
+ ```text
345
+ AUDIT TRAIL TAMPERED — a record was altered; the log cannot be trusted.
346
+ #5: the block's digest does not match its content
347
+ #11: 2 records are missing here
348
+ #13: this block does not follow the block before it
349
+
350
+ # TIME METHOD STAGE DIGEST STATE
351
+ 5 2026-10-31T15:52:51.881Z tools/list request b1c5e3ae7973 EDITED
352
+ 11 - - - - DELETED
353
+ 13 2026-10-31T15:52:51.882Z tools/call request 65cbcbd329ef REORDERED
354
+ 30 2026-10-31T15:52:51.883Z tools/call request 97adbec2a3bd ok
355
+ ```
356
+
357
+ Export it as SARIF for a viewer or code scanning. The file gets the SARIF and the terminal still shows the report above:
358
+
359
+ ```sh
360
+ agent-latch . --runtime-result runtime-logs/gate-results.csv \
361
+ --ledger runtime-logs/trace.ledger.jsonl --anchor /mnt/audit/anchors.jsonl \
362
+ --format sarif --output audit.sarif
363
+ ```
364
+
365
+ A failed trail exits `1` even with `--fail-on none`, because log integrity is not a severity threshold.
366
+
367
+ **What to expect:** without an anchor the best verdict is `unanchored`: the chain is consistent, but nothing outside the machine proves the file was not rebuilt. The ledger makes tampering visible; it does not prevent it, and it cannot show a change made before a record was sealed. Check live sessions with `verify runtime-logs` (the folder, without `--all`) and use `--all` to audit archived sessions on purpose. What an agent with write access can still do, and how to narrow it: [the ledger operations guide](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-operations.md#what-an-agent-can-still-do).
368
+
369
+ **Go deeper:** [Audit ledger overview](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger.md) · [Setup](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-setup.md) · [Reference](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-reference.md) · [Operations and incident runbook](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-operations.md)
370
+
371
+ ## 5. Connect Claude, ChatGPT or Cursor
372
+
373
+ **What it does:** your app starts the proxy instead of the MCP server, and the proxy starts the real server. Nothing else about the app changes.
374
+
375
+ **Run it:** in the app's MCP settings, replace the server's `command` with the proxy and move the old command after `--`. Use full paths: desktop apps often start servers with a different `PATH` and working directory.
376
+
377
+ ```json
378
+ {
379
+ "mcpServers": {
380
+ "github": {
381
+ "command": "/full/path/to/.venv/bin/agent-latch-runtime",
382
+ "args": [
383
+ "proxy", "--name", "github", "--trace", "/full/path/to/runtime-logs/trace.jsonl", "--",
384
+ "npx", "-y", "@modelcontextprotocol/server-github"
385
+ ]
386
+ }
387
+ }
388
+ }
389
+ ```
390
+
391
+ Restart the app afterwards. Add `"--ledger", "/full/path/to/runtime-logs/trace.ledger.jsonl"` before the `--` to also seal the log (section 4).
392
+
393
+ | App | Settings file |
394
+ |---|---|
395
+ | Claude Code | `.mcp.json` in the project |
396
+ | Claude Desktop | **Settings → Developer → Edit Config** |
397
+ | Cursor | `~/.cursor/mcp.json` |
398
+ | GitHub Copilot in VS Code | `.vscode/mcp.json` (top-level key is `servers`, not `mcpServers`) |
399
+ | ChatGPT (web) | cannot start a local program: it reaches the proxy through OpenAI's Secure MCP Tunnel, see the [ChatGPT guide](https://github.com/AgentLatch/agent-latch/blob/main/docs/clients/chatgpt.md) |
400
+
401
+ **See the result:** use the app as usual, then follow the traffic with `agent-latch-runtime import-logs` and read it with the commands from sections 3 and 4.
402
+
403
+ **Go deeper:** [Connect an app](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md#connect-an-app) (exact paths per OS, remote servers over HTTP, the supported-clients table) · [ChatGPT through the tunnel](https://github.com/AgentLatch/agent-latch/blob/main/docs/clients/chatgpt.md) · [Claude Desktop on Windows with the MCP server in WSL](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md#4b-claude-desktop-on-windows-with-the-gateway-in-wsl)
404
+
405
+ ## How it works
406
+
407
+ AgentLatch looks at an agent at two different times. The scanner reads the project's files before anything runs. The runtime proxy watches the agent's MCP tool traffic while it runs. Both stay on your machine.
408
+
409
+ ```mermaid
410
+ flowchart LR
411
+ subgraph before["Before you run: static scanner"]
412
+ code["Python agent code<br/>prompts, YAML, manifests"] --> scan["agent-latch scan"]
413
+ scan --> report["Findings<br/>terminal · JSON · SARIF<br/>mapped to OWASP ASI01–ASI10"]
414
+ end
415
+ subgraph during["While it runs: runtime proxy (preview)"]
416
+ agent["AI agent<br/>CrewAI · Claude Desktop · Cursor · ..."] --> proxy["agent-latch-runtime proxy"]
417
+ proxy --> server["MCP server"]
418
+ proxy --> logs["Masked logs<br/>trace.jsonl · payloads.jsonl"]
419
+ logs --> importer["agent-latch-runtime import-logs"]
420
+ importer --> events["One event per message<br/>events.csv · normalized.jsonl<br/>optional --database (local SQLite)"]
421
+ end
422
+ ```
423
+
424
+ The scanner never imports or runs the code it checks. The proxy passes every MCP message through unchanged and never blocks anything.
425
+
426
+ For one tool call, the runtime path looks like this:
427
+
428
+ ```mermaid
429
+ sequenceDiagram
430
+ participant A as AI agent
431
+ participant P as agent-latch-runtime proxy
432
+ participant S as MCP server
433
+ participant I as import-logs
434
+ A->>P: tools/call (arguments)
435
+ P->>S: forwarded unchanged
436
+ S-->>P: result
437
+ P-->>A: returned unchanged
438
+ P->>P: write masked trace + payload records
439
+ I->>P: tail the log files (read-only)
440
+ I->>I: join request, payload and response into one event
441
+ ```
442
+
234
443
  ## What the scanner checks today
235
444
 
236
- | Rule | Detection | OWASP Agentic mapping |
237
- |---|---|---|
238
- | `AGENTLATCH-PY001` | Direct Python `eval()` and `exec()` calls | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
239
- | `AGENTLATCH-PY002` | `subprocess.*(..., shell=True)` calls | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
240
- | `AGENTLATCH-PY003` | Calls with a literal `verify=False` argument | ASI02 Tool Misuse and Exploitation |
241
- | `AGENTLATCH-AG001` | CrewAI `Agent(..., allow_delegation=True)` review hint | ASI02 Tool Misuse and Exploitation; ASI03 Identity and Privilege Abuse |
242
- | `AGENTLATCH-AG002` | LangChain `create_pandas_dataframe_agent(...)` code-execution capability | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
243
- | `AGENTLATCH-AG003` | Web-search, web-loader, or HTTP output flowing unfenced into an LLM message (indirect prompt injection) | ASI01 Agent Goal Hijack |
244
- | `AGENTLATCH-AG004` | Function exposed to the model as a tool that runs commands, writes files, sends email, or writes data, with no human-approval gate | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03; ASI09 |
245
- | `AGENTLATCH-AG005` | Agent given an unrestricted built-in tool (shell, Python REPL, unscoped file access) | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03 |
246
- | `AGENTLATCH-AG006` | Human approval turned off for agent actions (`human_input_mode="NEVER"` with code execution, `auto_approve=True`, `permission_mode="bypassPermissions"`) | ASI09 Human-Agent Trust Exploitation; ASI05 / ASI02 |
247
- | `AGENTLATCH-AG007` | Agent loop with no effective limit (`max_iterations=None`, very high limits, `while True` around an agent call) | ASI08 Cascading Failures |
248
- | `AGENTLATCH-SEC001` | Credential-like quoted assignments; matched value is redacted | ASI03 Identity and Privilege Abuse; ASI04 Agentic Supply Chain Vulnerabilities |
249
- | `AGENTLATCH-DEP001` | Known advisory for a package in an audited requirements file | ASI04 Agentic Supply Chain Vulnerabilities |
250
- | `AGENTLATCH-MAN001` | Manifest tool with a high-risk capability and no human-approval gate | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03; ASI09 |
251
- | `AGENTLATCH-MAN002` | Manifest tool with wildcard permissions | ASI02 Tool Misuse and Exploitation; ASI03 Identity and Privilege Abuse |
252
- | `AGENTLATCH-MAN003` | Manifest tool calling a remote endpoint without authentication | ASI03 Identity and Privilege Abuse; ASI02 Tool Misuse and Exploitation |
253
- | `AGENTLATCH-PRM001` | Prompt-injection signatures in prompts in code, YAML, prompt template files, and manifests | ASI01 Agent Goal Hijack |
254
- | `AGENTLATCH-PRM002` | User-input placeholder interpolated into a system prompt | ASI01 Agent Goal Hijack |
445
+ | Rule | Gate | Detection | OWASP Agentic mapping |
446
+ |---|---|---|---|
447
+ | `PY001` | `ALR06` | Direct Python `eval()` and `exec()` calls | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
448
+ | `PY002` | `ALR06` | `subprocess.*(..., shell=True)` calls | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
449
+ | `PY003` | `ALR12` | Calls with a literal `verify=False` argument | ASI02 Tool Misuse and Exploitation |
450
+ | `AG001` | `ALR07` | CrewAI `Agent(..., allow_delegation=True)` review hint | ASI02 Tool Misuse and Exploitation; ASI03 Identity and Privilege Abuse |
451
+ | `AG002` | `ALR06` | LangChain `create_pandas_dataframe_agent(...)` code-execution capability | ASI05 Unexpected Code Execution (RCE); ASI02 Tool Misuse and Exploitation |
452
+ | `AG003` | `ALR05` | Web-search, web-loader, or HTTP output flowing unfenced into an LLM message (indirect prompt injection) | ASI01 Agent Goal Hijack |
453
+ | `AG004` | `ALR09` | Function exposed to the model as a tool that runs commands, writes files, sends email, or writes data, with no human-approval gate | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03; ASI09 |
454
+ | `AG005` | `ALR07` | Agent given an unrestricted built-in tool (shell, Python REPL, unscoped file access) | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03 |
455
+ | `AG006` | `ALR09` | Human approval turned off for agent actions (`human_input_mode="NEVER"` with code execution, `auto_approve=True`, `permission_mode="bypassPermissions"`) | ASI09 Human-Agent Trust Exploitation; ASI05 / ASI02 |
456
+ | `AG007` | `ALR08` | Agent loop with no effective limit (`max_iterations=None`, very high limits, `while True` around an agent call) | ASI08 Cascading Failures |
457
+ | `SEC001` | `ALR10` | Credential-like quoted assignments; matched value is redacted | ASI03 Identity and Privilege Abuse; ASI04 Agentic Supply Chain Vulnerabilities |
458
+ | `DEP001` | `ALR11` | Known advisory for a package in an audited requirements file | ASI04 Agentic Supply Chain Vulnerabilities |
459
+ | `MAN001` | `ALR09` | Manifest tool with a high-risk capability and no human-approval gate | ASI02 Tool Misuse and Exploitation; ASI05 / ASI03; ASI09 |
460
+ | `MAN002` | `ALR07` | Manifest tool with wildcard permissions | ASI02 Tool Misuse and Exploitation; ASI03 Identity and Privilege Abuse |
461
+ | `MAN003` | `ALR03` | Manifest tool calling a remote endpoint without authentication | ASI03 Identity and Privilege Abuse; ASI02 Tool Misuse and Exploitation |
462
+ | `PRM001` | `ALR01` | Prompt-injection signatures in prompts in code, YAML, prompt template files, and manifests | ASI01 Agent Goal Hijack |
463
+ | `PRM002` | `ALR01` | User-input placeholder interpolated into a system prompt | ASI01 Agent Goal Hijack |
464
+ | `ALR01-S01` | `ALR01` | Invisible, bidi, or zero-width characters in a prompt | ASI01 Agent Goal Hijack |
465
+ | `ALR03-S01` | `ALR03` | Agent or MCP server bound to every interface (`host="0.0.0.0"`) | ASI03 Identity and Privilege Abuse; ASI07 |
466
+ | `ALR06-S01` | `ALR06` | Unsafe deserialization (`yaml.load` without a safe loader, `pickle`, `torch.load` without `weights_only`) | ASI05 Unexpected Code Execution (RCE) |
467
+ | `ALR06-S02` | `ALR06` | Model-written code runs without a sandbox (`use_docker=False`, `code_execution_mode="unsafe"`, local executor) | ASI05 Unexpected Code Execution (RCE); ASI02 |
468
+ | `ALR08-S01` | `ALR08` | Outbound HTTP call without a timeout | ASI08 Cascading Failures |
469
+ | `ALR08-S02` | `ALR08` | Unbounded retry (`@retry` without `stop`, `Retry(total=None)`, `max_retries=None`) | ASI08 Cascading Failures |
470
+ | `ALR11-S01` | `ALR11` | Model or dataset loaded with `trust_remote_code=True` | ASI04 Agentic Supply Chain Vulnerabilities |
471
+ | `ALR12-S01` | `ALR12` | Agent, tool, or model endpoint on plaintext `http://` or `ws://` | ASI02 Tool Misuse and Exploitation; ASI07 |
472
+ | `ALR13-S01` | `ALR13` | Web or tool output written to agent memory or a vector store without validation | ASI06 Memory & Context Poisoning |
473
+ | `ALR13-S02` | `ALR13` | Memory or vector store created once at module level, shared by every session | ASI06 Memory & Context Poisoning |
474
+ | `ALR14-S01` | `ALR14` | Agent writes to its own prompts, instructions, or settings | ASI10 Rogue Agents |
475
+ | `ALR14-S02` | `ALR14` | Agent installs persistence (cron, systemd, launchd, shell profile, SSH keys) | ASI10 Rogue Agents |
476
+ | `ALR14-S03` | `ALR14` | Agent installs packages at runtime | ASI10 Rogue Agents |
255
477
 
256
478
  Rule behavior and known blind spots are documented in [docs/RULES.md](https://github.com/AgentLatch/agent-latch/blob/main/docs/RULES.md).
257
479
 
480
+ Every rule belongs to one **gate**: the security outcome it checks, such as `ALR09` Human approval for sensitive actions. Reports show a rule with its gate, for example `AG006 (ALR09)`. SARIF and JSON keep the full rule ID (`AGENTLATCH-AG006`), and suppressions accept either form. [docs/GATES.md](https://github.com/AgentLatch/agent-latch/blob/main/docs/GATES.md) lists every gate, its detectors (static rules and runtime checks such as ALR04), and how it maps to OWASP and the EU AI Act. These mappings are informational, not a compliance claim.
481
+
258
482
  ## OWASP Agentic Top 10 coverage
259
483
 
260
484
  How the scanner's rules map to the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/). This table is the static scanner. The runtime gate ALR04 also cites ASI01, ASI02, and ASI04 on a finding. That does not add a scanner check.
261
485
 
262
486
  | ID | Category | Coverage | Rules |
263
487
  |---|---|---|---|
264
- | ASI01 | Agent Goal Hijack | ✅ checks | `AG003`, `PRM001`, `PRM002` |
265
- | ASI02 | Tool Misuse and Exploitation | ✅ checks | `PY001`–`PY003`, `AG001`, `AG002`, `AG004`–`AG006`, `MAN001`–`MAN003` |
266
- | ASI03 | Identity and Privilege Abuse | ✅ checks | `AG001`, `AG004`, `AG005`, `SEC001`, `MAN001`–`MAN003` |
267
- | ASI04 | Agentic Supply Chain Vulnerabilities | ✅ checks | `SEC001`, `DEP001` |
268
- | ASI05 | Unexpected Code Execution (RCE) | ✅ checks | `PY001`, `PY002`, `AG002`, `AG004`–`AG006`, `MAN001` |
269
- | ASI06 | Memory & Context Poisoning | ⬜ no checks yet | |
270
- | ASI07 | Insecure Inter-Agent Communication | ⬜ no checks yet | |
271
- | ASI08 | Cascading Failures | 🟨 partial | `AG007` |
488
+ | ASI01 | Agent Goal Hijack | ✅ checks | `AG003`, `PRM001`, `PRM002`, `ALR01-S01` |
489
+ | ASI02 | Tool Misuse and Exploitation | ✅ checks | `PY001`–`PY003`, `AG001`, `AG002`, `AG004`–`AG006`, `MAN001`–`MAN003`, `ALR06-S02`, `ALR12-S01` |
490
+ | ASI03 | Identity and Privilege Abuse | ✅ checks | `AG001`, `AG004`, `AG005`, `SEC001`, `MAN001`–`MAN003`, `ALR03-S01` |
491
+ | ASI04 | Agentic Supply Chain Vulnerabilities | ✅ checks | `SEC001`, `DEP001`, `ALR11-S01` |
492
+ | ASI05 | Unexpected Code Execution (RCE) | ✅ checks | `PY001`, `PY002`, `AG002`, `AG004`–`AG006`, `MAN001`, `ALR06-S01`, `ALR06-S02` |
493
+ | ASI06 | Memory & Context Poisoning | 🟨 partial | `ALR13-S01`, `ALR13-S02` |
494
+ | ASI07 | Insecure Inter-Agent Communication | 🟨 partial | `ALR03-S01`, `ALR12-S01` |
495
+ | ASI08 | Cascading Failures | 🟨 partial | `AG007`, `ALR08-S01`, `ALR08-S02` |
272
496
  | ASI09 | Human-Agent Trust Exploitation | 🟨 partial | `AG004`, `AG006`, `MAN001` |
273
- | ASI10 | Rogue Agents | ⬜ no checks yet | |
497
+ | ASI10 | Rogue Agents | 🟨 partial | `ALR14-S01`, `ALR14-S02`, `ALR14-S03` |
274
498
 
275
499
  Every scan report ends with the same ASI01–ASI10 summary and marks the uncovered categories as `no checks yet`, so they aren't mistaken for clean results. A ✅ means some checks exist, not that the category is fully covered. The mapping is informational, not an OWASP endorsement or certification.
276
500
 
@@ -282,6 +506,8 @@ Every scan report ends with the same ASI01–ASI10 summary and marks the uncover
282
506
  | [Agent manifests](https://github.com/AgentLatch/agent-latch/blob/main/docs/agent-manifest.md) | Declaring agents, tools, permissions, and prompts in `agent-manifest.yaml`, and what is checked |
283
507
  | [pre-commit and CI](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md) | pre-commit hook, GitHub Action inputs and outputs, other CI systems, choosing a threshold |
284
508
  | [Detection rules](https://github.com/AgentLatch/agent-latch/blob/main/docs/RULES.md) | What every rule detects, its OWASP mapping, and its known blind spots |
509
+ | [Gates](https://github.com/AgentLatch/agent-latch/blob/main/docs/GATES.md) | The security outcomes AgentLatch checks, which rules and runtime checks belong to each, and their OWASP and EU AI Act references |
510
+ | [Audit ledger](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger.md) | Making the runtime log tamper-evident: the hash chain, anchors, the six verdicts, and what it cannot catch. Then [setup](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-setup.md), [reference](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-reference.md) and [operations](https://github.com/AgentLatch/agent-latch/blob/main/docs/ledger-operations.md) |
285
511
  | [Vulnerable example](https://github.com/AgentLatch/agent-latch/tree/main/examples/vulnerable-agent) | A demo project and the findings it should produce |
286
512
  | [Runtime proxy for MCP (preview)](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md) | Install, connecting an app, what is recorded, `import-logs` and `demo`, limits. Optional local SQLite: [Store events in SQLite](https://github.com/AgentLatch/agent-latch/blob/main/docs/runtime.md#store-events-in-sqlite) |
287
513
  | [MCP gateway](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/README.md) | A local MCP gateway for running agents against real tools, with [step-by-step setup](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md) for Claude Code, Claude Desktop, Cursor, Codex CLI, and HTTP clients, and [live runs through the runtime proxy](https://github.com/AgentLatch/agent-latch/blob/main/mcp-server/SETUP.md#part-4-watch-a-live-agent-run-with-agentlatch) |
@@ -325,7 +551,7 @@ Install AgentLatch and run `agent-latch scan /path/to/agent`. It checks Python a
325
551
 
326
552
  ### How do I monitor the MCP tool calls my AI agent makes?
327
553
 
328
- Put `agent-latch-runtime proxy` in front of the MCP server, either in your app's MCP config or as an HTTP proxy, and run `agent-latch-runtime import-logs` next to it from the same folder. Every tool list, tool call, result and prompt is recorded with secrets masked, and shown as one event per message. Add `--database runtime-logs/runtime.db` when you want those events in a local SQLite file as well. Run `agent-latch-runtime demo` to see the whole flow first. See [Runtime monitoring for MCP](#runtime-monitoring-for-mcp-preview).
554
+ Put `agent-latch-runtime proxy` in front of the MCP server, either in your app's MCP config or as an HTTP proxy, and run `agent-latch-runtime import-logs` next to it from the same folder. Every tool list, tool call, result and prompt is recorded with secrets masked, and shown as one event per message. Add `--database runtime-logs/runtime.db` when you want those events in a local SQLite file as well. Run `agent-latch-runtime demo` to see the whole flow first. See [Runtime monitor for MCP](#3-runtime-monitor-for-mcp-preview).
329
555
 
330
556
  ### Can AgentLatch block a dangerous MCP tool call?
331
557
 
@@ -341,7 +567,7 @@ The source rules work on any Python code. Framework-specific checks cover CrewAI
341
567
 
342
568
  ### How do I check AI agent security in CI or GitHub Actions?
343
569
 
344
- Use the [GitHub Action](https://github.com/marketplace/actions/agentlatch-scan) (`uses: AgentLatch/agent-latch@v0.4.0`) to scan every push and pull request and show findings in GitHub code scanning, or the [pre-commit hook](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md#pre-commit-hook) to block risky commits. Any other CI can run `agent-latch scan --fail-on high`, which exits with code 1 when high-severity findings exist.
570
+ Use the [GitHub Action](https://github.com/marketplace/actions/agentlatch-scan) (`uses: AgentLatch/agent-latch@v0.5.0`) to scan every push and pull request and show findings in GitHub code scanning, or the [pre-commit hook](https://github.com/AgentLatch/agent-latch/blob/main/docs/ci.md#pre-commit-hook) to block risky commits. Any other CI can run `agent-latch scan --fail-on high`, which exits with code 1 when high-severity findings exist.
345
571
 
346
572
  ### Does AgentLatch upload my code or call an LLM?
347
573
 
@@ -386,6 +612,8 @@ The project will not claim to be an industry standard or a universal security gu
386
612
 
387
613
  See [CONTRIBUTING.md](https://github.com/AgentLatch/agent-latch/blob/main/CONTRIBUTING.md) for development and rule authoring, and [SECURITY.md](https://github.com/AgentLatch/agent-latch/blob/main/SECURITY.md) for responsible vulnerability reporting. Please submit synthetic test fixtures rather than real secrets or confidential source code.
388
614
 
615
+ Questions, rule ideas, false-positive reports and setups are welcome in [GitHub Discussions](https://github.com/AgentLatch/agent-latch/discussions). Use [SECURITY.md](https://github.com/AgentLatch/agent-latch/blob/main/SECURITY.md), not a public thread, for a vulnerability in AgentLatch itself.
616
+
389
617
  ## Name and standards references
390
618
 
391
619
  AgentLatch is an independent open-source project. It references selected categories from the [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) where useful. OWASP is not affiliated with or endorsing AgentLatch.