{
"markdown": "# TAR Engine — audit AI skill safety before you ship\n\n> Static + semantic + adversarial + supply-chain audit for AI agent skills. Run it in CI, or call it as an MCP tool from Claude Code / Cursor / Codex. BYOK for the LLM layers; free hosted tier + live Playground on [tarai.dev](https://tarai.dev/).\n\n[](https://pypi.org/project/tar-engine/)\n[](https://registry.modelcontextprotocol.io/?q=tar-engine)\n[](LICENSE)\n[](https://www.python.org/)\n\nListed on the official [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/?q=tar-engine) and published to [PyPI](https://pypi.org/project/tar-engine/) — one-click install into any MCP-compatible agent.\n\n
\n \n
\n\n`tar-engine` audits **SKILL.md** (OpenClaw, Claude Code), **Codex `skill.yaml`**, **Claude Code custom commands** (`.claude/commands/*.md`), and **OpenCode configs** — with no change to how you author skills. The core idea: a skill can pass every static red-flag check and still behave maliciously at runtime. TAR Engine catches that.\n\nThree ways to run it — **two of them install nothing on your machine:**\n\n- **Hosted — zero install.** Paste or upload a skill on the [tarai.dev Playground](https://tarai.dev/) and read the audit in your browser. Nothing to install, nothing to trust locally.\n- **In CI — zero install into your agent.** The [GitHub Action](#run-it-in-ci--zero-install) runs a *pinned* release inside your own CI sandbox: `tar-engine scan ./skills --min-score 70` exits `1` if any skill scores below the bar. A pre-publish gate, not a nicer directory card.\n- **In your agent — opt in.** Install the MCP server and audit any `SKILL.md` while you write. It's a **pinned, hash-verifiable PyPI release** — no arbitrary `git+https` install. Details below.\n\n---\n\n## What an audit looks like\n\nPoint it at a skill that *looks* fine. A \"weekly note formatter\" whose `SKILL.md` reads clean — but buried in it is a `curl … | bash` step, a \"cloud sync\" that tars up `~/.aws` and `~/.ssh`, and an instruction telling the agent to hide those network calls from you:\n\n```\nweekly-note-formatter 0 / 100 grade F risk CRITICAL\n\n L01 static SS-003 critical remote script piped to shell (curl … | bash)\n L01 static PI-002 critical hidden instruction — \"don't tell the user\"\n L02 semantic SEM-003 critical only formats docs, yet packages up AWS creds + SSH keys\n L02 semantic SEM-004 high instructs the model to lie about its network calls\n L03 adversarial AR-002 high 3/3 role-jailbreak probes changed the skill's behavior\n\n → below --min-score 70, exit 1\n```\n\nRegex catches the `curl | bash`. The semantic and adversarial layers catch the parts regex can't: intent that exceeds the skill's stated purpose, and instructions that turn the agent against its user. Every finding cites the exact source line with a fix.\n\n---\n\n## The four audit layers\n\n| Layer | What it looks for | LLM? |\n| ----- | ----------------- | ---- |\n| **L01 Static** | Regex red flags: `curl\\|bash` installs, credential/SSH exfil, obfuscated or base64 strings, hidden \"ignore previous\" style instructions, out-of-scope file writes | No |\n| **L02 Semantic** | Reads what the skill *actually* asks the agent to do and flags intent beyond its stated purpose | Yes (BYOK) |\n| **L03 Adversarial** | Treats the `SKILL.md` as a system prompt and runs 15 probes across 5 attack classes to see if it can be coerced into unsafe behavior | Yes (BYOK) |\n| **L06 Supply chain** | Parses declared dependencies and checks them against [OSV.dev](https://osv.dev/) advisories + a typosquat reference list | No |\n\nThe 5 adversarial classes (L03):\n\n| Class | ID | Probes for |\n| ----- | -- | ---------- |\n| Instruction override | AR-001 | `ignore previous`, `new system prompt` hijacks |\n| Role jailbreak | AR-002 | DAN / hypothetical / fictional-roleplay bypasses |\n| Hidden payload | AR-003 | base64 / leetspeak / unicode-lookalike smuggling |\n| Authority spoof | AR-004 | `I'm the developer / admin / platform staff` |\n| Reflective injection | AR-005 | output-as-instruction loops |\n\nEvery skill gets a **0–100 score**, an **A–F grade**, and a risk class. L01 and L06 are deterministic and free; L02 and L03 require your own LLM key ([BYOK](#byok-semantic--adversarial-layers)).\n\nThese four layers implement a **vendor-neutral standard** — the [Skill Audit Dimensions](docs/SKILL_AUDIT_DIMENSIONS.md) checklist (static, semantic, adversarial/behavioral, supply-chain). The dimensions are the standard; TAR Engine is one open-source reference implementation. That checklist also says the audit *tooling* must meet its own supply-chain bar — which is why TAR Engine ships as a pinned, hash-verifiable PyPI release with a zero-install hosted and CI path, not a `git+https` install.\n\n---\n\n## CLI — audit AI skill from the command line\n\nThe `tar-engine` CLI walks a directory, audits every skill it finds, and exits with a CI-friendly status code.\n\n```bash\n# audit every skill under ./skills, fail the build if any scores below 70\ntar-engine scan ./skills --min-score 70\n\n# list discovered skills without auditing\ntar-engine list ./skills\n\n# JSON output for downstream processing\ntar-engine scan ./skills --json\n```\n\nDiscovery covers five formats out of the box:\n\n| File pattern | Format |\n|-----------------------------|-------------------------------------|\n| `**/SKILL.md` | OpenClaw, Claude Code, generic md |\n| `**/.claude/commands/*.md` | Claude Code custom commands |\n| `**/skill.yaml` / `.yml` | Codex |\n| `**/manifest.json` | Codex / Claude Code (key-detected) |\n| `**/opencode.json` | OpenCode |\n\nEach audit payload bundles the primary skill file plus sibling `.sh / .py / .js / .ts / .yaml / .json` helper files in the same directory (200 KB cap). Catches the \"SKILL.md clean but `install.sh` malicious\" pattern.\n\n\n**Run it in CI — zero install.** The audit runs inside *your own* CI sandbox on a pinned release; nothing is installed into your agent, and there is no arbitrary git fetch to trust:\n\n```yaml\n- name: Audit AI skills\n uses: qingxuantang/tar-engine@v0.3.3 # pinned release\n with:\n path: ./skills\n min-score: 70\n```\n\nPrefer a plain step? Run the **pinned PyPI release** directly — still no `git+https`:\n\n```yaml\n- run: uvx --from tar-engine==0.3.3 tar-engine scan ./skills --min-score 70\n```\n\n**Pre-commit hook:**\n\n```bash\n#!/usr/bin/env bash\ntar-engine scan ./skills --min-score 80 || exit 1\n```\n\nExit codes: `0` clean, `1` below threshold, `2` usage/missing path.\n\n---\n\n## Install as an MCP tool\n\nTAR Engine ships an **MCP server** as a Python package, runnable with\n[`uvx`](https://docs.astral.sh/uv/) — no Docker. By default it talks to\nthe hosted backend at **[tarai.dev](https://tarai.dev/)** (free,\nrate-limited).\n\n### Read this first — what you're trusting\n\n- **Where SKILL.md goes.** With the default config the MCP server POSTs\n the SKILL.md content you ask it to audit to `https://tarai.dev`. We\n don't write skill text to disk or log it, but it does leave your\n machine. If you're auditing proprietary or sensitive skills,\n [self-host](#self-host) and set `TAR_ENGINE_URL=http://localhost:8765`.\n- **No silent key forwarding.** The server does NOT forward your\n `OPENAI_API_KEY`. Semantic + adversarial audit layers require an\n explicit opt-in via `TAR_ENGINE_BYOK_OPENAI_KEY` in the MCP server\n config — see [BYOK](#byok-semantic--adversarial-layers) below.\n- **What environments work.** Claude Code CLI, Cursor, Codex CLI —\n anywhere your agent can launch a subprocess. **Claude Desktop,\n Claude.ai web, and the mobile apps cannot install local MCP servers**;\n hosted endpoint for those is coming — [waitlist on tarai.dev](https://tarai.dev/).\n\n### Step 0 — install `uv` (one-time, ~5 seconds)\n\nThe package is run via `uvx`, which comes with `uv`. Install once:\n\n```bash\n# macOS / Linux\ncurl -fsSL https://astral.sh/uv/install.sh | sh\n\n# Windows (PowerShell)\nirm https://astral.sh/uv/install.ps1 | iex\n\n# Alternative — via pipx if you don't trust curl|sh\npipx install uv\n\n# Alternative — via pip\npip install --user uv\n```\n\nVerify with `uvx --version`.\n\n### Step 1 — register with your agent\n\n**One-click:** grab [`setup-mcp.sh`](setup-mcp.sh) and run it — it checks\nfor `uv`, prompts for an optional BYOK key (hidden input, never written to\ndisk by the script), and registers the server with your agent:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/qingxuantang/tar-engine/master/setup-mcp.sh -o setup-mcp.sh\nchmod +x setup-mcp.sh\n./setup-mcp.sh # Claude Code (default); add --client cursor|codex\n```\n\nOr configure it manually. Two install forms are supported:\n\n- **From PyPI — recommended, pinned & verifiable:** `uvx --from tar-engine==0.3.3 tar-engine-mcp`. Every release ships to PyPI with a published hash you can lock in your lockfile — this is the canonical, reproducible install and the form the MCP registry / Anthropic MCPB clients use. **No arbitrary `git+https`; pin the version so you always know exactly what you're running.**\n- **From source — development only:** installing from a git checkout runs unreleased code without a published release hash. Use this only if you're hacking on TAR Engine itself — it is *not* the recommended way to run it, precisely because \"install this unvetted git URL\" is the pattern a supply-chain audit should warn against.\n\n\nClaude Code\n\n```bash\nclaude mcp add tar-engine -- uvx --from tar-engine==0.3.3 tar-engine-mcp\n```\n\nVerify: `/mcp list` should show `tar-engine` Connected. Restart Claude\nCode so this session picks up the new tool surface, then ask:\n\n> Audit this SKILL.md: [paste a skill]\n\n\n\n\nCursor\n\nEdit `~/.cursor/mcp.json` (or project-level `.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"tar-engine\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tar-engine==0.3.3\", \"tar-engine-mcp\"]\n }\n }\n}\n```\n\nReload MCP servers in Cursor (or restart the app), then call\n`audit_skill_text` from inside Cursor.\n\n\n\n\nCodex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.tar-engine]\ncommand = \"uvx\"\nargs = [\"--from\", \"tar-engine==0.3.3\", \"tar-engine-mcp\"]\n```\n\nRestart the Codex CLI, then call `audit_skill_text`.\n\n\n\n\nAny other MCP-compatible agent\n\nMost agents accept an MCP server spec with `command` + `args` (JSON or TOML):\n\n- **command:** `uvx`\n- **args:** `[\"--from\", \"tar-engine==0.3.3\", \"tar-engine-mcp\"]` — pinned to a published PyPI release for a reproducible, hash-verifiable install\n\n**env (optional):**\n\n- `TAR_ENGINE_URL=http://localhost:8765` to self-host\n- `TAR_ENGINE_BYOK_OPENAI_KEY=sk-...` to enable semantic + adversarial layers\n\nReload the agent and call `audit_skill_text` to verify.\n\n\n\n### BYOK (semantic + adversarial layers)\n\nBy default only the **static rule layer** runs against your skill —\nfree, deterministic, no LLM cost. To enable the semantic LLM review and\nthe adversarial prompt-fuzz pass, supply your own LLM key explicitly:\n\n```json\n\"tar-engine\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"tar-engine==0.3.3\", \"tar-engine-mcp\"],\n \"env\": {\n \"TAR_ENGINE_BYOK_OPENAI_KEY\": \"sk-...\"\n }\n}\n```\n\nThe key layer is OpenAI-compatible, so you can point it at any compatible endpoint (`TAR_ENGINE_BYOK_OPENAI_BASE_URL` / `TAR_ENGINE_BYOK_OPENAI_MODEL`). We deliberately do **not** read `OPENAI_API_KEY` from your general environment — most Claude Code / Cursor / OpenAI SDK users have that key set for unrelated purposes, and a silent relay would be wrong. Set `TAR_ENGINE_BYOK_OPENAI_KEY` only when you want this MCP server to use your key.\n\n### Self-host\n\nIf the privacy / latency tradeoff of the hosted backend doesn't work\nfor you, run the engine locally:\n\n```bash\ngit clone https://github.com/qingxuantang/tar-engine\ncd tar-engine\ncp .env.example .env # add OPENAI_API_KEY if you want semantic + adversarial\ndocker compose up -d\n```\n\nThen point the MCP server at it:\n\n```json\n\"env\": {\n \"TAR_ENGINE_URL\": \"http://localhost:8765\"\n}\n```\n\nSame tool surface, no data leaves your machine, your own key, no\nrate limit beyond what your hardware supports.\n\n---\n\n## Public audit reports + live Playground (AI 米其林指南)\n\nWe publish ongoing audit reports of popular open-source skills from major skill\nplatforms — Smithery, Claude Hub, MCPHub. Each report includes a security score,\nspecific findings, and remediation suggestions, generated by the exact pipeline\nshipped in this repo.\n\nRead the reports and paste any `SKILL.md` into the **[live Playground on tarai.dev](https://tarai.dev/)** to get a verdict in ~60 seconds — no install required. Self-hosting? The same static endpoint is one curl away:\n\n```bash\ncurl -X POST http://localhost:8765/api/cockpit/audit/static \\\n -H \"Content-Type: application/json\" \\\n -d '{\"skill_text\": \"\"}'\n```\n\n---\n\n## Beyond auditing\n\nThe audit pipeline is what most people install this for, and it's the OSS core. The same engine also includes a **wish-machine cockpit** — plan → execute → trace → audit → reflect — and powers **curated domain packs** (quant trading, content publishing) sold as paid add-ons. Those are secondary to the audit use case; see [tarai.dev](https://tarai.dev) for pack details and pricing, and [`docs/`](docs/) for the cockpit architecture.\n\n---\n\n## What's in this repo\n\n```\ntar-engine/\n├── backend/\n│ ├── app.py # FastAPI entry\n│ ├── auditor/ # Audit pipeline: L01 static / L02 semantic / L03 adversarial / L06 supply chain + risk scorer\n│ ├── cockpit/ # Wish machine: planner / dispatcher / skill executor / trace / retrospective\n│ ├── adapters/ # IDE/runtime adapters (Claude Code, Codex CLI, generic webhook)\n│ └── knowledge/ # Knowledge RAG (LlamaIndex + ChromaDB)\n├── mcp-server/ # MCP server + CLI (tar-engine / tar-engine-mcp entry points)\n├── packs/\n│ ├── hello-world/ # Reference demo pack — 5-min install verifier\n│ └── postall-content/ # Multi-platform content publishing pack\n├── frontend/ # Web UI (static, optional)\n├── setup-mcp.sh # One-click MCP registration\n├── docker-compose.yml\n└── docs/ # Architecture, deployment, contribution notes\n```\n\n---\n\n## Status\n\nCurrent release: **v0.3.3** — published to [PyPI](https://pypi.org/project/tar-engine/) and listed on the official [MCP Registry](https://registry.modelcontextprotocol.io/?q=tar-engine).\n\nWhat works today:\n\n- ✅ CLI `scan` / `list` with CI-friendly exit codes + `--min-score` gate\n- ✅ MCP server (`audit_skill_text`) for Claude Code / Cursor / Codex\n- ✅ Four audit layers — L01 static, L02 semantic, L03 adversarial (15 probes × 5 classes), L06 supply chain\n- ✅ Five skill formats discovered out of the box, with sibling helper-file bundling\n- ✅ Hosted free tier + live Playground on tarai.dev\n- ✅ Self-host via Docker Compose (BYOK, no data leaves your machine)\n\nOn the roadmap:\n\n- Hosted MCP endpoint for Claude Desktop / web / mobile\n- Multi-victim adversarial ensembles on the hosted advanced tier\n- Deeper supply-chain coverage + more skill-format adapters\n\n---\n\n## Contributing\n\nThe fastest ways to help:\n\n1. Run `tar-engine scan` on a skill you use and share findings (or false positives) in Issues\n2. Add a skill-format adapter or an audit rule — PRs to `backend/auditor/` and `mcp-server/` are welcome\n3. Try the self-host quickstart and report friction\n\nThe paid packs (quant trading, content publishing) are first-party only — we won't accept PRs that add UGC packs to `packs/`.\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for the full terms.\n\n---\n\n## Acknowledgments\n\nTAR Engine started as an audit tool for AI quant-trading workflows and grew into a\ngeneral-purpose skill auditor through real conversations with quant engineers,\ncontent creators, and security teams — all asking variations of the same question:\n*\"How do I let my AI agents do real work without shipping something malicious I never read?\"*\n\nBuilt by [Mark Zhou](https://tarai.dev) with [Claude Code](https://claude.com/code).\n",
"bytes": 16804,
"sha": "112a1584a5e1c699185749b4dae4bb772321455aca44fd3994f5e968f41551f9",
"repo_slug": "qingxuantang/tar-engine",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_qingxuantang_tar_engine_f67da890/readme"
}
![\"TAR](\"docs/assets/mcp-registry.png\")
\n