Clone URL: https://github.com/moses-y/agentseal

The Problem

AI‑agent deployments on developer machines accumulate skill files, MCP configurations and data‑flow paths that can be abused for credential theft, prompt injection or supply‑chain poisoning. Organisations need a local, no‑API key scanner that surfaces dangerous patterns, monitors for config drift, and audits live MCP servers—all without sending data off‑host.

What This Does

AgentSeal provides four commands (guard, scan, scan‑mcp, shield).

  • guard runs a six‑stage detection pipeline (pattern signatures, de‑obfuscation, semantic analysis via MiniLM, baseline SHA‑256 tracking, MCP‑registry enrichment, custom YAML rules) against every skill/MCP file found on the machine.
  • scan probes a system prompt against 225+ adversarial attacks (free with Ollama, cloud‑provider keys for OpenAI/Anthropic).
  • scan‑mcp connects to a live MCP server and reports tool‑description poisoning.
  • shield watches config files in real time, alerts on threats and can quarantine payloads.

All commands are invoked from the CLI entry point js/bin/agentseal.ts; the guard pipeline starts at js/src/guard.ts:210 (reaches 79 functions) and the shield daemon at js/src/shield.ts:404 (reaches 9 functions).

How It Is Wired

  • Import graph: 227 code files, 226 internal modules, 243 import edges, 4 modules in circular dependencies. The hub is js/src/index (Ca 1, Ce 35, instability 0.97); 31 other modules depend on it, so changes ripple widely.
  • Import cycles: js/src/mutations/index.ts, generate.ts and python/agentseal/remediation.py form a mutually reachable cycle; extracting shared types or inverting a dependency breaks it.
  • Oversized files: js/src/machine-discovery.ts (644 loc), python/agentseal/schemas.py, python/agentseal/cli.py exceed typical line‑count limits, making changes hard to hold and review.
  • Deep nesting: Python files cli.py, detection/dataflow.py, detection/skill_detector.py reach max indentation depth 8; guard clauses or extracted helpers are recommended.
  • Duplicated blocks: 138 repeated 6‑line patterns across js/bin/agentseal.ts, js/test/fix.test.ts, js/src/baselines.ts, js/src/fix.ts etc.; extract shared helpers.
  • File‑open leaks: open(...) without with in python/agentseal/detection/dataflow.py and python/tests/test_dataflow.py.
  • Broad except clauses: python/agentseal/blocklist.py, canaries.py, cli.py swallow exceptions indiscriminately.

Entry‑point flow: run → enrichMcpResults → bulkCheck (network via globalThis.fetch). The shortest path to a network call is three hops.

How To Use It

Setup

# npm install   (js/package.json implies pnpm/npm)
npm install

# pip install   (python/pyproject.toml implies pip/uv)
pip install agentseal   # or: uv pip install agentseal

Configuration No API key is required for guard or scan‑mcp. For scan with cloud models set the appropriate OPENAI_API_KEY, ANTHROPIC_API_KEY etc.; the guard pipeline reads no secrets. Environment variables are read from the process environment; no dedicated config file is mandated, but js/src/config.ts and python/agentseal/config.py host defaults.

Running it

# Local scan – no network, no key needed
agentseal guard

# Test a system prompt against adversarial probes (Ollama free)
agentseal scan --prompt "You are a helpful assistant..." --model ollama/llama3.1:8b

# Audit a live MCP server
agentseal scan-mcp --url http://localhost:8000

# Real‑time shield
agentseal shield

Output formats

agentseal guard --output sarif   # GitHub Security tab
agentseal guard --output json    # machine‑readable
agentseal guard --no-diff        # skip baseline delta

Real‑World Use

A security engineer runs agentseal guard on a developer workstation after onboarding a new Claude‑Code agent. The pipeline flags a skill file containing a Base64‑encoded exfiltration URL (de‑obfuscation step), cross‑references the MCP registry and discovers the associated server has a “write‑file” tool flagged as poisoned. The engineer remediates the skill file, updates the MCP config, and re‑runs guard to confirm the drift is cleared. Subsequent scan runs verify that no prompt‑injection payloads slip through.

Code Health & Issues (Measured)

  • Pin third‑party GitHub Actions to a commit SHA – .github/workflows currently uses pypa/gh-action-pypi-publish@release/v1; replace with a 40‑character SHA and let Dependabot bump them.
  • Commit a lockfile beside the manifest – python/pyproject.toml has no lockfile; run the package manager once and commit the generated lockfile.
  • Enable Dependabot or Renovate – 2 manifests, no update bot configured; add .github/dependabot.yml covering npm and Python ecosystems plus GitHub Actions.
  • Pin the container base image by digest – .github/actions/guard/Dockerfile uses python:3.12-slim; switch to python:3.12-slim@sha256::<digest> and enable Docker‑ecosystem Dependabot.
  • Gate pull requests on a dependency vulnerability scan – CI lacks a dependency‑scan step; add dependency-review-action on pull_request or osv-scanner on push/schedule.
  • Set persist-credentials: false on checkout – .github/workflows/js.yml keeps the token for later steps; add with: persist-credentials: false and pass an explicit token only to the push step.
  • Add a non‑root USER to the image – Dockerfile has no USER directive; create an unprivileged user, chown needed paths, and end the Dockerfile with USER.
  • Set timeout-minutes on workflow jobs – Two jobs in .github/workflows/js.yml have no timeout; add a realistic bound to each job.

The Bottom Line

AgentSeal is a pragmatic, locally‑run security toolkit that fills a clear gap for AI‑agent operators who need to detect dangerous skills, MCP poisoning and prompt‑injection risk without external dependencies. The codebase is well‑structured (tests, CI, lockfile, license) but contains several high‑impact maintainability and SDLC gaps—notably import cycles, oversized files, duplicated logic and CI‑level dependency hygiene. Teams that value supply‑chain awareness and can tolerate the modest operational overhead of pinning SHAs and enabling Dependabot will find it a useful addition to their developer‑workstation security stack.