The Problem
AI‑agent developers and operators need a reliable way to discover malicious skill files, poisoned MCP (Model‑Control‑Plane) configurations, and supply‑chain changes on the machines that run their agents. Without automated scanning, hidden payloads or crafted prompts can exfiltrate data or hijack tool usage.
What This Does
agentseal delivers a local, zero‑API‑key scanner (guard) and a prompt‑injection tester (scan). The core logic lives in two parallel codebases:
JavaScript/TypeScript – entry points in js/src/guard.ts, js/src/scan-mcp.ts, and js/src/shield.ts. The detection pipeline is assembled in js/src/detection/index.ts and the mutation library in js/src/mutations/.ts. Python – CLI defined in python/agentseal/cli.py, with the same detection modules under python/agentseal/detection/ and mutation helpers in python/agentseal/mutations.py.
Both stacks share a common design: pattern signatures (js/src/blocklist.ts / python/agentseal/blocklist.py), deobfuscation utilities (js/src/deobfuscate.ts / python/agentseal/deobfuscate.py), semantic similarity checks (js/src/guard-models.ts / python/agentseal/guardmodels.py), and a baseline hash store (js/src/history.ts / python/agentseal/history.py). Results can be emitted as SARIF or JSON via the --output flag.
How To Use It
Install the language you prefer
pip install agentseal # Python package or npm install -g agentseal # Global npm install
Quick local scan – no API key needed
agentseal guard # runs the full detection pipeline
Prompt‑injection testing (requires an LLM endpoint)
agentseal scan \ --prompt "You are a helpful assistant…" \ --model ollama/llama3.1:8b # free local model or with a cloud provider (API key must be set in the environment) agentseal scan --prompt "…" --model gpt-4o
Setup – The repository includes js/package.json (npm) and a pure‑Python distribution on PyPI, so standard installers work. No Docker build is required for end users; the only Dockerfile (.github/actions/guard/Dockerfile) is used by the CI action.
Configuration – Custom policies are stored in a generated .agentseal.yaml (created by agentseal guard init). The file follows the schema defined in js/src/project-config.ts / python/agentseal/projectconfig.py.
Running – The CLI scripts (js/bin/agentseal.ts and python/agentseal/main.py) expose the sub‑commands (guard, scan, scan-mcp, shield). The test suite (js/test/.test.ts and python/agentseal/tests/) validates each command against fixture data.
Real‑World Use
A CI pipeline can prevent malicious skill commits by adding a step:
.github/workflows/guard.yml name: Run AgentSeal guard run: agentseal guard --output sarif > guard.sarif uses: github/codeql-action/upload-sarif@v2 with: sariffile: guard.sarif
The SARIF report appears in GitHub’s Security tab, alerting reviewers before code merges.
Code Health & Issues
Low – Test coverage – 225+ unit tests across both stacks (js/test/ and python/agentseal/), CI runs on GitHub Actions (.github/workflows/*.yml). Low – License clarity – SPDX identifiers present in LICENSE (FSL‑1.1 + Apache‑2.0) and referenced in package.json. Medium – Duplicate logic – Detection and mutation code duplicated in TS and Python; maintaining parity may introduce drift. Low – Secret handling – No hard‑coded keys, but environment‑variable reliance for cloud LLMs is undocumented; adding a README note would reduce user error. Low – Runtime safety – Functions that load external files (e.g., js/src/machine-discovery.ts, python/agentseal/machinediscovery.py) catch I/O errors but do not validate JSON schema; a malformed config could crash the scanner.
Overall the repo follows conventional structure, includes CI, linting (tsup.config.ts, vitest.config.ts), and type definitions (py.typed). No obvious security red flags are present in the source tree.
The Bottom Line
agentseal offers a well‑tested, dual‑language toolkit for locally scanning AI‑agent assets and evaluating prompt robustness. It is ready for integration into development pipelines, especially for teams that already use either npm or pip. The main limitation is the duplicated code paths between TypeScript and Python, which may increase maintenance overhead. Teams seeking automated supply‑chain security for agent tooling will find it immediately useful; solo developers should weigh the extra dependency load against the risk profile of their agents.