mcpgawk 0.1.7__tar.gz → 0.1.9__tar.gz

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/.github/workflows/publish-pypi.yml

@@ -75,4 +75,16 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: |
           python -m pip install twine
-          twine upload dist/*
+          # --skip-existing + retry: on 2026-07-23 (0.1.7) upload.pypi.org connect-timeouts made
+          # twine exit 1 AFTER both artefacts had already landed — a RED run over a SUCCESSFUL
+          # publish, and a plain re-run would then fail with "file already exists". --skip-existing
+          # makes a retry idempotent (already-uploaded files are skipped, not errored); the loop
+          # rides out a transient network blip instead of failing the whole release on it.
+          for attempt in 1 2 3; do
+            if twine upload --non-interactive --skip-existing dist/*; then
+              echo "upload ok (attempt $attempt)"; exit 0
+            fi
+            echo "::warning::twine upload attempt $attempt failed (likely a transient upload.pypi.org timeout) — retrying"
+            sleep 20
+          done
+          echo "::error::twine upload failed after 3 attempts"; exit 1

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to mcpgawk. Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/).
 
+## [0.1.8] — 2026-07-26
+
+One command. The paid capabilities are now subcommands of `mcpgawk`, not a separate binary.
+
+### Changed
+
+- **`mcpgawk --help` now lists the gawk Platform capabilities** (`verify`, `enforce`, `monitor`,
+  `build`) so you can see what a subscription adds without installing anything. Running one on a
+  free install prints a single line explaining what it is and where to get it, and exits 3 — no
+  Python traceback, and never a silent success.
+- **The free scanner is unchanged and stays free.** `mcpgawk scan` needs no licence, no account and
+  no network beyond the servers you point it at. Nothing in this release adds a paid dependency:
+  the paid engine is not in this package and the import that reaches for it is optional.
+
+### Why one command
+
+The paid tier used to install a second executable named `gawk`. That name belongs to **GNU AWK** —
+it owns `/usr/bin/gawk` across the Debian family and supplies `/usr/bin/awk` there through the
+alternatives system, so shipping our own `gawk` could break a machine's `awk`. Debian Policy §10.1
+requires a rename when two packages claim one path, and Homebrew's `gawk` formula *is* GNU awk.
+Projects that hit this before us all retreated: ast-grep deprecated its colliding `sg`, `fd` ships
+as `fdfind`, `bat` as `batcat`.
+
+One command plus a licence unlock is also the ordinary shape for this kind of tool — Semgrep, Snyk,
+GitLab and Terraform all do it. "gawk" remains the brand (gawk.dev); `mcpgawk` is the command.
+
+## [0.1.7] — 2026-07-23
+
+Engine sync release. Dispatch-aware drift, credential-safe fleet URLs, sturdier baselines.
+
+### Added
+
+- `fingerprint.py` — one shared surface-fingerprint used by both drift and the fleet view, so the
+  two can no longer disagree about whether a server changed.
+
+### Changed
+
+- **Fleet URLs are redacted for display.** A secret-named query parameter (`apiKey=`, `token=`) or
+  userinfo in a server URL no longer renders in the fleet listing. The real URL is untouched for
+  connecting — only what gets shown is masked.
+- Drift and history handling hardened around dispatch-style servers and baseline recording.
+
 ## [0.1.6] — 2026-07-22
 
 The drift release. Everything here is about one question a fresh look at your machine can never

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpgawk
-Version: 0.1.7
+Version: 0.1.9
 Summary: A local-first CLI that measures what an MCP server costs and what it can do. Nothing leaves your machine.
 Project-URL: Homepage, https://mcp.gawk.dev
 Project-URL: Documentation, https://mcp.gawk.dev

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcpgawk"
-version = "0.1.7"
+version = "0.1.9"
 description = "A local-first CLI that measures what an MCP server costs and what it can do. Nothing leaves your machine."
 readme = "README.md"
 requires-python = ">=3.10"

mcpgawk-0.1.9/src/mcpgawk/baseline.py

@@ -0,0 +1,155 @@
+"""The one answer to "what did this server look like when I trusted it".
+
+The product kept three memories of that: `history.py` (scan), `packages/verify/src/pins.ts`
+(verify) and `monitor/store.py` (the daemon). You could approve a server in one and still be told
+it had drifted by another, which is why no flow felt joined up — there wasn't one spine, there were
+three.
+
+This is the spine. It is deliberately a NARROW VIEW over the store that already exists
+(`history.json`) rather than a fourth file: a new store would have to be migrated into, kept in
+sync, and would itself become another memory to disagree with. The canonical record was already
+there — `servers[key]["approved"]` — it simply had no name and no reader outside scan.
+
+What makes one shared baseline possible at all is that the fingerprint is now identical everywhere:
+`fingerprint.surface_pin` is computed by scan (through `measure`), by monitor, and — since the
+schema-2.0 change — byte-for-byte by verify in TypeScript. Before that, sharing a baseline would
+have meant sharing a number the three pillars each interpreted differently.
+
+Shape (stable, and the contract other runtimes read through `mcpgawk baseline --json`):
+
+    {"schema": "gawk.baseline/1",
+     "servers": {"<key>": {"pin": "<16-hex>", "tools": {"<name>": "<hash>"},
+                           "approved_at": "<iso8601>", "aliases": [...]}}}
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import history
+
+#: Bumped only when the exported shape changes incompatibly. Readers check it rather than guessing.
+SCHEMA = "gawk.baseline/1"
+
+
+def approved_record(key: str, path: str | None = None) -> dict[str, Any] | None:
+    """The full approved record for one server, or None if nothing has been approved yet."""
+    store = history.load(path or history.default_path())
+    return history.approved(store, key)
+
+
+def approved_pin(key: str, path: str | None = None) -> str | None:
+    """The approved whole-surface pin — the single value every pillar compares against.
+
+    None means "never approved", which is NOT the same as "approved as empty": a caller that
+    conflates them reports drift against a baseline that does not exist, on a server the operator
+    has never looked at. Trust-on-first-use is scan's job (see history.record); this only reports.
+    """
+    rec = approved_record(key, path)
+    return (rec or {}).get("pin")
+
+
+def approved_tools(key: str, path: str | None = None) -> dict[str, str]:
+    """`{tool name: hash}` from the approved record. Empty dict when nothing is approved."""
+    rec = approved_record(key, path) or {}
+    tools = rec.get("tools")
+    return dict(tools) if isinstance(tools, dict) else {}
+
+
+def approved_annotations(key: str, path: str | None = None) -> dict[str, dict[str, Any]]:
+    """`{tool name: annotations}` as they were WHEN APPROVED.
+
+    The distinction that makes this worth having: `enforce` can already derive a policy from the
+    annotations a server declares at connect time — but that is the server's CURRENT claim about
+    itself. A server that quietly flips `readOnlyHint` to true would have the guard relax to match
+    it. Deriving from the approved record instead means the policy reflects the operator's decision,
+    and a server changing its story does not change what it is allowed to do.
+
+    Records store typed keys (`tool.read_file`) because a prompt and a tool may share a name; only
+    tools carry scopes, so only tools come back.
+    """
+    rec = approved_record(key, path) or {}
+    raw = rec.get("annotations")
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for ident, ann in raw.items():
+        if not isinstance(ident, str) or not ident.startswith("tool."):
+            continue
+        if isinstance(ann, dict):
+            out[ident[len("tool."):]] = dict(ann)
+    return out
+
+
+def export(path: str | None = None) -> dict[str, Any]:
+    """The whole approved baseline, in the shape other runtimes read.
+
+    Only APPROVED state crosses this boundary — never the sighting history. What a server looked
+    like last Tuesday is scan's business; what the operator has agreed to trust is everyone's.
+    """
+    store = history.load(path or history.default_path())
+    out: dict[str, Any] = {}
+    for key, entry in (store.get("servers") or {}).items():
+        if not isinstance(entry, dict):
+            continue
+        rec = entry.get("approved")
+        if not isinstance(rec, dict):
+            continue  # seen but never approved — deliberately absent, not exported as empty
+        out[key] = {
+            "pin": rec.get("pin"),
+            "tools": dict(rec.get("tools") or {}),
+            "approved_at": rec.get("measured_at"),
+            "aliases": list(entry.get("aliases") or []),
+            "annotations": {
+                ident[len("tool."):]: dict(ann)
+                for ident, ann in (rec.get("annotations") or {}).items()
+                if isinstance(ident, str) and ident.startswith("tool.") and isinstance(ann, dict)
+            },
+        }
+    return {"schema": SCHEMA, "servers": out}
+
+
+def publish(key: str, *, pin: str, tools: dict[str, str], approved_at: str,
+            alias: str | None = None, path: str | None = None) -> None:
+    """Write an approval INTO the spine from another pillar.
+
+    The read path (`export`) alone makes the spine a one-way mirror: verify and monitor could see
+    what scan approved, but an operator approving a drift in `gawk-monitor approve` left scan still
+    reporting it. A shared baseline that only one pillar can move is three memories again, with
+    extra steps.
+
+    Deliberately narrow — pin, per-tool hashes, when. A monitor Snapshot carries more (grade,
+    signals, verification state) and that stays in monitor's own store: the spine is the answer to
+    "what surface did we agree to trust", not a general-purpose replica.
+    """
+    p = path or history.default_path()
+    with history.locked(p):
+        store = history.load(p)
+        entry = store.setdefault("servers", {}).setdefault(key, {})
+        entry["approved"] = {
+            **(entry.get("approved") or {}),
+            "measured_at": approved_at,
+            "pin": pin,
+            "tools": dict(tools),
+        }
+        if alias:
+            entry["aliases"] = sorted(set(entry.get("aliases", [])) | {alias})
+        history.save(store, p)
+
+
+def resolve(name: str, path: str | None = None) -> str | None:
+    """Map a name the user typed to the key the baseline is stored under.
+
+    A server's identity key and the name it is configured under in an AI tool are not the same
+    string, and the same server is routinely configured under different names in different tools.
+    Without this, `approve slack` in one pillar and a lookup of `slack-mcp` in another miss each
+    other and the shared baseline silently does nothing.
+    """
+    store = history.load(path or history.default_path())
+    servers = store.get("servers") or {}
+    if name in servers:
+        return name
+    for key, entry in servers.items():
+        if isinstance(entry, dict) and name in (entry.get("aliases") or []):
+            return key
+    return None

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/src/mcpgawk/cli.py

@@ -127,7 +127,16 @@ def build_parser() -> argparse.ArgumentParser:
 
     Whether tracking defaults on is a product invariant (ADR-0012 N2), not a detail — asserting it
     needs a parser you can build without running a scan."""
-    p = argparse.ArgumentParser(prog="mcpgawk", description="gawk at an MCP server before you trust it")
+    p = argparse.ArgumentParser(
+        prog="mcpgawk",
+        description="gawk at an MCP server before you trust it",
+        epilog=(
+            "gawk Platform capabilities (£29/month — https://mcp.gawk.dev/pricing.html):\n"
+            + "".join(f"  {c:<9} {d}\n" for c, d in PLATFORM_CAPABILITIES.items())
+            + "Run `mcpgawk <capability>` once subscribed; scan stays free and open-source."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     sub = p.add_subparsers(dest="cmd", required=True)
     s = sub.add_parser("scan", help="measure MCP server(s) locally")
     s.add_argument("config", nargs="?", help="path to an mcp.json config")
@@ -175,6 +184,18 @@ def build_parser() -> argparse.ArgumentParser:
     # The other half of a sticky alarm. Drift now re-reports on every scan until acknowledged
     # (ADR-0012 N1), so there MUST be an obvious way to acknowledge it — an alarm a user cannot
     # clear is one they will silence with --no-track, which costs them the baseline entirely.
+    b = sub.add_parser(
+        "baseline",
+        help="print the approved baseline — what you have agreed to trust, per server",
+        description=(
+            "The shared baseline every pillar compares against. `verify` and `monitor` read this "
+            "so that approving a server once is approving it everywhere, instead of each keeping "
+            "its own memory and contradicting the others."
+        ),
+    )
+    b.add_argument("--json", action="store_true", help="machine-readable (the cross-runtime shape)")
+    b.add_argument("--server", metavar="NAME", help="one server (name or alias) instead of all")
+
     a = sub.add_parser("approve",
                        help="accept a server's current tools as the trusted baseline (clears DRIFT)")
     a.add_argument("server", nargs="?",
@@ -182,9 +203,118 @@ def build_parser() -> argparse.ArgumentParser:
     a.add_argument("--all", action="store_true", help="approve every server with pending drift")
     a.add_argument("--list", action="store_true",
                    help="show which servers have changes you have not approved, and change nothing")
+
+    k = sub.add_parser(
+        "skills",
+        help="scan agent SKILLS (SKILL.md trees) for injection, hidden text and risky content",
+        description=(
+            "Discovers agent skills across every supported host (Claude Code, Codex, Cursor, "
+            "Copilot, Windsurf, Antigravity, Kiro, Gemini, opencode, Amp) and scans their content "
+            "locally — nothing is uploaded anywhere. Give paths to scan a specific skill dir, a "
+            "skills root, or a project instead of the whole machine."
+        ),
+    )
+    k.add_argument("paths", nargs="*",
+                   help="skill dir / skills root / project root (default: discover all hosts)")
+    k.add_argument("--json", action="store_true", help="machine-readable output")
+    k.add_argument("--fail-on-findings", action="store_true",
+                   help="exit 1 if any finding fires (CI gate) — default reports and exits 0, "
+                        "because a signal is a signal, not a verdict")
     return p
 
 
+_SKILLS_NOT_CHECKED = (
+    "not checked (needs semantic analysis, not attempted): intent vs stated purpose, "
+    "financial-capability, third-party-content-exposure, system-service classification"
+)
+
+
+def _skills(args) -> int:
+    """Scan agent skills. Local-only by construction: skills.py has no network imports at all —
+    the differentiator against agent-scan, whose client uploads raw skill content for analysis."""
+    from pathlib import Path
+
+    from .signals import as_dicts
+    from .skills import discover_skills
+
+    snaps = discover_skills(explicit_paths=[Path(p) for p in args.paths] or None)
+    total_findings = sum(len(s.findings) for s in snaps)
+
+    if args.json:
+        print(json.dumps({
+            "skills": [{
+                "name": s.name, "root": s.root, "hosts": s.hosts,
+                "description": s.description,
+                "files_scanned": len(s.files), "files_seen": s.files_seen, "capped": s.capped,
+                "findings": as_dicts(s.findings),
+            } for s in snaps],
+            "not_checked": _SKILLS_NOT_CHECKED,
+        }, indent=2))
+    else:
+        if not snaps:
+            where = "the given path(s)" if args.paths else "any supported host on this machine"
+            print(f"mcpgawk skills: no skills found under {where}.")
+        for s in snaps:
+            hosts = ", ".join(s.hosts)
+            print(f"\n  {s.name}  ({s.root}; loaded by: {hosts})")
+            scope = f"    {len(s.files)} file(s) scanned"
+            if s.capped:
+                scope += f" of {s.files_seen} seen — CAPPED, the remainder was not examined"
+            print(scope)
+            if not s.findings:
+                print("    clean under the local detectors")
+            for f in s.findings:
+                print(f"    ⚠ [{f.kind}] {f.tool}: {f.evidence}")
+        if snaps:
+            print(f"\n  {len(snaps)} skill(s), {total_findings} finding(s). "
+                  f"All analysis LOCAL — no skill content left this machine.")
+            print(f"  {_SKILLS_NOT_CHECKED}.")
+
+    return 1 if (args.fail_on_findings and total_findings) else 0
+
+
+def _baseline(args) -> int:
+    """Print what the operator has agreed to trust — the spine other pillars read.
+
+    Only approved state is exported. A sighting is not a baseline: printing the last thing seen
+    would hand verify and monitor the poisoned surface as though it were trusted, which is the
+    exact failure ADR-0012 exists to prevent.
+    """
+    from . import baseline as _baseline_mod
+
+    data = _baseline_mod.export(getattr(args, "history", None))
+    servers = data["servers"]
+
+    if args.server:
+        key = _baseline_mod.resolve(args.server, getattr(args, "history", None))
+        if key is None or key not in servers:
+            print(f"mcpgawk: nothing approved for '{args.server}'. "
+                  f"Run `mcpgawk scan`, then `mcpgawk approve {args.server}`.", file=sys.stderr)
+            return 2
+        servers = {key: servers[key]}
+        data = {**data, "servers": servers}
+
+    if args.json:
+        print(json.dumps(data, indent=2, sort_keys=True))
+        return 0
+
+    if not servers:
+        print("Nothing approved yet. Run `mcpgawk scan`, then `mcpgawk approve <server>` to set "
+              "the baseline that verify and monitor will compare against.")
+        return 0
+
+    print(f"Approved baseline — {len(servers)} server(s). "
+          f"verify and monitor compare against exactly this.\n")
+    for key in sorted(servers):
+        rec = servers[key]
+        alias = f" ({', '.join(rec['aliases'])})" if rec.get("aliases") else ""
+        print(f"  {key}{alias}")
+        print(f"    pin        {rec.get('pin') or '—'}")
+        print(f"    tools      {len(rec.get('tools') or {})}")
+        print(f"    approved   {rec.get('approved_at') or '—'}")
+    return 0
+
+
 def _approve(args) -> int:
     """`mcpgawk approve` — move the trusted baseline forward, deliberately."""
     path = history.default_path()
@@ -222,13 +352,76 @@ def _approve(args) -> int:
     return 0
 
 
+# The paid capabilities, reachable as `mcpgawk <capability>` when gawk Platform is installed.
+#
+# ONE BINARY, on purpose (2026-07-26). Two reasons, both load-bearing:
+#   1. `gawk` cannot be an executable name. It is GNU AWK — it owns /usr/bin/gawk across the
+#      Debian family and supplies /usr/bin/awk there through the alternatives system, so our own
+#      `gawk` on PATH risks breaking a machine's `awk`. Debian Policy §10.1 requires one of two
+#      colliding programs to be renamed; Homebrew's `gawk` formula is GNU awk, so the name is
+#      simply unavailable. Everyone who tried this retreated: ast-grep deprecated `sg`, fd ships
+#      as `fdfind`, bat as `batcat`.
+#   2. A second binary for the paid tier is against convention anyway. Semgrep, Snyk, GitLab and
+#      Terraform all keep ONE command and unlock with a licence/login. A separate binary is only
+#      conventional when the paid thing is a different artefact (Docker Desktop). Ours isn't — it
+#      is more analysis on the same inputs.
+#
+# They are listed in `--help` even when unavailable: a free user should be able to SEE what the
+# subscription adds without installing anything, and get one honest line if they try it.
+PLATFORM_CAPABILITIES = {
+    "verify": "run a server in a no-egress sandbox and reproduce misbehaviour",
+    "enforce": "guard a live server, call by call",
+    "monitor": "watch a server for drift after you approved it",
+    "build": "generate a server from an OpenAPI spec (in development)",
+}
+
+_PLATFORM_UNAVAILABLE = (
+    "mcpgawk {cap}: {desc}.\n"
+    "This is a gawk Platform capability and it isn't installed in this environment.\n"
+    "  £29/month, 7-day free trial — https://mcp.gawk.dev/pricing.html\n"
+    "  Already subscribed? Your purchase email has the install instructions.\n"
+    "The free scanner (`mcpgawk scan`) stays free and open-source either way."
+)
+
+
+def _run_platform_capability(capability: str, rest: list[str]) -> int:
+    """Delegate to gawk Platform if it is installed, else say so honestly and exit 3.
+
+    The import is deliberately OPTIONAL and local: the free scanner is published to PyPI on its
+    own and must never depend on, or ship, the paid engine. A paid install supersedes the free
+    distribution in place (same distribution name), which is the GitLab CE→EE shape.
+    """
+    try:
+        from gawk_platform.cli import run_pillar
+    except ImportError:
+        print(
+            _PLATFORM_UNAVAILABLE.format(capability=capability, cap=capability,
+                                         desc=PLATFORM_CAPABILITIES[capability]),
+            file=sys.stderr,
+        )
+        return 3  # the same "not licensed / not available" code every paid entry point returns
+    return run_pillar(capability, rest)
+
+
 def main(argv: list[str] | None = None) -> int:
+    # Intercept the paid capabilities BEFORE argparse: their arguments are the pillar's own, and
+    # the free parser must not try to validate them.
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if raw and raw[0] in PLATFORM_CAPABILITIES:
+        return _run_platform_capability(raw[0], raw[1:])
+
     p = build_parser()
     args = p.parse_args(argv)
 
+    if args.cmd == "baseline":
+        return _baseline(args)
+
     if args.cmd == "approve":
         return _approve(args)
 
+    if args.cmd == "skills":
+        return _skills(args)
+
     # No args at all is VALID: it means "discover and scan everything on this machine". _run handles
     # the nothing-found message and default-deny consent before launching any discovered stdio server.
     snaps, entries, skipped = asyncio.run(_run(args))

{mcpgawk-0.1.7 → mcpgawk-0.1.9}/src/mcpgawk/label.py

@@ -28,6 +28,12 @@ LABEL_SCHEMA = "mcpgawk/label@0.1"
 #: thing.
 _SIGNAL_LEAD_BY_KIND = {
     "shadowing:cross-server-reference": "cross-server tool reference from",
+    "skill:download-url": "suspicious download URL in",
+    "skill:piped-exec": "fetch-and-execute pattern in",
+    "skill:runtime-fetch": "runtime instruction fetch in",
+    "skill:credential-emission": "credential-emission instruction in",
+    "skill:secret-hardcoded": "hardcoded secret in",
+    "skill:malformed": "unreviewable skill structure in",
 }
 
 _SIGNAL_LEAD = {
@@ -38,6 +44,8 @@ _SIGNAL_LEAD = {
     # Obfuscation is its OWN class, not a flavour of injection (Invariant separates them too: W021
     # vs E001). Hiding text is evidence of intent; what it hides is reported by its own detector.
     "obfuscation": "text hidden with invisible characters in",
+    # Agent-skill findings (SKILL.md trees) — surfaced by `mcpgawk skills`, not the server scan.
+    "skill": "risky skill content in",
 }