@topy-ai/maggie 0.7.61 → 0.8.0

package/bundled-tools/clis/maggie_security.py

@@ -31,7 +31,7 @@ import maggie_security_core as core  # noqa: E402
 AREA_MODULES = [
     "maggie_security_intel", "maggie_security_deps", "maggie_security_code", "maggie_security_web",
     "maggie_security_protect", "maggie_security_logs", "maggie_security_host", "maggie_security_health",
-    "maggie_security_standards", "maggie_security_agent", "maggie_security_report", "maggie_security_mcp", "maggie_security_hosted",
+    "maggie_security_standards", "maggie_security_agent", "maggie_security_report", "maggie_security_scan", "maggie_security_mcp", "maggie_security_hosted",
 ]
 
 # Commands from the PRDs that are not built yet, with their milestone, so the

package/bundled-tools/clis/maggie_security_code.py

@@ -535,6 +535,53 @@ def semgrep_to_findings(ctx: core.Context, data: dict, project: Path) -> list[di
     return findings
 
 
+# Bearer-inspired privacy lens (Bearer itself is Elastic-licensed and cannot be run
+# or bundled, so its detection *patterns* are reimplemented as native rules): flag a
+# log/print call that puts personal data in the output — a GDPR hazard (CWE-532).
+PII_LOG_CALL = re.compile(
+    r"(?i)(console\.(log|info|warn|error|debug)|[^\w.](print|println|printf)\s*\(|fmt\.(Print|Printf|Println|Sprintf)|"
+    r"System\.out\.print|var_dump|print_r|error_log|\b(logger|log|logging|logr|slog|console)\s*\.\s*"
+    r"(info|debug|warn|warning|error|trace|notice|log)\b)")
+PII_TOKEN = re.compile(
+    r"(?i)\b(e[-_]?mail(?:address|_address)?|ssn|social[_\s-]?security|passport(?:[_\s-]?(?:no|number))?|"
+    r"credit[_\s-]?card|card[_\s-]?number|cardnum|cvv|cvc|iban|phone[_\s-]?number|date[_\s-]?of[_\s-]?birth|"
+    r"\bdob\b|national[_\s-]?id|tax[_\s-]?id|driver'?s?[_\s-]?licen[cs]e)\b")
+PII_SOURCE_EXT = re.compile(r"(?i)\.(js|jsx|ts|tsx|mjs|cjs|py|php|rb|go|java|kt|cs|scala|swift|rs|vue|svelte|ex|exs)$")
+
+
+def native_pii_checks(ctx: core.Context, files: list[Path], project: Path) -> list[dict]:
+    """Logging of personal data (GDPR / CWE-532) — one finding per file, lines as evidence."""
+    findings = []
+    for path in files:
+        if not PII_SOURCE_EXT.search(path.name):
+            continue
+        text = read_text(path)
+        if not text:
+            continue
+        hits = []
+        for number, line in enumerate(text.splitlines(), 1):
+            if len(line) > 400:
+                continue
+            if PII_LOG_CALL.search(line) and PII_TOKEN.search(line):
+                hits.append((number, line.strip()[:200]))
+            if len(hits) >= 10:
+                break
+        if not hits:
+            continue
+        rel = path.relative_to(project).as_posix()
+        findings.append(core.make_finding(
+            kind="code", command="code-scan", primary_id="maggie.privacy.pii-in-logs", site=ctx.site,
+            title=f"Personal data may be written to logs ({rel})", severity="low", severity_source="maggie",
+            confidence="possible", cwe_ids=["CWE-532"], asvs_ids=["V7.1.1"], target={"path": rel}, tool="maggie-native",
+            rule_id="maggie.privacy.pii-in-logs",
+            evidence=[{"path": rel, "line": n, "excerpt": core.clean_excerpt(ln, 200)} for n, ln in hits[:5]],
+            remediation={"summary": "Avoid logging personal data (email, SSN, card, phone, DOB…). Redact or omit it, or log an opaque id instead. "
+                         "Logs are often shipped to third parties and retained — this is a GDPR exposure.",
+                         "steps": [], "snippets": [], "references": ["https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html"],
+                         "cheat_sheet": "Logging"}))
+    return findings
+
+
 def native_config_checks(ctx: core.Context, files: list[Path], project: Path) -> list[dict]:
     """Two checks semgrep expresses poorly: Dockerfile final stage without USER, nginx serving dotfiles."""
     findings = []
@@ -598,7 +645,8 @@ def code_scan(ctx: core.Context):
     else:
         targets = [str(project / p) for p in (args.paths or ["."])]
     files = [Path(t) for t in targets if Path(t).is_file()] + [f for t in targets if Path(t).is_dir() for f in text_files(Path(t), project)]
-    findings = native_config_checks(ctx, [f for f in files if not any(part in SKIP_DIRS for part in f.relative_to(project).parts)], project)
+    in_scope = [f for f in files if not any(part in SKIP_DIRS for part in f.relative_to(project).parts)]
+    findings = native_config_checks(ctx, in_scope, project) + native_pii_checks(ctx, in_scope, project)
     with tempfile.TemporaryDirectory() as tmp:
         out = Path(tmp) / "semgrep.json"
         argv = ["scan", "--json", "--json-output", str(out), "--timeout", "30", "--max-target-bytes", "1000000", "--quiet"]

package/bundled-tools/clis/maggie_security_deps.py

@@ -361,6 +361,99 @@ def image(ctx: core.Context):
     return ctx.finish(findings, covered=[f"image:{ref}"])
 
 
+# --------------------------------------------------------------------------- image-patch (copa remediation plan)
+
+# image-patch completes the safe-patching story for containers: `image` detects the
+# CVEs, image-patch turns a Trivy report into a reviewed copa command that rebuilds
+# the image with the OS-package fixes applied — into a NEW tag, so the original is
+# untouched. Plan only (like fix-plan/protect-plan): Maggie never runs copa; the
+# operator reviews it and runs it where Docker/buildkit is available.
+
+
+def _patched_tag(ref: str, override: str | None) -> str:
+    if override:
+        return override
+    name, _, _tag = ref.rpartition(":")
+    return f"{name}:patched" if name and "/" not in _tag else f"{ref}-patched"
+
+
+def image_patch(ctx: core.Context) -> dict:
+    import shlex
+
+    args = ctx.args
+    ref = args.ref
+    tag = _patched_tag(ref, args.tag)
+    pkg_types = args.pkg_types
+    report = args.report or "scan.json"
+
+    fixable = total = None
+    if args.report:
+        data = core.read_json(Path(args.report))
+        fixed_ids, all_ids = set(), set()
+        for result in data.get("Results") or []:
+            for vuln in result.get("Vulnerabilities") or []:
+                vid = vuln.get("VulnerabilityID")
+                all_ids.add(vid)
+                if vuln.get("FixedVersion"):
+                    fixed_ids.add(vid)
+        fixable, total = len(fixed_ids), len(all_ids)
+
+    scan_cmd = f"trivy image --quiet --scanners vuln --pkg-types os --format json -o {shlex.quote(report)} {shlex.quote(ref)}"
+    patch_cmd = f"copa patch -i {shlex.quote(ref)} -r {shlex.quote(report)} --pkg-types {pkg_types} -t {shlex.quote(tag)}"
+    verify_cmd = f"trivy image --quiet {shlex.quote(tag)}"
+
+    sh = [
+        "#!/usr/bin/env bash",
+        f"# Container patch plan for {ref} — generated {core.iso()[:10]} by maggie security image-patch.",
+        "# REVIEW BEFORE RUNNING. Maggie did not and will not run any of this.",
+        "# copa rebuilds the image with OS-package fixes into a NEW tag; the original image is untouched.",
+        "# Prerequisites: copa (maggie security tools install --tool copa) and a running Docker/buildkit.",
+        "set -euo pipefail",
+        "",
+        "# 1. Scan the image to a report copa can read:" if not args.report else f"# 1. Using the provided report {report}.",
+    ]
+    if not args.report:
+        sh.append(scan_cmd)
+    sh += [
+        "# 2. Patch OS packages into a new tag (original image untouched):",
+        patch_cmd,
+        "# 3. Re-scan the patched image to confirm the fixes, then test it before you deploy:",
+        verify_cmd,
+        "",
+    ]
+    script = "\n".join(sh).rstrip() + "\n"
+    if args.script:
+        path = Path(args.script)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(script, encoding="utf-8")
+        path.chmod(0o755)
+
+    md = [f"# Container patch plan — {ref}", "",
+          "**Review before running — Maggie never runs copa.** copa rebuilds the image with OS-package "
+          "fixes into a **new tag** (`" + tag + "`); the original image is untouched. Needs Docker/buildkit.", ""]
+    if fixable is not None:
+        md.append(f"The report lists **{fixable} fixable** OS-package CVE(s)" + (f" of {total} total." if total else ".") + "")
+        md.append("")
+    md += ["```bash", (scan_cmd + "\n" if not args.report else "") + patch_cmd + "\n" + verify_cmd, "```", "",
+           "After patching: re-scan with `maggie security image --ref " + tag + "` and test the image before deploying."]
+    runbook = "\n".join(md)
+
+    return {"schema": "maggie-security-image-patch.v1", "ref": ref, "patched_tag": tag, "pkg_types": pkg_types,
+            "fixable": fixable, "total": total, "commands": {"scan": scan_cmd, "patch": patch_cmd, "verify": verify_cmd},
+            "script_path": str(args.script) if args.script else None,
+            "note": "Plan only. Maggie never runs copa; it rebuilds into a new tag, leaving the original image untouched.",
+            "markdown": runbook}
+
+
+def _image_patch(p: argparse.ArgumentParser) -> None:
+    p.add_argument("ref", help="the image to patch, e.g. myapp:1.0")
+    p.add_argument("--report", help="a Trivy JSON report for the image (else the plan generates one with trivy)")
+    p.add_argument("--tag", help="output tag for the patched image (default <ref>-patched)")
+    p.add_argument("--pkg-types", choices=["os", "os,library"], default="os", dest="pkg_types",
+                   help="os (default) or os,library to also patch application dependencies")
+    p.add_argument("--script", help="write the runnable plan to this path (chmod 755)")
+
+
 # --------------------------------------------------------------------------- preinstall (vet a package before installing it)
 
 
@@ -554,6 +647,8 @@ COMMANDS = [core.Command("deps", "known vulnerabilities in dependencies (every l
                          ["osv-api", "retire-jsrepo", "kev", "epss"], configure, deps),
             core.Command("sbom", "CycloneDX SBOM of the project (or an image with syft)", [], _sbom, sbom, findings=False),
             core.Command("image", "container image vulnerabilities, secrets and best practices (trivy + dockle)", ["kev", "github-releases"], _image, image),
+            core.Command("image-patch", "a reviewed copa plan to rebuild a container image with OS-package fixes into a new tag; never applied by Maggie",
+                         [], _image_patch, image_patch, findings=False, routine_safe=False),
             core.Command("preinstall", "vet an npm package before installing it (age, install scripts, typosquats, malware, vulnerabilities, Scorecard)",
                          ["npm-registry", "osv-api", "scorecard", "kev", "epss"], _preinstall, preinstall, findings=False),
             core.Command("exposure-check", "known malicious packages already installed (OSV MAL- records and incident catalogs)", ["osv-api", "kev"],

package/bundled-tools/clis/maggie_security_mcp.py

@@ -95,11 +95,29 @@ SCHEMAS: dict[str, dict] = {
         "id": {"type": "string", "pattern": r"^msf_[0-9a-f]{24}$"}, "action": {"enum": ["accept", "false-positive", "reopen"]},
         "reason": {"type": "string", "maxLength": 300}, "until": {"type": "string", "pattern": r"^\d{4}-\d{2}-\d{2}$"},
         "confirm": {"type": "boolean"}, "confirmation": {"type": "string", "maxLength": 80}}},
+    "security_image_patch": {"type": "object", "required": ["ref"], "additionalProperties": False, "properties": {
+        "ref": {"type": "string", "pattern": r"^[a-z0-9][a-z0-9._/:-]*$", "description": "the image to patch, e.g. myapp:1.0"},
+        "report": {"type": "string", "maxLength": 300, "description": "a Trivy JSON report inside the project"},
+        "tag": {"type": "string", "maxLength": 200}, "pkg_types": {"enum": ["os", "os,library"]}}},
+    "security_scan": {"type": "object", "additionalProperties": False, "properties": {
+        "profile": {"type": "string", "maxLength": 20, "description": "override the detected site profile, e.g. wordpress, node-app"},
+        "domain": {"type": "string", "pattern": DOMAIN, "description": "verified domain for the web checks (headers, tls)"},
+        "kind": {"enum": ["weekly", "daily_ops"]}, "fix_plan": {"type": "boolean"}}},
+    "security_node_check": {"type": "object", "additionalProperties": False, "properties": {
+        "node_version": {"type": "string", "pattern": r"^\d+(\.\d+){0,2}$", "description": "Node.js version (default: the versions in the inventory)"}}},
+    "security_fix_plan": {"type": "object", "additionalProperties": False, "properties": {
+        "priority": {"enum": ["p0", "p1", "p2", "p3", "p4"], "description": "only include findings at or above this priority"},
+        "since": SINCE}},
+    "security_incident": {"type": "object", "required": ["action"], "additionalProperties": False, "properties": {
+        "action": {"enum": ["start", "log", "close"]}, "id": {"type": "string", "maxLength": 80},
+        "title": {"type": "string", "maxLength": 200}, "cve": {"type": "string", "maxLength": 40},
+        "finding": {"type": "string", "pattern": r"^msf_[0-9a-f]{24}$"}, "event": {"type": "string", "maxLength": 40},
+        "note": {"type": "string", "maxLength": 300}, "confirm": {"type": "boolean"}, "confirmation": {"type": "string", "maxLength": 80}}},
 }
 NETWORK_TOOLS = {"security_vuln_watch", "security_osv_query", "security_wp_check", "security_eol_check", "security_deps_scan",
                  "security_domain_verify_check", "security_headers_check", "security_tls_check", "security_web_scan", "security_public_check",
                  "security_uptime_status",
-                 "security_checklist_get", "security_package_vet", "security_exposure_check", "security_image_scan"}
+                 "security_checklist_get", "security_package_vet", "security_exposure_check", "security_image_scan", "security_node_check", "security_scan"}
 
 
 def registry_path() -> Path:
@@ -269,6 +287,54 @@ class Server:
             return ["image", args.get("ref", "x")]
         if name == "security_sbom_build":
             return ["sbom"]
+        if name == "security_image_patch":
+            argv = ["image-patch"]
+            if dry:
+                return argv
+            argv.append(args["ref"])
+            if args.get("report"):
+                argv += ["--report", self.safe_log_path(args["report"])]
+            if args.get("tag"):
+                argv += ["--tag", args["tag"]]
+            if args.get("pkg_types"):
+                argv += ["--pkg-types", args["pkg_types"]]
+            return argv
+        if name == "security_scan":
+            argv = ["scan"]
+            if dry:
+                return argv
+            if args.get("profile"):
+                argv += ["--profile", args["profile"]]
+            if args.get("domain"):
+                argv += ["--domain", args["domain"]]
+            if args.get("kind"):
+                argv += ["--kind", args["kind"]]
+            if args.get("fix_plan"):
+                argv += ["--fix-plan"]
+            return argv
+        if name == "security_node_check":
+            argv = ["node-check"]
+            if not dry and args.get("node_version"):
+                argv += ["--node-version", args["node_version"]]
+            return argv
+        if name == "security_fix_plan":
+            argv = ["fix-plan"]
+            if dry:
+                return argv
+            if args.get("priority"):
+                argv += ["--priority", args["priority"]]
+            if args.get("since"):
+                argv += ["--since", args["since"]]
+            return argv
+        if name == "security_incident":
+            if dry:
+                return ["incident"]
+            argv = ["incident", args["action"]]
+            for key, flag in (("id", "--id"), ("title", "--title"), ("cve", "--cve"), ("finding", "--finding"),
+                              ("event", "--event"), ("note", "--note")):
+                if args.get(key):
+                    argv += [flag, args[key]]
+            return argv
         if name == "security_report_build":
             return ["report", "--kind", args.get("kind", "weekly"), "--audience", args.get("audience", "owner")]
         if name == "security_ledger_mark":

package/bundled-tools/clis/maggie_security_report.py

@@ -161,6 +161,32 @@ def why(finding: dict) -> str:
     return f"{severity} known flaw (CVE) affects the version you run."
 
 
+# SSVC (CISA Stakeholder-Specific Vulnerability Categorization) gives each finding a
+# defensible "do it now vs watch it" decision from signals we already have, rather
+# than a bare severity number. A faithful simplification of the deployer tree:
+# Exploitation (KEV→active, EPSS→likely) × Automatable (EPSS/critical) × Impact (severity).
+SSVC_HELP = {"Act": "fix now", "Attend": "fix soon (this cycle)", "Track*": "watch closely", "Track": "routine"}
+
+
+def ssvc_decision(finding: dict) -> dict:
+    kev = bool((finding.get("kev") or {}).get("listed"))
+    epss = (finding.get("epss") or {}).get("score") or 0
+    severity = finding.get("severity", "medium")
+    exploitation = "active" if kev else ("likely" if epss >= 0.1 else "none")
+    high_impact = severity in ("critical", "high")
+    automatable = epss >= 0.1 or severity == "critical"
+    if exploitation == "active":
+        decision = "Act" if high_impact else "Attend"
+    elif automatable and high_impact:
+        decision = "Attend"
+    elif high_impact or automatable:
+        decision = "Track*"
+    else:
+        decision = "Track"
+    return {"decision": decision, "exploitation": exploitation,
+            "automatable": bool(automatable), "impact": "high" if high_impact else "partial"}
+
+
 def how(finding: dict) -> str:
     steps = (finding.get("remediation") or {}).get("steps") or []
     step = next((s for s in steps if not s.startswith("Listed by CISA")), None)
@@ -298,7 +324,8 @@ def build(ctx: core.Context) -> dict:
         "verdict": verdict_info,
         "counts": {"new": sum(1 for f in findings if f["status"] == "new"), "open": sum(1 for f in findings if f["status"] == "open"),
                    "fixed": len(fixed_ids), "by_priority": {p: sum(1 for f in actionable if f["priority"] == p) for p in core.PRIORITIES}},
-        "actions": [{"finding_id": a["ids"][0], "finding_ids": a["ids"], "priority": a["priority"], "title": a["title"]}
+        "actions": [{"finding_id": a["ids"][0], "finding_ids": a["ids"], "priority": a["priority"], "title": a["title"],
+                     "ssvc": ssvc_decision(a["lead"])["decision"]}
                     for a in group_actions(actions)[:5]],
         "coverage": None,
         "checked": checked, "not_checked": missing, "degraded_sources": degraded,
@@ -401,10 +428,12 @@ def render(data: dict, findings: list[dict], audience: str, site: str, clip: boo
         lines.append(f"   How: {action['how']}")
         if not owner:
             lead = action["lead"]
+            ssvc = ssvc_decision(lead)
             lines.append(f"   {action['count']} finding(s): " + ", ".join(f"`{i}`" for i in action["ids"][:6])
                          + (" …" if len(action["ids"]) > 6 else "") + f" · {', '.join((lead.get('aliases') or [])[:3])}"
                          + (f" · CVSS {lead['cvss']['score']}" if lead.get("cvss") else "")
-                         + (f" · EPSS {lead['epss']['score']:.2f}" if lead.get("epss") else ""))
+                         + (f" · EPSS {lead['epss']['score']:.2f}" if lead.get("epss") else "")
+                         + f" · SSVC {ssvc['decision']} ({SSVC_HELP[ssvc['decision']]})")
     if len(urgent_actions) > 5:
         lines.append(f"\n…and {len(urgent_actions) - 5} more below.")
     lines.append("")

package/bundled-tools/clis/maggie_security_scan.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""``maggie security scan`` — one command that runs the right detectors for the
+site's profile and then builds a report.
+
+The suite has many focused detectors; chaining them by hand (vuln-watch → deps →
+secrets → headers → tls → host-quick → … → report) is the main source of workflow
+friction, and it is what a scheduled routine or an MCP agent would otherwise have
+to script. ``scan`` reads the profile (from the inventory, or ``--profile``), runs
+exactly the detectors that profile expects, and finishes with a report — each
+detector in its own process, best-effort, so one that degrades or refuses does not
+abort the scan. It never does anything the individual commands would not: web
+checks still need a verified domain, host checks still need ``--ssh`` consent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_report as report
+
+CLI = Path(__file__).resolve().parent / "maggie_security.py"
+
+# Detectors that need a target beyond the project tree.
+WEB = {"headers", "tls", "web-scan"}                       # need a verified domain
+HOST = {"host-quick", "host-nginx-config", "host-impact"}  # need --ssh ALIAS=user@host
+# Interactive / heavy / uncontrolled-target commands are never auto-run by scan.
+NEVER_AUTORUN = {"logs-remote", "host-audit", "zap-baseline", "public-check", "web-scan", "hosted-job"}
+# Project detectors worth running for any profile even if EXPECTED omits them.
+ALWAYS = ["secrets", "code-scan"]
+
+
+def _argv_for(command: str, args: argparse.Namespace) -> tuple[list[str] | None, str | None]:
+    """The sub-command argv for this scan, or (None, reason) to skip it."""
+    if command in WEB:
+        if not args.domain:
+            return None, "needs a verified domain (pass --domain)"
+        return [command, "--domain", args.domain], None
+    if command in HOST:
+        if not args.ssh:
+            return None, "needs a server (pass --ssh ALIAS=user@host)"
+        return [command, "--ssh", args.ssh], None
+    return [command], None
+
+
+def _findings_count(data: dict) -> int | None:
+    summary = (data or {}).get("summary") or {}
+    if not summary:
+        return None
+    return int(summary.get("new", 0)) + int(summary.get("open", 0))
+
+
+def scan(ctx: core.Context) -> dict:
+    args = ctx.args
+    project = ctx.project
+    import maggie_security as dispatch
+
+    built = set(dispatch.area_commands())
+
+    def run_cmd(argv: list[str]) -> tuple[int, dict, str]:
+        full = [sys.executable, str(CLI), *argv, "--project", str(project), "--format", "json", "--max-items", "200"]
+        if args.offline:
+            full.append("--offline")
+        proc = subprocess.run(full, capture_output=True, text=True, timeout=1800, check=False)
+        try:
+            data = json.loads(proc.stdout) if proc.stdout.strip() else {}
+        except ValueError:
+            data = {}
+        return proc.returncode, (data if isinstance(data, dict) else {}), proc.stderr
+
+    steps: list[dict] = []
+    skipped: list[dict] = []
+
+    # 1. Inventory first, so the profile and every later detector see the same stack.
+    code, data, _ = run_cmd(["inventory"])
+    steps.append({"command": "inventory", "exit": code, "degraded": bool(data.get("degraded"))})
+
+    # 2. Decide the profile.
+    stack_path = ctx.state.path("inventory", "stack.json")
+    profile = args.profile
+    if not profile:
+        if stack_path.is_file():
+            profile = (core.read_json(stack_path).get("site") or {}).get("type") or "unknown"
+        else:
+            profile = core.detect_site_type(project)
+
+    # 3. Build the ordered detector plan from the profile, plus the always-useful ones.
+    plan: list[str] = []
+    for command in list(report.EXPECTED.get(profile, report.EXPECTED["unknown"])) + ALWAYS:
+        if command in built and command not in NEVER_AUTORUN and command not in plan:
+            plan.append(command)
+
+    # 4. Run each detector, best-effort.
+    for command in plan:
+        argv, reason = _argv_for(command, args)
+        if argv is None:
+            skipped.append({"command": command, "reason": reason})
+            continue
+        code, data, _ = run_cmd(argv)
+        steps.append({"command": command, "exit": code, "degraded": bool(data.get("degraded")),
+                      "findings": _findings_count(data),
+                      "refused": code in (core.EXIT_USAGE, core.EXIT_POLICY, core.EXIT_TOOL)})
+
+    # 5. Report (and optionally a fix-plan).
+    rcode, rdata, _ = run_cmd(["report"] + (["--kind", args.kind] if args.kind else []))
+    verdict = ((rdata.get("report") or {}).get("verdict") or {}) if rdata else {}
+    out: dict = {
+        "schema": "maggie-security-scan.v1", "site": ctx.site, "profile": profile,
+        "ran": [s["command"] for s in steps], "skipped": skipped, "steps": steps,
+        "degraded": [s["command"] for s in steps if s.get("degraded")],
+        "verdict": verdict, "report": rdata.get("report") if rdata else None,
+    }
+    if args.fix_plan:
+        _c, fdata, _e = run_cmd(["fix-plan"])
+        out["fix_plan"] = {"actions": fdata.get("actions"), "tiers": fdata.get("tiers")} if fdata else None
+
+    out["markdown"] = render_scan(out, rdata.get("markdown") if rdata else None)
+    # exit code: actionable report -> 1; else degraded -> 3; else 0
+    if verdict.get("code") in ("act-today", "possible-break-in"):
+        out["exit_code"] = core.EXIT_FINDINGS
+    elif out["degraded"]:
+        out["exit_code"] = core.EXIT_DEGRADED
+    return out
+
+
+def render_scan(out: dict, report_md: str | None) -> str:
+    lines = [f"# Security scan — {out['site']} ({out['profile']})", ""]
+    ran = [s for s in out["steps"] if not s.get("refused")]
+    lines.append(f"Ran {len(ran)} checks" + (f", {len(out['degraded'])} degraded" if out["degraded"] else "")
+                 + (f", {len(out['skipped'])} skipped." if out["skipped"] else "."))
+    lines.append("")
+    lines += ["| Check | Result |", "|---|---|"]
+    for step in out["steps"]:
+        if step["command"] == "inventory":
+            result = "degraded" if step["degraded"] else "ok"
+        elif step.get("refused"):
+            result = "refused"
+        elif step.get("findings"):
+            result = f"{step['findings']} finding(s)"
+        elif step["degraded"]:
+            result = "incomplete"
+        else:
+            result = "no issues"
+        lines.append(f"| {step['command']} | {result} |")
+    for skip in out["skipped"]:
+        lines.append(f"| {skip['command']} | skipped: {skip['reason']} |")
+    lines.append("")
+    if out.get("verdict"):
+        lines += [f"**Verdict:** {out['verdict'].get('text', '')}", ""]
+    if report_md:
+        lines += ["---", "", report_md]
+    return "\n".join(lines)
+
+
+def configure(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--profile", choices=sorted(report.EXPECTED), help="override the detected site profile")
+    parser.add_argument("--domain", help="verified domain for the web checks (headers, tls)")
+    parser.add_argument("--ssh", help="ALIAS=user@host for the host checks (needs ssh-read consent)")
+    parser.add_argument("--kind", choices=["weekly", "daily_ops"], help="report kind to build at the end (default: weekly)")
+    parser.add_argument("--fix-plan", action="store_true", dest="fix_plan", help="also build a remediation fix-plan")
+
+
+COMMANDS = [core.Command("scan", "run the detectors for the site's profile, then build a report (one-shot; each detector best-effort)", [],
+                         configure, scan, findings=False)]

package/bundled-tools/clis/maggie_security_web.py

@@ -453,6 +453,50 @@ def csp_problems(value: str) -> list[str]:
     return problems
 
 
+# Letter grade for HTTP security headers, using the additive model from
+# mdn-http-observatory (MPL-2.0; score table and grade chart ported as data):
+# start at 100, apply the single worst penalty per category, map to a letter.
+GRADE_CHART = [(100, "A+"), (85, "A"), (80, "B+"), (70, "B"), (65, "B-"),
+               (60, "C+"), (50, "C"), (45, "C-"), (40, "D+"), (30, "D"), (25, "D-"), (0, "F")]
+# rule_id stem (after the `header-` prefix) -> (category, penalty). Worst per category counts once.
+HEADER_PENALTIES = {
+    "csp-missing": ("csp", -25), "csp-": ("csp", -10),
+    "hsts-missing": ("hsts", -20), "hsts-short": ("hsts", -10),
+    "xcto": ("xcto", -5),
+    "framing": ("framing", -20), "xfo-allow-from": ("framing", -20),
+    "referrer-missing": ("referrer", -5), "referrer-weak": ("referrer", -5),
+    "cors-wildcard-credentials": ("cors", -50),
+    "cookie-": ("cookie", -20),
+    "version-": ("disclosure", -5),
+}
+
+
+def header_grade(findings: list[dict]) -> dict:
+    """Observatory-style score (0–100) and letter grade from the header findings."""
+    worst: dict[str, int] = {}
+    for finding in findings:
+        stem = (finding["source"]["rule_id"] or "").removeprefix("header-")
+        match = HEADER_PENALTIES.get(stem) or next((v for k, v in HEADER_PENALTIES.items() if k.endswith("-") and stem.startswith(k)), None)
+        if match:
+            category, penalty = match
+            worst[category] = min(worst.get(category, 0), penalty)
+    score = max(0, min(100, 100 + sum(worst.values())))
+    grade = next(letter for threshold, letter in GRADE_CHART if score >= threshold)
+    return {"score": score, "grade": grade, "deductions": sorted(worst.items(), key=lambda kv: kv[1])}
+
+
+def grade_finding(ctx: core.Context, url: str, findings: list[dict]) -> dict:
+    g = header_grade(findings)
+    gaps = ", ".join(c for c, _ in g["deductions"]) or "nothing major"
+    summary = (f"Security-header grade {g['grade']} ({g['score']}/100). "
+               + (f"Biggest gaps: {gaps}. Fix the items below to raise it." if g["deductions"] else "No major header gaps."))
+    return core.make_finding(
+        kind="header", command="headers", primary_id="header-grade", site=ctx.site,
+        title=f"HTTP security headers grade: {g['grade']} ({g['score']}/100)", severity="info", severity_source="maggie",
+        confidence="confirmed", target={"url": url, "host": host_of(url)}, rule_id="header-grade",
+        remediation={"summary": summary, "steps": [], "snippets": [], "references": [], "cheat_sheet": None})
+
+
 def grade_response(ctx: core.Context, url: str, response: dict, layer: str, https: bool) -> list[dict]:
     headers = response["headers"]
     first = lambda name: (headers.get(name) or [None])[0]  # noqa: E731
@@ -530,7 +574,7 @@ def grade_response(ctx: core.Context, url: str, response: dict, layer: str, http
     if origin and origin.strip() == "*" and (first("access-control-allow-credentials") or "").lower() == "true":
         add("cors-wildcard-credentials", "CORS allows any origin with credentials", "high", ["V3.4.2"], kind="misconfiguration",
             evidence="Access-Control-Allow-Origin: *; Allow-Credentials: true")
-    return findings
+    return [grade_finding(ctx, url, findings)] + findings
 
 
 def headers_cmd(ctx: core.Context):