agent-mcp-guard 0.4.7 → 0.4.9

package/README.md

@@ -19,9 +19,30 @@ Live demo PR: [mcp-guard-demo#1](https://github.com/ChaoYue0307/mcp-guard-demo/p
   <a href="https://github.com/marketplace/actions/mcp-guard-mcp-security-scanner"><img alt="GitHub Marketplace" src="https://img.shields.io/badge/Marketplace-mcp--guard-0f766e?logo=github"></a>
   <a href="https://github.com/ChaoYue0307/mcp-guard/actions"><img alt="CI" src="https://github.com/ChaoYue0307/mcp-guard/actions/workflows/ci.yml/badge.svg"></a>
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-111827"></a>
-  <a href="https://github.com/ChaoYue0307/mcp-guard/releases/tag/v0.4.7"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
+  <a href="https://github.com/ChaoYue0307/mcp-guard/releases/tag/v0.4.9"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
+## MCP Basics
+
+MCP, the Model Context Protocol, is a common way for AI apps and agents to connect to external tools, files, and services.
+
+In practice, most MCP risk lives in the config file that tells an AI client what servers to start or call.
+
+| Concept | Plain-English meaning | Why security teams should care |
+| --- | --- | --- |
+| MCP client | The AI app or agent runtime, such as Claude Desktop, Cursor, Codex, or an internal agent. | It decides which MCP servers are available to the model. |
+| MCP server | A local process or remote endpoint that exposes tools, resources, or prompts. | It may read files, run commands, call SaaS APIs, or send data outside the machine. |
+| MCP config | JSON or project config that lists server commands, URLs, args, env vars, working directories, and headers. | A small config change can introduce shell execution, broad filesystem access, or long-lived credentials. |
+| Review point | The moment before a server is added locally or merged into a repo. | This is where `mcp-guard` scans for risky commands, unpinned packages, leaked secrets, broad paths, and remote endpoints. |
+
+`mcp-guard` does not try to replace MCP. It gives teams a quick way to review MCP tool access before agents can use it.
+
+To see the exact risk checks in the current release:
+
+```bash
+mcp-guard rules --format markdown
+```
+
 ## Install
 
 ```bash
@@ -65,10 +86,18 @@ Generate SARIF for GitHub code scanning:
 mcp-guard scan --format sarif --output mcp-guard.sarif
 ```
 
+Inspect the rule catalog:
+
+```bash
+mcp-guard rules
+mcp-guard rules --format json
+```
+
 Generate a review-ready audit pack:
 
 ```bash
 mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --output-dir mcp-guard-audit
+mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json
 ```
 
 Use in CI:
@@ -93,7 +122,7 @@ mcp-guard scan --config .mcp.json --baseline .mcp-guard-baseline.json --fail-on
 Use the GitHub Action:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     # policy: .mcp-guard-policy.json
@@ -117,8 +146,9 @@ Use the transparent example to evaluate what the scanner actually does:
 - generated audit summary: [site/e2e/audit/mcp-guard-executive-summary.md](site/e2e/audit/mcp-guard-executive-summary.md)
 - generated remediation plan: [site/e2e/audit/mcp-guard-remediation.md](site/e2e/audit/mcp-guard-remediation.md)
 - generated remediation checklist: [site/e2e/audit/mcp-guard-remediation-checklist.md](site/e2e/audit/mcp-guard-remediation-checklist.md)
+- generated audit manifest: [site/e2e/audit/mcp-guard-audit-manifest.json](site/e2e/audit/mcp-guard-audit-manifest.json)
 
-The example scans 3 MCP servers and reports 9 active findings with a risk score of 98. It is synthetic, but fully reproducible from committed files.
+The example scans 3 MCP servers and reports 9 active findings with a risk score of 98. It is synthetic, but fully reproducible from committed files. The audit manifest can be verified with `mcp-guard verify-audit` to confirm the generated reports still match their recorded SHA-256 hashes.
 
 For the GitHub Action workflow, inspect the public demo repository: [ChaoYue0307/mcp-guard-demo](https://github.com/ChaoYue0307/mcp-guard-demo).
 
@@ -152,7 +182,7 @@ For paid setup or internal review handoff, `mcp-guard audit` writes a complete e
 - remediation plan grouped by MCP server;
 - remediation checklist for PR or handoff tracking;
 - Markdown, HTML, JSON, and SARIF reports;
-- machine-readable audit manifest with artifact hashes.
+- machine-readable audit manifest with artifact hashes and a CLI verifier.
 
 For stricter governance, commit `.mcp-guard-policy.json` and define the commands, remote packages, filesystem roots, and remote MCP endpoints the team has approved. See [Policy files](docs/policy.md).
 

package/docs/audit.md

@@ -26,6 +26,14 @@ Use `--fail-on` in CI when the audit should write artifacts and then fail on act
 mcp-guard audit --config .mcp.json --fail-on high
 ```
 
+Verify the audit pack before handoff or after downloading a CI artifact:
+
+```bash
+mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json
+```
+
+`verify-audit` recalculates every recorded artifact size and SHA-256 hash. It exits `0` when the pack still matches the manifest and exits `2` when a report is missing or changed.
+
 ## Generated Files
 
 | File | Purpose |
@@ -46,7 +54,7 @@ mcp-guard audit --config .mcp.json --fail-on high
 3. Work through `mcp-guard-remediation.md` with the engineering team.
 4. Track concrete work in `mcp-guard-remediation-checklist.md`.
 5. Use `mcp-guard-report.html` for readable evidence and `mcp-guard-report.json` or `mcp-guard.sarif` for automation.
-6. Use the `integrity.artifacts` section in `mcp-guard-audit-manifest.json` when you need to prove an audit artifact has not changed.
+6. Run `mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json` when you need to prove an audit artifact has not changed.
 7. Commit a reviewed policy and baseline only after the team has decided what risk is intentionally accepted.
 
 ## Privacy

package/docs/baseline.md

@@ -30,7 +30,7 @@ If the scan finds only baseline-accepted findings, the exit code is `0`. If a ne
 ## GitHub Action
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -45,7 +45,7 @@ The generated Markdown, HTML, JSON, and PR comment separate active findings from
 {
   "version": 1,
   "generatedAt": "2026-05-10T00:00:00.000Z",
-  "toolVersion": "0.4.7",
+  "toolVersion": "0.4.9",
   "findings": [
     {
       "fingerprint": "mcpg_a009b2c2",

package/docs/business-playbook.md

@@ -17,7 +17,7 @@ Deliverables:
 - install the CLI and GitHub Action;
 - run `mcp-guard init` or generate an equivalent workflow manually;
 - generate Markdown, HTML, JSON, and SARIF reports;
-- generate a customer handoff audit pack with executive summary, remediation plan, remediation checklist, reports, and hashed manifest;
+- generate a customer handoff audit pack with executive summary, remediation plan, remediation checklist, reports, hashed manifest, and verifier output;
 - define an initial `.mcp-guard-policy.json` for approved commands, packages, directories, and remote URLs;
 - create an initial baseline for accepted known findings;
 - enable PR comments and optional SARIF upload;

package/docs/examples/e2e-example.md

@@ -24,6 +24,7 @@ node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --form
 node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format json --output site/e2e/report.json
 node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format sarif --output site/e2e/report.sarif
 node ./bin/mcp-guard.js audit --config site/e2e/claude_desktop_config.json --output-dir site/e2e/audit
+node ./bin/mcp-guard.js verify-audit --manifest site/e2e/audit/mcp-guard-audit-manifest.json
 ```
 
 ## Expected Result
@@ -63,3 +64,4 @@ Important findings include:
 - Secret-like values are redacted in reports.
 - Findings include rule IDs, severity, evidence, and remediation guidance.
 - The same scan can feed a human-readable HTML report, automation JSON, GitHub code scanning SARIF, and a review-ready audit handoff package with a remediation checklist.
+- The audit handoff can be verified later because the manifest records SHA-256 hashes and byte sizes for each generated report.

package/docs/github-action.md

@@ -6,6 +6,8 @@ The action runs the CLI from the pinned GitHub Action tag, generates an audit pa
 
 It can also use a committed baseline to accept known findings, enforce a committed policy file, and optionally post a pull request comment with only the active findings.
 
+After downloading the artifact, run `mcp-guard verify-audit --manifest mcp-guard-report/mcp-guard-audit-manifest.json` to confirm the generated reports still match the manifest hashes.
+
 If `.mcp-guard-policy.json` is committed at the repository root, the CLI auto-loads it. Use the `policy` input when the policy file lives elsewhere.
 
 Marketplace/action repository: <https://github.com/ChaoYue0307/mcp-guard-action>
@@ -37,7 +39,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.7
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -65,7 +67,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.7
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -77,7 +79,7 @@ jobs:
 Use `fail-on: none` when you want artifacts and summaries without blocking a pull request.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     fail-on: none
 ```
@@ -93,7 +95,7 @@ mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
 Commit `.mcp-guard-baseline.json`, then reference it from the action:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -107,7 +109,7 @@ Reports will show active findings separately from findings accepted by the basel
 Use a policy when you want CI to enforce approved commands, packages, directories, and remote URLs.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json

package/docs/launch-checklist.md

@@ -32,12 +32,13 @@ mcp-guard scan --config .mcp.json --fail-on high
 
 ```bash
 mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --output-dir mcp-guard-audit
+mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json
 ```
 
 ## GitHub Action Setup
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json

package/docs/marketplace-action-readme.md

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.7
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -42,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.7
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -88,7 +88,7 @@ The action generates an audit pack:
 - SARIF 2.1.0 for GitHub code scanning.
 - Remediation Markdown for server-by-server handoff.
 - Remediation checklist for PR and setup tracking.
-- Audit manifest JSON with SHA-256 hashes and byte sizes for downstream automation.
+- Audit manifest JSON with SHA-256 hashes, byte sizes, and `mcp-guard verify-audit` support for downloaded artifacts.
 
 Secret-like values are redacted before reports are written.
 
@@ -103,7 +103,7 @@ mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
 Then enforce only new findings:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -115,7 +115,7 @@ Then enforce only new findings:
 Commit `.mcp-guard-policy.json` or pass `policy` to enforce approved commands, remote packages, directories, and remote MCP URLs.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json

package/docs/marketplace.md

@@ -82,17 +82,18 @@ Code quality
 Current release title:
 
 ```text
-v0.4.7
+v0.4.9
 ```
 
 Release notes:
 
 ```text
-Audit integrity release.
+Rule catalog and MCP education release.
 
-- Adds SHA-256 checksums and byte sizes for generated audit artifacts in `mcp-guard-audit-manifest.json`.
-- Keeps remediation checklist, first remediation steps in PR comments, executive summary, remediation plan, Markdown, HTML, JSON, SARIF, policy, baseline, artifacts, and SARIF upload support.
-- Improves paid setup and internal review handoff by making generated evidence easier to verify after delivery.
+- Adds `mcp-guard rules` so users can inspect every scanner rule from the CLI in text, Markdown, or JSON.
+- Adds MCP basics to the README and website so new readers can understand clients, servers, configs, and review points.
+- Keeps audit pack verification, remediation checklist, first remediation steps in PR comments, executive summary, remediation plan, Markdown, HTML, JSON, SARIF, policy, baseline, artifacts, and SARIF upload support.
+- Improves product transparency by making both the documented E2E example and the scanner rule catalog visible before adoption.
 ```
 
 ## Manual Publishing Steps
@@ -105,7 +106,7 @@ Completed:
 - README, docs, and website examples now use:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.7
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
 ```
 
 Remaining Marketplace web step:

package/docs/paid-audit.md

@@ -13,7 +13,7 @@ It is not currently advertised as an active consulting service. Keep public webs
 ## Deliverables
 
 - MCP and agent tool inventory.
-- `mcp-guard audit` evidence pack with executive summary, remediation plan, remediation checklist, reports, and hashed manifest.
+- `mcp-guard audit` evidence pack with executive summary, remediation plan, remediation checklist, reports, hashed manifest, and `verify-audit` output.
 - Risk report covering shell access, package execution, filesystem scope, secrets, remote servers, and dangerous commands.
 - Practical remediation checklist.
 - Optional PR with safer config and policy changes.

package/docs/roadmap.md

@@ -13,7 +13,7 @@
 - Optional GitHub pull request comments from the Marketplace Action.
 - `mcp-guard init` for bootstrapping a GitHub Action workflow and optional baseline.
 - Policy file enforcement for approved commands, packages, directories, and remote URLs.
-- `mcp-guard audit` for review-ready executive summaries, remediation plans, remediation checklists, reports, and hashed manifests.
+- `mcp-guard audit` and `mcp-guard verify-audit` for review-ready summaries, remediation plans, checklists, reports, and verifiable manifests.
 - npm Trusted Publishing workflow prepared for tokenless release publishing.
 
 ## Next

package/docs/rules.md

@@ -2,27 +2,35 @@
 
 `mcp-guard` uses practical heuristics for the first public version. It is designed to surface risky MCP configuration quickly, not to prove a system is fully secure.
 
-| Rule | Severity | What it detects |
-| --- | --- | --- |
-| MCP000 | Low | No MCP config files found in common locations. |
-| MCP001 | High | Server has neither `command` nor `url`. |
-| MCP002 | Medium | Config file has no `mcpServers` or `servers` object. |
-| MCP003 | High | Config file cannot be parsed as JSON. |
-| MCP010 | High/Critical | MCP server runs through a shell, especially with inline `-c`. |
-| MCP011 | High | Interpreter eval mode such as `node -e` or `python -c`. |
-| MCP020 | Medium | Remote package runner such as `npx`, `uvx`, `bunx`, or `pnpm dlx`. |
-| MCP021 | High | Remote package runner without exact package version pinning. |
-| MCP030 | High | Secret-like environment variable exposed to the MCP server. |
-| MCP040 | Medium/High | Broad working directory such as home, root, Desktop, Documents, or Downloads. |
-| MCP041 | Medium/High | Broad filesystem path passed in server arguments. |
-| MCP050 | Critical | Dangerous command pattern such as `rm -rf`, `sudo`, `chmod 777`, or curl pipe to shell. |
-| MCP060 | Medium | Remote MCP server URL configured. |
-| MCP061 | High | Secret-like header configured for a remote MCP server. |
-| MCP070 | High | MCP server command is outside `allowedCommands` policy. |
-| MCP071 | High | Remote MCP package is outside `allowedPackages` policy. |
-| MCP072 | High | MCP server working directory is outside `allowedDirectories` policy. |
-| MCP073 | High | Filesystem argument is outside `allowedDirectories` policy. |
-| MCP074 | High | Remote MCP URL is outside `allowedRemoteUrls` policy. |
+The same catalog is available from the CLI:
+
+```bash
+mcp-guard rules
+mcp-guard rules --format markdown
+mcp-guard rules --format json
+```
+
+| Rule | Severity | Title | What it detects | Recommended response |
+| --- | --- | --- | --- | --- |
+| MCP000 | Low | No MCP config files found | No MCP config files were found in common project or user locations. | Pass `--config` when the MCP config lives outside default discovery paths. |
+| MCP001 | High | Server has no command or URL | An MCP server entry has neither `command` nor `url`. | Remove the server or define an explicit command or URL with reviewed settings. |
+| MCP002 | Medium | Config has no MCP servers object | A config file does not contain an `mcpServers` or `servers` object. | Check that the file is the intended MCP config before relying on the scan. |
+| MCP003 | High | Config cannot be parsed as JSON | A config file could not be parsed as JSON. | Fix the JSON syntax so the scanner and MCP client can read the same config. |
+| MCP010 | High/Critical | MCP server runs through a shell | Shell wrappers such as `sh`, `bash`, `zsh`, `fish`, PowerShell, or `cmd`, especially inline scripts. | Use a direct, pinned executable instead of a shell wrapper. |
+| MCP011 | High | Interpreter eval mode is enabled | Interpreter eval flags such as `node -e`, `python -c`, `ruby -e`, or similar inline code execution. | Replace inline code with a reviewed package or checked-in script. |
+| MCP020 | Medium | Remote package runner is used | Remote package runners such as `npx`, `uvx`, `bunx`, `pipx`, or package-manager `dlx` commands. | Pin the package version and prefer a reviewed lockfile or vendored executable for sensitive tools. |
+| MCP021 | High | Remote MCP package is not version pinned | Remote package execution without an exact package version. | Pin the package to an exact version such as `package@1.2.3` and review updates before changing it. |
+| MCP030 | High | Secret-like environment variable is exposed | Secret-like environment variable names or values passed into an MCP server. | Use least-privilege, short-lived credentials and dedicated service accounts. |
+| MCP040 | Medium/High | MCP server has a broad working directory | Broad working directories such as home, root, Desktop, Documents, or Downloads. | Run the server in a narrow project directory or sandbox with only the files it needs. |
+| MCP041 | Medium/High | MCP server argument grants broad filesystem access | Filesystem arguments that grant broad access to home, root, or sensitive user folders. | Replace broad filesystem paths with a dedicated project folder or read-only sandbox path. |
+| MCP050 | Critical | Command includes a dangerous operation | Dangerous command patterns such as `rm -rf`, `sudo`, `chmod 777`, force push, or curl-pipe-shell. | Remove dangerous startup operations and run setup steps manually after review. |
+| MCP060 | Medium | Remote MCP server URL is configured | Remote HTTP or HTTPS MCP server URLs. | Verify the provider, document data sent to the server, and keep an allowlist of approved endpoints. |
+| MCP061 | High | Secret-like header is configured | Secret-like remote MCP headers such as authorization or API key headers. | Use scoped, short-lived credentials and avoid long-lived secrets in MCP config files. |
+| MCP070 | High | Command is outside policy | An MCP server command that is not listed in `allowedCommands`. | Use an approved command or update policy only after review. |
+| MCP071 | High | Remote package is outside policy | A remote MCP package that is not listed in `allowedPackages`. | Use an approved package or update policy only after package review. |
+| MCP072 | High | Working directory is outside policy | A server working directory outside `allowedDirectories`. | Move the server into an approved workspace or update policy only after review. |
+| MCP073 | High | Filesystem argument is outside policy | A filesystem argument outside `allowedDirectories`. | Limit filesystem arguments to approved directories or update policy only after review. |
+| MCP074 | High | Remote MCP URL is outside policy | A remote MCP endpoint outside `allowedRemoteUrls`. | Use an approved endpoint or update policy only after remote provider review. |
 
 ## Severity Model
 

package/docs/trusted-publishing.md

@@ -36,7 +36,7 @@ Configure this once on npmjs.com:
 After this is saved, run the workflow from GitHub Actions with the release tag, for example:
 
 ```text
-v0.4.7
+v0.4.9
 ```
 
 ## Release Flow After Setup
@@ -44,7 +44,7 @@ v0.4.7
 1. Update `package.json` and `src/cli.js`.
 2. Run `npm test` and `npm run release:check`.
 3. Commit and push to `main`.
-4. Create a GitHub release tag such as `v0.4.7`.
+4. Create a GitHub release tag such as `v0.4.9`.
 5. Run the `Publish npm` workflow with the same tag.
 6. Verify npm:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
   "homepage": "https://chaoyue0307.github.io/mcp-guard/",

package/site/e2e/audit/mcp-guard-audit-manifest.json

@@ -2,9 +2,9 @@
   "version": 1,
   "tool": {
     "name": "mcp-guard",
-    "version": "0.4.7"
+    "version": "0.4.9"
   },
-  "generatedAt": "2026-05-10T20:08:00.622Z",
+  "generatedAt": "2026-05-10T20:51:28.472Z",
   "status": "needs_review",
   "failOn": "none",
   "outputDir": "site/e2e/audit",
@@ -44,43 +44,43 @@
         "key": "executiveSummary",
         "path": "site/e2e/audit/mcp-guard-executive-summary.md",
         "bytes": 1764,
-        "sha256": "d4679b3353a25ed4f88479ae2594fa6a7e2b1b61a9455b56a61e10a70131c87e"
+        "sha256": "6418987f5621711309d1a0af3edf4b1c86f1b069f90e88e7bf0b62748d11bdbe"
       },
       {
         "key": "remediation",
         "path": "site/e2e/audit/mcp-guard-remediation.md",
         "bytes": 2752,
-        "sha256": "1a7a83531f9fea7f0dc8a074a378151f1f7e10a713abc93136e0200bb1dbd35a"
+        "sha256": "208468feb8bc3f7071654ad0e3901cd48312c97dd94f48389aac59ea10012103"
       },
       {
         "key": "remediationChecklist",
         "path": "site/e2e/audit/mcp-guard-remediation-checklist.md",
         "bytes": 2056,
-        "sha256": "d75a40e9c2f243cf9193e50d6d9fa8c56e2d50950deb2f1cc843e230c002e548"
+        "sha256": "e51752f15bd31384b5a170504f38861db503ac95850d720031b8ab858c9d7205"
       },
       {
         "key": "markdownReport",
         "path": "site/e2e/audit/mcp-guard-report.md",
         "bytes": 3297,
-        "sha256": "11a09f58c19ebb836ff4da6f75d050b508fc989dd41ea1c31a02dbafc3367317"
+        "sha256": "c493c4af9ddbcafd8f0538647662068a55206a0c670ccff2ff8ce038b0a6baa3"
       },
       {
         "key": "htmlReport",
         "path": "site/e2e/audit/mcp-guard-report.html",
         "bytes": 12988,
-        "sha256": "3f597e3e1423159f2665b5f5c3b754c2eda4df5645cc2707fa872ddb3c9b7a3c"
+        "sha256": "0c0908853c1f375ce425f5996d2239feb3cae9910139b6c594fe888f9ba22612"
       },
       {
         "key": "jsonReport",
         "path": "site/e2e/audit/mcp-guard-report.json",
         "bytes": 5938,
-        "sha256": "a7b2f086928c1d697c4402b37e84b055a7e12ed2bef55654a19733a80d082947"
+        "sha256": "16feaffcd491dd09864dcd548570c4a1adaea7f3ef401fce4f7fa4151af75796"
       },
       {
         "key": "sarifReport",
         "path": "site/e2e/audit/mcp-guard.sarif",
         "bytes": 20856,
-        "sha256": "994c3bd89e616a76c53cd3797f6323001cc11dcb1afd96ddaeeb9d53c6432ee8"
+        "sha256": "5a00e73219117d9f8e193519a9ddb174b2640c30ade4e963d0829ac94608fa62"
       }
     ]
   }

package/site/e2e/audit/mcp-guard-executive-summary.md

@@ -1,6 +1,6 @@
 # mcp-guard Executive Summary
 
-Generated: 2026-05-10T20:08:00.622Z
+Generated: 2026-05-10T20:51:28.472Z
 Status: **Needs review**
 Risk score: **98**
 Fail threshold: **none**

package/site/e2e/audit/mcp-guard-remediation-checklist.md

@@ -1,6 +1,6 @@
 # mcp-guard Remediation Checklist
 
-Generated: 2026-05-10T20:08:00.622Z
+Generated: 2026-05-10T20:51:28.472Z
 Risk score: **98**
 Active findings: **9**
 

package/site/e2e/audit/mcp-guard-remediation.md

@@ -1,6 +1,6 @@
 # mcp-guard Remediation Plan
 
-Generated: 2026-05-10T20:08:00.622Z
+Generated: 2026-05-10T20:51:28.472Z
 
 ## Priority
 

package/site/e2e/audit/mcp-guard-report.html

@@ -297,7 +297,7 @@
           <div class="metric"><strong>1</strong><span>Scanned files</span></div>
           <div class="metric"><strong>3</strong><span>MCP servers</span></div>
           <div class="metric"><strong>9</strong><span>Active findings</span></div>
-          <div class="metric"><strong>2026-05-10 20:08 UTC</strong><span>Generated</span></div>
+          <div class="metric"><strong>2026-05-10 20:51 UTC</strong><span>Generated</span></div>
         </div>
       </div>
       <aside class="scorecard" aria-label="Risk score">

package/site/e2e/audit/mcp-guard-report.json

@@ -1,11 +1,11 @@
 {
   "metadata": {
-    "generatedAt": "2026-05-10T20:08:00.622Z",
+    "generatedAt": "2026-05-10T20:51:28.472Z",
     "cwd": ".",
     "home": "~",
     "policyPath": "",
     "policyEnabled": false,
-    "toolVersion": "0.4.7"
+    "toolVersion": "0.4.9"
   },
   "policy": null,
   "scannedFiles": [

package/site/e2e/audit/mcp-guard-report.md

@@ -1,6 +1,6 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T20:08:00.622Z
+Generated: 2026-05-10T20:51:28.472Z
 
 ## Summary
 

package/site/e2e/audit/mcp-guard.sarif

@@ -7,7 +7,7 @@
         "driver": {
           "name": "mcp-guard",
           "informationUri": "https://github.com/ChaoYue0307/mcp-guard",
-          "semanticVersion": "0.4.7",
+          "semanticVersion": "0.4.9",
           "rules": [
             {
               "id": "MCP010",

package/site/e2e/report.html

@@ -297,7 +297,7 @@
           <div class="metric"><strong>1</strong><span>Scanned files</span></div>
           <div class="metric"><strong>3</strong><span>MCP servers</span></div>
           <div class="metric"><strong>9</strong><span>Active findings</span></div>
-          <div class="metric"><strong>2026-05-10 20:07 UTC</strong><span>Generated</span></div>
+          <div class="metric"><strong>2026-05-10 20:51 UTC</strong><span>Generated</span></div>
         </div>
       </div>
       <aside class="scorecard" aria-label="Risk score">

package/site/e2e/report.json

@@ -1,11 +1,11 @@
 {
   "metadata": {
-    "generatedAt": "2026-05-10T20:07:57.237Z",
+    "generatedAt": "2026-05-10T20:51:23.431Z",
     "cwd": ".",
     "home": "~",
     "policyPath": "",
     "policyEnabled": false,
-    "toolVersion": "0.4.7"
+    "toolVersion": "0.4.9"
   },
   "policy": null,
   "scannedFiles": [

package/site/e2e/report.md

@@ -1,6 +1,6 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T20:07:52.252Z
+Generated: 2026-05-10T20:51:23.405Z
 
 ## Summary
 

package/site/e2e/report.sarif

@@ -7,7 +7,7 @@
         "driver": {
           "name": "mcp-guard",
           "informationUri": "https://github.com/ChaoYue0307/mcp-guard",
-          "semanticVersion": "0.4.7",
+          "semanticVersion": "0.4.9",
           "rules": [
             {
               "id": "MCP010",

package/src/audit.js

@@ -72,6 +72,76 @@ export async function writeAuditPack({
   };
 }
 
+export async function verifyAuditPack({ cwd, manifestPath = "" }) {
+  const resolvedManifestPath = path.resolve(cwd, manifestPath || path.join("mcp-guard-audit", AUDIT_FILENAMES.manifest));
+  const manifestDir = path.dirname(resolvedManifestPath);
+  const manifest = JSON.parse(await fs.readFile(resolvedManifestPath, "utf8"));
+  const algorithm = manifest.integrity?.algorithm;
+  const artifacts = Array.isArray(manifest.integrity?.artifacts) ? manifest.integrity.artifacts : [];
+  const results = [];
+
+  if (algorithm !== "sha256") {
+    results.push({
+      key: "manifest",
+      path: displayPath(resolvedManifestPath, cwd),
+      status: "failed",
+      reason: `Unsupported or missing integrity algorithm: ${algorithm || "none"}`
+    });
+  }
+
+  if (artifacts.length === 0) {
+    results.push({
+      key: "manifest",
+      path: displayPath(resolvedManifestPath, cwd),
+      status: "failed",
+      reason: "No integrity artifacts found in manifest."
+    });
+  }
+
+  for (const artifact of artifacts) {
+    results.push(await verifyAuditArtifact(artifact, { cwd, manifestDir }));
+  }
+
+  const failedCount = results.filter((result) => result.status !== "passed").length;
+  const checkedCount = artifacts.length;
+  return {
+    manifestPath: resolvedManifestPath,
+    status: failedCount === 0 ? "passed" : "failed",
+    checkedCount,
+    passedCount: results.filter((result) => result.status === "passed").length,
+    failedCount,
+    results
+  };
+}
+
+export function generateAuditVerificationSummary(verification, cwd) {
+  const lines = [];
+  lines.push("mcp-guard audit verification");
+  lines.push(`Manifest: ${displayPath(verification.manifestPath, cwd)}`);
+  lines.push(`Status: ${verification.status}`);
+  lines.push(`Artifacts checked: ${verification.checkedCount}`);
+  lines.push(`Passed: ${verification.passedCount}`);
+  lines.push(`Failed: ${verification.failedCount}`);
+  lines.push("");
+
+  for (const result of verification.results) {
+    lines.push(`- [${result.status === "passed" ? "ok" : "failed"}] ${result.key}: ${result.path}`);
+    if (result.status !== "passed") {
+      lines.push(`  Reason: ${result.reason}`);
+      if (result.expectedSha256 || result.actualSha256) {
+        lines.push(`  Expected sha256: ${result.expectedSha256 || "-"}`);
+        lines.push(`  Actual sha256: ${result.actualSha256 || "-"}`);
+      }
+      if (Number.isInteger(result.expectedBytes) || Number.isInteger(result.actualBytes)) {
+        lines.push(`  Expected bytes: ${result.expectedBytes ?? "-"}`);
+        lines.push(`  Actual bytes: ${result.actualBytes ?? "-"}`);
+      }
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
 export function auditFilePaths(outputDir) {
   return Object.fromEntries(
     Object.entries(AUDIT_FILENAMES).map(([key, filename]) => [key, path.join(outputDir, filename)])
@@ -294,6 +364,69 @@ async function auditArtifacts(files, cwd) {
   return artifacts;
 }
 
+async function verifyAuditArtifact(artifact, { cwd, manifestDir }) {
+  if (!artifact?.key || !artifact?.path) {
+    return {
+      key: artifact?.key || "<unknown>",
+      path: artifact?.path || "<missing>",
+      status: "failed",
+      reason: "Artifact entry is missing key or path."
+    };
+  }
+
+  const resolvedPath = await resolveAuditArtifactPath(artifact.path, { cwd, manifestDir });
+  let content;
+  try {
+    content = await fs.readFile(resolvedPath);
+  } catch {
+    return {
+      key: artifact.key,
+      path: artifact.path,
+      resolvedPath: displayPath(resolvedPath, cwd),
+      status: "failed",
+      reason: "Artifact file is missing.",
+      expectedBytes: artifact.bytes,
+      expectedSha256: artifact.sha256
+    };
+  }
+
+  const actualBytes = content.byteLength;
+  const actualSha256 = crypto.createHash("sha256").update(content).digest("hex");
+  const bytesMatch = actualBytes === artifact.bytes;
+  const hashMatch = actualSha256 === artifact.sha256;
+  return {
+    key: artifact.key,
+    path: artifact.path,
+    resolvedPath: displayPath(resolvedPath, cwd),
+    status: bytesMatch && hashMatch ? "passed" : "failed",
+    reason: bytesMatch && hashMatch ? "" : "Artifact content does not match manifest integrity metadata.",
+    expectedBytes: artifact.bytes,
+    actualBytes,
+    expectedSha256: artifact.sha256,
+    actualSha256
+  };
+}
+
+async function resolveAuditArtifactPath(artifactPath, { cwd, manifestDir }) {
+  if (path.isAbsolute(artifactPath)) return artifactPath;
+
+  const candidates = [
+    path.join(manifestDir, path.basename(artifactPath)),
+    path.resolve(cwd, artifactPath)
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // Try the next candidate.
+    }
+  }
+
+  return candidates[0];
+}
+
 function decisionGuidance(result) {
   if (result.findings.length === 0) {
     return ["No active findings were detected. Continue reviewing new MCP servers before adding them."];

package/src/cli.js

@@ -1,13 +1,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { generateAuditSummary, writeAuditPack } from "./audit.js";
+import { generateAuditSummary, generateAuditVerificationSummary, verifyAuditPack, writeAuditPack } from "./audit.js";
 import { applyBaseline, loadBaselineFile, writeBaselineFile } from "./baseline.js";
 import { initProject, renderInitSummary } from "./init.js";
 import { scan } from "./scan.js";
 import { generateHtmlReport, generateJsonReport, generateMarkdownReport, generateSarifReport, generateTextReport } from "./report.js";
+import { generateRulesJson, generateRulesMarkdown, generateRulesText } from "./rule-catalog.js";
 import { compareSeverity, severityRank } from "./severity.js";
 
-const VERSION = "0.4.7";
+const VERSION = "0.4.9";
 
 export async function runCli(argv, io) {
   const args = argv.slice(2);
@@ -23,6 +24,17 @@ export async function runCli(argv, io) {
     return 0;
   }
 
+  if (command === "rules") {
+    if (args.includes("--help") || args.includes("-h")) {
+      io.stdout.write(helpText());
+      return 0;
+    }
+
+    const options = parseRulesArgs(args.slice(1));
+    io.stdout.write(renderRules(options.format));
+    return 0;
+  }
+
   if (command === "init") {
     if (args.includes("--help") || args.includes("-h")) {
       io.stdout.write(helpText());
@@ -84,6 +96,25 @@ export async function runCli(argv, io) {
     return 0;
   }
 
+  if (command === "verify-audit") {
+    if (args.includes("--help") || args.includes("-h")) {
+      io.stdout.write(helpText());
+      return 0;
+    }
+
+    const options = parseVerifyAuditArgs(args.slice(1), io.cwd);
+    const verification = await verifyAuditPack({
+      cwd: options.cwd,
+      manifestPath: options.manifestPath
+    });
+    io.stdout.write(generateAuditVerificationSummary(verification, options.cwd));
+    if (verification.status !== "passed") {
+      process.exitCode = 2;
+      return 2;
+    }
+    return 0;
+  }
+
   if (command !== "scan") {
     io.stderr.write(`Unknown command: ${command}\n\n`);
     io.stderr.write(helpText());
@@ -329,6 +360,51 @@ function parseAuditArgs(args, defaultCwd) {
   return options;
 }
 
+function parseVerifyAuditArgs(args, defaultCwd) {
+  const options = {
+    cwd: defaultCwd,
+    manifestPath: ""
+  };
+  let manifestValue = "";
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--manifest" || arg === "-m") {
+      manifestValue = readValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--cwd") {
+      options.cwd = path.resolve(readValue(args, index, arg));
+      index += 1;
+    } else {
+      throw new Error(`Unknown verify-audit option: ${arg}`);
+    }
+  }
+
+  options.manifestPath = manifestValue ? resolveInputPath(manifestValue, options.cwd) : "";
+  return options;
+}
+
+function parseRulesArgs(args) {
+  const options = {
+    format: "text"
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--format" || arg === "-f") {
+      options.format = readValue(args, index, arg);
+      index += 1;
+      if (!["text", "markdown", "json"].includes(options.format)) {
+        throw new Error("--format must be one of: text, markdown, json");
+      }
+    } else {
+      throw new Error(`Unknown rules option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
 function readValue(args, index, optionName) {
   const value = args[index + 1];
   if (!value || value.startsWith("--")) {
@@ -357,6 +433,16 @@ function renderReport(result, format) {
   return generateTextReport(result);
 }
 
+function renderRules(format) {
+  if (format === "json") {
+    return generateRulesJson();
+  }
+  if (format === "markdown") {
+    return generateRulesMarkdown();
+  }
+  return generateRulesText();
+}
+
 function shouldFail(result, failOn) {
   const threshold = severityRank(failOn);
   return result.findings.some((finding) => compareSeverity(finding.severity, threshold) >= 0);
@@ -370,6 +456,8 @@ Open-source scanner for risky MCP server and AI agent tool configuration.
 Usage:
   mcp-guard scan [options]
   mcp-guard audit [options]
+  mcp-guard verify-audit [options]
+  mcp-guard rules [options]
   mcp-guard init [options]
   mcp-guard version
   mcp-guard help
@@ -420,11 +508,21 @@ Audit options:
       --no-policy           Do not auto-load .mcp-guard-policy.json.
       --no-defaults         Only scan paths passed with --config.
 
+Verify audit options:
+  -m, --manifest <path>     Audit manifest to verify.
+                            Default: mcp-guard-audit/mcp-guard-audit-manifest.json.
+      --cwd <path>          Working directory for resolving relative artifact paths.
+
+Rules options:
+  -f, --format <format>     text, markdown, or json. Default: text.
+
 Examples:
   mcp-guard init
   mcp-guard init --write-baseline --upload-sarif
   mcp-guard scan
+  mcp-guard rules --format markdown
   mcp-guard audit --config .mcp.json --output-dir mcp-guard-audit
+  mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json
   mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --fail-on high
   mcp-guard scan --format markdown --output mcp-guard-report.md
   mcp-guard scan --format html --output mcp-guard-report.html

package/src/rule-catalog.js

@@ -0,0 +1,169 @@
+export const RULE_CATALOG = [
+  {
+    id: "MCP000",
+    severity: "low",
+    title: "No MCP config files found",
+    detects: "No MCP config files were found in common project or user locations.",
+    recommendation: "Pass --config when the MCP config lives outside default discovery paths."
+  },
+  {
+    id: "MCP001",
+    severity: "high",
+    title: "Server has no command or URL",
+    detects: "An MCP server entry has neither command nor url.",
+    recommendation: "Remove the server or define an explicit command or URL with reviewed settings."
+  },
+  {
+    id: "MCP002",
+    severity: "medium",
+    title: "Config has no MCP servers object",
+    detects: "A config file does not contain an mcpServers or servers object.",
+    recommendation: "Check that the file is the intended MCP config before relying on the scan."
+  },
+  {
+    id: "MCP003",
+    severity: "high",
+    title: "Config cannot be parsed as JSON",
+    detects: "A config file could not be parsed as JSON.",
+    recommendation: "Fix the JSON syntax so the scanner and MCP client can read the same config."
+  },
+  {
+    id: "MCP010",
+    severity: "high/critical",
+    title: "MCP server runs through a shell",
+    detects: "Shell wrappers such as sh, bash, zsh, fish, PowerShell, or cmd, especially inline scripts.",
+    recommendation: "Use a direct, pinned executable instead of a shell wrapper."
+  },
+  {
+    id: "MCP011",
+    severity: "high",
+    title: "Interpreter eval mode is enabled",
+    detects: "Interpreter eval flags such as node -e, python -c, ruby -e, or similar inline code execution.",
+    recommendation: "Replace inline code with a reviewed package or checked-in script."
+  },
+  {
+    id: "MCP020",
+    severity: "medium",
+    title: "Remote package runner is used",
+    detects: "Remote package runners such as npx, uvx, bunx, pipx, or package-manager dlx commands.",
+    recommendation: "Pin the package version and prefer a reviewed lockfile or vendored executable for sensitive tools."
+  },
+  {
+    id: "MCP021",
+    severity: "high",
+    title: "Remote MCP package is not version pinned",
+    detects: "Remote package execution without an exact package version.",
+    recommendation: "Pin the package to an exact version such as package@1.2.3 and review updates before changing it."
+  },
+  {
+    id: "MCP030",
+    severity: "high",
+    title: "Secret-like environment variable is exposed",
+    detects: "Secret-like environment variable names or values passed into an MCP server.",
+    recommendation: "Use least-privilege, short-lived credentials and dedicated service accounts."
+  },
+  {
+    id: "MCP040",
+    severity: "medium/high",
+    title: "MCP server has a broad working directory",
+    detects: "Broad working directories such as home, root, Desktop, Documents, or Downloads.",
+    recommendation: "Run the server in a narrow project directory or sandbox with only the files it needs."
+  },
+  {
+    id: "MCP041",
+    severity: "medium/high",
+    title: "MCP server argument grants broad filesystem access",
+    detects: "Filesystem arguments that grant broad access to home, root, or sensitive user folders.",
+    recommendation: "Replace broad filesystem paths with a dedicated project folder or read-only sandbox path."
+  },
+  {
+    id: "MCP050",
+    severity: "critical",
+    title: "Command includes a dangerous operation",
+    detects: "Dangerous command patterns such as rm -rf, sudo, chmod 777, force push, or curl-pipe-shell.",
+    recommendation: "Remove dangerous startup operations and run setup steps manually after review."
+  },
+  {
+    id: "MCP060",
+    severity: "medium",
+    title: "Remote MCP server URL is configured",
+    detects: "Remote HTTP or HTTPS MCP server URLs.",
+    recommendation: "Verify the provider, document data sent to the server, and keep an allowlist of approved endpoints."
+  },
+  {
+    id: "MCP061",
+    severity: "high",
+    title: "Secret-like header is configured",
+    detects: "Secret-like remote MCP headers such as authorization or API key headers.",
+    recommendation: "Use scoped, short-lived credentials and avoid long-lived secrets in MCP config files."
+  },
+  {
+    id: "MCP070",
+    severity: "high",
+    title: "Command is outside policy",
+    detects: "An MCP server command that is not listed in allowedCommands.",
+    recommendation: "Use an approved command or update policy only after review."
+  },
+  {
+    id: "MCP071",
+    severity: "high",
+    title: "Remote package is outside policy",
+    detects: "A remote MCP package that is not listed in allowedPackages.",
+    recommendation: "Use an approved package or update policy only after package review."
+  },
+  {
+    id: "MCP072",
+    severity: "high",
+    title: "Working directory is outside policy",
+    detects: "A server working directory outside allowedDirectories.",
+    recommendation: "Move the server into an approved workspace or update policy only after review."
+  },
+  {
+    id: "MCP073",
+    severity: "high",
+    title: "Filesystem argument is outside policy",
+    detects: "A filesystem argument outside allowedDirectories.",
+    recommendation: "Limit filesystem arguments to approved directories or update policy only after review."
+  },
+  {
+    id: "MCP074",
+    severity: "high",
+    title: "Remote MCP URL is outside policy",
+    detects: "A remote MCP endpoint outside allowedRemoteUrls.",
+    recommendation: "Use an approved endpoint or update policy only after remote provider review."
+  }
+];
+
+export function generateRulesText(rules = RULE_CATALOG) {
+  const lines = [];
+  lines.push("mcp-guard rule reference");
+  lines.push(`Rules: ${rules.length}`);
+  lines.push("");
+  for (const rule of rules) {
+    lines.push(`- [${rule.severity.toUpperCase()}] ${rule.id} ${rule.title}`);
+    lines.push(`  Detects: ${rule.detects}`);
+    lines.push(`  Fix: ${rule.recommendation}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function generateRulesMarkdown(rules = RULE_CATALOG) {
+  const lines = [];
+  lines.push("# mcp-guard Rule Reference");
+  lines.push("");
+  lines.push("| Rule | Severity | Title | What it detects | Recommended response |");
+  lines.push("| --- | --- | --- | --- | --- |");
+  for (const rule of rules) {
+    lines.push(`| ${cell(rule.id)} | ${cell(rule.severity)} | ${cell(rule.title)} | ${cell(rule.detects)} | ${cell(rule.recommendation)} |`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}`;
+}
+
+export function generateRulesJson(rules = RULE_CATALOG) {
+  return `${JSON.stringify({ rules }, null, 2)}\n`;
+}
+
+function cell(value) {
+  return String(value).replace(/\|/g, "\\|");
+}