@topy-ai/maggie 0.7.61 → 0.8.1

package/bundled-skills/maggie-spirit/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: maggie-spirit
+description: Generate an AI brand's flat-pixel spirit (sprite) system - a logo mark that animates through a fixed 32-state base set, and per-agent avatar faces animated through the same states. Use for agent/brand avatars, logo marks, sprite-sheet and sprite-animation assets, and a shared motion vocabulary across Core and Service agents.
+metadata:
+  version: 0.1.0
+---
+
+# Maggie Spirit
+
+Give an agent brand one flat-pixel visual language: a **logo mark** and a set of
+**agent avatars** that all animate through the **same fixed catalog of 32
+states** (power, work, comms, outcome, gov). Agents differ only by their
+**motif/face** and their **accent** hue; the motion vocabulary, semantic palette
+and status badges stay identical so a state reads the same everywhere.
+
+Everything is deterministic (seeded by accent + persona) and self-contained
+(Pillow only - no model calls, no per-image cost). It pairs with
+[agent goal-led design](../../references/agent-goal-design.md): design the agent,
+then give it a spirit.
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation
+and completion.
+
+## When to use
+
+- You are standing up a multi-agent product (a C-suite of AI cofounders, a set
+  of Service Apps) and want a consistent avatar + logo + status-animation set.
+- You need a logo mark that can show live state (idle, working, deploying,
+  success, warning, secure, ...) rather than a single static glyph.
+- You need sprite sheets / animation strips + a `states.json` manifest to drive
+  a web UI (the CSS `steps()` technique), not a one-off illustration.
+
+For page/layout design use `maggie-design`; for marketplace templates use
+`maggie-marketplace`; this skill produces the brand's character assets only.
+
+## The 32-state base set
+
+Five groups, fixed across every agent so severity and status read the same:
+
+- **power:** off, booting, idle, active, paused, offline
+- **work:** thinking, loading, syncing, writing, streaming, queued, scanning, deploying
+- **comms:** speaking, listening, notification, mention, recording
+- **outcome:** success, warning, critical, blocked, error, retrying
+- **gov:** awaiting, approved, rejected, secure, vulnerable, maintenance, celebrating
+
+Each state carries its own frame count, fps, motion and optional badge; every
+state animates (none is static). The per-state `[frames, fps]` are written to
+`states.json` beside the images so a UI can play each strip exactly.
+
+## CLI
+
+Run through the bundled tool so it uses the current project as the working
+directory:
+
+```bash
+# logo mark + 32-state animated base set (anim-*.png, mark-*.svg, sprite-sheet.png, states.json)
+maggie tool maggie_spirit.py mark --out public/assets/brand --name oneman \
+  --accent "#ff1212" --title ONEMAN
+
+# one agent avatar animated through all 32 states (+ stills + sheet + states.json)
+maggie tool maggie_spirit.py agent --out public/assets/brand --name cto \
+  --accent "#3b82f6" --spec cto.persona.json
+
+# a single still avatar face
+maggie tool maggie_spirit.py avatar --out public/assets/brand/cto/face.png \
+  --accent "#3b82f6" --spec cto.persona.json
+
+# the reference base set to copy and recolour: default mark + example cast + founder
+maggie tool maggie_spirit.py demo --out public/assets/brand
+```
+
+`persona.json` (all keys optional except implied by your design):
+
+```json
+{
+  "gender": "m",
+  "hair": "#2a2018",
+  "skin": "light | mid | tan | deep",
+  "hairstyle": "short|slick|spiky|buzz|longwavy|longstraight|longbob|ponytail",
+  "eyes": "round|wide|lash|happy",
+  "mouth": "flat|smile|smirk|lips|open",
+  "prop": "glasses|shades|cigar|headset|earbuds|monocle|pen|bandana",
+  "propcol": "#f2c75a",
+  "hoodie": true, "band": "#e23b3b", "mask": "#12201a", "specs": true
+}
+```
+
+## Output contract
+
+For each target (`<out>/<name>/`):
+
+- `anim-<state>.png` - one horizontal strip per state (frames laid left to right).
+- `still-<state>.png` - a representative still per state (agents only).
+- `mark-<state>.svg` - a crisp SVG still per state (mark only).
+- `sprite-sheet.png` - an overview contact sheet.
+- `states.json` - `{ title, accent, N, scale, groups, states: { <state>: {group, frames, fps, motion, badge} } }`.
+
+## Driving the animation in a UI
+
+Flat-pixel, pixel-exact. Use CSS `steps()` with the per-state frame count, never
+percentage-position stepping:
+
+```css
+.sprite{
+  --fw: 48px;                 /* one frame = one cell */
+  width: var(--fw); height: var(--fw);
+  background: url(/assets/brand/cto/anim-active.png) no-repeat;
+  background-size: calc(var(--n) * var(--fw)) var(--fw);
+  image-rendering: pixelated;
+  animation: play calc(var(--n) / var(--fps) * 1s) steps(var(--n)) infinite;
+}
+@keyframes play { to { background-position-x: calc(-1 * var(--n) * var(--fw)); } }
+```
+
+Set `--n` and `--fps` per state from `states.json`. If you build the sprite
+element with `innerHTML` in an Astro page, style it with `<style is:global>` -
+Astro's scoped styles do not reach runtime-injected nodes (see `maggie-design`).
+
+## Boundaries
+
+- Deterministic and local: no LLM/image-model calls and no per-image billing.
+  Pillow is the only dependency.
+- The mark is the brand's own; recolour via `--accent`, keep the semantic
+  palette (severity colours) fixed so status stays legible across agents.
+- Do not hand-edit generated files; change the persona/accent and regenerate so
+  the whole set stays consistent.
+- Store generated art under the host project's assets; keep source personas
+  (the `*.persona.json`) in the repo so the set is reproducible.

package/bundled-tools/clis/maggie_dash.py

@@ -38,6 +38,11 @@ def project_root(args: argparse.Namespace) -> Path:
 
 
 def store_for(root: Path) -> MaggieDashStore:
+    # ONEMAN forbids SQLite: when MAGGIEDASH_DATABASE_URL is set, back the store
+    # with Postgres. Otherwise fall back to the local SQLite dev store.
+    dsn = os.environ.get("MAGGIEDASH_DATABASE_URL")
+    if dsn:
+        return MaggieDashStore(dsn=dsn)
     return MaggieDashStore(root / ".maggie" / "maggiedash.sqlite")
 
 
@@ -642,6 +647,9 @@ def command_recommend(args: argparse.Namespace) -> int:
 def command_init(args: argparse.Namespace) -> int:
     require_confirm(args)
     root = project_root(args)
+    if str(getattr(args, "adapter", "")).endswith("postgres") and not os.environ.get("MAGGIEDASH_DATABASE_URL"):
+        print("POSTGRES_DSN_REQUIRED: adapter is postgres but MAGGIEDASH_DATABASE_URL is not set.", file=sys.stderr)
+        return 2
     store = store_for(root)
     try:
         project = store.init_project(args.project_id, args.name, args.adapter, args.locale)
@@ -652,9 +660,9 @@ def command_init(args: argparse.Namespace) -> int:
             "name": args.name,
             "adapter": args.adapter,
             "locale": args.locale,
-            "storage": str(store.path),
+            "storage": store.storage_label,
         }, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-        emit({"status": "initialized", "project": project, "contract": str(contract), "storage": str(store.path)})
+        emit({"status": "initialized", "project": project, "contract": str(contract), "storage": store.storage_label})
         return 0
     finally:
         store.close()
@@ -667,7 +675,7 @@ def command_status(args: argparse.Namespace) -> int:
     try:
         project = store.connection.execute("SELECT * FROM maggiedash_projects WHERE id=?", (project_id,)).fetchone()
         documents = store.connection.execute("SELECT id, kind, title, slug, status, updated_at FROM maggiedash_documents WHERE project_id=? ORDER BY updated_at DESC", (project_id,)).fetchall()
-        emit({"status": "ready" if project else "not_initialized", "project": dict(project) if project else None, "documents": [dict(row) for row in documents], "storage": str(store.path)})
+        emit({"status": "ready" if project else "not_initialized", "project": dict(project) if project else None, "documents": [dict(row) for row in documents], "storage": store.storage_label})
         return 0 if project else 1
     finally:
         store.close()
@@ -680,7 +688,7 @@ def command_migrate(args: argparse.Namespace) -> int:
     try:
         store.connection.execute("PRAGMA user_version = 1")
         store.connection.commit()
-        emit({"status": "migrated", "schemaVersion": "maggiedash-storage.v1", "storage": str(store.path)})
+        emit({"status": "migrated", "schemaVersion": "maggiedash-storage.v1", "storage": store.storage_label})
         return 0
     finally:
         store.close()

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("")