agent-mcp-guard 0.2.0 → 0.3.0

package/README.md

@@ -14,7 +14,7 @@ Website: [chaoyue0307.github.io/mcp-guard](https://chaoyue0307.github.io/mcp-gua
   <a href="https://www.npmjs.com/package/agent-mcp-guard"><img alt="npm version" src="https://img.shields.io/npm/v/agent-mcp-guard?color=0f766e"></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.2.0"><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.3.0"><img alt="Release" src="https://img.shields.io/github/v/release/ChaoYue0307/mcp-guard?color=7c2d12"></a>
 </p>
 
 ## Install
@@ -42,6 +42,12 @@ Generate an HTML report:
 mcp-guard scan --format html --output mcp-guard-report.html
 ```
 
+Generate SARIF for GitHub code scanning:
+
+```bash
+mcp-guard scan --format sarif --output mcp-guard.sarif
+```
+
 Use in CI:
 
 ```bash
@@ -51,9 +57,10 @@ mcp-guard scan --config .mcp.json --fail-on high
 Use the GitHub Action:
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard@v0.2.0
+- uses: ChaoYue0307/mcp-guard@v0.3.0
   with:
     fail-on: high
+    upload-sarif: "true"
 ```
 
 ## What It Finds
@@ -112,7 +119,7 @@ MCP configs often contain sensitive local paths, internal hostnames, tokens, and
 - no config upload;
 - no external API call;
 - secret-like values redacted in reports;
-- text, Markdown, HTML, and JSON output for local review and CI.
+- text, Markdown, HTML, JSON, and SARIF output for local review, CI artifacts, and GitHub code scanning.
 
 ## Commercial Support
 

package/action.yml

@@ -19,14 +19,14 @@ inputs:
     description: Directory where reports will be written.
     required: false
     default: mcp-guard-report
-  package-version:
-    description: npm package version to install.
-    required: false
-    default: latest
   upload-artifact:
     description: Upload generated reports as a workflow artifact.
     required: false
     default: "true"
+  upload-sarif:
+    description: "Upload SARIF to GitHub code scanning. Requires security-events: write permission."
+    required: false
+    default: "false"
   artifact-name:
     description: Artifact name for generated reports.
     required: false
@@ -42,6 +42,9 @@ outputs:
   json-report:
     description: Path to the generated JSON report.
     value: ${{ steps.reports.outputs.json-report }}
+  sarif-report:
+    description: Path to the generated SARIF report.
+    value: ${{ steps.reports.outputs.sarif-report }}
   exit-code:
     description: mcp-guard threshold exit code.
     value: ${{ steps.reports.outputs.exit-code }}
@@ -54,12 +57,6 @@ runs:
       with:
         node-version: "20"
 
-    - name: Install mcp-guard
-      shell: bash
-      env:
-        MCP_GUARD_PACKAGE_VERSION: ${{ inputs.package-version }}
-      run: npm install --global "agent-mcp-guard@${MCP_GUARD_PACKAGE_VERSION}"
-
     - name: Generate reports
       id: reports
       shell: bash
@@ -70,6 +67,7 @@ runs:
       run: |
         set -euo pipefail
 
+        guard_bin="${GITHUB_ACTION_PATH}/bin/mcp-guard.js"
         mkdir -p "${MCP_GUARD_OUTPUT_DIR}"
 
         scan_args=()
@@ -80,13 +78,15 @@ runs:
         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"
 
-        mcp-guard scan "${scan_args[@]}" --format markdown --output "${markdown_report}" --fail-on none
-        mcp-guard scan "${scan_args[@]}" --format html --output "${html_report}" --fail-on none
-        mcp-guard scan "${scan_args[@]}" --format json --output "${json_report}" --fail-on none
+        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
-        mcp-guard scan "${scan_args[@]}" --fail-on "${MCP_GUARD_FAIL_ON}"
+        node "${guard_bin}" scan "${scan_args[@]}" --fail-on "${MCP_GUARD_FAIL_ON}"
         status="$?"
         set -e
 
@@ -94,9 +94,23 @@ runs:
           echo "markdown-report=${markdown_report}"
           echo "html-report=${html_report}"
           echo "json-report=${json_report}"
+          echo "sarif-report=${sarif_report}"
           echo "exit-code=${status}"
         } >> "${GITHUB_OUTPUT}"
 
+    - name: Write job summary
+      if: ${{ always() && steps.reports.outputs.json-report != '' }}
+      shell: bash
+      env:
+        MCP_GUARD_FAIL_ON: ${{ inputs.fail-on }}
+      run: |
+        node "${GITHUB_ACTION_PATH}/scripts/action-summary.js" \
+          "${{ steps.reports.outputs.json-report }}" \
+          "${{ steps.reports.outputs.markdown-report }}" \
+          "${{ steps.reports.outputs.html-report }}" \
+          "${{ steps.reports.outputs.sarif-report }}" \
+          "${MCP_GUARD_FAIL_ON}" >> "${GITHUB_STEP_SUMMARY}"
+
     - name: Upload report artifact
       if: ${{ always() && inputs.upload-artifact == 'true' }}
       uses: actions/upload-artifact@v4
@@ -104,8 +118,18 @@ runs:
         name: ${{ inputs.artifact-name }}
         path: ${{ inputs.output-dir }}
 
+    - name: Upload SARIF to code scanning
+      if: ${{ always() && inputs.upload-sarif == 'true' && steps.reports.outputs.sarif-report != '' }}
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: ${{ steps.reports.outputs.sarif-report }}
+
     - name: Enforce severity threshold
       shell: bash
       env:
         MCP_GUARD_EXIT_CODE: ${{ steps.reports.outputs.exit-code }}
-      run: exit "${MCP_GUARD_EXIT_CODE}"
+      run: |
+        if [ -z "${MCP_GUARD_EXIT_CODE}" ]; then
+          exit 1
+        fi
+        exit "${MCP_GUARD_EXIT_CODE}"

package/docs/business-playbook.md

@@ -13,7 +13,7 @@ AI Agent/MCP Security Audit.
 Deliverables:
 
 - MCP server inventory;
-- `mcp-guard` Markdown, HTML, and JSON scan reports;
+- `mcp-guard` Markdown, HTML, JSON, and SARIF scan reports;
 - manual review of high-risk findings;
 - prioritized remediation plan;
 - optional GitHub Action setup for continuous scans;

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 installs the published npm package, generates Markdown, HTML, and JSON reports, uploads them as a workflow artifact, then fails the job when findings meet your selected severity threshold.
+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.
 
 ## Basic Workflow
 
@@ -22,29 +22,47 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ChaoYue0307/mcp-guard@v0.2.0
+      - uses: ChaoYue0307/mcp-guard@v0.3.0
         with:
           fail-on: high
 ```
 
-## Scan a Specific Config
+## Upload SARIF to GitHub Security
+
+Enable SARIF upload when you want findings in the repository Security tab. The workflow needs `security-events: write`.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard@v0.2.0
-  with:
-    config: .mcp.json
-    fail-on: medium
+name: mcp-guard
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ChaoYue0307/mcp-guard@v0.3.0
+        with:
+          config: .mcp.json
+          fail-on: high
+          upload-sarif: "true"
 ```
 
-## Pin the npm Package
+## Report-Only Mode
 
-The action defaults to `agent-mcp-guard@latest`. Pin it when you want deterministic CI behavior:
+Use `fail-on: none` when you want artifacts and summaries without blocking a pull request.
 
 ```yaml
-- uses: ChaoYue0307/mcp-guard@v0.2.0
+- uses: ChaoYue0307/mcp-guard@v0.3.0
   with:
-    package-version: 0.2.0
-    fail-on: high
+    fail-on: none
 ```
 
 ## Inputs
@@ -54,8 +72,8 @@ The action defaults to `agent-mcp-guard@latest`. Pin it when you want determinis
 | `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. |
 | `output-dir` | `mcp-guard-report` | Directory for generated reports. |
-| `package-version` | `latest` | npm package version to install. |
 | `upload-artifact` | `true` | Uploads generated reports as a workflow artifact. |
+| `upload-sarif` | `false` | Uploads SARIF to GitHub code scanning. Requires `security-events: write`. |
 | `artifact-name` | `mcp-guard-report` | Name of the uploaded artifact. |
 
 ## Outputs
@@ -65,4 +83,5 @@ The action defaults to `agent-mcp-guard@latest`. Pin it when you want determinis
 | `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. |
 | `exit-code` | `0` when below threshold, `2` when findings met the threshold. |

package/docs/roadmap.md

@@ -5,18 +5,18 @@
 ## Now
 
 - CLI config scanning.
-- Text, Markdown, HTML, and redacted JSON output.
+- Text, Markdown, HTML, redacted JSON, and SARIF output.
 - Rules for shell wrappers, remote package runners, unpinned packages, broad filesystem access, secret-like env vars/headers, and remote MCP URLs.
 - CI usage with `--fail-on`.
-- GitHub Action wrapper that uploads Markdown, HTML, and JSON reports as artifacts.
+- GitHub Action wrapper that writes a job summary, uploads Markdown/HTML/JSON/SARIF artifacts, and can upload SARIF to GitHub code scanning.
 
 ## Next
 
 1. More MCP client discovery paths.
 2. Rule packs mapped to MCP security best practices.
-3. `mcp-guard audit` mode for client-ready reports.
-4. Policy file for approved commands, packages, directories, and remote URLs.
-5. Baseline mode: accept known findings and fail only on new risks.
+3. Policy file for approved commands, packages, directories, and remote URLs.
+4. Baseline mode: accept known findings and fail only on new risks.
+5. `mcp-guard audit` mode for client-ready reports.
 
 ## Later
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
   "homepage": "https://chaoyue0307.github.io/mcp-guard/",
@@ -32,7 +32,9 @@
     "security",
     "cli",
     "scanner",
-    "devsecops"
+    "devsecops",
+    "sarif",
+    "github-actions"
   ],
   "author": "",
   "license": "Apache-2.0",
@@ -41,6 +43,7 @@
     "src",
     "README.md",
     "action.yml",
+    "scripts/action-summary.js",
     "LICENSE",
     "SECURITY.md",
     "docs",

package/scripts/action-summary.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const [jsonReportPath, markdownReportPath, htmlReportPath, sarifReportPath, failOn] = process.argv.slice(2);
+
+if (!jsonReportPath) {
+  process.stderr.write("Usage: action-summary.js <json-report> <markdown-report> <html-report> <sarif-report> <fail-on>\n");
+  process.exit(1);
+}
+
+const report = JSON.parse(fs.readFileSync(jsonReportPath, "utf8"));
+const counts = report.summary.counts;
+const topFindings = report.findings.slice(0, 8);
+
+const lines = [];
+lines.push("## mcp-guard scan");
+lines.push("");
+lines.push(`Risk score: **${report.summary.riskScore}**`);
+lines.push("");
+lines.push("| Severity | Count |");
+lines.push("| --- | ---: |");
+lines.push(`| Critical | ${counts.critical} |`);
+lines.push(`| High | ${counts.high} |`);
+lines.push(`| Medium | ${counts.medium} |`);
+lines.push(`| Low | ${counts.low} |`);
+lines.push("");
+lines.push(`Scanned files: **${report.summary.scannedFileCount}**`);
+lines.push(`MCP servers: **${report.summary.serverCount}**`);
+lines.push(`Findings: **${report.summary.findingCount}**`);
+lines.push(`Fail threshold: **${failOn || "high"}**`);
+lines.push("");
+
+if (topFindings.length === 0) {
+  lines.push("No findings.");
+} else {
+  lines.push("### Top findings");
+  lines.push("");
+  lines.push("| Severity | Rule | Server | Finding |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const finding of topFindings) {
+    lines.push(`| ${cell(finding.severity)} | ${cell(finding.id)} | ${cell(finding.serverName)} | ${cell(finding.title)} |`);
+  }
+}
+
+lines.push("");
+lines.push("### Reports");
+lines.push("");
+lines.push(`- Markdown: \`${relative(markdownReportPath)}\``);
+lines.push(`- HTML: \`${relative(htmlReportPath)}\``);
+lines.push(`- JSON: \`${relative(jsonReportPath)}\``);
+lines.push(`- SARIF: \`${relative(sarifReportPath)}\``);
+lines.push("");
+
+process.stdout.write(`${lines.join("\n")}\n`);
+
+function cell(value) {
+  return String(value ?? "").replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function relative(filePath) {
+  if (!filePath) return "";
+  return path.relative(process.cwd(), path.resolve(filePath)) || ".";
+}

package/src/cli.js

@@ -1,10 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { scan } from "./scan.js";
-import { generateHtmlReport, generateJsonReport, generateMarkdownReport, generateTextReport } from "./report.js";
+import { generateHtmlReport, generateJsonReport, generateMarkdownReport, generateSarifReport, generateTextReport } from "./report.js";
 import { compareSeverity, severityRank } from "./severity.js";
 
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 
 export async function runCli(argv, io) {
   const args = argv.slice(2);
@@ -80,8 +80,8 @@ function parseScanArgs(args, defaultCwd) {
     } else if (arg === "--format" || arg === "-f") {
       options.format = readValue(args, index, arg);
       index += 1;
-      if (!["text", "markdown", "json", "html"].includes(options.format)) {
-        throw new Error("--format must be one of: text, markdown, json, html");
+      if (!["text", "markdown", "json", "html", "sarif"].includes(options.format)) {
+        throw new Error("--format must be one of: text, markdown, json, html, sarif");
       }
     } else if (arg === "--fail-on") {
       options.failOn = readValue(args, index, arg);
@@ -124,6 +124,9 @@ function renderReport(result, format) {
   if (format === "html") {
     return generateHtmlReport(result);
   }
+  if (format === "sarif") {
+    return `${generateSarifReport(result)}\n`;
+  }
   return generateTextReport(result);
 }
 
@@ -145,7 +148,7 @@ Usage:
 Scan options:
   -c, --config <path>       Scan a specific MCP config file. Can be repeated.
   -o, --output <path>       Write report to a file.
-  -f, --format <format>     text, markdown, json, or html. Default: text.
+  -f, --format <format>     text, markdown, json, html, or sarif. Default: text.
       --fail-on <severity>  Exit 2 when finding severity is at least threshold.
                             critical, high, medium, low, none. Default: none.
       --cwd <path>          Working directory for project config discovery.
@@ -155,6 +158,7 @@ Examples:
   mcp-guard scan
   mcp-guard scan --format markdown --output mcp-guard-report.md
   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
 `;
 }

package/src/report.js

@@ -105,6 +105,40 @@ export function generateJsonReport(result) {
   return JSON.stringify(sanitizeResult(result), null, 2);
 }
 
+export function generateSarifReport(result) {
+  const rules = buildSarifRules(result.findings);
+  const sarif = {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "mcp-guard",
+            informationUri: "https://github.com/ChaoYue0307/mcp-guard",
+            semanticVersion: result.metadata.toolVersion,
+            rules
+          }
+        },
+        automationDetails: {
+          id: "mcp-guard/"
+        },
+        invocations: [
+          {
+            executionSuccessful: true,
+            workingDirectory: {
+              uri: uriFromPath(result.metadata.cwd, result.metadata.cwd)
+            }
+          }
+        ],
+        results: result.findings.map((finding) => sarifResult(finding, result.metadata.cwd))
+      }
+    ]
+  };
+
+  return JSON.stringify(sarif, null, 2);
+}
+
 export function generateHtmlReport(result) {
   const safeResult = sanitizeResult(result);
   const riskTone = riskToneForScore(safeResult.summary.riskScore);
@@ -491,6 +525,93 @@ function sanitizeResult(result) {
   };
 }
 
+function buildSarifRules(findings) {
+  const unique = new Map();
+  for (const finding of findings) {
+    if (unique.has(finding.id)) continue;
+    unique.set(finding.id, {
+      id: finding.id,
+      name: finding.id,
+      shortDescription: {
+        text: finding.title
+      },
+      fullDescription: {
+        text: finding.title
+      },
+      help: {
+        text: finding.recommendation,
+        markdown: finding.recommendation
+      },
+      defaultConfiguration: {
+        level: sarifLevel(finding.severity)
+      },
+      properties: {
+        severity: finding.severity,
+        tags: ["mcp", "ai-agent", "security"]
+      }
+    });
+  }
+  return [...unique.values()];
+}
+
+function sarifResult(finding, cwd) {
+  return {
+    ruleId: finding.id,
+    level: sarifLevel(finding.severity),
+    message: {
+      text: `${finding.title}. ${finding.evidence} Fix: ${finding.recommendation}`
+    },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: uriFromPath(finding.configPath, cwd)
+          },
+          region: {
+            startLine: 1,
+            startColumn: 1
+          }
+        },
+        logicalLocations: [
+          {
+            name: finding.serverName,
+            kind: "object"
+          }
+        ]
+      }
+    ],
+    partialFingerprints: {
+      "mcp-guard/rule-server-evidence": fingerprint(`${finding.id}:${finding.serverName}:${finding.evidence}`)
+    },
+    properties: {
+      severity: finding.severity,
+      serverName: finding.serverName,
+      evidence: finding.evidence,
+      recommendation: finding.recommendation
+    }
+  };
+}
+
+function sarifLevel(severity) {
+  if (severity === "critical" || severity === "high") return "error";
+  if (severity === "medium") return "warning";
+  return "note";
+}
+
+function uriFromPath(filePath, cwd) {
+  const display = displayPath(filePath, cwd) || ".";
+  return display.split("/").map(encodeURIComponent).join("/");
+}
+
+function fingerprint(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
 function metric(label, value) {
   return `<div class="metric"><strong>${escapeHtml(value)}</strong><span>${escapeHtml(label)}</span></div>`;
 }