ikanban 0.4.8 → 0.5.0

package/scanners/ikanban-import.py

@@ -0,0 +1,597 @@
+#!/usr/bin/env python3
+"""
+ikanban-import — turns another scanner's SARIF 2.1.0 file into iKanban code findings (plan 5 X1-T4).
+
+    python3 ikanban-import.py codeql.sarif                           # read it, print what would be filed
+    python3 ikanban-import.py codeql.sarif --publish --team TEAM_ID  # file the findings into iKanban
+
+A result whose rule (or the result itself) carries a CWE tag ("external/cwe/cwe-089",
+"CWE-79: …", a CWE taxon) becomes a code finding under the OWASP Top 10 2021 category that lists
+that CWE. A result with no CWE, or a CWE that no OWASP 2021 category lists, stays in the local
+report as "not filed: no OWASP category". Suppressed and passing results are not filed either.
+Every text field passes through scrub_text before it is sent; the SARIF file itself never leaves
+this machine. Standard library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+IMPORT_VERSION = "1.0.0"
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+MAX_FILED = 500  # the server takes at most this many findings in one publish
+
+# OWASP Top 10 2021, "List of Mapped CWEs" of each category, copied from the official pages
+# (https://owasp.org/Top10/A01_2021-Broken_Access_Control/ … A10_2021-Server-Side_Request_Forgery_(SSRF)/;
+# source text: github.com/OWASP/Top10, 2021/docs/en/A0x_2021-*.md). The official lists name CWE-259
+# under both A02 and A07; the first category in this order (A02) wins.
+OWASP_2021_CWES = {
+    "A01 — Broken Access Control": (
+        22, 23, 35, 59, 200, 201, 219, 264, 275, 276, 284, 285, 352, 359, 377, 402, 425, 441, 497, 538, 540,
+        548, 552, 566, 601, 639, 651, 668, 706, 862, 863, 913, 922, 1275),
+    "A02 — Cryptographic Failures": (
+        259, 261, 296, 310, 319, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 335, 336, 337, 338, 340,
+        347, 523, 720, 757, 759, 760, 780, 818, 916),
+    "A03 — Injection": (
+        20, 74, 75, 77, 78, 79, 80, 83, 87, 88, 89, 90, 91, 93, 94, 95, 96, 97, 98, 99, 100, 113, 116, 138, 184,
+        470, 471, 564, 610, 643, 644, 652, 917),
+    "A04 — Insecure Design": (
+        73, 183, 209, 213, 235, 256, 257, 266, 269, 280, 311, 312, 313, 316, 419, 430, 434, 444, 451, 472, 501,
+        522, 525, 539, 579, 598, 602, 642, 646, 650, 653, 656, 657, 799, 807, 840, 841, 927, 1021, 1173),
+    "A05 — Security Misconfiguration": (
+        2, 11, 13, 15, 16, 260, 315, 520, 526, 537, 541, 547, 611, 614, 756, 776, 942, 1004, 1032, 1174),
+    "A06 — Vulnerable and Outdated Components": (937, 1035, 1104),
+    "A07 — Identification and Authentication Failures": (
+        255, 259, 287, 288, 290, 294, 295, 297, 300, 302, 304, 306, 307, 346, 384, 521, 613, 620, 640, 798, 940,
+        1216),
+    "A08 — Software and Data Integrity Failures": (345, 353, 426, 494, 502, 565, 784, 829, 830, 915),
+    "A09 — Security Logging and Monitoring Failures": (117, 223, 532, 778),
+    "A10 — Server-Side Request Forgery (SSRF)": (918,),
+}
+_CWE_TO_OWASP = {}
+for _cat, _cwes in OWASP_2021_CWES.items():
+    for _cwe in _cwes:
+        _CWE_TO_OWASP.setdefault(_cwe, _cat)
+
+CWE_TAG = re.compile(r"(?i)\bcwe[-_/ :]*0*(\d{1,4})\b")
+NO_CATEGORY = "not filed: no OWASP category"
+
+
+def owasp_category(cwe: int) -> str | None:
+    return _CWE_TO_OWASP.get(cwe)
+
+
+def _text(node) -> str:
+    return (node or {}).get("text") or (node or {}).get("markdown") or "" if isinstance(node, dict) else ""
+
+
+def _cwes(*nodes) -> list:
+    """CWE numbers from tags, taxa and relationships, in the order they appear."""
+    found = []
+
+    def add(value):
+        for m in CWE_TAG.finditer(str(value)):
+            n = int(m.group(1))
+            if n not in found:
+                found.append(n)
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        for tag in (node.get("properties") or {}).get("tags") or []:
+            add(tag)
+        for taxon in node.get("taxa") or []:
+            if isinstance(taxon, dict) and "cwe" in str((taxon.get("toolComponent") or {}).get("name", "")).lower():
+                add(f"CWE-{taxon.get('id', '')}")
+        for rel in node.get("relationships") or []:
+            target = (rel or {}).get("target") or {}
+            if "cwe" in str((target.get("toolComponent") or {}).get("name", "")).lower():
+                add(f"CWE-{target.get('id', '')}")
+            else:
+                add(target.get("id", ""))
+    return found
+
+
+def _severity(rule: dict, res: dict) -> str:
+    for node in (res, rule):
+        raw = (node.get("properties") or {}).get("security-severity")
+        try:
+            score = float(raw)
+        except (TypeError, ValueError):
+            continue
+        return "Critical" if score >= 9 else "High" if score >= 7 else "Medium" if score >= 4 else "Low"
+    level = res.get("level") or (rule.get("defaultConfiguration") or {}).get("level") or "warning"
+    return {"error": "High", "warning": "Medium"}.get(level, "Low")
+
+
+def _location(res: dict) -> tuple:
+    for loc in res.get("locations") or []:
+        phys = (loc or {}).get("physicalLocation") or {}
+        uri = str((phys.get("artifactLocation") or {}).get("uri") or "")
+        if uri:
+            uri = re.sub(r"^file://", "", urllib.parse.unquote(uri))
+            line = (phys.get("region") or {}).get("startLine")
+            return uri, str(line) if isinstance(line, int) else None
+    return "", None
+
+
+def sarif_findings(doc) -> tuple:
+    """(filed payloads, not filed [{rule, location, why}]); ValueError when doc is not SARIF 2.1.0."""
+    if not isinstance(doc, dict) or doc.get("version") != "2.1.0" or not isinstance(doc.get("runs"), list):
+        raise ValueError("not a SARIF 2.1.0 file (needs \"version\": \"2.1.0\" and a \"runs\" list)")
+    filed, not_filed = [], []
+    for run in doc["runs"]:
+        driver = ((run or {}).get("tool") or {}).get("driver") or {}
+        tool = str(driver.get("name") or "sarif")
+        rules = [r for r in driver.get("rules") or [] if isinstance(r, dict)]
+        for ext in ((run or {}).get("tool") or {}).get("extensions") or []:
+            rules += [r for r in (ext or {}).get("rules") or [] if isinstance(r, dict)]
+        by_id = {r.get("id"): r for r in rules}
+        for res in (run or {}).get("results") or []:
+            if not isinstance(res, dict):
+                continue
+            rule_id = str(res.get("ruleId") or (res.get("rule") or {}).get("id") or "")
+            index = res.get("ruleIndex")
+            rule = rules[index] if isinstance(index, int) and 0 <= index < len(rules) else by_id.get(rule_id, {})
+            rule_id = rule_id or str(rule.get("id") or "unknown-rule")
+            uri, line = _location(res)
+            where = f"{uri}:{line}" if line else uri
+            if res.get("suppressions"):
+                not_filed.append({"rule": rule_id, "location": where, "why": "not filed: suppressed in the SARIF file"})
+                continue
+            if res.get("kind") in ("pass", "notApplicable"):
+                not_filed.append({"rule": rule_id, "location": where, "why": "not filed: the result is a pass"})
+                continue
+            cwes = _cwes(res, rule)
+            category = next((owasp_category(c) for c in cwes if owasp_category(c)), None)
+            if not category:
+                why = NO_CATEGORY + (f" ({', '.join(f'CWE-{c}' for c in cwes)})" if cwes else "")
+                not_filed.append({"rule": rule_id, "location": where, "why": why})
+                continue
+            message = _text(res.get("message")).strip()
+            name = _text(rule.get("shortDescription")) or rule.get("name") or rule_id
+            advice = _text(rule.get("help")) or _text(rule.get("fullDescription"))
+            raw_key = f"{tool}|{rule_id}|{uri}|{line or ''}"
+            filed.append(scrub_finding({
+                "finding_key": "import-" + hashlib.sha256(raw_key.encode()).hexdigest()[:16],
+                "owasp_category": category,
+                "severity": _severity(rule, res),
+                "title": f"{name}: {message.splitlines()[0] if message else rule_id}"[:300],
+                "location_file": uri[:500] or None,
+                "location_lines": line,
+                "remediation": (f"{message} {advice}".strip() + f" (from {tool}, rule {rule_id})")[:2000],
+            }))
+    return filed, not_filed
+
+
+def tool_name(doc) -> str:
+    runs = doc.get("runs") or [{}]
+    return str((((runs[0] or {}).get("tool") or {}).get("driver") or {}).get("name") or "sarif")
+
+
+def build_report(source: str, tool: str, filed: list, not_filed: list, cut: int) -> tuple:
+    counts = {s: sum(1 for f in filed if f["severity"].lower() == s) for s in SEVERITIES}
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    L = [f"# SARIF import — {source}", "", f"_{stamp} · `ikanban-import` · tool: {tool}_", "",
+         f"**{len(filed)} finding(s) to file, {len(not_filed)} result(s) not filed.**", "", "## Filed"]
+    L += [f"- **[{f['severity']}]** {f['owasp_category']}: {f['title']} — `{f['location_file'] or '-'}"
+          f"{':' + f['location_lines'] if f['location_lines'] else ''}`" for f in filed] or ["- none"]
+    if cut:
+        L.append(f"- {cut} more were left out of iKanban (the server takes {MAX_FILED}); this import is incomplete")
+    L += ["", "## Not filed"]
+    L += [f"- {n['rule']} — `{n['location'] or '-'}`: {n['why']}" for n in not_filed] or ["- none"]
+    return "\n".join(L), counts
+
+
+# ── 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="Turn a SARIF 2.1.0 file into iKanban code findings.")
+    ap.add_argument("--version", action="version", version=f"ikanban import {IMPORT_VERSION}")
+    ap.add_argument("file", help="A SARIF 2.1.0 file (.sarif or .json) from another scanner")
+    ap.add_argument("--path", default=".", help="The repository the results belong to (default: cwd)")
+    ap.add_argument("--publish", action="store_true",
+                    help="File the findings into iKanban (the SARIF file and the report stay 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 summary")
+    add_pipeline_args(ap)
+    add_work_dir_arg(ap)
+    args = ap.parse_args(argv)
+
+    root = Path(args.path).expanduser().resolve()
+    source = Path(args.file).expanduser()
+    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
+    try:
+        if source.stat().st_size > 200 * 1024 * 1024:
+            raise ValueError("the file is over 200 MB")
+        doc = json.loads(source.read_text(encoding="utf-8-sig"))
+        filed, not_filed = sarif_findings(doc)
+    except (OSError, ValueError) as e:  # json.JSONDecodeError is a ValueError
+        print(f"error: {source.name}: {e}. ikanban import reads SARIF 2.1.0 files only.", file=sys.stderr)
+        return 2
+    tool = tool_name(doc)
+    filed.sort(key=lambda f: (SEVERITY_RANK.get(f["severity"].lower(), 99), f["title"]))
+    cut = max(0, len(filed) - MAX_FILED)
+    filed = filed[:MAX_FILED]
+    work = scan_work_dir("import", root, args.work_dir)
+    progress(f"import {IMPORT_VERSION} · {tool}: {len(filed)} to file, {len(not_filed)} not filed")
+    md, counts = build_report(source.name, tool, filed, not_filed, cut)
+    detail = f"{len(filed)} findings from {tool}" + (f"; {len(not_filed)} not filed" if not_filed else "")
+    LAST_RUN.update(report=md, detail=detail, skipped=False)
+    write_private(work / "report.md", md)
+    if args.out:
+        Path(args.out).write_text(md, encoding="utf-8")
+    if args.json:
+        print(json.dumps({"file": source.name, "tool": tool, "filed": len(filed), "not_filed": len(not_filed),
+                          "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:
+        scope = f"sarif:{slug(tool).lower()}:{scan_scope(root)}"
+        ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token,
+                       {"findings": filed, "scope": scope, "complete": cut == 0})
+        if not ok:
+            print(f"filing findings FAILED: {data or 'this iKanban server does not take them yet'}", file=sys.stderr)
+            return 2
+        print(f"filed {data.get('submitted', len(filed))} findings ({data.get('new', 0)} new, reopened "
+              f"{data.get('reopened', 0)}, closed {data.get('closed', 0)} no longer found in {scope})", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_main("import", main))