ikanban 0.4.9 → 0.5.1

package/scanners/ikanban-controlscan.py

@@ -0,0 +1,783 @@
+#!/usr/bin/env python3
+"""
+ikanban-controlscan — checks the security controls of YOUR OWN repository (plan 5 X4).
+
+    python3 ikanban-controlscan.py --path .                    # check, print the result
+    python3 ikanban-controlscan.py --publish --team TEAM_ID    # also file it into iKanban
+
+The 8 repository checks, each pass / warn / fail / skipped with the reason:
+
+  Supply chain & dependency scanning
+    ci-dependency-audit   a CI workflow runs a dependency audit, or Dependabot or Renovate is configured
+    lockfiles-committed   every package manifest has its lockfile in git
+  Code & secrets scanning
+    ci-secret-scanning    a CI workflow runs gitleaks, trufflehog or detect-secrets (or GitHub secret
+                          scanning with push protection is on, read through your own gh sign-in)
+    ci-sast               a CI workflow runs CodeQL, Semgrep or another SAST tool
+    env-files-ignored     no .env or private key file is tracked in git; .gitignore covers .env
+  Repository & access
+    branch-protection     the default branch blocks force-push and deletion and needs a pull request
+                          (GitHub API through your own `gh`; skipped without gh or its sign-in)
+  Security process
+    codeowners            a CODEOWNERS file names owners
+    security-policy       SECURITY.md says how to report a vulnerability
+
+No network, except the GitHub API through the user's own `gh` (branch protection, secret scanning).
+--publish sends one POST /api/teams/{team}/security/scan-findings per control (kind ctl-<key>):
+a failed check files one Medium finding, a warning one Low finding, a pass none; a skipped check
+is sent as an incomplete run, so nothing closes. Standard library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+CONTROLSCAN_VERSION = "1.0.0"
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+SUPPLY, CODE, ACCESS, PROCESS = ("Supply chain & dependency scanning", "Code & secrets scanning",
+                                 "Repository & access", "Security process")
+
+# The control list of plan 5 X4 (the server computes findings-lifecycle and ai-red-team-fresh).
+CONTROLS = [
+    {"key": "ci-dependency-audit", "group": SUPPLY, "title": "CI audits dependencies",
+     "fix": "Add a dependency audit step to CI (npm audit, cargo audit, pip-audit, osv-scanner, ikanban secscan) "
+            "or configure Dependabot (.github/dependabot.yml) or Renovate."},
+    {"key": "lockfiles-committed", "group": SUPPLY, "title": "Lockfiles are committed",
+     "fix": "Commit the lockfile next to each manifest (package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.lock, "
+            "poetry.lock or uv.lock, Gemfile.lock, go.sum, composer.lock)."},
+    {"key": "ci-secret-scanning", "group": CODE, "title": "CI scans for secrets",
+     "fix": "Run gitleaks, trufflehog or detect-secrets in CI, or turn on GitHub secret scanning with push protection."},
+    {"key": "ci-sast", "group": CODE, "title": "CI runs static analysis (SAST)",
+     "fix": "Run CodeQL (github/codeql-action), Semgrep or another SAST tool in CI."},
+    {"key": "env-files-ignored", "group": CODE, "title": ".env and key files stay out of git",
+     "fix": "Remove the file from git (git rm --cached FILE), rotate what it held, and add .env and key "
+            "files to .gitignore."},
+    {"key": "branch-protection", "group": ACCESS, "title": "Default branch is protected",
+     "fix": "Protect the default branch: block force-push and deletion and require a pull request "
+            "(GitHub: Settings, Rules or Branches)."},
+    {"key": "codeowners", "group": ACCESS, "title": "CODEOWNERS names owners",
+     "fix": "Add a CODEOWNERS file (root, .github/ or docs/) with at least one line like `* @org/team`."},
+    {"key": "security-policy", "group": PROCESS, "title": "SECURITY.md says how to report a vulnerability",
+     "fix": "Add SECURITY.md with a contact: an email address or a private reporting link."},
+]
+CONTROL = {c["key"]: c for c in CONTROLS}
+
+CI_FILES = (".gitlab-ci.yml", "azure-pipelines.yml", "bitbucket-pipelines.yml", ".circleci/config.yml",
+            "Jenkinsfile", ".travis.yml", ".drone.yml", "buildspec.yml", "cloudbuild.yaml")
+AUDIT_TOOLS = re.compile(r"(?i)\b(?:npm|pnpm|yarn|bun)\s+(?:npm\s+)?audit\b|\bcargo[- ](?:audit|deny)\b|\bpip-audit\b|"
+                         r"\bsafety\s+(?:check|scan)\b|\bosv-scanner\b|\btrivy\s+(?:fs|repo)\b|\bsnyk\s+test\b|"
+                         r"dependency-check|dependency-review-action|\bgovulncheck\b|\bbundle(?:r|-)?\s*audit\b|"
+                         r"\bikanban\s+secscan\b|\bgrype\b")
+SECRET_TOOLS = re.compile(r"(?i)\bgitleaks\b|\btrufflehog\b|\bdetect-secrets\b|\bggshield\b|\bsecretlint\b|"
+                          r"\bikanban\s+secscan\b")
+SAST_TOOLS = re.compile(r"(?i)codeql|\bsemgrep\b|\bsonar(?:cloud|qube|-scanner)?\b|\bsnyk\s+code\b|\bbandit\b|"
+                        r"\bgosec\b|\bbrakeman\b|\bnjsscan\b|\bhorusec\b|checkmarx|\bbearer\b|\bopengrep\b")
+LOCKS = {
+    "package.json": ("package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "bun.lock"),
+    "Cargo.toml": ("Cargo.lock",),
+    "pyproject.toml": ("poetry.lock", "uv.lock", "pdm.lock", "Pipfile.lock", "requirements.txt"),
+    "Pipfile": ("Pipfile.lock",),
+    "Gemfile": ("Gemfile.lock",),
+    "go.mod": ("go.sum",),
+    "composer.json": ("composer.lock",),
+}
+SECRET_FILE = re.compile(r"(?i)(?:^|/)(?:\.env(?:\.[^/]*)?|id_rsa|id_dsa|id_ecdsa|id_ed25519|[^/]*\.(?:pem|key|p12|pfx|jks))$")
+SECRET_FILE_OK = re.compile(r"(?i)\.(?:example|sample|template|dist|defaults?)$|\.pub$")
+
+
+def result(key: str, status: str, reason: str) -> dict:
+    c = CONTROL[key]
+    return {"key": key, "group": c["group"], "title": c["title"], "status": status, "reason": reason}
+
+
+def git(root: Path, *args, timeout=20):
+    """(exit code, stdout); never raises."""
+    try:
+        p = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, timeout=timeout)
+        return p.returncode, p.stdout
+    except (OSError, subprocess.SubprocessError):
+        return 127, ""
+
+
+class Repo:
+    """What every check reads, gathered once: tracked files and the CI configuration text."""
+
+    def __init__(self, root: Path):
+        self.root = root
+        code, top = git(root, "rev-parse", "--show-toplevel")
+        self.is_git = code == 0 and bool(top.strip())
+        code, out = git(root, "ls-files", "-z") if self.is_git else (1, "")
+        self.tracked = sorted(f for f in out.split("\0") if f) if code == 0 else []
+        self.ci = {}
+        wf = root / ".github" / "workflows"
+        names = sorted(p for p in wf.glob("*.y*ml")) if wf.is_dir() else []
+        names += [root / n for n in CI_FILES if (root / n).is_file()]
+        for p in names:
+            try:
+                self.ci[p.relative_to(root).as_posix()] = p.read_text(encoding="utf-8", errors="replace")[:1_000_000]
+            except OSError:
+                continue
+
+    def ci_match(self, rx):
+        return sorted(name for name, text in self.ci.items() if rx.search(text))
+
+    def first_file(self, *rels):
+        for rel in rels:
+            p = self.root / rel
+            if p.is_file():
+                return p
+        return None
+
+
+# ── the GitHub API, only through the user's own gh ──────────────────────────────
+def gh_ready() -> bool:
+    """gh is installed and signed in."""
+    if not shutil.which("gh"):
+        return False
+    try:
+        return subprocess.run(["gh", "auth", "status"], capture_output=True, text=True, timeout=20).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def gh_json(path: str):
+    """(ok, data | error text) for `gh api <path>`; the path is built from checked parts only."""
+    try:
+        p = subprocess.run(["gh", "api", "-H", "Accept: application/vnd.github+json", path],
+                           capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError) as e:
+        return False, str(e)
+    if p.returncode != 0:
+        return False, (p.stderr or p.stdout).strip()[:200]
+    try:
+        return True, json.loads(p.stdout or "null")
+    except ValueError:
+        return False, "gh api did not answer JSON"
+
+
+GITHUB_SLUG = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+
+
+def github_slug(root: Path) -> str | None:
+    _, url = git(root, "remote", "get-url", "origin")
+    url = url.strip()
+    if not re.match(r"^(?:https://(?:[^@/]+@)?github\.com/|git@github\.com:|ssh://git@github\.com/)", url):
+        return None
+    slug = normalize_remote(url)
+    return slug if GITHUB_SLUG.match(slug) and ".." not in slug else None
+
+
+# ── the checks ──────────────────────────────────────────────────────────────────
+def check_dependency_audit(r: Repo) -> dict:
+    hits = r.ci_match(AUDIT_TOOLS)
+    if hits:
+        return result("ci-dependency-audit", "pass", f"dependency audit in {', '.join(hits)}")
+    bot = r.first_file(".github/dependabot.yml", ".github/dependabot.yaml", "renovate.json", "renovate.json5",
+                       ".github/renovate.json", ".github/renovate.json5", ".renovaterc", ".renovaterc.json",
+                       ".gitlab/renovate.json")
+    if bot:
+        return result("ci-dependency-audit", "pass", f"{bot.relative_to(r.root).as_posix()} is configured")
+    where = f"{len(r.ci)} CI file(s) read" if r.ci else "no CI workflow found"
+    return result("ci-dependency-audit", "fail", f"no dependency audit step in CI ({where}) and no Dependabot "
+                                                 "or Renovate config")
+
+
+def check_lockfiles(r: Repo) -> dict:
+    if not r.is_git:
+        return result("lockfiles-committed", "skipped", "not a git repository: cannot tell what is committed")
+    tracked = set(r.tracked)
+    manifests = [f for f in r.tracked if f.rsplit("/", 1)[-1] in LOCKS
+                 and "node_modules/" not in f and "vendor/" not in f]
+    if not manifests:
+        return result("lockfiles-committed", "skipped", "no package manifest is tracked in git")
+    missing = []
+    for m in manifests:
+        folder, name = (m.rsplit("/", 1) if "/" in m else ("", m))
+        parts = folder.split("/") if folder else []
+        dirs = ["/".join(parts[:i]) for i in range(len(parts), -1, -1)]  # the folder, then each parent
+        if not any(f"{d}/{lock}".lstrip("/") in tracked for d in dirs for lock in LOCKS[name]):
+            missing.append(m)
+    if missing:
+        more = f" and {len(missing) - 10} more" if len(missing) > 10 else ""
+        return result("lockfiles-committed", "fail", f"no committed lockfile for {', '.join(missing[:10])}{more}")
+    return result("lockfiles-committed", "pass", f"{len(manifests)} manifest(s), each with a committed lockfile")
+
+
+def github_secret_scanning(slug: str):
+    """(status, reason) from the repository's security_and_analysis, or None when it cannot be read."""
+    ok, data = gh_json(f"repos/{slug}")
+    sa = (data or {}).get("security_and_analysis") if ok and isinstance(data, dict) else None
+    if not sa:
+        return None
+    on = (sa.get("secret_scanning") or {}).get("status") == "enabled"
+    push = (sa.get("secret_scanning_push_protection") or {}).get("status") == "enabled"
+    if on and push:
+        return "pass", "GitHub secret scanning with push protection is on"
+    if on:
+        return "warn", "GitHub secret scanning is on, but push protection is off"
+    return None
+
+
+def check_secret_scanning(r: Repo) -> dict:
+    hits = r.ci_match(SECRET_TOOLS)
+    if hits:
+        return result("ci-secret-scanning", "pass", f"secret scanning in {', '.join(hits)}")
+    slug = github_slug(r.root) if r.is_git else None
+    if slug and gh_ready():
+        got = github_secret_scanning(slug)
+        if got:
+            return result("ci-secret-scanning", *got)
+    note = "" if slug and gh_ready() else "; GitHub secret scanning not read (needs a GitHub origin and gh signed in)"
+    return result("ci-secret-scanning", "fail", f"no CI step runs gitleaks, trufflehog or detect-secrets{note}")
+
+
+def check_sast(r: Repo) -> dict:
+    hits = r.ci_match(SAST_TOOLS)
+    if hits:
+        return result("ci-sast", "pass", f"static analysis in {', '.join(hits)}")
+    where = f"{len(r.ci)} CI file(s) read" if r.ci else "no CI workflow found"
+    return result("ci-sast", "fail", f"no CodeQL, Semgrep or other SAST step in CI ({where})")
+
+
+def check_env_files(r: Repo) -> dict:
+    if not r.is_git:
+        return result("env-files-ignored", "skipped", "not a git repository: cannot tell what is committed")
+    bad = [f for f in r.tracked if SECRET_FILE.search(f) and not SECRET_FILE_OK.search(f)]
+    if bad:
+        more = f" and {len(bad) - 10} more" if len(bad) > 10 else ""
+        return result("env-files-ignored", "fail", f"tracked in git: {', '.join(bad[:10])}{more}")
+    code, _ = git(r.root, "check-ignore", "-q", "--no-index", ".env")
+    if code != 0:
+        return result("env-files-ignored", "warn", "no .env or key file is tracked, but .gitignore does not cover .env")
+    return result("env-files-ignored", "pass", "no .env or key file is tracked; .gitignore covers .env")
+
+
+def check_branch_protection(r: Repo) -> dict:
+    if not r.is_git:
+        return result("branch-protection", "skipped", "not a git repository")
+    slug = github_slug(r.root)
+    if not slug:
+        return result("branch-protection", "skipped", "origin is not a GitHub repository; check the host's "
+                                                      "branch rules by hand")
+    if not gh_ready():
+        return result("branch-protection", "skipped", "needs the GitHub CLI (gh) installed and signed in "
+                                                      "(gh auth login)")
+    ok, repo = gh_json(f"repos/{slug}")
+    branch = repo.get("default_branch") if ok and isinstance(repo, dict) else None
+    if not branch or not re.match(r"^[A-Za-z0-9._/-]+$", branch) or ".." in branch:
+        return result("branch-protection", "skipped", f"GitHub API: could not read {slug} ({repo if not ok else 'no default branch'})")
+    b = urllib.parse.quote(branch, safe="")
+    ok_rules, rules = gh_json(f"repos/{slug}/rules/branches/{b}")
+    types = {x.get("type") for x in rules if isinstance(x, dict)} if ok_rules and isinstance(rules, list) else set()
+    ok_prot, prot = gh_json(f"repos/{slug}/branches/{b}/protection")
+    prot = prot if ok_prot and isinstance(prot, dict) else {}
+    if not ok_rules and not ok_prot and "404" not in f"{rules}{prot}":
+        return result("branch-protection", "skipped", f"GitHub API: could not read the rules of {branch}")
+    no_force = "non_fast_forward" in types or (prot and not (prot.get("allow_force_pushes") or {}).get("enabled", True))
+    no_delete = "deletion" in types or (prot and not (prot.get("allow_deletions") or {}).get("enabled", True))
+    needs_pr = "pull_request" in types or bool(prot.get("required_pull_request_reviews"))
+    missing = [label for label, ok in (("force-push is not blocked", no_force), ("deletion is not blocked", no_delete),
+                                       ("no pull request is required", needs_pr)) if not ok]
+    if missing:
+        return result("branch-protection", "fail", f"{branch}: {'; '.join(missing)}")
+    return result("branch-protection", "pass", f"{branch} blocks force-push and deletion and needs a pull request")
+
+
+OWNER = re.compile(r"(?:^|\s)(?:@[\w.-]+(?:/[\w.-]+)?|[\w.+-]+@[\w-]+\.[\w.-]+)")
+
+
+def check_codeowners(r: Repo) -> dict:
+    f = r.first_file(".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS", ".gitlab/CODEOWNERS")
+    if not f:
+        return result("codeowners", "fail", "no CODEOWNERS file in the root, .github/, docs/ or .gitlab/")
+    rel = f.relative_to(r.root).as_posix()
+    lines = [ln for ln in f.read_text(encoding="utf-8", errors="replace").splitlines()
+             if ln.strip() and not ln.lstrip().startswith("#")]
+    if not any(OWNER.search(ln) for ln in lines):
+        return result("codeowners", "warn", f"{rel} names no owner (@user, @org/team or an email)")
+    return result("codeowners", "pass", f"{rel} names owners on {len(lines)} line(s)")
+
+
+CONTACT = re.compile(r"(?i)[\w.+-]+@[\w-]+\.[\w.-]+|https?://\S+|security/advisories|private vulnerability report")
+
+
+def check_security_policy(r: Repo) -> dict:
+    found = None
+    for folder in ("", ".github", "docs"):
+        d = r.root / folder if folder else r.root
+        if d.is_dir():
+            found = next((p for p in sorted(d.iterdir()) if p.is_file() and p.name.lower() == "security.md"), None)
+        if found:
+            break
+    if not found:
+        return result("security-policy", "fail", "no SECURITY.md in the root, .github/ or docs/")
+    rel = found.relative_to(r.root).as_posix()
+    if not CONTACT.search(found.read_text(encoding="utf-8", errors="replace")):
+        return result("security-policy", "warn", f"{rel} gives no contact (an email or a reporting link)")
+    return result("security-policy", "pass", f"{rel} says how to report a vulnerability")
+
+
+CHECKS = [check_dependency_audit, check_lockfiles, check_secret_scanning, check_sast, check_env_files,
+          check_branch_protection, check_codeowners, check_security_policy]
+
+
+def run_checks(root: Path) -> list:
+    r = Repo(root)
+    out = []
+    for check in CHECKS:
+        try:
+            out.append(check(r))
+        except Exception as e:  # noqa: BLE001 — one broken check never hides the others
+            key = CONTROLS[len(out)]["key"]
+            out.append(result(key, "skipped", f"the check stopped: {type(e).__name__}"))
+    return out
+
+
+# ── report and publish ──────────────────────────────────────────────────────────
+MARK = {"pass": "✅ pass", "warn": "⚠️ warn", "fail": "❌ fail", "skipped": "⏭ skipped"}
+
+
+def build_report(name: str, results: list) -> tuple:
+    counts = {s: sum(1 for x in results if x["status"] == s) for s in ("pass", "warn", "fail", "skipped")}
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    L = [f"# Repository controls — {name}", "", f"_{stamp} · `ikanban-controlscan`_", "",
+         "| Control | Group | Result | Why |", "|---|---|---|---|"]
+    L += [f"| {x['key']} | {x['group']} | {MARK[x['status']]} | {x['reason']} |" for x in results]
+    L += ["", f"**{counts['pass']} pass, {counts['warn']} warn, {counts['fail']} fail, {counts['skipped']} skipped.**", ""]
+    for x in results:
+        if x["status"] in ("fail", "warn"):
+            L.append(f"- **{x['key']}**: {CONTROL[x['key']]['fix']}")
+    L += ["", "A skipped check is a gap, not a pass: its control stays unchecked in iKanban."]
+    return "\n".join(L), counts
+
+
+def finding_key(kind: str, scope: str) -> str:
+    return "controlscan-" + hashlib.sha256(f"{kind}|{scope}".encode()).hexdigest()[:16]
+
+
+def publish_bodies(results: list, scope: str) -> list:
+    """[(kind, scan-findings body)] — one per control; every text field through scrub_text."""
+    out = []
+    for x in results:
+        kind = f"ctl-{x['key']}"
+        findings = []
+        if x["status"] in ("fail", "warn"):
+            findings.append(scrub_finding({
+                "finding_key": finding_key(kind, scope),
+                "owasp_category": x["group"],
+                "severity": "Medium" if x["status"] == "fail" else "Low",
+                "title": f"{CONTROL[x['key']]['title']}: {x['status']}"[:300],
+                "location_file": None,
+                "location_lines": None,
+                "remediation": f"{x['reason']}. {CONTROL[x['key']]['fix']}"[:2000],
+            }))
+        out.append((kind, {"findings": findings, "scope": scope, "complete": x["status"] != "skipped", "kind": kind}))
+    return out
+
+
+def publish(results: list, scope: str, args) -> int:
+    for kind, body in publish_bodies(results, scope):
+        ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token, body)
+        if not ok:
+            print(f"filing {kind} FAILED: {data or 'this iKanban server does not take repository controls yet'}",
+                  file=sys.stderr)
+            return 2
+    print(f"filed {len(results)} repository controls for {scope}", file=sys.stderr)
+    return 0
+
+
+# ── copied from ikanban-secscan.py: scope, key-host pinning, API, work folder, Pipelines ──────
+def normalize_remote(url: str) -> str:
+    """owner/repo from any remote style (scp, https, ssh, a host alias), lower case;
+    never the user or a token in the URL."""
+    path = re.sub(r"^[a-z+]+://[^/]*/?", "", url.strip())   # scheme, user, host[:port]
+    if path == url.strip():
+        path = path.split(":", 1)[-1]                       # scp style user@host:path
+    path = path.strip("/")
+    path = path[:-4] if path.endswith(".git") else path
+    return "/".join(path.split("/")[-2:]).lower() if path else ""
+
+
+def scan_scope(root: Path) -> str:
+    """Plan 11 H3: which repository a scan covers, the same on every laptop and agent
+    run (an agent's run folder is named by its run id): origin's owner/repo, else the
+    repository's folder name; plus the subfolder when --path is one. A rescan closes
+    only findings of the same scope."""
+    root = root.resolve()
+
+    def git(*a):
+        try:
+            return subprocess.run(["git", "-C", str(root), *a], capture_output=True,
+                                  text=True, timeout=10).stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            return ""
+    top = git("rev-parse", "--show-toplevel")
+    base = Path(top).resolve() if top else root
+    base_name = normalize_remote(git("remote", "get-url", "origin")) or base.name.lower()
+    sub = root.relative_to(base).as_posix() if base in root.parents else ""
+    return f"{base_name}/{sub}" if sub else base_name
+
+
+# Coding standard T3: the iKanban key goes only to iKanban's API (or this machine), and never
+# on a redirect. A --base-url, IKANBAN_BASE_URL or config file cannot send it anywhere else.
+IKANBAN_APIS = ("https://api.i-kanban.com", "https://dev-api.i-kanban.com")
+
+
+def ikanban_api(base_url):
+    """The origin of base_url if it is iKanban's API; otherwise stop, naming it (never the key)."""
+    u = urllib.parse.urlsplit(base_url or "")
+    origin = f"{u.scheme}://{u.netloc}"
+    if u.username is None and u.path in ("", "/") and not u.query and (
+            origin in IKANBAN_APIS or (u.scheme == "http" and u.hostname in ("127.0.0.1", "localhost", "::1"))):
+        return origin
+    raise SystemExit(f"error: {base_url or '(empty)'} is not an iKanban API "
+                     f"({', '.join(IKANBAN_APIS)} or this machine); the key was not sent")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None  # a 3xx comes back as an HTTPError, and the key goes nowhere else
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def api(method: str, path: str, base_url: str, token: str, payload=None):
+    """(ok, data | error text | None for 404)."""
+    req = urllib.request.Request(
+        f"{ikanban_api(base_url)}/api{path}",
+        data=json.dumps(payload).encode() if payload is not None else None,
+        headers={"Authorization": f"Bearer {token}",
+                 "Content-Type": "application/json"},
+        method=method,
+    )
+    try:
+        with _OPENER.open(req, timeout=30) as r:
+            body = json.loads(r.read().decode() or "{}")
+        return True, body.get("data", body)
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode()[:300]
+        if e.code in (404, 405) and not detail.strip():
+            return False, None  # an unknown route: GET answers 404, POST 405, both empty
+        return False, f"HTTP {e.code}: {detail}"
+    except Exception as e:  # noqa: BLE001 — surface any transport failure verbatim
+        return False, str(e)
+
+
+# ── Scan work folder (plan 11 H12-T10, owner): raw tool output and the report live under
+# <repo>/.iKanban/scans/<scanner>-<UTC time>/, never the system temp folder. The scans folder
+# holds its own .gitignore ("*"), so nothing in it is committed and no repo .gitignore is edited.
+def add_work_dir_arg(ap):
+    ap.add_argument("--work-dir", default=os.environ.get("IKANBAN_SCAN_DIR", ""),
+                    help="Folder for this scan's files (or IKANBAN_SCAN_DIR; default "
+                         "<repository>/.iKanban/scans)")
+    ap.add_argument("--print-report", action="store_true",
+                    help="Print the full report on stdout (under the ikanban CLI stdout otherwise shows the "
+                         "counts and `ikanban scans show <id>`)")
+
+
+def scan_work_dir(scanner: str, base: Path, override: str = "") -> Path:
+    # Plan 5 X3: the ikanban CLI hands over a private temp folder (IKANBAN_SCAN_DIR) and the scan id
+    # (IKANBAN_SCAN_ID). That folder is this run's folder; the CLI seals it into ~/.ikanban/scans.
+    cli_dir = os.environ.get("IKANBAN_SCAN_DIR", "")
+    if override and cli_dir and os.environ.get("IKANBAN_SCAN_ID") and (
+            Path(override).expanduser().resolve() == Path(cli_dir).expanduser().resolve()):
+        run_dir = Path(cli_dir).expanduser().resolve()
+        run_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        os.chmod(run_dir, 0o700)
+        return run_dir
+    scans = Path(override).expanduser().resolve() if override else base / ".iKanban" / "scans"
+    scans.mkdir(parents=True, exist_ok=True)
+    ignore = scans / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text("*\n")
+    run_dir = scans / f"{scanner}-{datetime.now(timezone.utc):%Y%m%d-%H%M%S}"
+    run_dir.mkdir(mode=0o700, exist_ok=True)
+    os.chmod(run_dir, 0o700)  # mkdir's mode is masked by umask; raw tool output stays private
+    return run_dir
+
+
+def write_private(path: Path, text: str) -> None:
+    """Write a file (0600) without following a symlink planted at its name: write a new
+    temp file next to it (O_EXCL | O_NOFOLLOW), then rename it over the name."""
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, path)
+
+
+def slug(text: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", text).strip("_")[:80] or "x"
+
+
+# ── scrub_text: identical in every scanner (test_scrub_text.py compares the copies) ──────────
+# Plan 5 X2-T1: every text field of every finding passes through scrub_text before it leaves this
+# machine. A secret keeps its first 4 characters; a home folder becomes ~. The server scrubs again.
+_SCRUB_CUT = (
+    re.compile(r"-{5}BEGIN [A-Z ]*PRIVATE KEY-{5}.*?(?:-{5}END [A-Z ]*PRIVATE KEY-{5}|\Z)", re.S),
+    re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"),
+    re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{22,}\b"),
+    re.compile(r"\bglpat-[A-Za-z0-9_-]{20,}\b"),
+    re.compile(r"\bxox[abposr]-[A-Za-z0-9-]{10,}\b"),
+    re.compile(r"\b(?:sk|rk)_live_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{24,}\b"),
+    re.compile(r"\bwhsec_[A-Za-z0-9]{16,}\b"),
+    re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"),
+    re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b"),
+    re.compile(r"\bvk_[A-Za-z0-9_-]{8,}"),
+)
+_SCRUB_ASSIGNED = re.compile(
+    r"(?i)(\b(?:aws_secret_access_key|aws_session_token|client_secret|secret_key|private_key|api[_-]?key|"
+    r"access[_-]?token|auth[_-]?token|token|password|passwd|pwd|secret)\b[\"']?\s*[:=]\s*[\"']?)([^\s\"',;&]+)")
+_SCRUB_BEARER = re.compile(r"(?i)(\b(?:bearer|basic)\s+)([A-Za-z0-9._~+/=-]{12,})")
+_SCRUB_URL_CREDS = re.compile(r"(\b[a-z][a-z0-9+.-]*://[^\s/:@]+:)([^\s@/]+)(@)")
+_SCRUB_HOME = re.compile(r"(?<![\w.-])(?:[A-Za-z]:\\[Uu]sers\\|/Users/|/home/)[^\\/\s\"'<>]+")
+
+
+def scrub_text(text) -> str:
+    """Secrets, iKanban keys, tokens, AWS and GitHub keys, private key blocks and home folders
+    cut from one text. None becomes ""."""
+    if text is None:
+        return ""
+    text = str(text)
+    for rx in _SCRUB_CUT:
+        text = rx.sub(lambda m: m.group(0)[:4] + "…[hidden]", text)
+    text = _SCRUB_ASSIGNED.sub(
+        lambda m: m.group(1) + "[hidden]" if len(m.group(2)) >= 8 or any(c.isdigit() for c in m.group(2))
+        else m.group(0), text)
+    text = _SCRUB_BEARER.sub(lambda m: m.group(1) + "[hidden]", text)
+    text = _SCRUB_URL_CREDS.sub(lambda m: m.group(1) + "[hidden]" + m.group(3), text)
+    home = str(Path.home())
+    if home and home not in ("/", "\\") and home in text:
+        text = text.replace(home, "~")
+    return _SCRUB_HOME.sub("~", text)
+
+
+def scrub_finding(value):
+    """scrub_text on every string in a finding, through nested dicts and lists; other values stay."""
+    if isinstance(value, str):
+        return scrub_text(value)
+    if isinstance(value, dict):
+        return {k: scrub_finding(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [scrub_finding(v) for v in value]
+    return value
+
+
+# ── end scrub_text ──
+
+
+# ── Pipelines (plan 11 H12, owner): with --task, the scan shows in that task's Pipelines view ──
+# Same calls as `ikanban pipeline` (vibe-cli/lib/pipeline.js → routes/pipeline.rs): an event
+# "running" at the start, "passed" / "failed" / "skipped" at the end with a one-line detail,
+# then that line as the log (plan 5: never the report). A plan without Pipelines (402) or any error never fails the scan.
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+# Every iKanban scanner reports into one named lane, not the server's "legacy" lane.
+PIPE_RUN = "security-scan"
+PIPE_CHUNK = 15 * 1024  # the server takes 16 KB per log line
+LAST_RUN = {"report": "", "detail": "", "skipped": False}
+
+
+def add_pipeline_args(ap):
+    ap.add_argument("--task", default=os.environ.get("IKANBAN_TASK", ""),
+                    help="Also show this run in the task's Pipelines (a key like IKA-123, or its id; "
+                         "or IKANBAN_TASK)")
+    ap.add_argument("--task-team", default=os.environ.get("IKANBAN_TASK_TEAM", ""),
+                    help="The task's team: id or identifier like IKA (or IKANBAN_TASK_TEAM; default --team)")
+
+
+def summary_detail(counts: dict, total: int, skipped: list) -> str:
+    if skipped and not total and all(s for s in skipped):
+        return ("SKIPPED: " + "; ".join(skipped))[:300]
+    worst = ", ".join(f"{counts[s]} {s}" for s in ("critical", "high", "medium", "low") if counts.get(s))
+    return f"{total} findings" + (f": {worst}" if worst else "")
+
+
+def mask_report(text: str) -> str:
+    """scrub_text before a line leaves for Pipelines, plus a scanner's own rules (scrub_report)."""
+    text = scrub_text(text)
+    scrub = globals().get("scrub_report")
+    return scrub(text)[0] if scrub else text
+
+
+def show_report(md: str, summary: str, print_report: bool = False) -> None:
+    """Plan 5 X3: under the ikanban CLI (IKANBAN_SCAN_ID set) stdout gets the counts and where the
+    full report is stored; the body only with --print-report. A plain python run prints the body."""
+    scan_id = os.environ.get("IKANBAN_SCAN_ID", "")
+    if scan_id and not print_report:
+        print(summary)
+        print(f"Full report: ikanban scans show {scan_id}")
+    else:
+        print(md)
+
+
+def scan_files_note(work: Path) -> str:
+    """Where this run's files are: the encrypted store under the CLI, else the run folder."""
+    scan_id = os.environ.get("IKANBAN_SCAN_ID", "")
+    return f"scan files: sealed into ~/.ikanban/scans as {scan_id}" if scan_id else f"scan files: {work}"
+
+
+
+# The running Pipeline (set by run_main with --task). Owner: Pipelines showed nothing while a
+# scan ran, so each step also sends one line as it starts and ends; the one-line summary follows at the end.
+# Progress lines are fixed status text: never raw tool output or an error body (it can carry
+# secrets or text an attacker wrote). Those stay on local stderr and in the masked report.
+PIPE = None
+
+
+def progress(text: str) -> None:
+    if os.environ.get("IKANBAN_SCAN_ID") and "--json" not in sys.argv:
+        print(text, flush=True)  # Plan 5: under the CLI stdout shows progress, not the report
+    if PIPE:
+        PIPE.log(text)
+
+
+
+class Pipeline:
+    def __init__(self, stage, task, team, base_url, token):
+        self.stage, self.task, self.team, self.base, self.token = stage, task, team, base_url, token
+        self.on = bool(task and team and token)
+        self.tid = None
+
+    def _off(self, why):
+        self.on = False
+        note = "the plan does not include Pipelines" if "402" in str(why) else why
+        print(f"ikanban: Pipelines not updated ({note}); the scan goes on", file=sys.stderr)
+
+    def _call(self, method, path, body=None):
+        try:
+            return api(method, path, self.base, self.token, body)
+        except SystemExit as e:  # ikanban_api refuses a base URL that is not iKanban's
+            return False, str(e)
+
+    def _post(self, path, body):
+        if not self.on:
+            return
+        if self.tid is None:
+            if _UUID.match(self.team):
+                self.tid = self.team
+            else:
+                ok, teams = self._call("GET", "/teams")
+                if not ok:
+                    return self._off(teams)
+                found = [t.get("id") for t in teams or [] if (t.get("identifier") or "").lower() == self.team.lower()]
+                if not found:
+                    return self._off(f"team {self.team} not found among your teams")
+                self.tid = found[0]
+        ok, data = self._call("POST", f"/teams/{self.tid}/{path}", body)
+        if not ok:
+            self._off(data or "this iKanban server has no Pipelines")
+
+    def start(self):
+        self._post("pipeline-events", {"task": self.task, "stage": self.stage, "status": "running",
+                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}"})
+
+    def log(self, line):
+        """One progress line, sent as it happens (masked like the report). A failure only turns Pipelines off."""
+        self._post("pipeline-logs", {"task": self.task, "run": PIPE_RUN, "stage": self.stage,
+                                     "text": mask_report(line.rstrip("\n"))[:PIPE_CHUNK - 1] + "\n"})
+
+    def finish(self, code):
+        status = "failed" if code else ("skipped" if LAST_RUN["skipped"] else "passed")
+        detail = LAST_RUN["detail"] or ("the scan stopped with an error" if code == 2 else "")
+        if code == 1 and not LAST_RUN["skipped"]:
+            detail = (detail + " (at or above --fail-on)").strip()
+        self._post("pipeline-events", {"task": self.task, "stage": self.stage, "status": status,
+                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}",
+                                       "detail": detail[:300] or None})
+        # Plan 5 X1-T2: the summary only; the report stays on the machine that ran the scan.
+        summary = f"{self.stage} {status}" + (f": {detail[:300]}" if detail else "")
+        self._post("pipeline-logs", {"task": self.task, "run": PIPE_RUN, "stage": self.stage,
+                                     "text": mask_report(summary) + "\n"})
+
+
+def run_main(stage, main_fn, argv=None):
+    """main() as it is, wrapped in Pipelines events when --task is given."""
+    raw = sys.argv[1:] if argv is None else argv
+    if any(a in ("-h", "--help", "--version", "--list-apps") for a in raw):
+        return main_fn(argv)
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--task", default=os.environ.get("IKANBAN_TASK", ""))
+    pre.add_argument("--task-team", default=os.environ.get("IKANBAN_TASK_TEAM", ""))
+    pre.add_argument("--team", default=os.environ.get("IKANBAN_TEAM_ID", ""))
+    pre.add_argument("--token", default=os.environ.get("VIBE_API_TOKEN", ""))
+    pre.add_argument("--base-url", default=os.environ.get("IKANBAN_BASE_URL", "https://api.i-kanban.com"))
+    known, _ = pre.parse_known_args(raw)
+    pl = Pipeline(stage, known.task, known.task_team or known.team, known.base_url, known.token)
+    pl.start()
+    global PIPE
+    PIPE = pl if pl.on else None
+    try:
+        code = main_fn(argv)
+    except SystemExit as e:
+        if not isinstance(e.code, int):
+            print(e.code, file=sys.stderr)
+        code = e.code if isinstance(e.code, int) else 2
+    pl.finish(code)
+    return code
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Repository security controls check that reports into iKanban.")
+    ap.add_argument("--version", action="version", version=f"ikanban controlscan {CONTROLSCAN_VERSION}")
+    ap.add_argument("--path", default=".", help="Repository to check (default: cwd)")
+    ap.add_argument("--publish", action="store_true",
+                    help="File the control results into iKanban (one per control; the report stays here)")
+    ap.add_argument("--team", default=os.environ.get("IKANBAN_TEAM_ID", ""),
+                    help="Team UUID to publish into (or IKANBAN_TEAM_ID)")
+    ap.add_argument("--base-url", default=os.environ.get("IKANBAN_BASE_URL", "https://api.i-kanban.com"))
+    ap.add_argument("--token", default=os.environ.get("VIBE_API_TOKEN", ""),
+                    help="Personal API key (or VIBE_API_TOKEN)")
+    ap.add_argument("--out", default=None, help="Also write the report here")
+    ap.add_argument("--json", action="store_true", help="Machine-readable result")
+    add_pipeline_args(ap)
+    add_work_dir_arg(ap)
+    args = ap.parse_args(argv)
+
+    root = Path(args.path).expanduser().resolve()
+    if not root.is_dir():
+        print(f"error: {root} is not a directory", file=sys.stderr)
+        return 2
+    if args.publish and (not args.token or not args.team):
+        print("error: --publish needs --token (or VIBE_API_TOKEN) and --team (or IKANBAN_TEAM_ID)", file=sys.stderr)
+        return 2
+    work = scan_work_dir("controlscan", root, args.work_dir)
+    progress(f"controlscan {CONTROLSCAN_VERSION} · {root.name}")
+    results = run_checks(root)
+    for x in results:
+        progress(f"{x['key']} … {x['status']}")
+    md, counts = build_report(root.name, results)
+    detail = f"{counts['pass']} pass, {counts['warn']} warn, {counts['fail']} fail, {counts['skipped']} skipped"
+    LAST_RUN.update(report=md, detail=detail, skipped=counts["skipped"] == len(results))
+    write_private(work / "report.md", md)
+    write_private(work / "controls.json", json.dumps(results, indent=2))
+    if args.out:
+        Path(args.out).write_text(md, encoding="utf-8")
+    if args.json:
+        print(json.dumps({"path": str(root), "controls": results, "counts": counts}, indent=2))
+    else:
+        show_report(md, detail, args.print_report)
+    sys.stdout.flush()
+    print(scan_files_note(work), file=sys.stderr)
+    if args.publish:
+        return publish(results, scan_scope(root), args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_main("controlscan", main))