@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-tools/clis/maggie_security_agent.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Agent security (docs/maggie-security/10-agent-security-prd.md):
+``skills-scan``, ``mcp-self-check``, ``github-alerts``.
+
+- ``skills-scan`` runs NVIDIA SkillSpector (Apache-2.0, external, Python 3.12+)
+  with ``--no-llm`` forced and its LLM provider variable removed, and maps the
+  report to findings. Maggie re-applies ``--max-risk`` from the JSON instead
+  of trusting the upstream threshold. LLM mode is not offered here: routing
+  SkillSpector through a gateway cannot lock the provider (global BYOK rule).
+- ``mcp-self-check`` reviews an MCP tool registry, an exported ``tools/list``
+  and the server config against the checks in PRD 10 section 8 (risk and
+  confirmations, annotations, hidden text and cross-tool instructions in
+  descriptions, untrusted results, clipping, transport auth, caps, audit,
+  description drift between releases).
+- ``github-alerts`` turns the person's own GitHub Dependabot, code-scanning
+  and secret-scanning alerts into findings, from a file the agent exported
+  with github-mcp-server, or directly with ``GITHUB_TOKEN`` (read-only; the
+  token is never stored). A secret alert's value is never read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import tempfile
+import unicodedata
+from pathlib import Path
+
+import maggie_security_core as core
+
+core.SOURCES.setdefault("github-api", {"hosts": ["api.github.com"], "ttl": "0s", "url": "https://api.github.com/"})
+SKILLSPECTOR_SEVERITY = {"CRITICAL": "critical", "HIGH": "high", "MEDIUM": "medium", "LOW": "low", "INFO": "info"}
+
+
+# --------------------------------------------------------------------------- skills-scan
+
+
+def skillspector_to_findings(ctx: core.Context, report: dict, target: str) -> list[dict]:
+    findings = []
+    # SkillSpector 2.x JSON: issues[] with id, category, pattern, severity, confidence, location{file, start_line}, finding, explanation, remediation.
+    for item in report.get("issues") or report.get("findings") or []:
+        confidence = float(item.get("confidence") or 0.5)
+        category = item.get("category") or "Security"
+        excerpt = core.clean_excerpt(item.get("finding") or item.get("code_snippet") or "", 200)
+        location = item.get("location") or {}
+        skill_file = location.get("file") or item.get("file") or "SKILL.md"
+        item = {**item, "rule_id": item.get("id") or item.get("rule_id"), "start_line": location.get("start_line") or item.get("start_line"),
+                "message": item.get("pattern") or item.get("message")}
+        findings.append(core.make_finding(
+            kind="agent-skill", command="skills-scan", primary_id=str(item.get("rule_id")), site=ctx.site,
+            title=f"{category}: {core.clean_excerpt(item.get('message') or item.get('rule_id'), 110)}",
+            severity=SKILLSPECTOR_SEVERITY.get(str(item.get("severity", "")).upper(), "low"), severity_source="tool",
+            confidence="confirmed" if confidence >= 0.8 else "likely" if confidence >= 0.5 else "possible",
+            asvs_ids=["V15.2.4"] if "supply" in category.lower() else [],
+            target={"path": f"{target.rstrip('/')}/{skill_file}" if not target.endswith(skill_file) else target, "url": item.get("source_url")},
+            evidence=[{"path": skill_file, "line": int(item.get("start_line") or 1), "excerpt": excerpt}],
+            tool="skillspector", rule_id=str(item.get("rule_id")),
+            remediation={"summary": core.clean_excerpt(item.get("remediation") or item.get("explanation") or "Review before installing.", 400),
+                         "steps": [], "snippets": [], "references": ["https://github.com/NVIDIA/SkillSpector"], "cheat_sheet": None},
+            untrusted={"matched": excerpt, "explanation": core.clean_excerpt(item.get("explanation") or "", 300)}))
+    return findings
+
+
+def skills_scan(ctx: core.Context):
+    args = ctx.args
+    target = args.target
+    if args.report_json:
+        report = core.read_json(Path(args.report_json))
+    else:
+        if not ("://" in target or Path(target).exists()):
+            raise core.UsageError(f"not found: {target}")
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "report.json"
+            argv = ["scan", target, "--format", "json", "--output", str(out)]
+            if args.kind == "mcp-registry":
+                argv.append("--mcp-registry")
+            if args.recursive:
+                argv.append("--recursive")
+            if args.baseline:
+                argv += ["--baseline", args.baseline]
+            env = {k: "" for k in os.environ if k.startswith("SKILLSPECTOR_PROVIDER")}
+            if not args.allow_osv:
+                env["SKILLSPECTOR_OFFLINE"] = "1"
+            proc = core.run_tool("skillspector", argv, ctx.lock, timeout=1800, env=env)
+            if proc.returncode == 2:
+                raise core.UsageError(f"SkillSpector could not read the target: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 300)}")
+            if not out.is_file():
+                raise core.DegradedError(f"SkillSpector produced no report: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 300)}")
+            report = core.read_json(out)
+        ctx.run["tools"].append({"name": "skillspector", "version": ctx.lock["tools"]["skillspector"]["version"], "sha256": None})
+    findings = skillspector_to_findings(ctx, report, target)
+    assessment = report.get("risk_assessment") or {}
+    risk = assessment.get("score", report.get("risk_score"))
+    ctx.run["inputs"]["skillspector"] = {"risk_score": risk, "risk_severity": assessment.get("severity", report.get("risk_severity")),
+                                         "recommendation": assessment.get("recommendation", report.get("risk_recommendation")), "max_risk": args.max_risk,
+                                         "completeness": (report.get("analysis_completeness") or {}).get("status")}
+    doc = ctx.finish(findings, covered=["*"])
+    if risk is not None and float(risk) > args.max_risk:
+        doc["run"]["refused"].append(f"risk score {risk} is above the limit {args.max_risk}: do not install")
+    return doc
+
+
+# --------------------------------------------------------------------------- mcp-self-check
+
+HIDDEN = re.compile("[​-‏‪-‮⁠-⁤]")
+CROSS_TOOL = re.compile(r"(?i)\b(ignore (all |any )?(previous|prior|above)|before (calling|using) any other tool|you must (always )?call|"
+                        r"do not (tell|inform) the user|<\s*(system|tool|important)\s*>|send (the|all) .* to)\b")
+
+
+def mcp_self_check(ctx: core.Context):
+    args = ctx.args
+    import maggie_security_mcp as mcp
+
+    registry_path = Path(args.registry) if args.registry else mcp.registry_path()
+    registry = core.read_json(registry_path)
+    tools = {t["name"]: t for t in registry.get("tools") or []}
+    listed = core.read_json(Path(args.mcp_tools)).get("tools") if args.mcp_tools else None
+    if listed is None and not args.registry:
+        listed = [mcp.Server(ctx.project, "all", None).describe(t) for t in mcp.Server(ctx.project, "all", None).tools.values()]
+    server_config = core.read_json(Path(args.server_config)) if args.server_config else {}
+    findings = []
+    where = str(registry_path.name)
+
+    def add(check: str, title: str, severity: str, tool: str | None = None, summary: str = "") -> None:
+        findings.append(core.make_finding(kind="agent-skill", command="mcp-self-check", primary_id=f"{check}:{tool or '-'}", site=ctx.site,
+                                          title=f"{check}: {title}", severity=severity, severity_source="maggie", confidence="confirmed",
+                                          target={"path": where}, evidence=[{"path": where, "excerpt": tool or ""}], tool="maggie", rule_id=check,
+                                          remediation={"summary": summary or title, "steps": [], "snippets": [],
+                                                       "references": ["https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html"],
+                                                       "cheat_sheet": "MCP Security"}))
+
+    from maggie_assistant_tools import validate_registry
+
+    validation = validate_registry(registry)
+    for error in validation["errors"]:
+        add("MCP-01", f"registry: {error}", "high")
+    for name, tool in tools.items():
+        if tool.get("risk") not in ("read", "never") and not (tool.get("user") or {}).get("confirm"):
+            add("MCP-01", f"write tool {name} has no approval sentence (user.confirm)", "high", name)
+        text = tool.get("description", "") + " " + json.dumps(tool.get("user") or {})
+        if HIDDEN.search(text) or any(unicodedata.category(ch) == "Cf" for ch in text):
+            add("MCP-07", f"{name} has hidden or bidirectional control characters in its text", "high", name)
+        if CROSS_TOOL.search(tool.get("description", "")):
+            add("MCP-07", f"{name}'s description contains instructions aimed at the model or other tools", "high", name)
+        for url in re.findall(r"https?://([^/\s\"']+)", tool.get("description", "")):
+            if url not in (args.allow_host or []):
+                add("MCP-07", f"{name}'s description links to {url}", "medium", name, "Keep links out of model-facing descriptions, or allowlist the host.")
+        if re.search(r"(?i)(advisor|log|page|feed|third-party|skill)", tool.get("description", "")) and tool.get("risk") == "read" \
+                and "untrusted" not in tool.get("description", "").lower() and not tool.get("untrusted") and name in ("security_findings_list", "security_finding_get"):
+            add("MCP-09", f"{name} returns third-party text without saying it is untrusted", "high", name)
+    if listed is not None:
+        listed_names = {t["name"] for t in listed}
+        for name, tool in tools.items():
+            if tool.get("risk") == "never" and name in listed_names:
+                add("MCP-03", f"'never' tool {name} is exposed over MCP", "critical", name)
+        for entry in listed:
+            tool = tools.get(entry["name"])
+            if not tool:
+                add("MCP-08", f"{entry['name']} is served but not in the registry", "high", entry["name"])
+                continue
+            hints = entry.get("annotations") or {}
+            if tool.get("risk") == "read" and hints.get("readOnlyHint") is not True:
+                add("MCP-02", f"{entry['name']} is a read tool without readOnlyHint", "high", entry["name"])
+            if tool.get("risk") != "read" and hints.get("readOnlyHint"):
+                add("MCP-02", f"{entry['name']} writes but claims readOnlyHint", "high", entry["name"])
+            if tool.get("risk") in ("write-public", "never") and not hints.get("destructiveHint"):
+                add("MCP-02", f"{entry['name']} is a public/irreversible write without destructiveHint", "high", entry["name"])
+            schema = entry.get("inputSchema") or {}
+            if schema.get("additionalProperties") is not False:
+                add("MCP-05", f"{entry['name']} accepts arbitrary extra arguments (additionalProperties is not false)", "medium", entry["name"])
+            if tool.get("risk") != "read" and "confirm" not in (schema.get("properties") or {}):
+                add("MCP-06", f"write tool {entry['name']} has no preview → confirm step", "high", entry["name"])
+    if args.previous:
+        previous = {t["name"]: t for t in core.read_json(Path(args.previous)).get("tools") or []}
+        for entry in listed or []:
+            before = previous.get(entry["name"])
+            if before and (before.get("description") != entry.get("description") or before.get("inputSchema") != entry.get("inputSchema")):
+                add("MCP-08", f"{entry['name']} changed its description or input schema since the previous release: review it", "medium", entry["name"])
+    for server in registry.get("mcpServers") or []:
+        if server.get("auth") == "none":
+            writes = [n for n, t in tools.items() if server.get("name") in (t.get("mcpServers") or []) and t.get("risk") != "read"]
+            if writes:
+                add("MCP-04", f"public server {server.get('name')} exposes write tools: {', '.join(writes)}", "critical")
+    transport = server_config.get("transport")
+    if transport == "http":
+        if not server_config.get("auth"):
+            bind = str(server_config.get("bind", "0.0.0.0"))
+            if not bind.startswith(("127.", "localhost", "::1")):
+                add("MCP-11", f"HTTP transport without auth listens on {bind}", "critical")
+        if server_config.get("token_in_query"):
+            add("MCP-11", "access tokens are accepted in the URL query string", "critical")
+    writes = [n for n, t in tools.items() if t.get("risk") not in ("read", "never")]
+    unattended = registry.get("unattended") or {}
+    if writes and not unattended and any("routine" in (t.get("description") or "").lower() for t in tools.values()):
+        add("MCP-12", "tools meant for scheduled agents have no server-side daily caps (unattended)", "medium")
+    if writes and not any((t.get("audit") or {}) for t in tools.values() if t.get("risk") not in ("read", "never")) and args.require_audit:
+        add("MCP-13", "write tools declare no audit settings", "medium")
+    evals = core.ROOT / "skills" / "maggie-security" / "evals" / "evals.json"
+    if args.registry is None and evals.is_file() and "security_ledger_mark" not in evals.read_text():
+        add("MCP-15", "no prompt-injection case in the tool-selection evals", "low")
+    ctx.run["inputs"].update({"registry": str(registry_path), "tools": len(tools), "listed": len(listed or []), "checks": "MCP-01..MCP-15"})
+    return ctx.finish(findings, covered=["*"])
+
+
+# --------------------------------------------------------------------------- github-alerts
+
+
+def github_alert_to_finding(ctx: core.Context, alert: dict, repo: str) -> dict | None:
+    state = alert.get("state")
+    url = alert.get("html_url")
+    if "security_advisory" in alert or "dependency" in alert:
+        advisory = alert.get("security_advisory") or {}
+        vuln = alert.get("security_vulnerability") or {}
+        package = (alert.get("dependency") or {}).get("package") or vuln.get("package") or {}
+        first = (vuln.get("first_patched_version") or {}).get("identifier")
+        cvss = advisory.get("cvss") or {}
+        aliases = [i.get("value") for i in advisory.get("identifiers") or [] if i.get("value")] or [advisory.get("ghsa_id")]
+        return core.make_finding(
+            kind="vulnerability", command="github-alerts", primary_id=advisory.get("cve_id") or advisory.get("ghsa_id") or str(alert.get("number")), site=ctx.site,
+            title=f"{package.get('name')}: {core.clean_excerpt(advisory.get('summary') or advisory.get('ghsa_id') or 'Dependabot alert', 150)}",
+            severity={"critical": "critical", "high": "high", "medium": "medium", "moderate": "medium", "low": "low"}.get(str(advisory.get("severity")).lower(), "medium"),
+            severity_source="vendor", cvss={"version": "3.1", "score": float(cvss["score"]), "vector": cvss.get("vector_string") or ""} if cvss.get("score") else None,
+            confidence="likely", aliases=[a for a in aliases if a],
+            affected={"purl": core.make_purl(package.get("ecosystem", ""), package.get("name", "")), "ecosystem": package.get("ecosystem"),
+                      "name": package.get("name") or "", "version": None, "component_type": "library", "direct": None, "scope": "runtime"},
+            fix={"fixed_versions": [first] if first else [], "recommended": first, "available": bool(first)},
+            target={"path": (alert.get("dependency") or {}).get("manifest_path"), "url": url}, feed="github", rule_id=advisory.get("ghsa_id"),
+            remediation={"summary": f"Update {package.get('name')} to {first} or later." if first else "No patched version yet.", "steps": [], "snippets": [],
+                         "references": [url] if url else [], "cheat_sheet": None}), state
+    if "rule" in alert:
+        rule = alert.get("rule") or {}
+        instance = alert.get("most_recent_instance") or {}
+        location = instance.get("location") or {}
+        return core.make_finding(
+            kind="code", command="github-alerts", primary_id=str(rule.get("id")), site=ctx.site,
+            title=f"{rule.get('description') or rule.get('id')} ({location.get('path')})"[:300],
+            severity={"critical": "critical", "high": "high", "medium": "medium", "low": "low"}.get(str(rule.get("security_severity_level")).lower(), "medium"),
+            severity_source="tool", confidence="likely", target={"path": location.get("path"), "url": url},
+            evidence=[{"path": location.get("path") or "", "line": location.get("start_line") or 1}], feed="github", rule_id=str(rule.get("id")),
+            tool=(alert.get("tool") or {}).get("name"),
+            remediation={"summary": "See the code scanning alert.", "steps": [], "snippets": [], "references": [url] if url else [], "cheat_sheet": None}), state
+    if "secret_type" in alert:
+        return core.make_finding(
+            kind="secret", command="github-alerts", primary_id=f"gh-secret-{alert.get('number')}", site=ctx.site,
+            title=f"GitHub found a {alert.get('secret_type_display_name') or alert.get('secret_type')} in {repo}", severity="high", severity_source="vendor",
+            confidence="confirmed", target={"url": url, "path": repo}, feed="github", rule_id=str(alert.get("secret_type")),
+            remediation={"summary": "Revoke the secret with its provider first, then close the alert.", "steps": [], "snippets": [],
+                         "references": [url] if url else [], "cheat_sheet": None}), state
+    return None
+
+
+def github_alerts(ctx: core.Context):
+    args = ctx.args
+    alerts: list[tuple[str, dict]] = []
+    if args.from_file:
+        data = core.read_json(Path(args.from_file))
+        items = data if isinstance(data, list) else data.get("alerts") or data.get("items") or []
+        alerts = [(args.repo[0] if args.repo else "repo", a) for a in items]
+    else:
+        token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+        if not token:
+            raise core.PolicyError("direct mode needs your own GITHUB_TOKEN in the environment (read: Dependabot alerts, security_events); "
+                                   "or export alerts with github-mcp-server and pass --from-file")
+        if not args.repo:
+            raise core.UsageError("give --repo OWNER/NAME")
+        for repo in args.repo:
+            for kind in (args.include or "dependabot,code-scanning,secret-scanning").split(","):
+                url = f"https://api.github.com/repos/{repo}/{kind}/alerts?state={args.state}&per_page=100"
+                ctx.guard.check("github-api", url)
+                try:
+                    status, _h, body = core.http_request(url, headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json",
+                                                                       "X-GitHub-Api-Version": "2022-11-28"}, timeout=30, retries=1)
+                except core.DegradedError as error:
+                    ctx.degrade(f"github-{kind}", str(error))
+                    continue
+                if status in (403, 404):
+                    ctx.degrade(f"github-{kind}", f"HTTP {status}: not available on this plan or token scope (not the same as clean)")
+                    continue
+                alerts += [(repo, a) for a in json.loads(body.decode() or "[]")]
+    findings = []
+    for repo, alert in alerts:
+        converted = github_alert_to_finding(ctx, alert, repo)
+        if not converted:
+            continue
+        finding, state = converted
+        if state not in (None, "open"):
+            continue
+        findings.append(finding)
+    ctx.run["inputs"].update({"repos": args.repo, "alerts": len(alerts), "mode": "file" if args.from_file else "direct"})
+    return ctx.finish(findings, covered=["*"] if not ctx.run["degraded"] else [])
+
+
+def _skills(p: argparse.ArgumentParser) -> None:
+    p.add_argument("target", help="skill folder, SKILL.md, .zip, git URL, or MCP registry JSON/URL")
+    p.add_argument("--kind", choices=["skill", "mcp-registry"], default="skill")
+    p.add_argument("--max-risk", type=float, default=50.0)
+    p.add_argument("--recursive", action="store_true")
+    p.add_argument("--baseline")
+    p.add_argument("--allow-osv", action="store_true", help="let SkillSpector look up dependency CVEs on osv.dev")
+    p.add_argument("--report-json", help="parse a saved SkillSpector JSON report")
+
+
+def _mcp(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--registry", help="maggie-assistant-tool-registry.v1 file (default: Maggie Security's own)")
+    p.add_argument("--mcp-tools", help="exported tools/list JSON from the running server")
+    p.add_argument("--server-config", help="transport/auth settings JSON")
+    p.add_argument("--previous", help="the previous release's tools/list export (description drift)")
+    p.add_argument("--allow-host", action="append", help="host allowed in descriptions")
+    p.add_argument("--require-audit", action="store_true")
+
+
+def _github(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--repo", action="append")
+    p.add_argument("--state", default="open")
+    p.add_argument("--include", help="dependabot,code-scanning,secret-scanning")
+    p.add_argument("--from-file", help="alerts exported by github-mcp-server (list_*_alerts)")
+
+
+COMMANDS = [
+    core.Command("skills-scan", "check an agent skill or MCP server before installing it (SkillSpector, no LLM)", ["osv-api"], _skills, skills_scan),
+    core.Command("mcp-self-check", "review an MCP tool registry and server settings against the OWASP MCP checks", [], _mcp, mcp_self_check),
+    core.Command("github-alerts", "your GitHub Dependabot, code-scanning and secret-scanning alerts as findings (your own token or an export)",
+                 ["github-api"], _github, github_alerts),
+]