@apitella/scan 0.1.0 → 0.2.0

package/README.md

@@ -39,10 +39,13 @@ Apitella scan  my-warehouse-mcp v1.4.0
 | `--token <t>`                           | Bearer token shorthand.                                                             |
 | `--baseline [file]`                     | Diff the scan against a committed snapshot (default `.apitella/baseline.json`).     |
 | `--update-baseline`                     | Write the current surface to the baseline file and exit 0.                          |
-| `--json`                                | Machine-readable output (includes the baseline diff when `--baseline` is set).      |
+| `--format <fmt>`                        | `text` (default), `json`, `sarif` (code scanning), `markdown` (PR comment).         |
+| `--json`                                | Deprecated alias for `--format json`.                                               |
 | `--fail-on <error\|warning>`            | Non-zero exit threshold (default: `warning`). Ignored with `--baseline`.            |
 | `--no-fail`                             | Always exit 0 unless the scan itself failed.                                        |
 
+All formats keep the same exit codes, so `--format sarif` / `markdown` still gate a build.
+
 ### Exit codes
 
 | Code | Meaning                                                                  |
@@ -55,8 +58,8 @@ Apitella scan  my-warehouse-mcp v1.4.0
 
 Commit a snapshot of your server's surface, then fail a PR only when the change makes
 it **worse** — a tool removed, a tool that lost its `readOnlyHint` / `destructiveHint`,
-or a new error/warning. Pre-existing findings you've decided to live with don't fail
-the build.
+a resource whose `mimeType` changed, or a new error/warning. Pre-existing findings
+you've decided to live with don't fail the build.
 
 ```
 # once, checked in:
@@ -93,15 +96,29 @@ the diff lands in the PR alongside the code.
     npm ci && npm run build
     node dist/server.js &
     npx --yes wait-on http://localhost:3000/mcp
-- uses: dodogeny/apitella-saas/cli@v1
+- uses: dodogeny/apitella-scan-action@v1
   with:
     url: http://localhost:3000/mcp
     baseline: .apitella/baseline.json
 ```
 
-Action inputs: `url` **or** `input` (a `tools/list` dump), `baseline`, `fail-on`,
-`headers` (newline-separated `Name: value`), `package-version`. A full example is in
-[`examples/mcp-scan.yml`](./examples/mcp-scan.yml).
+On `pull_request` events the action posts a **sticky PR comment** with the result and
+baseline diff (needs `permissions: pull-requests: write`; `comment: false` to disable).
+Other inputs: `url`/`input`, `baseline`, `fail-on`, `headers`, `format`, `output-file`,
+`package-version`. Full example: [`examples/mcp-scan.yml`](./examples/mcp-scan.yml).
+
+### SARIF → GitHub code scanning
+
+```yaml
+- uses: dodogeny/apitella-scan-action@v1
+  with:
+    url: http://localhost:3000/mcp
+    format: sarif
+    output-file: apitella.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: apitella.sarif
+```
 
 ### Plain npx
 
@@ -116,6 +133,8 @@ Action inputs: `url` **or** `input` (a `tools/list` dump), `baseline`, `fail-on`
   "wipes…") but `destructiveHint` isn't `true`.
 - **`readonly-hint-contradicted`** — `readOnlyHint: true` on a tool that takes a
   `content` / `body` / `payload` / `data` parameter.
+- **`openworld-hint-contradicted`** — `openWorldHint: false` on a tool whose description
+  says it reaches arbitrary external URLs or the open web.
 - **`instruction-injection`** — tool or parameter text contains instruction-override
   phrasing or invisible characters aimed at the model reading it.
 - **`credential-exposed`** — an AWS key, GitHub/Slack token, or private-key block in

package/dist/analyze.js

@@ -23,6 +23,11 @@ const INJECTION_PATTERNS = [
     /[​‌‍⁠]/,
 ];
 const DESTRUCTIVE_VERBS = /\b(delete|deletes|deleted|deleting|remove|removes|removed|removing|drop|drops|dropped|dropping|wipe|wipes|wiped|wiping|purge|purges|purged|purging|destroy|destroys|destroyed|destroying|erase|erases|erased|erasing)\b/i;
+// Phrasing that only makes sense if the tool reaches an "open world" of external entities —
+// arbitrary/caller-supplied URLs, the public web. Deliberately narrow, same reasoning as
+// DESTRUCTIVE_VERBS: it only ever fires alongside an explicit openWorldHint: false, so a
+// false positive needs both a misleading description AND a wrong hint.
+const OPEN_WORLD_PHRASES = /\b(arbitrary|any|external|remote|user[- ]?(?:provided|supplied|specified)|third[- ]?party)\s+(?:url|uri|endpoint|host|website|site|web\s?page|address)\b|\bthe (?:web|internet)\b|\bfetch(?:es|ing)?\s+(?:a\s+)?(?:url|link|web\s?page|remote\s+\w+)\b/i;
 // Exact param-name match — catch a payload param named exactly "content" without
 // false-positiving on "contentType" or "dataSource".
 const WRITE_SHAPED_PARAM_NAMES = new Set([
@@ -111,6 +116,16 @@ export function analyze(schema, url) {
                 message: "Neither readOnlyHint nor destructiveHint is declared — an agent can't tell whether this is safe to auto-approve.",
             });
         }
+        if (op.annotations?.openWorldHint === false &&
+            op.description &&
+            OPEN_WORLD_PHRASES.test(op.description)) {
+            findings.push({
+                severity: "warning",
+                rule: "openworld-hint-contradicted",
+                operation: op.id,
+                message: "Declared openWorldHint: false, but the description says it reaches arbitrary external URLs or the open web — that's open-world behaviour a host would sandbox differently.",
+            });
+        }
     }
     findings.push({
         severity: "note",

package/dist/index.js

@@ -3,9 +3,11 @@ import { parseArgs } from "node:util";
 import { analyze } from "./analyze.js";
 import { diffSnapshots, makeSnapshot, readSnapshot, writeSnapshot, } from "./baseline.js";
 import { fetchFromFile, fetchFromUrl } from "./fetch.js";
-import { renderBaselineDiff, renderJson, renderText } from "./report.js";
-const VERSION = "0.1.0";
+import { renderBaselineDiff, renderJson, renderMarkdown, renderText, } from "./report.js";
+import { renderSarif } from "./sarif.js";
+const VERSION = "0.2.0";
 const DEFAULT_BASELINE = ".apitella/baseline.json";
+const FORMATS = ["text", "json", "sarif", "markdown"];
 const HELP = `
 apitella-scan — check an MCP server's tool surface for safety-annotation gaps
                 and prompt-injection risks.
@@ -27,10 +29,14 @@ OPTIONS
       --baseline [file]   Compare the scan to a committed snapshot and report what
                           changed (default file: ${DEFAULT_BASELINE}). Exits non-zero
                           only on a regression — a removed tool, a tool that lost its
-                          safety hint, or a new error/warning.
+                          safety hint, a resource whose mimeType changed, or a new
+                          error/warning.
       --update-baseline   Write the current surface to the baseline file and exit 0.
                           Run this to accept the current state as the new reference.
-      --json              Emit JSON instead of the formatted report.
+      --format <fmt>      Output format: text (default), json, sarif, markdown.
+                          sarif is for GitHub code scanning; markdown is for a PR
+                          comment. All formats keep the same exit codes.
+      --json              Deprecated alias for --format json.
       --fail-on <lvl>     Without --baseline: exit non-zero when findings reach this
                           level, "error" or "warning" (default: warning).
       --no-fail           Always exit 0 unless the scan itself failed.
@@ -70,6 +76,7 @@ async function main() {
                 token: { type: "string" },
                 baseline: { type: "string" },
                 "update-baseline": { type: "boolean", default: false },
+                format: { type: "string" },
                 json: { type: "boolean", default: false },
                 "fail-on": { type: "string", default: "warning" },
                 "no-fail": { type: "boolean", default: false },
@@ -94,6 +101,15 @@ async function main() {
     if (failOn !== "error" && failOn !== "warning") {
         throw new UsageError(`--fail-on must be "error" or "warning", got "${failOn}".`);
     }
+    let format = "text";
+    if (values.json)
+        format = "json";
+    if (values.format !== undefined) {
+        if (!FORMATS.includes(values.format)) {
+            throw new UsageError(`--format must be one of ${FORMATS.join(", ")}, got "${values.format}".`);
+        }
+        format = values.format;
+    }
     const url = positionals[0];
     if (!url && !values.input) {
         throw new UsageError("Pass an MCP server URL or --input <file>. See --help.");
@@ -137,14 +153,21 @@ async function main() {
             findings: report.findings,
         })
         : null;
-    if (values.json) {
-        process.stdout.write(`${renderJson(report, target, meta, diff)}\n`);
-    }
-    else {
-        process.stdout.write(renderText(report, target, meta));
-        if (diff && baselinePath) {
-            process.stdout.write(renderBaselineDiff(diff, baselinePath));
-        }
+    switch (format) {
+        case "json":
+            process.stdout.write(renderJson(report, target, meta, diff));
+            break;
+        case "sarif":
+            process.stdout.write(renderSarif(report, target, meta, VERSION));
+            break;
+        case "markdown":
+            process.stdout.write(renderMarkdown(report, target, meta, diff));
+            break;
+        default:
+            process.stdout.write(renderText(report, target, meta));
+            if (diff && baselinePath) {
+                process.stdout.write(renderBaselineDiff(diff, baselinePath));
+            }
     }
     if (values["no-fail"])
         return 0;

package/dist/report.js

@@ -20,6 +20,11 @@ const LABEL = {
     warning: c.yellow,
     note: c.dim,
 };
+function serverLabel(target, meta) {
+    return meta?.serverName
+        ? `${meta.serverName}${meta.serverVersion ? ` v${meta.serverVersion}` : ""}`
+        : target;
+}
 function countsLine(report) {
     const parts = [
         `${report.toolCount} tool${report.toolCount === 1 ? "" : "s"}`,
@@ -35,13 +40,18 @@ function countsLine(report) {
     }
     return parts.join(" · ");
 }
+function baselineIsEmpty(diff) {
+    return (diff.addedOps.length === 0 &&
+        diff.removedOps.length === 0 &&
+        diff.lostSafetyHint.length === 0 &&
+        diff.mimeTypeChanges.length === 0 &&
+        diff.newFindings.length === 0 &&
+        diff.resolvedFindings.length === 0);
+}
 export function renderText(report, target, meta) {
     const lines = [];
-    const server = meta?.serverName
-        ? `${meta.serverName}${meta.serverVersion ? ` v${meta.serverVersion}` : ""}`
-        : target;
     lines.push("");
-    lines.push(`${c.bold("Apitella scan")}  ${c.dim(server)}`);
+    lines.push(`${c.bold("Apitella scan")}  ${c.dim(serverLabel(target, meta))}`);
     lines.push(c.dim(countsLine(report)));
     lines.push("");
     const ordered = [
@@ -74,12 +84,7 @@ export function renderText(report, target, meta) {
 export function renderBaselineDiff(diff, baselinePath) {
     const lines = [];
     lines.push(`${c.bold("vs. baseline")}  ${c.dim(baselinePath)}`);
-    const nothing = diff.addedOps.length === 0 &&
-        diff.removedOps.length === 0 &&
-        diff.lostSafetyHint.length === 0 &&
-        diff.newFindings.length === 0 &&
-        diff.resolvedFindings.length === 0;
-    if (nothing) {
+    if (baselineIsEmpty(diff)) {
         lines.push(c.green("  ✔ No change to the surface since the baseline."));
         lines.push("");
         return lines.join("\n");
@@ -93,6 +98,9 @@ export function renderBaselineDiff(diff, baselinePath) {
     for (const id of diff.lostSafetyHint) {
         lines.push(`  ${c.red("!")} ${c.cyan(id)} lost its safety hint — it declared readOnlyHint/destructiveHint in the baseline and now declares neither.`);
     }
+    for (const m of diff.mimeTypeChanges) {
+        lines.push(`  ${c.red("~")} ${c.cyan(m.id)} mimeType ${m.from ?? "(none)"} → ${m.to ?? "(none)"} — a client parsing the old type will misread the new one.`);
+    }
     for (const f of diff.newFindings) {
         const scope = f.operation ? c.cyan(f.operation) : c.dim("server");
         lines.push(`  ${MARK[f.severity]} new      ${scope}  ${LABEL[f.severity](`[${f.rule}]`)}`);
@@ -110,7 +118,7 @@ export function renderBaselineDiff(diff, baselinePath) {
     return lines.join("\n");
 }
 export function renderJson(report, target, meta, diff) {
-    return JSON.stringify({
+    return `${JSON.stringify({
         target,
         server: meta ?? null,
         summary: {
@@ -122,5 +130,53 @@ export function renderJson(report, target, meta, diff) {
         },
         findings: report.findings,
         baseline: diff ?? null,
-    }, null, 2);
+    }, null, 2)}\n`;
+}
+// A PR-comment-ready block. The leading HTML comment is a stable marker so a CI step can
+// find and update its own comment in place instead of piling on new ones.
+export const MARKDOWN_MARKER = "<!-- apitella-scan -->";
+export function renderMarkdown(report, target, meta, diff) {
+    const out = [MARKDOWN_MARKER];
+    const { error, warning } = report.counts;
+    const verdict = error > 0
+        ? `❌ **${error} error${error === 1 ? "" : "s"}**${warning ? `, ${warning} warning${warning === 1 ? "" : "s"}` : ""}`
+        : warning > 0
+            ? `⚠️ **${warning} warning${warning === 1 ? "" : "s"}**`
+            : "✅ **Nothing flagged**";
+    out.push(`### Apitella MCP scan — \`${serverLabel(target, meta)}\``);
+    out.push("");
+    out.push(`${countsLine(report)} · ${verdict}`);
+    const flagged = report.findings.filter((f) => f.severity !== "note");
+    if (flagged.length > 0) {
+        out.push("");
+        out.push("| | Operation | Rule | Detail |");
+        out.push("|---|---|---|---|");
+        for (const f of flagged) {
+            const icon = f.severity === "error" ? "❌" : "⚠️";
+            out.push(`| ${icon} | \`${f.operation ?? "server"}\` | \`${f.rule}\` | ${f.message.replace(/\|/g, "\\|")} |`);
+        }
+    }
+    if (diff && !baselineIsEmpty(diff)) {
+        out.push("");
+        out.push(diff.regressed
+            ? "#### 🔻 This change makes the MCP surface worse than the baseline"
+            : "#### Changes vs. baseline (no regressions)");
+        const bullets = [];
+        for (const id of diff.removedOps)
+            bullets.push(`\`−\` removed \`${id}\``);
+        for (const id of diff.addedOps)
+            bullets.push(`\`+\` added \`${id}\``);
+        for (const id of diff.lostSafetyHint)
+            bullets.push(`\`!\` \`${id}\` lost its safety hint`);
+        for (const m of diff.mimeTypeChanges)
+            bullets.push(`\`~\` \`${m.id}\` mimeType ${m.from ?? "(none)"} → ${m.to ?? "(none)"}`);
+        for (const f of diff.newFindings)
+            bullets.push(`${f.severity === "error" ? "❌" : "⚠️"} new \`${f.rule}\` on \`${f.operation ?? "server"}\``);
+        for (const f of diff.resolvedFindings)
+            bullets.push(`✅ resolved \`${f.rule}\` on \`${f.operation ?? "server"}\``);
+        out.push(...bullets.map((b) => `- ${b}`));
+    }
+    out.push("");
+    out.push("<sub>[Apitella MCP scan](https://apitella.com/guides/scanning-mcp-servers-in-ci) · point-in-time; continuous monitoring is the hosted product.</sub>");
+    return `${out.join("\n")}\n`;
 }

package/dist/sarif.js

@@ -0,0 +1,94 @@
+// SARIF 2.1.0 output for GitHub code scanning (upload-sarif). MCP findings have no source
+// file, so results are grouped under a path derived from the target — code scanning shows
+// them there rather than "not associated with a file".
+const HELP_URI = "https://apitella.com/guides/scanning-mcp-servers-in-ci";
+const INFO_URI = "https://apitella.com/scan";
+const SARIF_LEVEL = {
+    error: "error",
+    warning: "warning",
+    note: "note",
+};
+const RULE_DESCRIPTIONS = {
+    "no-safety-hints": "Tool declares neither readOnlyHint nor destructiveHint.",
+    "destructive-hint-mismatch": "Description reads as destructive but destructiveHint is not true.",
+    "readonly-hint-contradicted": "readOnlyHint is true on a tool that takes a write-shaped parameter.",
+    "openworld-hint-contradicted": "openWorldHint is false but the description implies open-web access.",
+    "instruction-injection": "Tool or parameter text reads as an instruction override, or hides characters.",
+    "credential-exposed": "A credential-shaped string appears in tool text.",
+    "insecure-transport": "The server URL is plain HTTP.",
+    "no-version-signal": "The server exposes no version or changelog signal.",
+};
+function uriForTarget(target) {
+    try {
+        const u = new URL(target);
+        return `${u.host}${u.pathname}`.replace(/\/+$/, "") || u.host;
+    }
+    catch {
+        // Already a file path (input mode) — keep it relative, forward slashes.
+        return target.replace(/^\.?\//, "").replace(/\\/g, "/");
+    }
+}
+const toCamel = (kebab) => kebab.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+export function renderSarif(report, target, meta, version) {
+    const uri = uriForTarget(target);
+    const levelByRule = new Map();
+    for (const f of report.findings) {
+        const worse = !levelByRule.has(f.rule) ||
+            f.severity === "error" ||
+            (f.severity === "warning" && levelByRule.get(f.rule) === "note");
+        if (worse)
+            levelByRule.set(f.rule, f.severity);
+    }
+    const rules = [...levelByRule.keys()].sort().map((id) => ({
+        id,
+        name: toCamel(id),
+        shortDescription: { text: RULE_DESCRIPTIONS[id] ?? id },
+        helpUri: HELP_URI,
+        defaultConfiguration: { level: SARIF_LEVEL[levelByRule.get(id)] },
+    }));
+    const results = report.findings.map((f) => ({
+        ruleId: f.rule,
+        level: SARIF_LEVEL[f.severity],
+        message: { text: f.operation ? `${f.operation}: ${f.message}` : f.message },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: { uri },
+                    region: { startLine: 1 },
+                },
+                ...(f.operation
+                    ? { logicalLocations: [{ name: f.operation, kind: "function" }] }
+                    : {}),
+            },
+        ],
+        partialFingerprints: {
+            "apitellaScan/v1": `${f.rule}:${f.operation ?? "server"}`,
+        },
+        properties: { operation: f.operation, mcpTarget: target },
+    }));
+    return `${JSON.stringify({
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "apitella-scan",
+                        informationUri: INFO_URI,
+                        version,
+                        rules,
+                    },
+                },
+                results,
+                ...(meta?.serverName
+                    ? {
+                        properties: {
+                            mcpServer: meta.serverName,
+                            mcpServerVersion: meta.serverVersion,
+                        },
+                    }
+                    : {}),
+            },
+        ],
+    }, null, 2)}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apitella/scan",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Check an MCP server's tool surface for safety-annotation gaps and prompt-injection risks — at build time, in CI, or against a live URL.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
-    "test": "node --test --import tsx test/analyze.test.ts test/baseline.test.ts",
+    "test": "node --test --import tsx test/analyze.test.ts test/baseline.test.ts test/output.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [