agent-mcp-guard 0.4.8 → 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.8"><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,6 +86,13 @@ 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
@@ -94,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.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     # policy: .mcp-guard-policy.json

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.8
+- 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.8",
+  "toolVersion": "0.4.9",
   "findings": [
     {
       "fingerprint": "mcpg_a009b2c2",

package/docs/github-action.md

@@ -39,7 +39,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.8
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -67,7 +67,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.8
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -79,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.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     fail-on: none
 ```
@@ -95,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.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -109,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.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json

package/docs/launch-checklist.md

@@ -38,7 +38,7 @@ mcp-guard verify-audit --manifest mcp-guard-audit/mcp-guard-audit-manifest.json
 ## GitHub Action Setup
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.8
+- 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.8
+      - 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.8
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.9
         with:
           config: .mcp.json
           fail-on: high
@@ -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.8
+- 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.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json

package/docs/marketplace.md

@@ -82,18 +82,18 @@ Code quality
 Current release title:
 
 ```text
-v0.4.8
+v0.4.9
 ```
 
 Release notes:
 
 ```text
-Audit verification release.
+Rule catalog and MCP education release.
 
-- Adds `mcp-guard verify-audit` so downloaded audit packs can be checked against the manifest without custom scripts.
-- Verifies 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 or CI download.
+- 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
@@ -106,7 +106,7 @@ Completed:
 - README, docs, and website examples now use:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.8
+- uses: ChaoYue0307/mcp-guard-action@v0.4.9
 ```
 
 Remaining Marketplace web step:

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.8
+v0.4.9
 ```
 
 ## Release Flow After Setup
@@ -44,7 +44,7 @@ v0.4.8
 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.8`.
+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.8",
+  "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.8"
+    "version": "0.4.9"
   },
-  "generatedAt": "2026-05-10T20:20:35.470Z",
+  "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": "63e42ed47cc429f8ccdfe1bb47c35c62d47f483e4ed6582c87d2542e7cbaf7e6"
+        "sha256": "6418987f5621711309d1a0af3edf4b1c86f1b069f90e88e7bf0b62748d11bdbe"
       },
       {
         "key": "remediation",
         "path": "site/e2e/audit/mcp-guard-remediation.md",
         "bytes": 2752,
-        "sha256": "2a71e9fb0f426ee99ee045112264bc24d220610098c1e991e0a3dc409310fed8"
+        "sha256": "208468feb8bc3f7071654ad0e3901cd48312c97dd94f48389aac59ea10012103"
       },
       {
         "key": "remediationChecklist",
         "path": "site/e2e/audit/mcp-guard-remediation-checklist.md",
         "bytes": 2056,
-        "sha256": "26902af05eb8d4c880b32ec96130177c0ff00ade96b004e15564caa82cd01d48"
+        "sha256": "e51752f15bd31384b5a170504f38861db503ac95850d720031b8ab858c9d7205"
       },
       {
         "key": "markdownReport",
         "path": "site/e2e/audit/mcp-guard-report.md",
         "bytes": 3297,
-        "sha256": "6882a79e02c821697e8e4a02168f9f87372822ac2b1e135ea399621c77f742c0"
+        "sha256": "c493c4af9ddbcafd8f0538647662068a55206a0c670ccff2ff8ce038b0a6baa3"
       },
       {
         "key": "htmlReport",
         "path": "site/e2e/audit/mcp-guard-report.html",
         "bytes": 12988,
-        "sha256": "eefc4b523c90dcb46c2ebad6dff6b7885be913d1a8bfb36ff930b35dd0da7ca9"
+        "sha256": "0c0908853c1f375ce425f5996d2239feb3cae9910139b6c594fe888f9ba22612"
       },
       {
         "key": "jsonReport",
         "path": "site/e2e/audit/mcp-guard-report.json",
         "bytes": 5938,
-        "sha256": "e7c65a367d5115e25042a71e9408427e25c357c762a00747d2046167980b54f5"
+        "sha256": "16feaffcd491dd09864dcd548570c4a1adaea7f3ef401fce4f7fa4151af75796"
       },
       {
         "key": "sarifReport",
         "path": "site/e2e/audit/mcp-guard.sarif",
         "bytes": 20856,
-        "sha256": "16bfca40d3158c8864bc2d0dd120ffb48e2277f60e576477c65b22fd3eb2bbd0"
+        "sha256": "5a00e73219117d9f8e193519a9ddb174b2640c30ade4e963d0829ac94608fa62"
       }
     ]
   }

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

@@ -1,6 +1,6 @@
 # mcp-guard Executive Summary
 
-Generated: 2026-05-10T20:20:35.470Z
+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:20:35.470Z
+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:20:35.470Z
+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:20 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:20:35.470Z",
+    "generatedAt": "2026-05-10T20:51:28.472Z",
     "cwd": ".",
     "home": "~",
     "policyPath": "",
     "policyEnabled": false,
-    "toolVersion": "0.4.8"
+    "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:20:35.470Z
+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.8",
+          "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:20 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:20:32.748Z",
+    "generatedAt": "2026-05-10T20:51:23.431Z",
     "cwd": ".",
     "home": "~",
     "policyPath": "",
     "policyEnabled": false,
-    "toolVersion": "0.4.8"
+    "toolVersion": "0.4.9"
   },
   "policy": null,
   "scannedFiles": [

package/site/e2e/report.md

@@ -1,6 +1,6 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T20:20:32.709Z
+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.8",
+          "semanticVersion": "0.4.9",
           "rules": [
             {
               "id": "MCP010",

package/src/cli.js

@@ -5,9 +5,10 @@ import { applyBaseline, loadBaselineFile, writeBaselineFile } from "./baseline.j
 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.8";
+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());
@@ -372,6 +384,27 @@ function parseVerifyAuditArgs(args, defaultCwd) {
   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("--")) {
@@ -400,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);
@@ -414,6 +457,7 @@ 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
@@ -469,10 +513,14 @@ Verify audit options:
                             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

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, "\\|");
+}