agent-mcp-guard 0.4.3 → 0.4.4

package/README.md

@@ -19,7 +19,7 @@ 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.3"><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.4"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -71,6 +71,12 @@ Use in CI:
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
+Enforce a team policy for approved commands, packages, directories, and remote URLs:
+
+```bash
+mcp-guard scan --config .mcp.json --policy .mcp-guard-policy.json --fail-on high
+```
+
 Accept known findings and fail only on new risk:
 
 ```bash
@@ -81,9 +87,10 @@ 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.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   with:
     config: .mcp.json
+    # policy: .mcp-guard-policy.json
     baseline: .mcp-guard-baseline.json
     fail-on: high
     comment-pr: "true"
@@ -117,6 +124,7 @@ For the GitHub Action workflow, inspect the public demo repository: [ChaoYue0307
 | Broad filesystem access | Home, root, Desktop, Documents, and Downloads are high-blast-radius paths. |
 | Remote MCP URLs | Data may leave the local trust boundary. |
 | Dangerous command patterns | `rm -rf`, `sudo`, `chmod 777`, and curl-pipe-shell should block review. |
+| Policy violations | Teams can enforce approved commands, packages, directories, and remote URLs. |
 
 ## Team Workflow
 
@@ -129,6 +137,8 @@ For the GitHub Action workflow, inspect the public demo repository: [ChaoYue0307
 
 The GitHub Action can also post an optional pull request comment with the active finding summary.
 
+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).
+
 For a guided setup, run:
 
 ```bash
@@ -193,6 +203,7 @@ Typical scope:
 
 - install and run the CLI against redacted local MCP configs;
 - create the GitHub Action workflow;
+- define an initial `.mcp-guard-policy.json`;
 - generate and review an initial baseline;
 - enable PR comments and optional GitHub code scanning;
 - record missing rules or config shapes as product feedback.
@@ -203,6 +214,7 @@ Contact: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
 
 - [Rule reference](docs/rules.md)
 - [Baseline and allowlist](docs/baseline.md)
+- [Policy files](docs/policy.md)
 - [GitHub Action](docs/github-action.md)
 - [Marketplace publishing plan](docs/marketplace.md)
 - [Privacy and security](docs/privacy-and-security.md)

package/action.yml

@@ -19,6 +19,10 @@ inputs:
     description: Optional mcp-guard baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow.
     required: false
     default: ""
+  policy:
+    description: Optional mcp-guard policy JSON path. Leave empty to auto-load .mcp-guard-policy.json when present.
+    required: false
+    default: ""
   comment-pr:
     description: "Post or update a pull request comment with the scan summary. Requires pull-requests: write permission."
     required: false
@@ -67,6 +71,7 @@ runs:
       uses: actions/setup-node@v6
       with:
         node-version: "24"
+        package-manager-cache: false
 
     - name: Generate reports
       id: reports
@@ -74,6 +79,7 @@ runs:
       env:
         MCP_GUARD_CONFIG: ${{ inputs.config }}
         MCP_GUARD_BASELINE: ${{ inputs.baseline }}
+        MCP_GUARD_POLICY: ${{ inputs.policy }}
         MCP_GUARD_FAIL_ON: ${{ inputs.fail-on }}
         MCP_GUARD_OUTPUT_DIR: ${{ inputs.output-dir }}
       run: |
@@ -89,6 +95,9 @@ runs:
         if [ -n "${MCP_GUARD_BASELINE}" ]; then
           scan_args+=(--baseline "${MCP_GUARD_BASELINE}")
         fi
+        if [ -n "${MCP_GUARD_POLICY}" ]; then
+          scan_args+=(--policy "${MCP_GUARD_POLICY}")
+        fi
 
         markdown_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.md"
         html_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.html"

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.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   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.3",
+  "toolVersion": "0.4.4",
   "findings": [
     {
       "fingerprint": "mcpg_a009b2c2",

package/docs/business-playbook.md

@@ -17,6 +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;
+- 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;
 - document missing rule requests for future product work;
@@ -39,7 +40,7 @@ I built mcp-guard, an open-source local scanner for MCP and AI agent tool config
 
 It checks for risky shell access, unpinned npx packages, broad filesystem permissions, exposed secrets, and remote MCP servers.
 
-It now includes `mcp-guard init`, which creates a GitHub Action workflow and can generate a baseline for accepted current findings.
+It now includes `mcp-guard init`, which creates a GitHub Action workflow, can generate a baseline for accepted current findings, and can enforce a committed policy for approved MCP commands, packages, directories, and URLs.
 
 I am collecting real-world MCP and AI agent config patterns from teams using Claude, Cursor, Codex, or MCP in production-like workflows. If you can share a redacted config or run the CLI locally, your feedback can help improve the scanner's rules and reports.
 ```

package/docs/github-action.md

@@ -4,7 +4,9 @@ Use the `mcp-guard` action to scan MCP and AI agent tool configuration in pull r
 
 The action runs the CLI from the pinned GitHub Action tag, generates Markdown, HTML, JSON, and SARIF reports, writes a job summary, uploads reports as an artifact, and fails the job when findings meet your selected severity threshold.
 
-It can also use a committed baseline to accept known findings and optionally post a pull request comment with only the active findings.
+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.
+
+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>
 
@@ -35,7 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.3
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
         with:
           config: .mcp.json
           fail-on: high
@@ -63,7 +65,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.3
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
         with:
           config: .mcp.json
           fail-on: high
@@ -75,7 +77,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.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   with:
     fail-on: none
 ```
@@ -91,7 +93,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.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -100,6 +102,20 @@ Commit `.mcp-guard-baseline.json`, then reference it from the action:
 
 Reports will show active findings separately from findings accepted by the baseline.
 
+## Policy Mode
+
+Use a policy when you want CI to enforce approved commands, packages, directories, and remote URLs.
+
+```yaml
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
+  with:
+    config: .mcp.json
+    policy: .mcp-guard-policy.json
+    fail-on: high
+```
+
+See [Policy files](policy.md) for the file format.
+
 ## Inputs
 
 | Input | Default | Description |
@@ -107,6 +123,7 @@ Reports will show active findings separately from findings accepted by the basel
 | `config` | empty | Optional MCP config path. Empty scans default project and user config locations. |
 | `fail-on` | `high` | Fails the job for `critical`, `high`, `medium`, or `low` findings. Use `none` for report-only mode. |
 | `baseline` | empty | Optional baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow. |
+| `policy` | empty | Optional policy JSON path. Empty auto-loads `.mcp-guard-policy.json` when present. |
 | `comment-pr` | `false` | Posts or updates a pull request comment with the scan summary. Requires `pull-requests: write`. |
 | `output-dir` | `mcp-guard-report` | Directory for generated reports. |
 | `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |

package/docs/launch-checklist.md

@@ -31,7 +31,7 @@ mcp-guard scan --config .mcp.json --fail-on high
 ## GitHub Action Setup
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   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.3
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
         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.3
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
         with:
           config: .mcp.json
           fail-on: high
@@ -56,6 +56,7 @@ jobs:
 | `config` | empty | Optional MCP config path. Empty scans default project and user config locations. |
 | `fail-on` | `high` | Fails the job for `critical`, `high`, `medium`, or `low` findings. Use `none` for report-only mode. |
 | `baseline` | empty | Optional baseline/allowlist JSON path. Matching findings are accepted and do not fail the workflow. |
+| `policy` | empty | Optional policy JSON path. Empty auto-loads `.mcp-guard-policy.json` when present. |
 | `comment-pr` | `false` | Posts or updates a pull request comment with the scan summary. Requires `pull-requests: write`. |
 | `output-dir` | `mcp-guard-report` | Directory for generated reports. |
 | `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |
@@ -95,13 +96,25 @@ 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.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
     fail-on: high
 ```
 
+## Policy Mode
+
+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.4
+  with:
+    config: .mcp.json
+    policy: .mcp-guard-policy.json
+    fail-on: high
+```
+
 ## Transparent Example
 
 Inspect a committed input config, reproduction commands, and generated Markdown, HTML, JSON, and SARIF artifacts:

package/docs/marketplace.md

@@ -82,16 +82,17 @@ Code quality
 Current release title:
 
 ```text
-v0.4.3
+v0.4.4
 ```
 
 Release notes:
 
 ```text
-Trusted Publishing readiness release.
+Policy enforcement release.
 
-- Adds a GitHub Actions workflow for npm Trusted Publishing readiness.
-- Keeps `mcp-guard init` for generating a GitHub Action workflow and baseline.
+- Adds `.mcp-guard-policy.json` support for approved commands, packages, directories, and remote URLs.
+- Adds the `policy` GitHub Action input and automatic root policy discovery.
+- Adds MCP070-MCP074 policy findings.
 - Keeps Node.js 24, PR comments, artifacts, and SARIF upload support.
 ```
 
@@ -105,7 +106,7 @@ Completed:
 - README, docs, and website examples now use:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.4
 ```
 
 Remaining Marketplace web step:

package/docs/policy.md

@@ -0,0 +1,50 @@
+# Policy Files
+
+Use a policy file when a team wants an explicit approval boundary for MCP servers, not just heuristic risk findings.
+
+`mcp-guard scan` automatically loads `.mcp-guard-policy.json` from the working directory when the file exists. You can also pass a policy explicitly:
+
+```bash
+mcp-guard scan --config .mcp.json --policy .mcp-guard-policy.json --fail-on high
+```
+
+Disable automatic policy loading with:
+
+```bash
+mcp-guard scan --no-policy
+```
+
+## Example
+
+```json
+{
+  "version": 1,
+  "allowedCommands": ["node", "uvx"],
+  "allowedPackages": ["@approved/mcp-server"],
+  "allowedDirectories": ["./workspace"],
+  "allowedRemoteUrls": ["https://approved.example.com"]
+}
+```
+
+Each field is optional. Empty or omitted fields are not enforced.
+
+## Fields
+
+| Field | Meaning |
+| --- | --- |
+| `allowedCommands` | Approved command basenames, such as `node`, `docker`, or `uvx`. |
+| `allowedPackages` | Approved remote-runner package names, without requiring a version suffix. |
+| `allowedDirectories` | Approved filesystem roots. Relative paths resolve from the scan working directory. |
+| `allowedRemoteUrls` | Approved remote MCP URL origins or path prefixes. |
+
+## Policy Findings
+
+| Rule | Severity | What it detects |
+| --- | --- | --- |
+| MCP070 | High | MCP server command is not in `allowedCommands`. |
+| MCP071 | High | Remote package runner uses a package outside `allowedPackages`. |
+| MCP072 | High | MCP server `cwd` is outside `allowedDirectories`. |
+| MCP073 | High | Filesystem argument is outside `allowedDirectories`. |
+| MCP074 | High | Remote MCP URL is outside `allowedRemoteUrls`. |
+
+Policy findings are additive. A policy does not suppress the built-in rules for shell execution, unpinned packages, broad filesystem access, secret-like values, or dangerous commands.

package/docs/roadmap.md

@@ -12,15 +12,15 @@
 - Baseline/allowlist mode for accepting known findings and failing only on new risks.
 - 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.
 - npm Trusted Publishing workflow prepared for tokenless release publishing.
 
 ## Next
 
 1. More MCP client discovery paths.
 2. Rule packs mapped to MCP security best practices.
-3. Policy file for approved commands, packages, directories, and remote URLs.
-4. `mcp-guard audit` mode for review-ready reports.
-5. Safer default remediation snippets for common MCP servers.
+3. `mcp-guard audit` mode for review-ready reports.
+4. Safer default remediation snippets for common MCP servers.
 
 ## Later
 

package/docs/rules.md

@@ -18,6 +18,11 @@
 | 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. |
 
 ## Severity Model
 
@@ -32,4 +37,3 @@
 - The scanner does not upload configs.
 - Detection is heuristic and will miss some risks.
 - A clean report is not a security guarantee.
-

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.3
+v0.4.4
 ```
 
 ## Release Flow After Setup
@@ -44,7 +44,7 @@ v0.4.3
 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.3`.
+4. Create a GitHub release tag such as `v0.4.4`.
 5. Run the `Publish npm` workflow with the same tag.
 6. Verify npm:
 

package/examples/mcp-guard-policy.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "allowedCommands": [
+    "node",
+    "uvx"
+  ],
+  "allowedPackages": [
+    "@approved/mcp-server"
+  ],
+  "allowedDirectories": [
+    "./workspace"
+  ],
+  "allowedRemoteUrls": [
+    "https://approved.example.com"
+  ]
+}

package/examples/sample-report.md

@@ -1,6 +1,6 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T13:47:08.616Z
+Generated: 2026-05-10T14:01:29.032Z
 
 ## Summary
 

package/package.json

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

package/scripts/action-comment.js

@@ -29,6 +29,9 @@ lines.push(`Active findings: **${report.summary.findingCount}**`);
 if (acceptedCount > 0 || report.baseline?.enabled) {
   lines.push(`Accepted by baseline: **${acceptedCount}**`);
 }
+if (report.policy?.path) {
+  lines.push(`Policy: **${report.policy.path}**`);
+}
 lines.push(`Fail threshold: **${failOn || "high"}**`);
 if (runUrl) {
   lines.push(`Workflow run: ${runUrl}`);

package/scripts/action-summary.js

@@ -33,6 +33,9 @@ lines.push(`Active findings: **${report.summary.findingCount}**`);
 if (acceptedCount > 0 || report.baseline?.enabled) {
   lines.push(`Accepted by baseline: **${acceptedCount}**`);
 }
+if (report.policy?.path) {
+  lines.push(`Policy: **${report.policy.path}**`);
+}
 lines.push(`Fail threshold: **${failOn || "high"}**`);
 lines.push("");
 

package/scripts/prepare-marketplace-action.js

@@ -58,6 +58,7 @@ function validateExport() {
     "package.json",
     "bin/mcp-guard.js",
     "src/cli.js",
+    "src/policy.js",
     "src/report.js",
     "scripts/action-summary.js",
     "scripts/action-comment.js"

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 13:47 UTC</strong><span>Generated</span></div>
+          <div class="metric"><strong>2026-05-10 14:01 UTC</strong><span>Generated</span></div>
         </div>
       </div>
       <aside class="scorecard" aria-label="Risk score">
@@ -324,6 +324,8 @@
       <div class="table-wrap"><table><thead><tr><th>Path</th></tr></thead><tbody><tr><td><code>site/e2e/claude_desktop_config.json</code></td></tr></tbody></table></div>
     </section>
 
+
+
     <section>
       <h2>MCP Server Inventory</h2>
       <div class="table-wrap"><table>

package/site/e2e/report.json

@@ -1,10 +1,13 @@
 {
   "metadata": {
-    "generatedAt": "2026-05-10T13:47:08.576Z",
+    "generatedAt": "2026-05-10T14:01:28.980Z",
     "cwd": ".",
     "home": "~",
-    "toolVersion": "0.4.3"
+    "policyPath": "",
+    "policyEnabled": false,
+    "toolVersion": "0.4.4"
   },
+  "policy": null,
   "scannedFiles": [
     "site/e2e/claude_desktop_config.json"
   ],

package/site/e2e/report.md

@@ -1,6 +1,6 @@
 # mcp-guard Scan Report
 
-Generated: 2026-05-10T13:47:08.555Z
+Generated: 2026-05-10T14:01:28.971Z
 
 ## Summary
 

package/site/e2e/report.sarif

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

package/src/baseline.js

@@ -107,6 +107,8 @@ export function summarize(findings, servers, scannedFiles, acceptedFindingCount
     }
   }
 
+  const rawRiskScore = counts.critical * 20 + counts.high * 10 + counts.medium * 4 + counts.low;
+
   return {
     scannedFileCount: scannedFiles.length,
     serverCount: servers.length,
@@ -115,7 +117,7 @@ export function summarize(findings, servers, scannedFiles, acceptedFindingCount
     acceptedFindingCount,
     totalFindingCount: findings.length + acceptedFindingCount,
     counts,
-    riskScore: counts.critical * 20 + counts.high * 10 + counts.medium * 4 + counts.low
+    riskScore: Math.min(100, rawRiskScore)
   };
 }
 

package/src/cli.js

@@ -6,7 +6,7 @@ import { scan } from "./scan.js";
 import { generateHtmlReport, generateJsonReport, generateMarkdownReport, generateSarifReport, generateTextReport } from "./report.js";
 import { compareSeverity, severityRank } from "./severity.js";
 
-const VERSION = "0.4.3";
+const VERSION = "0.4.4";
 
 export async function runCli(argv, io) {
   const args = argv.slice(2);
@@ -36,6 +36,7 @@ export async function runCli(argv, io) {
       includeDefaults: options.includeDefaults,
       workflowPath: options.workflowPath,
       baselinePath: options.baselinePath,
+      policyPath: options.policyPath,
       failOn: options.failOn,
       commentPr: options.commentPr,
       uploadSarif: options.uploadSarif,
@@ -68,6 +69,8 @@ export async function runCli(argv, io) {
     env: io.env,
     configPaths: options.configPaths,
     includeDefaults: options.includeDefaults,
+    policyPath: options.policyPath,
+    includePolicy: options.includePolicy,
     toolVersion: VERSION
   });
 
@@ -106,6 +109,7 @@ function parseInitArgs(args, defaultCwd) {
     includeDefaults: true,
     workflowPath: "",
     baselinePath: "",
+    policyPath: "",
     failOn: "high",
     commentPr: true,
     uploadSarif: false,
@@ -119,6 +123,7 @@ function parseInitArgs(args, defaultCwd) {
   options.baselinePath = path.join(options.cwd, ".mcp-guard-baseline.json");
   let workflowPathProvided = false;
   let baselinePathProvided = false;
+  let policyPathProvided = false;
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -134,6 +139,10 @@ function parseInitArgs(args, defaultCwd) {
       options.useBaseline = true;
       baselinePathProvided = true;
       index += 1;
+    } else if (arg === "--policy") {
+      options.policyPath = resolveInputPath(readValue(args, index, arg), options.cwd);
+      policyPathProvided = true;
+      index += 1;
     } else if (arg === "--write-baseline" || arg === "--write-allowlist") {
       options.writeBaseline = true;
       options.useBaseline = true;
@@ -160,6 +169,9 @@ function parseInitArgs(args, defaultCwd) {
       if (!baselinePathProvided) {
         options.baselinePath = path.join(options.cwd, ".mcp-guard-baseline.json");
       }
+      if (!policyPathProvided && options.policyPath) {
+        options.policyPath = path.join(options.cwd, ".mcp-guard-policy.json");
+      }
       index += 1;
     } else if (arg === "--no-defaults") {
       options.includeDefaults = false;
@@ -185,6 +197,8 @@ function parseScanArgs(args, defaultCwd) {
     failOn: "none",
     baselinePath: "",
     writeBaselinePath: "",
+    policyPath: "",
+    includePolicy: true,
     baselineReason: "Accepted current MCP findings"
   };
 
@@ -217,9 +231,14 @@ function parseScanArgs(args, defaultCwd) {
     } else if (arg === "--baseline-reason") {
       options.baselineReason = readValue(args, index, arg);
       index += 1;
+    } else if (arg === "--policy") {
+      options.policyPath = resolveInputPath(readValue(args, index, arg), options.cwd);
+      index += 1;
     } else if (arg === "--cwd") {
       options.cwd = path.resolve(readValue(args, index, arg));
       index += 1;
+    } else if (arg === "--no-policy") {
+      options.includePolicy = false;
     } else if (arg === "--no-defaults") {
       options.includeDefaults = false;
     } else {
@@ -279,6 +298,7 @@ Init options:
   -c, --config <path>       MCP config path to reference in the workflow. Can be repeated for baseline generation.
       --fail-on <severity>  Workflow fail threshold. Default: high.
       --baseline <path>     Reference an existing baseline JSON file in the workflow.
+      --policy <path>       Reference an MCP guard policy file in the workflow.
       --write-baseline      Generate a baseline from current findings and reference it in the workflow.
       --baseline-reason <text>
                             Reason stored for newly written baseline entries.
@@ -301,7 +321,10 @@ Scan options:
                             Write current findings to a baseline JSON file.
       --baseline-reason <text>
                             Reason stored for newly written baseline entries.
+      --policy <path>       Enforce an explicit policy file.
+                            Default: auto-load .mcp-guard-policy.json when present.
       --cwd <path>          Working directory for project config discovery.
+      --no-policy           Do not auto-load .mcp-guard-policy.json.
       --no-defaults         Only scan paths passed with --config.
 
 Examples:
@@ -312,6 +335,7 @@ Examples:
   mcp-guard scan --format html --output mcp-guard-report.html
   mcp-guard scan --format sarif --output mcp-guard.sarif
   mcp-guard scan --config .mcp.json --fail-on high
+  mcp-guard scan --config .mcp.json --policy .mcp-guard-policy.json --fail-on high
   mcp-guard scan --config .mcp.json --write-baseline .mcp-guard-baseline.json
   mcp-guard scan --config .mcp.json --baseline .mcp-guard-baseline.json --fail-on high
 `;

package/src/init.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { writeBaselineFile } from "./baseline.js";
 import { discoverConfigFiles } from "./discovery.js";
 import { displayPath } from "./fingerprint.js";
+import { DEFAULT_POLICY_FILE } from "./policy.js";
 import { scan } from "./scan.js";
 
 export async function initProject({
@@ -12,6 +13,7 @@ export async function initProject({
   includeDefaults = true,
   workflowPath,
   baselinePath,
+  policyPath = "",
   failOn = "high",
   commentPr = true,
   uploadSarif = false,
@@ -30,6 +32,7 @@ export async function initProject({
     explicitConfigPaths: configPaths,
     discoveredConfigPaths
   });
+  const workflowPolicyPath = policyPath || await defaultPolicyPath(cwd);
   const files = [];
 
   if (writeBaseline) {
@@ -46,6 +49,7 @@ export async function initProject({
       env,
       configPaths: baselineConfigPaths,
       includeDefaults: false,
+      includePolicy: false,
       toolVersion
     });
     const baseline = await writeBaselineFileIfAllowed(baselinePath, result, {
@@ -65,6 +69,7 @@ export async function initProject({
     actionRef: `ChaoYue0307/mcp-guard-action@v${toolVersion}`,
     configPath: workflowConfigPath ? displayPath(workflowConfigPath, cwd) : "",
     baselinePath: useBaseline || writeBaseline ? displayPath(baselinePath, cwd) : "",
+    policyPath: workflowPolicyPath ? displayPath(workflowPolicyPath, cwd) : "",
     failOn,
     commentPr,
     uploadSarif
@@ -80,10 +85,11 @@ export async function initProject({
     dryRun,
     workflowPath,
     baselinePath,
+    policyPath: workflowPolicyPath,
     configPath: workflowConfigPath,
     discoveredConfigPaths,
     files,
-    nextSteps: buildNextSteps({ workflowPath, baselinePath, writeBaseline, uploadSarif })
+    nextSteps: buildNextSteps({ workflowPath, baselinePath, policyPath: workflowPolicyPath, writeBaseline, uploadSarif })
   };
 }
 
@@ -99,6 +105,9 @@ export function renderInitSummary(result, cwd) {
   } else {
     lines.push("Config: default discovery paths");
   }
+  if (result.policyPath) {
+    lines.push(`Policy: ${displayPath(result.policyPath, cwd)}`);
+  }
 
   for (const file of result.files) {
     const label = file.action === "skipped" ? "Skipped" : actionLabel(file.action);
@@ -115,7 +124,7 @@ export function renderInitSummary(result, cwd) {
   return `${lines.join("\n")}\n`;
 }
 
-export function renderGithubWorkflow({ actionRef, configPath, baselinePath, failOn, commentPr, uploadSarif }) {
+export function renderGithubWorkflow({ actionRef, configPath, baselinePath, policyPath, failOn, commentPr, uploadSarif }) {
   const permissions = ["  contents: read"];
   if (commentPr) {
     permissions.push("  pull-requests: write");
@@ -131,6 +140,9 @@ export function renderGithubWorkflow({ actionRef, configPath, baselinePath, fail
   if (baselinePath) {
     inputs.push(`          baseline: ${quoteYaml(baselinePath)}`);
   }
+  if (policyPath) {
+    inputs.push(`          policy: ${quoteYaml(policyPath)}`);
+  }
   inputs.push(`          fail-on: ${quoteYaml(failOn)}`);
   if (commentPr) {
     inputs.push('          comment-pr: "true"');
@@ -208,6 +220,11 @@ async function writeTextFileIfAllowed(filePath, content, { force, dryRun }) {
   };
 }
 
+async function defaultPolicyPath(cwd) {
+  const filePath = path.join(cwd, DEFAULT_POLICY_FILE);
+  return await fileExists(filePath) ? filePath : "";
+}
+
 async function fileExists(filePath) {
   try {
     await fs.access(filePath);
@@ -217,7 +234,7 @@ async function fileExists(filePath) {
   }
 }
 
-function buildNextSteps({ workflowPath, baselinePath, writeBaseline, uploadSarif }) {
+function buildNextSteps({ workflowPath, baselinePath, policyPath, writeBaseline, uploadSarif }) {
   const steps = [
     `Review ${path.basename(workflowPath)} before committing it.`,
     "Run mcp-guard scan locally and confirm the findings are expected.",
@@ -228,6 +245,10 @@ function buildNextSteps({ workflowPath, baselinePath, writeBaseline, uploadSarif
     steps.splice(1, 0, `Review ${path.basename(baselinePath)} because accepted findings will not fail CI.`);
   }
 
+  if (policyPath) {
+    steps.splice(1, 0, `Review ${path.basename(policyPath)} because it defines approved commands, packages, directories, and remote URLs.`);
+  }
+
   if (uploadSarif) {
     steps.push("Confirm GitHub code scanning is enabled for SARIF results.");
   }

package/src/policy.js

@@ -0,0 +1,109 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_POLICY_FILE = ".mcp-guard-policy.json";
+
+export async function loadPolicy({ cwd, home, policyPath = "", includePolicy = true }) {
+  if (!includePolicy) return null;
+
+  const explicit = Boolean(policyPath);
+  const resolvedPath = explicit ? resolvePolicyPath(policyPath, cwd) : path.join(cwd, DEFAULT_POLICY_FILE);
+
+  if (!explicit && !(await fileExists(resolvedPath))) {
+    return null;
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(await fs.readFile(resolvedPath, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid policy file ${resolvedPath}: ${message}`);
+  }
+
+  return normalizePolicy(raw, resolvedPath, { cwd, home });
+}
+
+export function policyForReport(policy) {
+  if (!policy) return null;
+  return {
+    path: policy.path,
+    version: policy.version,
+    allowedCommands: [...policy.allowedCommands],
+    allowedPackages: [...policy.allowedPackages],
+    allowedDirectories: [...policy.allowedDirectories],
+    allowedRemoteUrls: [...policy.allowedRemoteUrls]
+  };
+}
+
+function normalizePolicy(raw, policyPath, context) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Policy must be a JSON object.");
+  }
+
+  const allowedCommands = stringArray(raw.allowedCommands, "allowedCommands")
+    .map((command) => path.basename(command).toLowerCase());
+  const allowedPackages = stringArray(raw.allowedPackages, "allowedPackages")
+    .map(packageIdentity);
+  const allowedDirectories = stringArray(raw.allowedDirectories, "allowedDirectories");
+  const allowedRemoteUrls = stringArray(raw.allowedRemoteUrls, "allowedRemoteUrls")
+    .map(normalizePolicyUrl);
+
+  return {
+    path: policyPath,
+    version: raw.version || 1,
+    allowedCommands: new Set(allowedCommands),
+    allowedPackages: new Set(allowedPackages),
+    allowedDirectories,
+    allowedDirectoryPaths: allowedDirectories.map((directory) => normalizePolicyPath(directory, context)),
+    allowedRemoteUrls,
+    raw: raw
+  };
+}
+
+function stringArray(value, fieldName) {
+  if (value == null) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(`${fieldName} must be an array of non-empty strings.`);
+  }
+  return value.map((item) => item.trim());
+}
+
+function packageIdentity(packageName) {
+  if (packageName.startsWith("@")) {
+    const secondAt = packageName.indexOf("@", 1);
+    return secondAt > 1 ? packageName.slice(0, secondAt) : packageName;
+  }
+  const at = packageName.lastIndexOf("@");
+  return at > 0 ? packageName.slice(0, at) : packageName;
+}
+
+function normalizePolicyPath(value, context) {
+  if (value === "~") return path.normalize(context.home);
+  if (value.startsWith("~/")) return path.join(context.home, value.slice(2));
+  if (path.isAbsolute(value)) return path.normalize(value);
+  return path.resolve(context.cwd, value);
+}
+
+function normalizePolicyUrl(value) {
+  try {
+    const parsed = new URL(value);
+    const pathname = parsed.pathname === "/" ? "" : parsed.pathname.replace(/\/+$/, "");
+    return `${parsed.origin}${pathname}`;
+  } catch {
+    throw new Error(`allowedRemoteUrls contains an invalid URL: ${value}`);
+  }
+}
+
+function resolvePolicyPath(value, cwd) {
+  return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/report.js

@@ -12,6 +12,9 @@ export function generateTextReport(result) {
     lines.push(`Accepted by baseline: ${result.summary.acceptedFindingCount}`);
     lines.push(`Total observed findings: ${result.summary.totalFindingCount}`);
   }
+  if (hasPolicy(result)) {
+    lines.push(`Policy: ${displayPath(result.policy.path, result.metadata.cwd)}`);
+  }
   lines.push(`Risk score: ${result.summary.riskScore}`);
   lines.push(`Critical: ${result.summary.counts.critical}  High: ${result.summary.counts.high}  Medium: ${result.summary.counts.medium}  Low: ${result.summary.counts.low}`);
   lines.push("");
@@ -69,6 +72,9 @@ export function generateMarkdownReport(result) {
     lines.push(`- Total observed findings: ${result.summary.totalFindingCount}`);
     lines.push(`- Baseline: \`${result.baseline.path || "enabled"}\``);
   }
+  if (hasPolicy(result)) {
+    lines.push(`- Policy: \`${displayPath(result.policy.path, result.metadata.cwd)}\``);
+  }
   lines.push(`- Risk score: ${result.summary.riskScore}`);
   lines.push(`- Critical: ${result.summary.counts.critical}`);
   lines.push(`- High: ${result.summary.counts.high}`);
@@ -87,6 +93,17 @@ export function generateMarkdownReport(result) {
   }
   lines.push("");
 
+  if (hasPolicy(result)) {
+    lines.push("## Policy");
+    lines.push("");
+    lines.push(`- Path: \`${displayPath(result.policy.path, result.metadata.cwd)}\``);
+    lines.push(`- Allowed commands: ${inlineList(result.policy.allowedCommands)}`);
+    lines.push(`- Allowed packages: ${inlineList(result.policy.allowedPackages)}`);
+    lines.push(`- Allowed directories: ${inlineList(result.policy.allowedDirectories)}`);
+    lines.push(`- Allowed remote URLs: ${inlineList(result.policy.allowedRemoteUrls)}`);
+    lines.push("");
+  }
+
   lines.push("## MCP Server Inventory");
   lines.push("");
   if (result.servers.length === 0) {
@@ -510,6 +527,11 @@ export function generateHtmlReport(result) {
       ${renderScannedFiles(safeResult)}
     </section>
 
+${hasPolicy(safeResult) ? `    <section>
+      <h2>Policy</h2>
+      ${renderPolicy(safeResult)}
+    </section>` : ""}
+
     <section>
       <h2>MCP Server Inventory</h2>
       ${renderServerTable(servers, safeResult.metadata.cwd)}
@@ -549,8 +571,13 @@ function sanitizeResult(result) {
     metadata: {
       ...result.metadata,
       cwd: ".",
-      home: "~"
+      home: "~",
+      policyPath: result.metadata.policyPath ? displayPath(result.metadata.policyPath, cwd) : ""
     },
+    policy: result.policy ? {
+      ...result.policy,
+      path: displayPath(result.policy.path, cwd)
+    } : null,
     scannedFiles: result.scannedFiles.map((file) => displayPath(file, cwd)),
     servers: result.servers.map((server) => ({
       name: server.name,
@@ -673,6 +700,19 @@ function renderScannedFiles(result) {
   return `<div class="table-wrap"><table><thead><tr><th>Path</th></tr></thead><tbody>${items}</tbody></table></div>`;
 }
 
+function renderPolicy(result) {
+  const policy = result.policy;
+  const rows = [
+    ["Path", policy.path],
+    ["Allowed commands", policy.allowedCommands.join(", ") || "-"],
+    ["Allowed packages", policy.allowedPackages.join(", ") || "-"],
+    ["Allowed directories", policy.allowedDirectories.join(", ") || "-"],
+    ["Allowed remote URLs", policy.allowedRemoteUrls.join(", ") || "-"]
+  ].map(([key, value]) => `<tr><th>${escapeHtml(key)}</th><td>${codeOrDash(value)}</td></tr>`).join("");
+
+  return `<div class="table-wrap"><table><tbody>${rows}</tbody></table></div>`;
+}
+
 function renderServerTable(servers, cwd) {
   if (servers.length === 0) {
     return `<p class="empty">No MCP servers were found.</p>`;
@@ -774,10 +814,19 @@ function hasBaseline(result) {
   return Boolean(result.baseline?.enabled);
 }
 
+function hasPolicy(result) {
+  return Boolean(result.policy);
+}
+
 function hasAcceptedFindings(result) {
   return (result.acceptedFindings || []).length > 0;
 }
 
+function inlineList(items) {
+  if (!items || items.length === 0) return "not restricted";
+  return items.map((item) => `\`${item}\``).join(", ");
+}
+
 function escapeHtml(value) {
   return String(value ?? "")
     .replaceAll("&", "&amp;")

package/src/rules.js

@@ -31,6 +31,11 @@ export function evaluateServer(server, context) {
   findings.push(...ruleDangerousCommandPattern(server));
   findings.push(...ruleRemoteUrl(server));
   findings.push(...ruleHeaders(server));
+  findings.push(...rulePolicyAllowedCommand(server, context));
+  findings.push(...rulePolicyAllowedPackage(server, context));
+  findings.push(...rulePolicyAllowedWorkingDirectory(server, context));
+  findings.push(...rulePolicyAllowedFilesystemArgs(server, context));
+  findings.push(...rulePolicyAllowedRemoteUrl(server, context));
 
   return findings;
 }
@@ -220,6 +225,103 @@ function ruleHeaders(server) {
   return findings;
 }
 
+function rulePolicyAllowedCommand(server, context) {
+  const policy = context.policy;
+  if (!policy || policy.allowedCommands.size === 0 || !server.command) return [];
+
+  const command = commandBase(server.command);
+  if (policy.allowedCommands.has(command)) return [];
+
+  return [finding({
+    id: "MCP070",
+    severity: "high",
+    title: "MCP server command is not allowed by policy",
+    server,
+    evidence: `command=${server.command} allowed=${listSet(policy.allowedCommands)}`,
+    recommendation: "Use an approved command, or add this command to allowedCommands only after review."
+  })];
+}
+
+function rulePolicyAllowedPackage(server, context) {
+  const policy = context.policy;
+  if (!policy || policy.allowedPackages.size === 0) return [];
+
+  const command = commandBase(server.command);
+  const usesRemoteRunner = REMOTE_EXEC_COMMANDS.has(command) || (PACKAGE_MANAGER_COMMANDS.has(command) && server.args[0] === "dlx");
+  if (!usesRemoteRunner) return [];
+
+  const packageArg = firstPackageArg(server.args);
+  if (!packageArg) return [];
+
+  const packageName = packageIdentity(packageArg);
+  if (policy.allowedPackages.has(packageName)) return [];
+
+  return [finding({
+    id: "MCP071",
+    severity: "high",
+    title: "Remote MCP package is not allowed by policy",
+    server,
+    evidence: `package=${packageName} allowed=${listSet(policy.allowedPackages)}`,
+    recommendation: "Use an approved MCP package, or add this package to allowedPackages only after review."
+  })];
+}
+
+function rulePolicyAllowedWorkingDirectory(server, context) {
+  const policy = context.policy;
+  if (!policy || policy.allowedDirectoryPaths.length === 0 || !server.cwd) return [];
+
+  const normalized = normalizePath(server.cwd, context);
+  if (isAllowedPath(normalized, policy.allowedDirectoryPaths)) return [];
+
+  return [finding({
+    id: "MCP072",
+    severity: "high",
+    title: "MCP server working directory is outside policy",
+    server,
+    evidence: `cwd=${server.cwd} allowed=${policy.allowedDirectories.join(", ")}`,
+    recommendation: "Move this server into an approved workspace directory, or add the directory to allowedDirectories after review."
+  })];
+}
+
+function rulePolicyAllowedFilesystemArgs(server, context) {
+  const policy = context.policy;
+  if (!policy || policy.allowedDirectoryPaths.length === 0) return [];
+
+  const findings = [];
+  for (const arg of server.args) {
+    const value = filesystemPathFromArg(arg);
+    if (!value) continue;
+
+    const normalized = normalizePath(value, context);
+    if (isAllowedPath(normalized, policy.allowedDirectoryPaths)) continue;
+
+    findings.push(finding({
+      id: "MCP073",
+      severity: "high",
+      title: "MCP server filesystem argument is outside policy",
+      server,
+      evidence: `arg=${arg} allowed=${policy.allowedDirectories.join(", ")}`,
+      recommendation: "Limit filesystem arguments to approved directories, or update allowedDirectories only after review."
+    }));
+  }
+  return findings;
+}
+
+function rulePolicyAllowedRemoteUrl(server, context) {
+  const policy = context.policy;
+  if (!policy || policy.allowedRemoteUrls.length === 0 || !server.url) return [];
+  if (isAllowedRemoteUrl(server.url, policy.allowedRemoteUrls)) return [];
+
+  return [finding({
+    id: "MCP074",
+    severity: "high",
+    title: "Remote MCP URL is not allowed by policy",
+    server,
+    evidence: `url=${server.url} allowed=${policy.allowedRemoteUrls.join(", ")}`,
+    recommendation: "Use an approved remote MCP endpoint, or add this URL to allowedRemoteUrls only after review."
+  })];
+}
+
 function finding({ id, severity, title, server, evidence, recommendation }) {
   return {
     id,
@@ -252,6 +354,15 @@ function isPinnedPackage(packageName) {
   return at > 0 && at < packageName.length - 1;
 }
 
+function packageIdentity(packageName) {
+  if (packageName.startsWith("@")) {
+    const secondAt = packageName.indexOf("@", 1);
+    return secondAt > 1 ? packageName.slice(0, secondAt) : packageName;
+  }
+  const at = packageName.lastIndexOf("@");
+  return at > 0 ? packageName.slice(0, at) : packageName;
+}
+
 function valueFromArg(arg) {
   if (!arg) return "";
   const equalIndex = arg.indexOf("=");
@@ -260,6 +371,14 @@ function valueFromArg(arg) {
   return "";
 }
 
+function filesystemPathFromArg(arg) {
+  const value = valueFromArg(arg);
+  if (!value) return "";
+  if (value === "~" || value.startsWith("~/")) return value;
+  if (value.startsWith("/") || value.startsWith("./") || value.startsWith("../")) return value;
+  return "";
+}
+
 function normalizePath(value, context) {
   if (!value) return "";
   if (value === "~") return context.home;
@@ -268,3 +387,26 @@ function normalizePath(value, context) {
   return path.resolve(context.cwd, value);
 }
 
+function isAllowedPath(filePath, allowedPaths) {
+  return allowedPaths.some((allowedPath) => {
+    const normalizedAllowed = path.normalize(allowedPath);
+    return filePath === normalizedAllowed || filePath.startsWith(`${normalizedAllowed}${path.sep}`);
+  });
+}
+
+function isAllowedRemoteUrl(value, allowedUrls) {
+  let target;
+  try {
+    target = new URL(value);
+  } catch {
+    return false;
+  }
+
+  const targetPath = target.pathname === "/" ? "" : target.pathname.replace(/\/+$/, "");
+  const targetValue = `${target.origin}${targetPath}`;
+  return allowedUrls.some((allowed) => targetValue === allowed || targetValue.startsWith(`${allowed}/`));
+}
+
+function listSet(items) {
+  return [...items].join(", ");
+}

package/src/scan.js

@@ -3,12 +3,14 @@ import path from "node:path";
 import { extractServers, loadConfigFile } from "./config.js";
 import { discoverConfigFiles } from "./discovery.js";
 import { findingFingerprint } from "./fingerprint.js";
+import { loadPolicy, policyForReport } from "./policy.js";
 import { evaluateServer } from "./rules.js";
 import { sortFindings } from "./severity.js";
 import { summarize } from "./baseline.js";
 
-export async function scan({ cwd, env, configPaths = [], includeDefaults = true, toolVersion = "0.0.0" }) {
+export async function scan({ cwd, env, configPaths = [], includeDefaults = true, policyPath = "", includePolicy = true, toolVersion = "0.0.0" }) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
+  const policy = await loadPolicy({ cwd, home, policyPath, includePolicy });
   const explicitPaths = configPaths.map((item) => path.resolve(item));
   const shouldDiscover = explicitPaths.length === 0 && includeDefaults;
   const discoveredPaths = shouldDiscover ? await discoverConfigFiles({ cwd, env }) : [];
@@ -63,7 +65,7 @@ export async function scan({ cwd, env, configPaths = [], includeDefaults = true,
   }
 
   for (const server of servers) {
-    findings.push(...evaluateServer(server, { cwd, home }));
+    findings.push(...evaluateServer(server, { cwd, home, policy }));
   }
 
   const sortedFindings = sortFindings(findings).map((finding) => ({
@@ -76,8 +78,11 @@ export async function scan({ cwd, env, configPaths = [], includeDefaults = true,
       generatedAt: new Date().toISOString(),
       cwd,
       home,
+      policyPath: policy?.path || "",
+      policyEnabled: Boolean(policy),
       toolVersion
     },
+    policy: policyForReport(policy),
     scannedFiles,
     servers,
     findings: sortedFindings,