agent-mcp-guard 0.4.3 → 0.4.5

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.5"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -65,12 +65,24 @@ Generate SARIF for GitHub code scanning:
 mcp-guard scan --format sarif --output mcp-guard.sarif
 ```
 
+Generate a review-ready audit pack:
+
+```bash
+mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --output-dir mcp-guard-audit
+```
+
 Use in CI:
 
 ```bash
 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 +93,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.5
   with:
     config: .mcp.json
+    # policy: .mcp-guard-policy.json
     baseline: .mcp-guard-baseline.json
     fail-on: high
     comment-pr: "true"
@@ -101,6 +114,8 @@ Use the transparent example to evaluate what the scanner actually does:
 - generated HTML report: [site/e2e/report.html](site/e2e/report.html)
 - generated JSON report: [site/e2e/report.json](site/e2e/report.json)
 - generated SARIF report: [site/e2e/report.sarif](site/e2e/report.sarif)
+- 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)
 
 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.
 
@@ -117,6 +132,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 +145,15 @@ 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 paid setup or internal review handoff, `mcp-guard audit` writes a complete evidence package with:
+
+- executive summary;
+- remediation plan grouped by MCP server;
+- Markdown, HTML, JSON, and SARIF reports;
+- machine-readable audit manifest.
+
+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 +218,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.
@@ -202,7 +228,9 @@ Contact: [hechaoyue0307@gmail.com](mailto:hechaoyue0307@gmail.com)
 ## Documentation
 
 - [Rule reference](docs/rules.md)
+- [Audit packs](docs/audit.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
@@ -41,6 +45,9 @@ inputs:
     default: mcp-guard-report
 
 outputs:
+  executive-summary:
+    description: Path to the generated executive summary.
+    value: ${{ steps.reports.outputs.executive-summary }}
   markdown-report:
     description: Path to the generated Markdown report.
     value: ${{ steps.reports.outputs.markdown-report }}
@@ -53,6 +60,12 @@ outputs:
   sarif-report:
     description: Path to the generated SARIF report.
     value: ${{ steps.reports.outputs.sarif-report }}
+  remediation-report:
+    description: Path to the generated remediation plan.
+    value: ${{ steps.reports.outputs.remediation-report }}
+  audit-manifest:
+    description: Path to the generated audit pack manifest.
+    value: ${{ steps.reports.outputs.audit-manifest }}
   exit-code:
     description: mcp-guard threshold exit code.
     value: ${{ steps.reports.outputs.exit-code }}
@@ -67,6 +80,7 @@ runs:
       uses: actions/setup-node@v6
       with:
         node-version: "24"
+        package-manager-cache: false
 
     - name: Generate reports
       id: reports
@@ -74,6 +88,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,34 +104,45 @@ 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"
         json_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-report.json"
         sarif_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard.sarif"
+        executive_summary="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-executive-summary.md"
+        remediation_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-remediation.md"
+        audit_manifest="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-audit-manifest.json"
         comment_report="${MCP_GUARD_OUTPUT_DIR}/mcp-guard-pr-comment.md"
 
-        node "${guard_bin}" scan "${scan_args[@]}" --format markdown --output "${markdown_report}" --fail-on none
-        node "${guard_bin}" scan "${scan_args[@]}" --format html --output "${html_report}" --fail-on none
-        node "${guard_bin}" scan "${scan_args[@]}" --format json --output "${json_report}" --fail-on none
-        node "${guard_bin}" scan "${scan_args[@]}" --format sarif --output "${sarif_report}" --fail-on none
+        set +e
+        node "${guard_bin}" audit "${scan_args[@]}" --output-dir "${MCP_GUARD_OUTPUT_DIR}" --fail-on "${MCP_GUARD_FAIL_ON}"
+        status="$?"
+        set -e
+        if [ "${status}" != "0" ] && [ "${status}" != "2" ]; then
+          exit "${status}"
+        fi
+
         node "${GITHUB_ACTION_PATH}/scripts/action-comment.js" \
           "${json_report}" \
           "${markdown_report}" \
           "${html_report}" \
           "${sarif_report}" \
-          "${MCP_GUARD_FAIL_ON}" > "${comment_report}"
-
-        set +e
-        node "${guard_bin}" scan "${scan_args[@]}" --fail-on "${MCP_GUARD_FAIL_ON}"
-        status="$?"
-        set -e
+          "${MCP_GUARD_FAIL_ON}" \
+          "${executive_summary}" \
+          "${remediation_report}" \
+          "${audit_manifest}" > "${comment_report}"
 
         {
+          echo "executive-summary=${executive_summary}"
           echo "markdown-report=${markdown_report}"
           echo "html-report=${html_report}"
           echo "json-report=${json_report}"
           echo "sarif-report=${sarif_report}"
+          echo "remediation-report=${remediation_report}"
+          echo "audit-manifest=${audit_manifest}"
           echo "comment-report=${comment_report}"
           echo "exit-code=${status}"
         } >> "${GITHUB_OUTPUT}"
@@ -132,7 +158,10 @@ runs:
           "${{ steps.reports.outputs.markdown-report }}" \
           "${{ steps.reports.outputs.html-report }}" \
           "${{ steps.reports.outputs.sarif-report }}" \
-          "${MCP_GUARD_FAIL_ON}" >> "${GITHUB_STEP_SUMMARY}"
+          "${MCP_GUARD_FAIL_ON}" \
+          "${{ steps.reports.outputs.executive-summary }}" \
+          "${{ steps.reports.outputs.remediation-report }}" \
+          "${{ steps.reports.outputs.audit-manifest }}" >> "${GITHUB_STEP_SUMMARY}"
 
     - name: Comment on pull request
       if: ${{ always() && inputs.comment-pr == 'true' && github.event_name == 'pull_request' && steps.reports.outputs.comment-report != '' }}

package/docs/audit.md

@@ -0,0 +1,51 @@
+# Audit Packs
+
+`mcp-guard audit` generates a review-ready evidence package for setup pilots, internal security reviews, and customer handoff notes.
+
+It runs the same scanner as `mcp-guard scan`, then writes a directory with human-readable reports, machine-readable outputs, and a manifest.
+
+## Usage
+
+```bash
+mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --output-dir mcp-guard-audit
+```
+
+Use a baseline when the team has accepted known findings:
+
+```bash
+mcp-guard audit \
+  --config .mcp.json \
+  --baseline .mcp-guard-baseline.json \
+  --policy .mcp-guard-policy.json \
+  --output-dir mcp-guard-audit
+```
+
+Use `--fail-on` in CI when the audit should write artifacts and then fail on active risk:
+
+```bash
+mcp-guard audit --config .mcp.json --fail-on high
+```
+
+## Generated Files
+
+| File | Purpose |
+| --- | --- |
+| `mcp-guard-executive-summary.md` | Short decision summary for founders, security leads, and engineering managers. |
+| `mcp-guard-remediation.md` | Server-by-server remediation plan with evidence and fixes. |
+| `mcp-guard-report.md` | Full Markdown scan report. |
+| `mcp-guard-report.html` | Readable HTML report for review artifacts. |
+| `mcp-guard-report.json` | Redacted machine-readable report for automation. |
+| `mcp-guard.sarif` | SARIF 2.1.0 report for GitHub code scanning. |
+| `mcp-guard-audit-manifest.json` | Manifest listing status, summary, policy/baseline context, and file paths. |
+
+## Review Flow
+
+1. Run `mcp-guard audit` locally or through the GitHub Action.
+2. Open `mcp-guard-executive-summary.md` to decide whether the MCP setup is acceptable.
+3. Work through `mcp-guard-remediation.md` with the engineering team.
+4. Use `mcp-guard-report.html` for readable evidence and `mcp-guard-report.json` or `mcp-guard.sarif` for automation.
+5. Commit a reviewed policy and baseline only after the team has decided what risk is intentionally accepted.
+
+## Privacy
+
+The audit pack is generated locally. Secret-like environment variables and headers are redacted in reports before they are written.

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.5
   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.5",
   "findings": [
     {
       "fingerprint": "mcpg_a009b2c2",

package/docs/business-playbook.md

@@ -17,6 +17,8 @@ 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, reports, and manifest;
+- 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 +41,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, can enforce a committed policy for approved MCP commands, packages, directories, and URLs, and can export a review-ready audit pack.
 
 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/examples/e2e-example.md

@@ -1,6 +1,6 @@
 # End-to-End Example
 
-This example is designed for transparent product evaluation. It uses a synthetic MCP config committed to the repository, then runs the real `mcp-guard` CLI to generate Markdown, HTML, JSON, and SARIF outputs.
+This example is designed for transparent product evaluation. It uses a synthetic MCP config committed to the repository, then runs the real `mcp-guard` CLI to generate Markdown, HTML, JSON, SARIF, and audit pack outputs.
 
 The input is intentionally unsafe so users can see whether the scanner catches concrete risks.
 
@@ -23,6 +23,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 html --output site/e2e/report.html
 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
 ```
 
 ## Expected Result
@@ -51,10 +52,13 @@ Important findings include:
 - [HTML report](../../site/e2e/report.html)
 - [JSON report](../../site/e2e/report.json)
 - [SARIF report](../../site/e2e/report.sarif)
+- [Audit executive summary](../../site/e2e/audit/mcp-guard-executive-summary.md)
+- [Audit remediation plan](../../site/e2e/audit/mcp-guard-remediation.md)
+- [Audit manifest](../../site/e2e/audit/mcp-guard-audit-manifest.json)
 
 ## What This Proves
 
 - The scanner does not need the config to leave the machine.
 - 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, and GitHub code scanning SARIF.
+- The same scan can feed a human-readable HTML report, automation JSON, GitHub code scanning SARIF, and a review-ready audit handoff package.

package/docs/github-action.md

@@ -2,9 +2,11 @@
 
 Use the `mcp-guard` action to scan MCP and AI agent tool configuration in pull requests and CI.
 
-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.
+The action runs the CLI from the pinned GitHub Action tag, generates an audit pack with Markdown, HTML, JSON, SARIF, remediation, and manifest files, 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.5
         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.5
         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.5
   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.5
   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.5
+  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. |
@@ -117,9 +134,12 @@ Reports will show active findings separately from findings accepted by the basel
 
 | Output | Description |
 | --- | --- |
+| `executive-summary` | Path to the generated executive summary. |
 | `markdown-report` | Path to the generated Markdown report. |
 | `html-report` | Path to the generated HTML report. |
 | `json-report` | Path to the generated JSON report. |
 | `sarif-report` | Path to the generated SARIF report. |
+| `remediation-report` | Path to the generated remediation plan. |
+| `audit-manifest` | Path to the generated audit pack manifest. |
 | `comment-report` | Path to the generated pull request comment body. |
 | `exit-code` | `0` when below threshold, `2` when findings met the threshold. |

package/docs/launch-checklist.md

@@ -28,10 +28,16 @@ mcp-guard scan
 mcp-guard scan --config .mcp.json --fail-on high
 ```
 
+## Audit Pack
+
+```bash
+mcp-guard audit --config .mcp.json --policy .mcp-guard-policy.json --output-dir mcp-guard-audit
+```
+
 ## GitHub Action Setup
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.3
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   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.5
         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.5
         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. |
@@ -66,21 +67,26 @@ jobs:
 
 | Output | Description |
 | --- | --- |
+| `executive-summary` | Path to the generated executive summary. |
 | `markdown-report` | Path to the generated Markdown report. |
 | `html-report` | Path to the generated HTML report. |
 | `json-report` | Path to the generated JSON report. |
 | `sarif-report` | Path to the generated SARIF report. |
+| `remediation-report` | Path to the generated remediation plan. |
+| `audit-manifest` | Path to the generated audit pack manifest. |
 | `comment-report` | Path to the generated pull request comment body. |
 | `exit-code` | `0` when below threshold, `2` when findings met the threshold. |
 
 ## Reports
 
-The action generates:
+The action generates an audit pack:
 
 - Markdown for pull request review.
 - HTML for review-ready artifacts.
 - JSON for automation.
 - SARIF 2.1.0 for GitHub code scanning.
+- Remediation Markdown for server-by-server handoff.
+- Audit manifest JSON for downstream automation.
 
 Secret-like values are redacted before reports are written.
 
@@ -95,13 +101,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.5
   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.5
+  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,17 +82,17 @@ Code quality
 Current release title:
 
 ```text
-v0.4.3
+v0.4.5
 ```
 
 Release notes:
 
 ```text
-Trusted Publishing readiness release.
+Audit pack release.
 
-- Adds a GitHub Actions workflow for npm Trusted Publishing readiness.
-- Keeps `mcp-guard init` for generating a GitHub Action workflow and baseline.
-- Keeps Node.js 24, PR comments, artifacts, and SARIF upload support.
+- Adds `mcp-guard audit` for executive summary, remediation plan, Markdown, HTML, JSON, SARIF, and manifest outputs.
+- The GitHub Action now uploads audit pack artifacts, including remediation and manifest files.
+- Keeps policy enforcement, baseline support, PR comments, artifacts, and SARIF upload support.
 ```
 
 ## Manual Publishing Steps
@@ -105,7 +105,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.5
 ```
 
 Remaining Marketplace web step:

package/docs/operator-runbook.md

@@ -11,6 +11,7 @@ npm test
 npm run release:check
 npm --cache ./.npm-cache pack --dry-run
 node ./bin/mcp-guard.js scan --config examples/unsafe-claude_desktop_config.json
+node ./bin/mcp-guard.js audit --config examples/unsafe-claude_desktop_config.json --policy examples/mcp-guard-policy.json --output-dir .release-check/audit-pack
 ```
 
 If your global npm cache has permission errors, either keep using the local cache flag above or fix ownership:

package/docs/paid-audit.md

@@ -13,6 +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, reports, and manifest.
 - 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/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,16 @@
 - 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.
+- `mcp-guard audit` for review-ready executive summaries, remediation plans, reports, and manifests.
 - 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. Safer default remediation snippets for common MCP servers.
+4. Package metadata checks for remote MCP server packages.
 
 ## 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.
-