@topy-ai/maggie 0.7.55 → 0.7.56

package/bundled-tools/clis/maggie_security_code.py

@@ -0,0 +1,650 @@
+#!/usr/bin/env python3
+"""``maggie security secrets`` (and later ``code-scan``) — docs/maggie-security/03-code-secrets-prd.md.
+
+Secrets are looked for in three places:
+
+- A. git history (``git log -p``), including files deleted since;
+- B. the working tree (tracked and untracked, not ``node_modules``/``vendor``);
+- C. build output that gets served (``dist/``, ``build/``, ``.next/static``,
+  ``.output/public``, ``public/``, ``out/``, ``.vercel/output/static``), plus
+  the environment-leak check: a value from a ``.env*`` file found verbatim in
+  an artifact.
+
+Engine: the pinned gitleaks binary when installed (``--redact=100`` so its
+report holds no values), otherwise the native engine with gitleaks' own
+default rules (MIT, converted by ``scripts/security/build_gitleaks_rules.py``)
+plus Maggie's rules. Values are hashed and shown only as first 4 + last 4
+characters; they are never written anywhere.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+import maggie_security_core as core
+
+ARTIFACT_DIRS = {"dist": "public", "build": "public", "out": "public", "public": "public", ".output/public": "public",
+                 ".vercel/output/static": "public", ".next/static": "public", ".next/server": "server", ".svelte-kit/output": "server",
+                 ".wrangler/deploy": "server"}
+SKIP_DIRS = {"node_modules", "vendor", ".git", ".maggie", "__pycache__", ".venv", "venv", ".cache", "bower_components"}
+MAX_FILE = 5 * 1024 * 1024
+BINARY_EXT = re.compile(r"(?i)\.(png|jpe?g|gif|webp|avif|ico|svgz|woff2?|ttf|otf|eot|pdf|zip|gz|tgz|br|zst|mp4|webm|mp3|wasm|lockb|sqlite|db|bin|exe|dll|so|dylib|class|jar)$")
+ENV_FILE = re.compile(r"^\.env(\..+)?$")
+ENV_SKIP = re.compile(r"(?i)\.(example|sample|template|dist|defaults?)$")
+PLACEHOLDER = re.compile(r"(?i)^(x+|\*+|changeme|change-me|your[_-].*|example.*|dummy.*|placeholder.*|test.*|todo|<.*>|\$\{.*\}|null|none|true|false)$")
+
+# Maggie rules on top of gitleaks' defaults (PRD 03 section 6.2).
+MAGGIE_RULES = [
+    {"id": "maggie-openrouter-key", "description": "OpenRouter API key", "regex": r"\b(sk-or-v1-[a-f0-9]{64})\b", "keywords": ["sk-or-v1-"]},
+    {"id": "maggie-resend-key", "description": "Resend API key", "regex": r"\b(re_[A-Za-z0-9]{8,}_[A-Za-z0-9]{16,})\b", "keywords": ["re_"]},
+    {"id": "maggie-db-url", "description": "Database URL with a password",
+     "regex": r"\b((?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis|rediss)://[^:\s/@'\"]+:([^@\s'\"]{6,})@[^\s'\"]+)", "secretGroup": 2,
+     "keywords": ["://"]},
+    {"id": "maggie-wp-salts", "description": "WordPress salt or key with a real value",
+     "regex": r"define\(\s*'(?:AUTH|SECURE_AUTH|LOGGED_IN|NONCE)_(?:KEY|SALT)'\s*,\s*'([^']{32,})'\s*\)", "keywords": ["_key", "_salt"],
+     "allowlists": [{"regexes": [r"put your unique phrase here"]}], "path_exclude": r"wp-config-sample\.php$"},
+    {"id": "maggie-public-env-misuse", "description": "A public build variable named like a server secret",
+     "regex": r"\b((?:NEXT_PUBLIC|PUBLIC|VITE|NUXT_PUBLIC|REACT_APP|EXPO_PUBLIC)_[A-Z0-9_]*(?:SECRET|PRIVATE|SERVICE_ROLE|API_KEY|PASSWORD|TOKEN)[A-Z0-9_]*)\b",
+     "keywords": ["public_", "vite_", "react_app_"], "name_only": True},
+]
+
+
+def shannon(text: str) -> float:
+    if not text:
+        return 0.0
+    counts: dict[str, int] = {}
+    for ch in text:
+        counts[ch] = counts.get(ch, 0) + 1
+    return -sum(c / len(text) * math.log2(c / len(text)) for c in counts.values())
+
+
+class Rules:
+    def __init__(self, extra_allow_paths: list[str] | None = None) -> None:
+        data = core.read_json(core.DATA_DIR / "gitleaks-rules.json")
+        self.version = data.get("version")
+        self.rules = []
+        self.path_rules: list[dict] = []  # rules that flag a file by its name (e.g. a .p12 key store)
+        for rule in data["rules"] + MAGGIE_RULES:
+            if not rule.get("regex"):
+                if rule.get("path"):
+                    self.path_rules.append({**rule, "_path": re.compile(rule["path"])})
+                continue
+            compiled = {**rule, "_re": re.compile(rule["regex"]), "_keywords": [k.lower() for k in rule.get("keywords") or []],
+                        "_path": re.compile(rule["path"]) if rule.get("path") else None,
+                        "_path_exclude": re.compile(rule["path_exclude"]) if rule.get("path_exclude") else None,
+                        "_allow": [{"regexes": [re.compile(r) for r in a.get("regexes", [])], "paths": [re.compile(p) for p in a.get("paths", [])],
+                                    "stopwords": [w.lower() for w in a.get("stopwords", [])], "target": a.get("regexTarget", "secret"),
+                                    "condition": (a.get("condition") or "OR").upper()} for a in rule.get("allowlists") or []]}
+            self.rules.append(compiled)
+        allow = data.get("allowlist") or {}
+        self.allow_paths = [re.compile(p) for p in allow.get("paths", []) + (extra_allow_paths or [])]
+        self.allow_regexes = [re.compile(p) for p in allow.get("regexes", [])]
+        self.stopwords = [w.lower() for w in allow.get("stopwords", [])]
+
+    def path_allowed(self, rel: str) -> bool:
+        return any(p.search(rel) for p in self.allow_paths)
+
+    def _rule_allowed(self, rule: dict, secret: str, match: str, line: str, rel: str) -> bool:
+        for allow in rule["_allow"]:
+            checks = []
+            if allow["regexes"]:
+                target = {"match": match, "line": line}.get(allow["target"], secret)
+                checks.append(any(r.search(target) for r in allow["regexes"]))
+            if allow["paths"]:
+                checks.append(any(p.search(rel) for p in allow["paths"]))
+            if allow["stopwords"]:
+                checks.append(any(w in secret.lower() for w in allow["stopwords"]))
+            if checks and (all(checks) if allow["condition"] == "AND" else any(checks)):
+                return True
+        return False
+
+    def scan_line(self, line: str, rel: str):
+        if len(line) > 4000:
+            line = line[:4000]
+        lower = line.lower()
+        for rule in self.rules:
+            if rule["_keywords"] and not any(k in lower for k in rule["_keywords"]):
+                continue
+            if rule["_path"] and not rule["_path"].search(rel):
+                continue
+            if rule["_path_exclude"] and rule["_path_exclude"].search(rel):
+                continue
+            for match in rule["_re"].finditer(line):
+                group = rule.get("secretGroup")
+                secret = match.group(group) if group and match.lastindex and group <= match.lastindex else \
+                    next((g for g in match.groups() if g), match.group(0)) if match.groups() else match.group(0)
+                if not secret:
+                    continue
+                if rule.get("entropy") and shannon(secret) < float(rule["entropy"]):
+                    continue
+                if any(r.search(secret) for r in self.allow_regexes) or any(w in secret.lower() for w in self.stopwords):
+                    continue
+                if not rule.get("name_only") and PLACEHOLDER.match(secret):
+                    continue
+                if self._rule_allowed(rule, secret, match.group(0), line, rel):
+                    continue
+                yield rule, secret
+
+
+def text_files(root: Path, base: Path, skip_artifacts: bool = False):
+    for current, dirs, files in os.walk(root):
+        current_path = Path(current)
+        rel_dir = current_path.relative_to(base).as_posix() if current_path != base else ""
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not (skip_artifacts and _artifact_kind(f"{rel_dir}/{d}".lstrip("/")))]
+        for name in files:
+            path = current_path / name
+            if BINARY_EXT.search(name):
+                continue
+            try:
+                if path.is_symlink() or path.stat().st_size > MAX_FILE:
+                    continue
+            except OSError:
+                continue
+            yield path
+
+
+def _artifact_kind(rel: str) -> str | None:
+    for prefix, kind in ARTIFACT_DIRS.items():
+        if rel == prefix or rel.startswith(prefix + "/"):
+            return kind
+    return None
+
+
+def read_text(path: Path) -> str | None:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    if b"\x00" in data[:8192]:
+        return None
+    return data.decode("utf-8", errors="replace")
+
+
+class Collector:
+    """Groups hits by (rule, secret hash) so one secret in many places is one finding."""
+
+    def __init__(self) -> None:
+        self.groups: dict[tuple[str, str], dict] = {}
+        self._values: dict[str, tuple[str, str]] = {}  # in memory for this run only: value -> group key; cleared by forget()
+
+    def forget(self) -> None:
+        self._values.clear()
+
+    def add(self, rule: dict, secret: str, *, rel: str, line_no: int | None, line: str, where: str, commit: str | None = None) -> None:
+        info = core.redact_secret(secret)
+        key = (rule["id"], info["value_sha256"])
+        group = self.groups.setdefault(key, {"rule": rule, "info": info, "hits": []})
+        excerpt = line.replace(secret, info["redacted"]).strip()
+        hit = {"path": rel, "line": line_no, "excerpt": core.clean_excerpt(excerpt), "redacted": info["redacted"],
+               "value_sha256": info["value_sha256"], "where": where}
+        if commit:
+            hit["commit"] = commit[:12]
+        if not any(h["path"] == rel and h["line"] == line_no and h.get("commit") == hit.get("commit") for h in group["hits"]):
+            group["hits"].append(hit)
+        if len(secret) >= 12 and not secret.startswith(("gitleaks:", "file:")):
+            self._values.setdefault(secret, key)
+        del secret
+
+    def find_in_artifacts(self, project: Path) -> int:
+        """A value found anywhere (code, history) that also sits in served output, even without a keyword next to it."""
+        if not self._values:
+            return 0
+        hits = 0
+        for prefix, kind in ARTIFACT_DIRS.items():
+            root = project / prefix
+            if not root.is_dir():
+                continue
+            for path in text_files(root, project):
+                text = read_text(path)
+                if not text:
+                    continue
+                rel = path.relative_to(project).as_posix()
+                for value, key in self._values.items():
+                    if value in text:
+                        group = self.groups[key]
+                        number = text[: text.index(value)].count("\n") + 1
+                        if any(h["path"] == rel for h in group["hits"]):
+                            continue
+                        line = text.splitlines()[number - 1][:400]
+                        self.add(group["rule"], value, rel=rel, line_no=number, line=line, where=f"artifact-{kind}")
+                        hits += 1
+        return hits
+
+
+def scan_tree(project: Path, rules: Rules, collector: Collector, include_artifacts: bool = True) -> int:
+    count = 0
+    for path in text_files(project, project):
+        rel = path.relative_to(project).as_posix()
+        if rules.path_allowed(rel):
+            continue
+        kind = _artifact_kind(rel)
+        if kind and not include_artifacts:
+            continue
+        for rule in rules.path_rules:
+            if rule["_path"].search(rel):
+                collector.add(rule, f"file:{rel}", rel=rel, line_no=None, line=f"file {rel}", where=f"artifact-{kind}" if kind else "tree")
+        text = read_text(path)
+        if text is None:
+            continue
+        count += 1
+        for number, line in enumerate(text.splitlines(), 1):
+            for rule, secret in rules.scan_line(line, rel):
+                collector.add(rule, secret, rel=rel, line_no=number, line=line, where=f"artifact-{kind}" if kind else "tree")
+    return count
+
+
+def scan_git(project: Path, rules: Rules, collector: Collector, since: str | None) -> tuple[bool, int]:
+    if not (project / ".git").exists():
+        return False, 0
+    argv = ["git", "-C", str(project), "log", "-p", "--all", "--no-color", "-U0", "--no-ext-diff", "--format=commit %H"]
+    if since:
+        argv.insert(4, f"--since={since}")
+    try:
+        proc = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, errors="replace")
+    except OSError:
+        return False, 0
+    commit = None
+    rel = None
+    line_no = 0
+    commits = 0
+    assert proc.stdout is not None
+    with proc.stdout:
+        commit, rel, line_no, commits = _walk_git_log(proc.stdout, rules, collector)
+    proc.wait()
+    return proc.returncode == 0, commits
+
+
+def _walk_git_log(stream, rules: Rules, collector: Collector) -> tuple[str | None, str | None, int, int]:
+    commit = None
+    rel = None
+    line_no = 0
+    commits = 0
+    for raw in stream:
+        line = raw.rstrip("\n")
+        if line.startswith("commit ") and len(line) == 47:
+            commit = line[7:]
+            commits += 1
+        elif line.startswith("+++ "):
+            rel = None if line.endswith("/dev/null") else line[6:] if line.startswith("+++ b/") else line[4:]
+        elif line.startswith("@@"):
+            match = re.search(r"\+(\d+)", line)
+            line_no = int(match.group(1)) if match else 0
+        elif line.startswith("+") and rel and not line.startswith("+++"):
+            if not rules.path_allowed(rel):
+                for rule, secret in rules.scan_line(line[1:], rel):
+                    collector.add(rule, secret, rel=rel, line_no=line_no, line=line[1:], where="history", commit=commit)
+            line_no += 1
+    return commit, rel, line_no, commits
+
+
+def env_leak_check(project: Path, collector: Collector) -> int:
+    """PRD 03 section 6.3: values from .env files that appear verbatim in served artifacts."""
+    values: dict[str, list[str]] = {}
+    for path in sorted(project.iterdir()) if project.is_dir() else []:
+        if not path.is_file() or not ENV_FILE.match(path.name) or ENV_SKIP.search(path.name):
+            continue
+        for line in (read_text(path) or "").splitlines():
+            match = re.match(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$", line)
+            if not match:
+                continue
+            value = match.group(2).strip().strip('"').strip("'")
+            if len(value) < 8 or PLACEHOLDER.match(value) or re.fullmatch(r"(https?://)?(localhost|127\.0\.0\.1)[:/\w.-]*", value) \
+                    or re.fullmatch(r"\d+", value) or value.lower() in ("production", "development", "staging"):
+                continue
+            values.setdefault(value, []).append(match.group(1))
+    if not values:
+        return 0
+    rule = {"id": "maggie-env-value-in-artifact", "description": "A value from a .env file is in served build output"}
+    hits = 0
+    for prefix, kind in ARTIFACT_DIRS.items():
+        root = project / prefix
+        if not root.is_dir():
+            continue
+        for path in text_files(root, project):
+            text = read_text(path)
+            if not text:
+                continue
+            rel = path.relative_to(project).as_posix()
+            for value, names in values.items():
+                if value in text:
+                    number = text[: text.index(value)].count("\n") + 1
+                    line = text.splitlines()[number - 1] if text.splitlines() else ""
+                    collector.add({**rule, "description": f"{rule['description']} ({', '.join(sorted(set(names)))})"}, value,
+                                  rel=rel, line_no=number, line=line[:400], where=f"artifact-{kind}")
+                    hits += 1
+    values.clear()
+    return hits
+
+
+# --------------------------------------------------------------------------- gitleaks binary
+
+
+def run_gitleaks(ctx: core.Context, project: Path, mode: str, target: Path, since: str | None) -> list[dict] | None:
+    with tempfile.TemporaryDirectory() as tmp:
+        report = Path(tmp) / "report.json"
+        args = [mode, "--report-format", "json", "--report-path", str(report), "--redact=100", "--exit-code", "0"]
+        if mode == "git" and since:
+            args += ["--log-opts", f"--all --since={since}"]
+        if mode == "dir":
+            args += ["--max-target-megabytes", "5"]
+        args.append(str(target))
+        proc = core.run_tool("gitleaks", args, ctx.lock, cwd=project)
+        if not report.is_file():
+            ctx.degrade(f"gitleaks-{mode}", core.clean_excerpt(proc.stderr.decode(errors="replace"), 200))
+            return None
+        return json.loads(report.read_text(encoding="utf-8") or "[]")
+
+
+def gitleaks_to_collector(items: list[dict], project: Path, target: Path, where_default: str, collector: Collector) -> None:
+    for item in items:
+        rel_file = item.get("File") or ""
+        path = Path(rel_file)
+        rel = (path if path.is_absolute() else (target / path)).resolve()
+        try:
+            rel_text = rel.relative_to(project.resolve()).as_posix()
+        except ValueError:
+            rel_text = rel_file
+        kind = _artifact_kind(rel_text)
+        where = f"artifact-{kind}" if kind else where_default
+        # --redact=100 means Secret is "REDACTED"; the fingerprint stands in for the value hash.
+        # --redact=100 means Secret is "REDACTED": rule + file + line stands in for the value hash, so the
+        # same line in history and in the working tree is one finding.
+        stand_in = f"{rel_text}:{item.get('RuleID')}:{item.get('StartLine')}"
+        rule = {"id": item.get("RuleID") or "gitleaks", "description": item.get("Description") or item.get("RuleID") or "secret"}
+        collector.add(rule, "gitleaks:" + stand_in, rel=rel_text, line_no=item.get("StartLine"),
+                      line=f"{item.get('RuleID')} match (value redacted by gitleaks)", where=where, commit=item.get("Commit") or None)
+
+
+# --------------------------------------------------------------------------- findings
+
+
+def severity_for(hits: list[dict], rule: dict) -> str:
+    if rule.get("name_only"):
+        return "medium"
+    if any(h["where"] == "artifact-public" for h in hits):
+        return "critical"
+    return "high"
+
+
+def to_findings(ctx: core.Context, collector: Collector) -> list[dict]:
+    findings = []
+    for (rule_id, value_hash), group in collector.groups.items():
+        hits = sorted(group["hits"], key=lambda h: ({"artifact-public": 0, "artifact-server": 1, "tree": 2, "history": 3}[h["where"]], h["path"]))
+        rule = group["rule"]
+        lead = hits[0]
+        public = lead["where"] == "artifact-public"
+        history_only = all(h["where"] == "history" for h in hits)
+        where_text = {"artifact-public": "in a file your site serves publicly", "artifact-server": "in a deployed server bundle",
+                      "tree": "in the project files", "history": "in git history"}[lead["where"]]
+        name_only = rule.get("name_only")
+        title = f"{rule.get('description') or rule_id} {where_text}: {lead['path']}" + (f":{lead['line']}" if lead.get("line") else "")
+        steps = [] if name_only else ["Revoke or rotate this key with its provider first (assume it is already copied).",
+                                      "Remove it from the code and build output; keep it in the platform's secret store "
+                                      "(for Cloudflare Workers: maggie deployment worker-secrets).",
+                                      "Rebuild and redeploy."]
+        if history_only and not name_only:
+            steps.append("It is only in git history now: rotating is enough; purging history (git filter-repo) is optional.")
+        if name_only:
+            steps = ["Rename the variable without the public prefix and read it only on the server; anything with a public prefix is sent to browsers."]
+        finding = core.make_finding(
+            kind="secret", command="secrets", primary_id=rule_id, site=ctx.site, title=title[:300],
+            severity=severity_for(hits, rule), severity_source="maggie", confidence="likely" if name_only else ("confirmed" if public else "likely"),
+            asvs_ids=["V13.3.1"], cwe_ids=["CWE-798"],
+            target={"path": lead["path"]},
+            evidence=[{k: v for k, v in h.items() if k in ("path", "line", "excerpt", "redacted", "value_sha256", "commit")} for h in hits[:20]],
+            rule_id=rule_id, tool=ctx.run.get("_engine"), feed=None,
+            remediation={"summary": "Rotate the key, then remove it." if not name_only else "Keep secret values out of public build variables.",
+                         "steps": steps, "snippets": [], "references": ["https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html"],
+                         "cheat_sheet": "Secrets Management"})
+        # One secret in many files is one finding: the id follows the value hash, not the path.
+        finding["id"] = core.fingerprint("secret", rule_id, f"secret:{value_hash[:24]}", ctx.site)
+        if public and not name_only:
+            finding["priority"] = "p0"
+        findings.append(finding)
+    return findings
+
+
+def apply_baseline(ctx: core.Context, findings: list[dict], command: str = "secrets") -> None:
+    args = ctx.args
+    path = Path(args.baseline) if args.baseline else ctx.state.path("baselines", f"{command}.json")
+    if args.write_baseline:
+        public = [f for f in findings if f["severity"] == "critical" and f["kind"] == "secret"]
+        if public:
+            raise core.PolicyError("a secret in served build output cannot be baselined: rotate it and remove it first")
+        target = Path(args.write_baseline)
+        core.write_json(target, {"schema": "maggie-security-baseline.v1", "command": command, "created_at": core.iso(),
+                                 "rules_version": rule_pack_version() if command == "code-scan" else core.read_json(core.DATA_DIR / "gitleaks-rules.json").get("version"),
+                                 "reason": "baseline", "ids": sorted(f["id"] for f in findings)})
+        ctx.run["inputs"]["baseline_written"] = str(target)
+        return
+    if not path.is_file():
+        return
+    ids = set(core.read_json(path).get("ids") or [])
+    ledger = core.Ledger(ctx.state.path("ledger.jsonl"))
+    history = ledger.history()
+    for finding in findings:
+        if finding["id"] in ids and not (finding["kind"] == "secret" and finding["severity"] == "critical"):
+            state = core.Ledger.derive(history.get(finding["id"], [])) if finding["id"] in history else {"status": None}
+            if state["status"] != "accepted-risk":
+                ledger.append([{"id": finding["id"], "at": core.iso(), "event": "seen", "run": ctx.run["id"], "command": command,
+                                "severity": finding["severity"]},
+                               {"id": finding["id"], "at": core.iso(), "event": "accepted-risk", "by": "baseline", "reason": "baseline"}])
+    ctx.run["inputs"]["baseline"] = str(path)
+
+
+def secrets(ctx: core.Context):
+    args = ctx.args
+    project = ctx.project
+    scopes = set((args.scope or "git,tree,dist").split(","))
+    config = ctx.state.config()
+    collector = Collector()
+    engine = args.engine
+    if engine == "auto":
+        engine = "gitleaks" if core.resolve_tool("gitleaks", ctx.lock)[2] == "pinned" else "native"
+    ctx.run["_engine"] = "gitleaks" if engine == "gitleaks" else "maggie-native"
+    ctx.run["tools"].append({"name": "gitleaks" if engine == "gitleaks" else "maggie-secrets-native",
+                             "version": ctx.lock["tools"]["gitleaks"]["version"] if engine == "gitleaks" else core.read_json(core.DATA_DIR / "gitleaks-rules.json").get("version"),
+                             "sha256": None})
+    rules = Rules((config.get("secrets") or {}).get("allow_paths"))
+    covered_ok = True
+    if engine == "gitleaks":
+        if "git" in scopes and (project / ".git").exists():
+            items = run_gitleaks(ctx, project, "git", project, args.since)
+            covered_ok &= items is not None
+            gitleaks_to_collector(items or [], project, project, "history", collector)
+        if "tree" in scopes or "dist" in scopes:
+            items = run_gitleaks(ctx, project, "dir", project, None)
+            covered_ok &= items is not None
+            gitleaks_to_collector(items or [], project, project, "tree", collector)
+        files = None
+    else:
+        files = scan_tree(project, rules, collector, include_artifacts="dist" in scopes) if ("tree" in scopes or "dist" in scopes) else 0
+        if "git" in scopes:
+            ok, commits = scan_git(project, rules, collector, args.since)
+            ctx.run["inputs"]["git_commits"] = commits
+            if (project / ".git").exists() and not ok:
+                ctx.degrade("git-history", "git log failed")
+                covered_ok = False
+    leaks = env_leak_check(project, collector) if "dist" in scopes else 0
+    copied = collector.find_in_artifacts(project) if "dist" in scopes else 0
+    collector.forget()
+    findings = to_findings(ctx, collector)
+    apply_baseline(ctx, findings, "secrets")
+    ctx.run["inputs"].update({"engine": ctx.run.pop("_engine"), "scopes": sorted(scopes), "files_scanned": files, "env_value_hits": leaks,
+                              "copied_into_artifacts": copied})
+    return ctx.finish(findings, covered=["*"] if covered_ok and scopes >= {"tree", "dist"} else [])
+
+
+# --------------------------------------------------------------------------- code-scan (semgrep + Maggie rule pack)
+
+
+def rule_pack_dir() -> Path:
+    for base in (core.ROOT / "skills", core.ROOT / "bundled-skills"):
+        path = base / "maggie-security" / "data" / "semgrep"
+        if path.is_dir():
+            return path
+    raise core.UsageError("Maggie semgrep rule pack not found")
+
+
+def rule_pack_version() -> str:
+    return (rule_pack_dir() / "VERSION").read_text(encoding="utf-8").strip()
+
+
+SEMGREP_EXCLUDES = ["node_modules", "vendor", "dist", "build", ".next", ".output", ".maggie", ".git", "wp-content/plugins", "wp-content/themes",
+                    "wp-admin", "wp-includes", "coverage", "__pycache__", "*.min.js"]  # names match anywhere in the path: keep them specific
+SEMGREP_SEVERITY = {"ERROR": "high", "WARNING": "medium", "INFO": "low"}
+
+
+def semgrep_to_findings(ctx: core.Context, data: dict, project: Path) -> list[dict]:
+    """semgrep --json -> finding-v1 (PRD 03 section 9.1). One finding per rule and file; each hit is evidence."""
+    findings = []
+    for result in data.get("results") or []:
+        extra = result.get("extra") or {}
+        meta = extra.get("metadata") or {}
+        check = str(result.get("check_id") or "")
+        rule_id = check[check.index("maggie."):] if "maggie." in check else check.rsplit(".", 1)[-1]
+        path = str(result.get("path") or "")
+        try:
+            rel = Path(path).resolve().relative_to(project).as_posix()
+        except ValueError:
+            rel = path
+        line = (result.get("start") or {}).get("line")
+        severity = meta.get("severity") or SEMGREP_SEVERITY.get(str(extra.get("severity")).upper(), "medium")
+        confidence = {"high": "likely", "medium": "possible", "low": "possible"}.get(str(meta.get("confidence") or "medium").lower(), "possible")
+        message = str(extra.get("message") or rule_id)
+        cwes = meta.get("cwe") or []
+        cwes = [cwes] if isinstance(cwes, str) else cwes
+        asvs = meta.get("asvs") or []
+        asvs = [asvs] if isinstance(asvs, str) else asvs
+        findings.append(core.make_finding(
+            kind="code", command="code-scan", primary_id=rule_id, site=ctx.site, title=f"{message.split('. ')[0].rstrip('.')} ({rel})"[:300],
+            severity=severity, severity_source="tool", confidence=confidence,
+            cwe_ids=[c.split(":")[0].strip() for c in cwes if re.match(r"^CWE-\d+", str(c))],
+            asvs_ids=[a for a in asvs if re.match(r"^V\d+\.\d+\.\d+$", str(a))], target={"path": rel},
+            evidence=[{"path": rel, "line": line, "excerpt": core.clean_excerpt(str(extra.get("lines") or ""), 200)}],
+            tool="semgrep", rule_id=rule_id,
+            remediation={"summary": message, "steps": [], "snippets": [{"kind": "patch", "text": extra["fix"]}] if extra.get("fix") else [],
+                         "references": [meta["fix_doc"]] if meta.get("fix_doc") else [], "cheat_sheet": None}))
+    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 = []
+    for path in files:
+        rel = path.relative_to(project).as_posix()
+        name = path.name.lower()
+        text = read_text(path) or ""
+        if name == "dockerfile" or name.startswith("dockerfile.") or name.endswith(".dockerfile"):
+            stages = re.split(r"(?im)^\s*FROM\s+", text)
+            final = stages[-1] if len(stages) > 1 else ""
+            if final and not re.search(r"(?im)^\s*USER\s+(?!root\b|0\b)\S+", final) and not re.match(r"(?i)scratch\b", final.strip()):
+                findings.append(core.make_finding(
+                    kind="code", command="code-scan", primary_id="maggie.docker.root-user", site=ctx.site,
+                    title=f"The container runs as root (no USER in the final stage of {rel})", severity="low", severity_source="maggie",
+                    confidence="likely", cwe_ids=["CWE-250"], target={"path": rel}, tool="maggie-native", rule_id="maggie.docker.root-user",
+                    evidence=[{"path": rel, "excerpt": "FROM " + final.splitlines()[0][:150] if final else ""}],
+                    remediation={"summary": "Add a non-root USER (for example `USER node` or `USER www-data`) in the final stage.", "steps": [],
+                                 "snippets": [], "references": ["https://docs.docker.com/build/building/best-practices/#user"], "cheat_sheet": None}))
+        if name.endswith(".conf") or name.startswith("nginx.conf"):
+            for block in re.findall(r"(?s)server\s*\{(.*?)\n\}", text):
+                if re.search(r"(?m)^\s*root\s+\S+;", block) and not re.search(r"location\s+~\*?\s*/\\\.", block):
+                    findings.append(core.make_finding(
+                        kind="code", command="code-scan", primary_id="maggie.nginx.dotfiles-served", site=ctx.site,
+                        title=f"nginx may serve hidden files like .git or .env ({rel})", severity="medium", severity_source="maggie",
+                        confidence="likely", cwe_ids=["CWE-538"], asvs_ids=["V13.4.1"], target={"path": rel}, tool="maggie-native",
+                        rule_id="maggie.nginx.dotfiles-served",
+                        remediation={"summary": "Deny hidden files in the server block.", "steps": [],
+                                     "snippets": [{"kind": "nginx", "text": "location ~ /\\.(?!well-known) { deny all; }"}],
+                                     "references": [], "cheat_sheet": None}))
+                    break
+    return findings
+
+
+def changed_files(project: Path, ref: str) -> list[str]:
+    proc = subprocess.run(["git", "-C", str(project), "diff", "--name-only", "--diff-filter=ACMR", ref], capture_output=True, text=True, check=False)
+    if proc.returncode != 0:
+        raise core.UsageError(f"git diff against {ref} failed: {proc.stderr.strip()[:200]}")
+    untracked = subprocess.run(["git", "-C", str(project), "ls-files", "--others", "--exclude-standard"], capture_output=True, text=True, check=False)
+    return sorted(set(proc.stdout.split()) | set(untracked.stdout.split()))
+
+
+def code_scan(ctx: core.Context):
+    args = ctx.args
+    project = ctx.project
+    configs = []
+    for rule in args.rules or ["maggie"]:
+        if rule == "maggie":
+            configs.append(str(rule_pack_dir() / "rules"))
+        elif "://" in rule or rule in ("auto", "p", "r") or rule.startswith(("p/", "r/")):
+            raise core.PolicyError(f"--rules {rule}: only the Maggie pack or local rule folders are allowed (no registry downloads)")
+        else:
+            local = Path(rule) if Path(rule).is_absolute() else project / rule
+            if not local.exists():
+                raise core.UsageError(f"rule folder not found: {rule}")
+            configs.append(str(local))
+    if args.changed_since:
+        targets = [str(project / f) for f in changed_files(project, args.changed_since) if (project / f).is_file()]
+        if not targets:
+            ctx.run["inputs"]["note"] = f"no files changed since {args.changed_since}"
+            return ctx.finish([], covered=[])
+    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)
+    with tempfile.TemporaryDirectory() as tmp:
+        out = Path(tmp) / "semgrep.json"
+        argv = ["scan", "--json", "--json-output", str(out), "--timeout", "30", "--max-target-bytes", "1000000", "--quiet"]
+        for config in configs:
+            argv += ["--config", config]
+        for exclude in SEMGREP_EXCLUDES:
+            argv += ["--exclude", exclude]
+        if args.baseline_commit:
+            argv += ["--baseline-commit", args.baseline_commit]
+        argv += targets
+        proc = core.run_tool("semgrep", argv, ctx.lock, cwd=project, timeout=1800, env={"SEMGREP_SEND_METRICS": "off", "SEMGREP_ENABLE_VERSION_CHECK": "0"})
+        if not out.is_file():
+            raise core.DegradedError(f"semgrep produced no report: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 200)}")
+        data = json.loads(out.read_text(encoding="utf-8") or "{}")
+    findings += semgrep_to_findings(ctx, data, project)
+    errors = [e for e in data.get("errors") or [] if str(e.get("level", "")).lower() == "error"]
+    if errors:
+        ctx.degrade("semgrep", f"{len(errors)} file(s) could not be parsed")
+    version = (data.get("version") or ctx.lock["tools"]["semgrep"]["version"])
+    ctx.run["tools"].append({"name": "semgrep", "version": version, "sha256": None})
+    ctx.run["inputs"].update({"rule_pack": rule_pack_version(), "configs": [Path(c).name for c in configs], "files": len(files),
+                              "changed_since": args.changed_since})
+    apply_baseline(ctx, findings, "code-scan")
+    return ctx.finish(findings, covered=["*"] if not args.changed_since and not args.paths and not errors else [])
+
+
+def _code(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--rules", action="append", help="'maggie' (default) or a local rule folder; registry configs are refused")
+    p.add_argument("--paths", nargs="*", help="limit to these paths")
+    p.add_argument("--changed-since", help="scan only files changed since a git ref (pre-commit use)")
+    p.add_argument("--baseline-commit", help="semgrep's own diff-aware baseline")
+    p.add_argument("--baseline", help="baseline file (default .maggie/security/baselines/code-scan.json)")
+    p.add_argument("--write-baseline", help="record all current findings as accepted")
+
+
+def _secrets(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--scope", help="comma list of git,tree,dist (default all three)")
+    p.add_argument("--engine", choices=["auto", "gitleaks", "native"], default="auto",
+                   help="auto: the pinned gitleaks if installed, else Maggie's native engine with gitleaks' rules")
+    p.add_argument("--baseline", help="baseline file (default .maggie/security/baselines/secrets.json)")
+    p.add_argument("--write-baseline", help="record all current findings as accepted (not allowed for public build output)")
+
+
+COMMANDS = [
+    core.Command("code-scan", "find unsafe code patterns (XSS, SSRF, SQL injection, open redirects, insecure cookies…) with semgrep and Maggie's rules",
+                 [], _code, code_scan),
+    core.Command("secrets", "find API keys and passwords in git history, project files and served build output (values never shown)",
+                 [], _secrets, secrets),
+]