aishield

# AIShield — Full LLM Briefing

*Canonical: https://aishield.tools · GitHub: https://github.com/lm203688/aishield · Version: 4.8.3*

AIShield is an open-source, local-first **AI Agent security scanner and trust authority** for the MCP / Agentic AI economy. This file is the long-form, machine-readable briefing for LLMs and agents (paired with the short `/llms.txt`).

---

## 1. What AIShield does

AIShield protects AI agents and the MCP (Model Context Protocol) tools they call. It detects:

- **Tool poisoning** — malicious or rug-pulled tool descriptions, hidden instructions in tool metadata.
- **Prompt injection** — goal-hijack patterns in tool results, fetched web content, and agent inputs.
- **Secret leakage** — API keys, tokens, credentials in tool arguments, outputs, or environment.
- **Supply-chain risk** — compromised MCP servers, malicious npm/PyPI packages, dependencies; offline **slopsquatting / hallucinated-package detection** across package.json / requirements.txt / pyproject.toml. Six channels, zero network calls: Levenshtein typosquat, homoglyph normalization, brand impersonation, **composite hallucination (the ~50% of AI-fabricated names that are NOT edit-distance-similar to any real package, e.g. `react-codeshift`)**, cross-registry confusion (8.7% of Python-hallucinated names exist on npm), and dependency confusion / internal-namespace leakage. Plus manifest hygiene: install-script poisoning (`postinstall` running curl/wget/base64/chmod), untrusted sources (`git+`/`http://`/`file:`), unpinned specs (`*`/`latest`), and missing lockfile.
- **Agentic AI risks (OWASP Agentic AI Top 10, ASI01–ASI10)** — goal hijack, tool misuse, identity & privilege abuse, supply chain, unexpected code execution, memory/context poisoning, insecure inter-agent communication, cascading failures, human-agent trust exploitation, rogue agents.
- **Misconfigured MCP clients** — auto-discovery and static audit of MCP server configurations across **14 client surfaces**: Claude Desktop, Claude Code (user + project), Cursor (user + project), VS Code (user + project), Windsurf, Gemini CLI, GitHub Copilot CLI, Augment, Zed, Cline, WorkBuddy. Per-server checks: privileged launch (`sudo`/`runas`), STDIO command-execution exposure, runtime package fetch at startup (`npx -y` / `uvx` pulling latest), shell-interpreter invocation (`bash -c`, `cmd /c`), non-registry provenance (`git+`, raw URL, local path), inline plaintext credentials, insecure transport (`http://` remote), wildcard bind (`0.0.0.0`), unauthenticated remote endpoints, and project-level configuration trust traps. Cross-server checks: **namespace shadowing** (two servers exposing colliding tool names — the NSA-flagged confused-deputy pattern) and **7 classes of toxic capability flows** (private-data read + untrusted egress, credential access + code execution, filesystem write + network fetch, etc.).

  **Design invariant — never execute the scanned config.** Enumerating a server's `tools/list` requires spawning it, and an MCP `command` is arbitrary code; some scanners state outright that scanning configurations will execute the commands defined in them. AIShield performs pure static analysis: it parses the config, infers capabilities from command/args/env shape, and never launches a process. Auditing a hostile configuration therefore cannot compromise the auditing machine. Credentials found in a config are reported as `<redacted:kind>` — the raw value is never echoed back.

- **Agent-computer sandbox misconfiguration** — 11 sandbox-hardening rules covering the ways an isolated agent environment quietly hands the host back: mounted `docker.sock`, `--privileged`, host network / PID / IPC namespaces, `cap_add: ALL`, `CAP_SYS_ADMIN`, `seccomp=unconfined`, `--user 0`, Kubernetes `hostPath`. You can have a sandbox and still have no isolation.

- **Poisoned skills, treated as code** — for skill-type assets, Markdown *is* the executable payload. `SKILL.md`, `AGENTS.md`, `CLAUDE.md`, files under `skills/` or `prompts/`, and any Markdown carrying `name` + `description` frontmatter are scanned as instructions, not documentation. Scanners that downgrade `.md` findings to "documentation example" structurally miss the entire skill supply chain — a malicious `SKILL.md` combining prompt injection with a `curl | bash` payload scores 98/100 under that assumption and 61/100 with critical findings once it is corrected.

**Scale:** 235 MCP rule categories / 241 skill rule categories — 110 OWASP MCP Top 10 rules, 60 OWASP Agentic AI Top 10 (ASI01–ASI10) rules, 31 Chinese prompt-injection rules, 11 sandbox-hardening rules, plus rules promoted from the daily tech-radar pipeline through a six-check gate (schema, compilable regex, not overly broad, deduplicated, zero false positives on a benign corpus).

**Deployment:** fully local / offline. No source code is uploaded to any cloud. Detection runs on the developer's machine or in CI.

### Position in the stack: the content-trust plane for agent computers

Giving an agent its own computer is now solved infrastructure — Cloudflare Sandboxes/Containers, forgevm / agent-forge, E2B, Open Interpreter and Goose all provide a shell, filesystem and network stack inside a container or micro-VM. That layer solves **blast radius** (what the agent can reach). It does not solve **content trust** (whether the MCP servers, skills and tool descriptions loaded inside that box should be believed). A sandboxed agent that loads a poisoned skill still exfiltrates data — from inside the container, using credentials that were deliberately granted to it.

AIShield is the complementary plane, not a competitor to any isolation runtime. Four controls, one per lifecycle stage:

1. **Pre-flight workspace scan** (`scanner/workspace_scan.py`, `scripts/scan_workspace.py`) — parse `.mcp.json`, forge / Goose / Open Interpreter configs and every skill file *before* the sandbox boots, and refuse to start on high risk. Never spawns anything.
2. **Sandbox-hardening rules** — audit the box definition itself (see the 11 rules above).
3. **Guardrail-as-harness** (`eco/guardrail_harness.py`) — admission check on every tool call between the model and the tools, evaluated as kill-switch → deny-list → allow-list → default-deny, with a hash-chained append-only audit log where tampering, deletion and insertion are all detectable.
4. **Continuous attestation** (`eco/attestation.py`) — re-scan on a cycle (default 7 days), detect drift against the recorded evidence hash, revoke certification below threshold. Certification without expiry is marketing; rug-pulls happen after the audit.

Full writeup: https://aishield.tools/agent-computer-security-plane

### Self-audit of published artifacts

Every artifact AIShield ships to an external marketplace is registered in `distribution/published.json`, keeps its source in-repo, and must pass AIShield's own scanner via `scripts/verify_distribution.py` before release (blocking on any critical/high finding or a score below 80). The gate is proven to be able to fail — `tests/test_distribution_gate.py` includes negative cases, and the first artifact it ever blocked was AIShield's own published skill, which had hardcoded an internal address.

---

## 2. How to use AIShield

- **MCP server (stdio):** `npx aishield-mcp-server` — connects to any MCP-capable agent (Claude, Cursor, etc.).
- **MCP remote (streamable-http):** `https://aishield.tools/api/v1/mcp`
- **REST API:** `https://aishield.tools/api/v1/health`
- **A2A Agent Card:** `https://aishield.tools/.well-known/agent-card.json`
- **CI gate:** fail the build on risk above a threshold.

---

## 3. The Trust Standard (AIShield Trust Standard v0.1)

AIShield is more than a scanner — it is a **trust authority** for the agent economy. The open standard defines three sub-standards:

### Sub-standard A — Agent Security Certification
Three levels:
- **Level 1 (Basic):** automatic scan, score ≥ 60/100, 90-day cert.
- **Level 2 (Verified):** automatic scan + human review, score ≥ 80/100, 180-day cert.
- **Level 3 (Enterprise):** Level 2 + on-chain anchoring + continuous monitoring, SLA ≥ 99.5%.

Certificates are published at each agent's `/.well-known/aishield-cert.json` and verifiable via `GET /aishield-trust/v1/cert/{cert_id}`.

### Sub-standard B — Agent Trust Score
A 0–100 score from five weighted dimensions: Security (30%), Reliability (25%), Reputation (25%), Activity (10%), Identity (10%). Queryable at `GET /aishield-trust/v1/score/{did}`. Includes anti-gaming (new-agent caps, rating-weighting, collusion detection) and an appeal process.

### Sub-standard C — Agent Delegation Protocol
An extension of Google's A2A Task model adding: escrow (USDC), trust requirements, security requirements, dispute resolution, and completion receipts. Enables safe agent-to-agent task delegation.

---

## 4. Service-system modules already built (data + spec layer)

- **Agent Registry** (`api/data/agent_registry.json`): agents with A2A cards, skills, reputation scores, DID-style identity, status.
- **Marketplace** (`api/data/marketplace.json`): listed tools, badges (gold/silver/bronze), webhook events (`tool.certified`, `tool.scanned`).
- **Billing** (`api/data/billing.json`): accounts, plans (free/pro), monthly usage, payment history. (Agent-native x402/USDC billing is implemented in `eco/x402.py`.)
- **Certifications** (`api/data/certifications.json`): issued cert records.
- **Ecosystem evolution docs:** delegation-chain visualization & verification (P0), agent-culture integrity / drift detection (P1).

---

## 5. Competitive positioning (2026-08)

The MCP/agent-security category is now crowded (mid-2026): open-source static scanners (Cisco mcp-scanner, Invariant mcp-scan, Snyk agent-scan, agent-security-scanner-mcp, mcp-audit), cloud SaaS (Nightfall, Akto, ScanMCP, aishield.ai), and enterprise gateways (Palo Alto Prisma AIRS AI Gateway, Cyera, Teleport, MCP Guardian). AIShield's defensible edges:

| Dimension | AIShield | Cloud SaaS (Nightfall/Akto/ScanMCP/aishield.ai) | MCP-only scanners (mcp-scan/mcp-audit/Cisco) | Enterprise gateways (Palo Alto/Cyera) |
|---|---|---|---|---|
| Runs locally / offline (no code to cloud) | Yes | No | Yes | No (runtime proxy) |
| Open source & free | Yes | No | Yes / Partial | No |
| OWASP MCP Top 10 | Yes (110) | Partial | Yes | N/A (runtime) |
| OWASP Agentic AI Top 10 (ASI01–10) | Yes (60) | Partial | No | Partial |
| Neutral trust authority (cert L1–3 + score + badge + API + x402) | Yes | No | No | No |
| CycloneDX SBOM + SARIF 2.1.0 | Yes | Varies | Partial | No |
| Offline hallucinated-package detection (incl. non-similar names) | Yes | No | Rare | No |
| Multi-client MCP config auto-discovery | Yes (14 surfaces) | Rare | Yes (varies) | No |
| Config audit **without executing** the scanned config | Yes (pure static) | N/A | No (spawns server for `tools/list`) | N/A |
| Namespace shadowing + toxic-flow cross-server analysis | Yes | Rare | Rare | Partial |
| Agent-native & GEO (llms.txt / Agent Card / A2A) | Yes | Rare | Rare | No |
| Markdown treated as executable payload for skills | Yes | Rare | No (downgraded as "docs") | N/A |
| Sandbox-hardening rules for agent computers | Yes (11) | No | No | Partial |
| Content-trust plane composable with agent sandboxes (Cloudflare / forgevm / E2B / Goose) | Yes | No | No | No |

---

## 6. Status & roadmap (2026-08)

**Shipped in v4.2.0 (all live in code):**
- Agentic AI Top 10 detection module (60 ASI rules on the 214-rule base).
- Trust Standard productized: live cert + score API (`/api/v1/trust/*`), auto-issued certs, SVG badges, Agent Registry + Marketplace data.
- Local-first architecture: zero third-party dependencies, rule engine fully offline; optional remote LLM for semantic analysis only.
- SBOM (CycloneDX 1.5) + SARIF 2.1.0 export (`/api/v1/export/sbom`, `/api/v1/export/sarif`).
- x402 / USDC agent-native billing rail (`eco/x402.py`).
- **Slopsquatting detection v2 (2026-08-05)** — offline hallucinated-package detection for npm & PyPI covering the non-similar half that edit-distance scanners structurally miss, plus cross-registry confusion, dependency confusion, and manifest hygiene (install-script poisoning, untrusted sources, unpinned specs, missing lockfile). Composite-hallucination findings ship at `info` severity with zero score deduction and a 5-per-manifest cap, because offline non-existence cannot be proven. Measured **0 false positives on 40 real widely-used packages**; **127 tests passing**.
- **Multi-client MCP config discovery & static audit (2026-08-05)** — 14 client surfaces, 10 per-server risk checks, namespace-shadowing and 7 toxic-flow classes across servers, exposed at `POST /api/v1/scan/client-config` and via `scanner.discover_and_scan()`. Purely static: no configured command is ever executed; credentials are redacted in evidence. Measured **0 false positives across 20 officially recommended configurations (score 94/100)** and **10/10 detection on 10 malicious configurations (score 0/100)**; **190 tests passing**.
- Multi-channel distribution: Claude Skill, GPT Store manifest, Hugging Face card, MCP Hub entry.

**Next (from 2026-08-05 competitive intelligence):**
- Runtime governance hooks (ASI08/ASI10): **fail-closed enforcement gateway + immutable decision log**, per CoSAI Workstream 4 *Agentic Identity and Access Management* (approved 2026-03-20). This is now the category's centre of gravity — 2026 H2 competitor releases moved from pre-deployment scanning to runtime proxying/firewalling, typically requiring a cloud API token. AIShield's differentiated answer must stay local and tokenless.
- Optional remote registry verification for package existence/age/downloads (opt-in, off by default) to extend the offline heuristic; default stays fully offline.
- Neutral trust-authority narrative amplification + GEO/agent-native discovery (llms.txt, Agent Card, A2A).
- Independent benchmark + first-to-market "Agentic AI Top 10 certified" claim.

---

## 7. Contact & references
- Website: https://aishield.tools
- GitHub: https://github.com/lm203688/aishield
- Trust Standard: https://aishield.tools/aishield-trust-standard-v0.1
- Agent Ecosystem Directions: https://aishield.tools/agent-ecology-evolution-directions
- Short LLM briefing: https://aishield.tools/llms.txt