AgentSeal: a local scanner for agent skills, MCP configs and prompt injection

The gap AgentSeal is aimed at: config files nobody reads

An MCP server hands an agent access to local files, databases, APIs and credentials. The tool descriptions that broker that access are text the model reads and the user usually does not. A description can carry instructions the agent follows, and the README states this plainly: tool descriptions can contain hidden instructions that the agent follows but the user never sees. The same applies to skill files and to the config files that register MCP servers in the first place.

The target user is a developer or small security team running agents on their own machines. The README lists 28 supported agents, including Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Gemini CLI, Codex CLI, Cline, Aider, Continue, Zed, Goose and OpenCode. That list is the real scope statement. AgentSeal is a workstation tool, not a server-side gateway. If your agents run in a hosted environment with no local config directory, there is little here for you to point it at.

Guard's six-stage pipeline and what each stage can actually catch

guard needs no API key and the README says it makes no network calls, so the first five stages run entirely on the machine. Stage one is pattern signatures for known malicious shapes: credential access, exfiltration URLs, shell commands. Stage two is deobfuscation, decoding Unicode tags, Base64, BiDi overrides, zero-width characters and TR39 confusables. Stage three is semantic analysis using embedding similarity with MiniLM-L6-v2, which the README describes as catching rephrased attacks that bypass patterns. Stage four is baseline tracking: SHA-256 hashes of config files, compared against the previous scan, which is how it detects a rug pull where a file changed after you approved it. Stage five enriches findings with trust scores from the MCP Security Registry, described as covering 6,600+ servers. Stage six loads custom YAML rules.

The split between stages two and three is the design decision worth noting. Pattern matching plus deobfuscation handles known encodings; the embedding stage exists because an attacker who paraphrases an injection defeats both. Embedding similarity is a blunt instrument in the other direction too. It will produce matches on legitimate text that sits near malicious examples in vector space, and the README gives no false-positive rate, no threshold, and no way to inspect why a given similarity score fired. Treat stage three as a prompt to read the file yourself, not as a verdict.

The scan command's canary design avoids the LLM-judge problem

scan runs a system prompt against what the README counts as 225 adversarial attack probes: 82 extraction techniques, 143 injection techniques and 8 adaptive mutation transforms. The detection mechanism is the part that distinguishes it from most prompt-injection harnesses. Injection probes embed a unique canary string, with the example SEAL_A1B2C3D4_CONFIRMED, and the probe counts as leaked only if that canary appears in the response. Extraction probes use n-gram matching against the ground truth prompt. The README states there is no LLM judge, so the same input produces the same result every time.

That is a real property and it is worth being precise about what it buys. A deterministic scorer is reproducible in CI, which is why the documented pipeline form works: agentseal scan --file ./prompt.txt --model gpt-4o --min-score 75 exits with code 1 when the trust score falls below the threshold. What it does not buy is coverage of attacks that do not require the model to emit a canary or reproduce prompt n-grams. A model that leaks the gist of a system prompt in its own words, without copying n-grams, is not obviously caught by either detector. The trust score bands (85 to 100 Excellent, 70 to 84 High, 50 to 69 Medium, 30 to 49 Low, 0 to 29 Critical) are a summary of canary and n-gram hits, not a general measure of how hard the prompt is to break.

Running it: install, guard, scan-mcp

Installation is a single package from either registry. The README gives pip install agentseal, or npm install agentseal. The first command most people will run is agentseal guard, which the README describes as needing no API key.

For scanning a prompt, the model string carries the provider. Local Ollama is ollama/llama3.1:8b and the README marks it free. Cloud models take the provider's own name, for example gpt-4o or claude-sonnet-4-5-20250929. A prompt can come from a file with --file ./prompt.txt, or you can point the scanner at an arbitrary HTTP endpoint with --url http://localhost:8080/chat, which is the escape hatch for a self-hosted model behind your own API.

scan-mcp connects to a live server rather than reading config. Over stdio: agentseal scan-mcp --server npx @modelcontextprotocol/server-filesystem /tmp. Over SSE: agentseal scan-mcp --sse http://localhost:3001/sse. It enumerates every tool and runs each description through pattern matching, deobfuscation, semantic similarity and optional LLM classification, producing a trust score per server. Note the asymmetry: scan-mcp without the LLM stage needs no key, and the optional classifier is the only part that does.

guard has its own subcommands. agentseal guard init generates a .agentseal.yaml project policy. agentseal guard test validates your custom rules, which is the step to run before trusting stage six. Output formats are agentseal guard --output sarif for the GitHub Security tab and agentseal guard --output json for machine consumption. agentseal guard --no-diff skips the baseline delta section, which you would want if you do not retain scan history between runs.

Shield watches continuously, and that is where the false-positive cost lands

shield is the same path set as guard, watched continuously. It needs an extra install: pip install agentseal[shield], which pulls in watchdog and desktop notification dependencies. It raises desktop notifications when threats appear and the README states it automatically quarantines files with detected payloads. The stated use case is supply chain attacks, where an npm install or pip install silently modifies your agent configs.

Automatic quarantine is the sharpest trade-off in the tool. If a detection is wrong, a config file your agent needs is moved, and the failure surfaces later as an agent that will not start rather than as a notification you can dismiss. The README does not describe an undo command, a quarantine directory layout, or a dry-run mode for shield. Before leaving it running unattended, find out where quarantined files go. The desktop notification path also assumes a graphical session, so on a headless box or over SSH the alerting half of shield is not obviously useful, though the quarantine half presumably still fires.

Where it is the wrong tool, and what it does not replace

AgentSeal is a pre-flight and a tripwire. It is not a runtime guard. Nothing in the README intercepts a tool call, filters a model response, or sits between the agent and the MCP server while the agent works. If your threat model is a compromised server returning hostile data mid-session, scan-mcp tells you about the server's descriptions at scan time and then stops. The README's own framing supports this: guard runs a pipeline on files it finds, shield watches files, scan-mcp connects once and audits descriptions.

The natural alternative is a general static analysis or secret-scanning tool already wired into CI, such as Semgrep or gitleaks. The difference in approach is what they look for. Those tools match source code and credentials against rules you write in their own languages. AgentSeal matches natural-language tool descriptions and skill files, and its second and third stages exist specifically because the payload is prose: Unicode tag characters, zero-width characters, TR39 confusables, and paraphrases that defeat literal patterns. A Semgrep rule will not decode a BiDi override in a tool description, and AgentSeal will not tell you that your Python service has an injection flaw. Running one does not substitute for the other.

The second limitation is coverage of the agent list. Twenty-eight agents are named, but the README does not enumerate the config paths for each. If you use something outside that list, guard has nothing to scan and will presumably report nothing, which looks identical to a clean result. That ambiguity is worth resolving before you treat a clean guard run as evidence of anything.

Licence, releases and the maintenance you are signing up for

The repository's licence field reads NOASSERTION, while the README badge says FSL-1.1-Apache-2.0. Functional Source License is not an open source licence in the OSI sense: it typically restricts competing use for a period and then converts to a permissive licence, here Apache 2.0. The two signals do not agree, and the practical terms (what counts as a competing use, when the conversion date falls) are in the LICENSE file, not in the README. If you are packaging AgentSeal into a product, read that file rather than the badge. This is a description of the discrepancy, not legal advice.

The release cadence visible in the material is two releases in roughly three months: v0.6.2 on 2026-03-11 and v0.8.0, subtitled Guard, on 2026-03-25, with the last push to main on 2026-06-11. A minor-version jump from 0.6 to 0.8 in two weeks suggests the CLI surface is still moving. That matters for two things you would otherwise treat as stable. The SARIF output shape is what your GitHub Security tab consumes, and the trust score bands are what your --min-score threshold is calibrated against. A probe-set change shifts scores without any change to your prompt, so a threshold of 75 can start failing a pipeline that passed last month. Pin the version in CI and re-baseline the threshold when you bump it.

On the positive side, guard's local-only design keeps the maintenance surface small: no API key to rotate, no network dependency in the scan path. The cost you take on instead is a periodic re-scan to keep the SHA-256 baseline current, since stage four is only as good as the last recorded state. If you never re-run guard, the rug-pull detection has nothing to compare against.

Editorial conclusion

Adopt AgentSeal if you run several agents on one developer machine, or if you publish MCP servers and want a repeatable check before shipping a tool description. Skip it if your agents are hosted and you have no local config files to scan, because guard and shield both operate on paths on disk. Before trusting the output, run agentseal guard init, then agentseal guard test against your own YAML rules, and confirm which of the 28 listed agents it actually recognises on your machine.

Official sources

1. getagentseal/agentseal on GitHub
2. Issues
3. Project website
4. README
5. Releases