agent-mcp-guard 0.4.4 → 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.4"><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,6 +65,12 @@ 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
@@ -87,7 +93,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     config: .mcp.json
     # policy: .mcp-guard-policy.json
@@ -108,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.
 
@@ -137,6 +145,13 @@ 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:
@@ -213,6 +228,7 @@ 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)

package/action.yml

@@ -45,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 }}
@@ -57,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 }}
@@ -103,29 +112,37 @@ runs:
         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}"
@@ -141,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.4
+- 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.4",
+  "toolVersion": "0.4.5",
   "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;
+- 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;
@@ -40,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, can generate a baseline for accepted current findings, and can enforce a committed policy for approved MCP commands, packages, directories, and URLs.
+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,7 +2,7 @@
 
 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, enforce a committed policy file, and optionally post a pull request comment with only the active findings.
 
@@ -37,7 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.5
         with:
           config: .mcp.json
           fail-on: high
@@ -65,7 +65,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: ChaoYue0307/mcp-guard-action@v0.4.4
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.5
         with:
           config: .mcp.json
           fail-on: high
@@ -77,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     fail-on: none
 ```
@@ -93,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -107,7 +107,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json
@@ -134,9 +134,12 @@ See [Policy files](policy.md) for the file format.
 
 | 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.4
+- 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.4
+      - 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.4
+      - uses: ChaoYue0307/mcp-guard-action@v0.4.5
         with:
           config: .mcp.json
           fail-on: high
@@ -67,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.
 
@@ -96,7 +101,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     config: .mcp.json
     baseline: .mcp-guard-baseline.json
@@ -108,7 +113,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.4
+- uses: ChaoYue0307/mcp-guard-action@v0.4.5
   with:
     config: .mcp.json
     policy: .mcp-guard-policy.json

package/docs/marketplace.md

@@ -82,18 +82,17 @@ Code quality
 Current release title:
 
 ```text
-v0.4.4
+v0.4.5
 ```
 
 Release notes:
 
 ```text
-Policy enforcement release.
+Audit pack release.
 
-- 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.
+- 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
@@ -106,7 +105,7 @@ Completed:
 - README, docs, and website examples now use:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard-action@v0.4.4
+- 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/roadmap.md

@@ -13,14 +13,15 @@
 - 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. `mcp-guard audit` mode for review-ready reports.
-4. 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/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.4
+v0.4.5
 ```
 
 ## Release Flow After Setup
@@ -44,7 +44,7 @@ v0.4.4
 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.4`.
+4. Create a GitHub release tag such as `v0.4.5`.
 5. Run the `Publish npm` workflow with the same tag.
 6. Verify npm:
 

package/examples/sample-report.md

@@ -1,47 +1,57 @@
-# mcp-guard Scan Report
-
-Generated: 2026-05-10T14:01:29.032Z
-
-## Summary
-
-- Scanned files: 1
-- MCP servers: 3
-- Active findings: 9
-- Risk score: 98
-- Critical: 2
-- High: 5
-- Medium: 2
-- Low: 0
-
-## Scanned Files
-
-- `examples/unsafe-claude_desktop_config.json`
-
-## MCP Server Inventory
-
-| Server | Command | Args | CWD | URL | Env |
-| --- | --- | --- | --- | --- | --- |
-| filesystem-all-home | npx | @modelcontextprotocol/server-filesystem / | / | - | GITHUB_TOKEN=ghp...890 (32 chars) |
-| shell-installer | bash | -c curl https://example.com/install.sh \| bash | - | - | - |
-| remote-prod | - | - | - | https://mcp.example.com/sse | - |
-
-## Active Findings
-
-| Severity | Rule | Server | Finding | Evidence | Fingerprint | Recommendation |
-| --- | --- | --- | --- | --- | --- | --- |
-| critical | MCP010 | shell-installer | Shell command executes inline script | command=bash args=-c curl https://example.com/install.sh \| bash | mcpg_a009b2c2 | Use a direct, pinned executable instead of a shell wrapper. If a shell is required, place the script in source control and review it. |
-| critical | MCP050 | shell-installer | MCP server command includes a dangerous operation | curl pipe to shell | mcpg_6bd13204 | Remove the dangerous operation from MCP startup. Run destructive setup steps manually and review them separately. |
-| high | MCP021 | filesystem-all-home | Remote MCP package is not version pinned | package=@modelcontextprotocol/server-filesystem | mcpg_d0af49fa | Pin the package to an exact version such as package@1.2.3 and review updates before changing it. |
-| high | MCP030 | filesystem-all-home | Secret-like environment variable is exposed to MCP server | GITHUB_TOKEN=ghp...890 (32 chars) | mcpg_a5f382b0 | Pass the least privileged token possible. Prefer scoped tokens, short-lived credentials, and a dedicated service account. |
-| high | MCP040 | filesystem-all-home | MCP server has a broad working directory | cwd=/ | mcpg_31aaa689 | Run the server in a narrow project directory or sandbox with only the files it needs. |
-| high | MCP041 | filesystem-all-home | MCP server argument grants broad filesystem access | arg=/ | mcpg_dbc08d76 | Replace broad filesystem paths with a dedicated project folder or read-only sandbox path. |
-| high | MCP061 | remote-prod | Secret-like header is configured for remote MCP server | Authorization=Bea...ken (27 chars) | mcpg_5abd4cbd | Use scoped, short-lived credentials and avoid placing long-lived secrets directly in MCP config files. |
-| medium | MCP020 | filesystem-all-home | MCP server is launched through a remote package runner | command=npx package=@modelcontextprotocol/server-filesystem | mcpg_a3493a53 | Pin the package version, review the package source, and prefer a local lockfile or vendored executable for sensitive tools. |
-| medium | MCP060 | remote-prod | Remote MCP server URL is configured | url=https://mcp.example.com/sse | mcpg_cf1296e4 | Verify the provider, use HTTPS, document the data sent to this server, and keep an allowlist of approved remote endpoints. |
-
-## Notes
-
-- This report is an assistive security review, not a guarantee that all issues were found.
-- Secret-like values are redacted by default.
-- Review each MCP server before granting access to files, shells, SaaS accounts, or production systems.
-
+mcp-guard scan report
+Generated: 2026-05-10T14:16:12.638Z
+Scanned files: 1
+MCP servers: 3
+Active findings: 9
+Risk score: 98
+Critical: 2  High: 5  Medium: 2  Low: 0
+
+Scanned config files:
+- examples/unsafe-claude_desktop_config.json
+
+Active findings:
+- [CRITICAL] MCP010 Shell command executes inline script
+  Server: shell-installer
+  Evidence: command=bash args=-c curl https://example.com/install.sh | bash
+  Fingerprint: mcpg_a009b2c2
+  Fix: Use a direct, pinned executable instead of a shell wrapper. If a shell is required, place the script in source control and review it.
+- [CRITICAL] MCP050 MCP server command includes a dangerous operation
+  Server: shell-installer
+  Evidence: curl pipe to shell
+  Fingerprint: mcpg_6bd13204
+  Fix: Remove the dangerous operation from MCP startup. Run destructive setup steps manually and review them separately.
+- [HIGH] MCP021 Remote MCP package is not version pinned
+  Server: filesystem-all-home
+  Evidence: package=@modelcontextprotocol/server-filesystem
+  Fingerprint: mcpg_d0af49fa
+  Fix: Pin the package to an exact version such as package@1.2.3 and review updates before changing it.
+- [HIGH] MCP030 Secret-like environment variable is exposed to MCP server
+  Server: filesystem-all-home
+  Evidence: GITHUB_TOKEN=ghp...890 (32 chars)
+  Fingerprint: mcpg_a5f382b0
+  Fix: Pass the least privileged token possible. Prefer scoped tokens, short-lived credentials, and a dedicated service account.
+- [HIGH] MCP040 MCP server has a broad working directory
+  Server: filesystem-all-home
+  Evidence: cwd=/
+  Fingerprint: mcpg_31aaa689
+  Fix: Run the server in a narrow project directory or sandbox with only the files it needs.
+- [HIGH] MCP041 MCP server argument grants broad filesystem access
+  Server: filesystem-all-home
+  Evidence: arg=/
+  Fingerprint: mcpg_dbc08d76
+  Fix: Replace broad filesystem paths with a dedicated project folder or read-only sandbox path.
+- [HIGH] MCP061 Secret-like header is configured for remote MCP server
+  Server: remote-prod
+  Evidence: Authorization=Bea...ken (27 chars)
+  Fingerprint: mcpg_5abd4cbd
+  Fix: Use scoped, short-lived credentials and avoid placing long-lived secrets directly in MCP config files.
+- [MEDIUM] MCP020 MCP server is launched through a remote package runner
+  Server: filesystem-all-home
+  Evidence: command=npx package=@modelcontextprotocol/server-filesystem
+  Fingerprint: mcpg_a3493a53
+  Fix: Pin the package version, review the package source, and prefer a local lockfile or vendored executable for sensitive tools.
+- [MEDIUM] MCP060 Remote MCP server URL is configured
+  Server: remote-prod
+  Evidence: url=https://mcp.example.com/sse
+  Fingerprint: mcpg_cf1296e4
+  Fix: Verify the provider, use HTTPS, document the data sent to this server, and keep an allowlist of approved remote endpoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "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

@@ -3,10 +3,10 @@
 import fs from "node:fs";
 import path from "node:path";
 
-const [jsonReportPath, markdownReportPath, htmlReportPath, sarifReportPath, failOn] = process.argv.slice(2);
+const [jsonReportPath, markdownReportPath, htmlReportPath, sarifReportPath, failOn, executiveSummaryPath, remediationReportPath, auditManifestPath] = process.argv.slice(2);
 
 if (!jsonReportPath) {
-  process.stderr.write("Usage: action-comment.js <json-report> <markdown-report> <html-report> <sarif-report> <fail-on>\n");
+  process.stderr.write("Usage: action-comment.js <json-report> <markdown-report> <html-report> <sarif-report> <fail-on> [executive-summary] [remediation-report] [audit-manifest]\n");
   process.exit(1);
 }
 
@@ -61,6 +61,15 @@ lines.push(`- Markdown: \`${relative(markdownReportPath)}\``);
 lines.push(`- HTML: \`${relative(htmlReportPath)}\``);
 lines.push(`- JSON: \`${relative(jsonReportPath)}\``);
 lines.push(`- SARIF: \`${relative(sarifReportPath)}\``);
+if (executiveSummaryPath) {
+  lines.push(`- Executive summary: \`${relative(executiveSummaryPath)}\``);
+}
+if (remediationReportPath) {
+  lines.push(`- Remediation: \`${relative(remediationReportPath)}\``);
+}
+if (auditManifestPath) {
+  lines.push(`- Audit manifest: \`${relative(auditManifestPath)}\``);
+}
 lines.push("");
 
 process.stdout.write(`${lines.join("\n")}\n`);