ikanban 0.3.4 → 0.4.0

package/scanners/ikanban-infrascan.py

@@ -0,0 +1,511 @@
+#!/usr/bin/env python3
+"""
+ikanban-infrascan — container image and IaC (infrastructure as code) scan of YOUR OWN
+repository and images, reporting into iKanban's Infrastructure tab (plan 11 H12).
+
+    npx ikanban infrascan                          # IaC misconfiguration scan of cwd
+    npx ikanban infrascan --image myapp:latest     # also scan a container image
+    npx ikanban infrascan --publish --team TEAM    # file the report and its findings
+
+It runs Trivy (Apache-2.0, https://github.com/aquasecurity/trivy), which must already be
+installed; a missing Trivy is reported as SKIPPED with the install lines, never as a clean
+scan, and nothing is filed for a check that did not run.
+  IaC        trivy fs --scanners misconfig --format json --output FILE PATH
+  Container  trivy image --format json --output FILE IMAGE
+(trivy.dev docs: "trivy fs --scanners misconfig /path/to/dir"; reporting docs:
+"trivy image --format json --output result.json debian:12".)
+
+JSON read (pkg/types/report.go and misconfiguration.go in the Trivy source):
+  Results[].Target
+  Results[].Misconfigurations[]: ID, AVDID, Title, Message, Resolution, Severity,
+      PrimaryURL, Status ("PASS" | "FAIL" | "EXCEPTION"), CauseMetadata.StartLine
+  Results[].Vulnerabilities[]: VulnerabilityID, PkgName, InstalledVersion, FixedVersion,
+      Severity, Title, PrimaryURL
+
+Helpers below are copied from ikanban-secscan.py (the scanners ship as single files).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+INFRASCAN_VERSION = "1.0.0"
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+# Trivy's severities; UNKNOWN (no score yet) is filed as low.
+TRIVY_SEVERITY = {"CRITICAL": "critical", "HIGH": "high", "MEDIUM": "medium", "LOW": "low", "UNKNOWN": "low"}
+
+TRIVY_INSTALL = ("Trivy is not installed — macOS: `brew install trivy`; Linux and Windows: a release "
+                 "binary from https://github.com/aquasecurity/trivy/releases, or `docker run aquasec/trivy`")
+
+CATEGORY = {"iac": "A05 — Security Misconfiguration",
+            "container": "A06 — Vulnerable and Outdated Components"}
+
+
+@dataclass
+class Finding:
+    severity: str
+    title: str
+    detail: str
+    location: str = ""
+    line: str | None = None
+    rule: str = ""
+    remediation: str = ""
+
+
+@dataclass
+class Section:
+    name: str
+    kind: str
+    scope: str
+    findings: list = field(default_factory=list)
+    skipped: list = field(default_factory=list)
+    ran: list = field(default_factory=list)
+    complete: bool = False
+
+
+def run(cmd, cwd=None, timeout=900):
+    """Run a command, returning (ok, stdout, stderr). Never raises."""
+    try:
+        p = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+        return p.returncode == 0, p.stdout, p.stderr
+    except FileNotFoundError:
+        return False, "", "not-installed"
+    except subprocess.TimeoutExpired:
+        return False, "", f"timed out after {timeout}s"
+
+
+def trivy_json(args: list) -> tuple[dict | None, str]:
+    """Run trivy with --format json into a temp file; (report, "") or (None, why skipped)."""
+    if not shutil.which("trivy"):
+        return None, TRIVY_INSTALL
+    with tempfile.TemporaryDirectory() as tmp:
+        out = os.path.join(tmp, "trivy.json")
+        ok, _o, err = run(["trivy", *args[:1], "--format", "json", "--output", out, *args[1:]])
+        if not ok or not os.path.exists(out):
+            return None, f"trivy {args[0]} failed: {(err or '').strip()[-300:] or 'no output'}"
+        try:
+            return json.loads(Path(out).read_text() or "{}"), ""
+        except ValueError:
+            return None, f"trivy {args[0]} wrote no JSON"
+
+
+def parse_misconfigurations(report: dict) -> list:
+    """Failed checks only; PASS and EXCEPTION are not findings."""
+    out = []
+    for res in report.get("Results") or []:
+        target = res.get("Target") or ""
+        for m in res.get("Misconfigurations") or []:
+            if m.get("Status") not in (None, "FAIL"):
+                continue
+            line = (m.get("CauseMetadata") or {}).get("StartLine")
+            rule = m.get("AVDID") or m.get("ID") or ""
+            fix = " ".join(x for x in (m.get("Resolution"), m.get("PrimaryURL")) if x)
+            out.append(Finding(
+                severity=TRIVY_SEVERITY.get((m.get("Severity") or "").upper(), "low"),
+                title=f"{m.get('Title') or rule}",
+                detail=m.get("Message") or "",
+                location=target, line=str(line) if line else None, rule=rule,
+                remediation=fix or "Change the configuration as the check describes."))
+    return out
+
+
+def parse_vulnerabilities(report: dict, image: str) -> list:
+    out = []
+    for res in report.get("Results") or []:
+        target = res.get("Target") or image
+        for v in res.get("Vulnerabilities") or []:
+            pkg, have, fixed = v.get("PkgName") or "", v.get("InstalledVersion") or "", v.get("FixedVersion")
+            vid = v.get("VulnerabilityID") or ""
+            fix = f"Upgrade {pkg} to {fixed}" if fixed else f"No fixed version of {pkg} yet; use another base image or package"
+            if v.get("PrimaryURL"):
+                fix += f". {v['PrimaryURL']}"
+            out.append(Finding(
+                severity=TRIVY_SEVERITY.get((v.get("Severity") or "").upper(), "low"),
+                title=f"{pkg} {have}: {vid}" + (f" — {v['Title']}" if v.get("Title") else ""),
+                detail="", location=f"{image} ({target})", rule=f"{vid}|{pkg}", remediation=fix))
+    return out
+
+
+def scan_iac(root: Path, scope: str) -> Section:
+    sec = Section("IaC misconfiguration", "iac", scope)
+    report, why = trivy_json(["fs", "--scanners", "misconfig", str(root)])
+    if report is None:
+        sec.skipped.append(why)
+        return sec
+    sec.ran.append(f"trivy fs --scanners misconfig {root.name}")
+    sec.findings = parse_misconfigurations(report)
+    for f in sec.findings:  # paths relative to the repository, like secscan
+        f.location = f.location.removeprefix(str(root) + os.sep)
+    sec.complete = True
+    return sec
+
+
+def scan_image(image: str) -> Section:
+    sec = Section(f"Container image {image}", "container", image)
+    report, why = trivy_json(["image", image])
+    if report is None:
+        sec.skipped.append(why)
+        return sec
+    sec.ran.append(f"trivy image {image}")
+    sec.findings = parse_vulnerabilities(report, image)
+    sec.complete = True
+    return sec
+
+
+def build_report(title: str, sections: list) -> tuple:
+    counts = {s: 0 for s in SEVERITIES}
+    for sec in sections:
+        for f in sec.findings:
+            counts[f.severity] = counts.get(f.severity, 0) + 1
+    total = sum(counts.values())
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    L = [f"# Infrastructure scan — {title}", "", f"_{stamp} · `ikanban-infrascan`_", "",
+         "| Severity | Count |", "|---|---|"]
+    L += [f"| {s} | {counts[s]} |" for s in SEVERITIES if counts[s]]
+    if not total:
+        L.append("| _none_ | 0 |")
+    L += ["", f"**{total} finding(s).**", ""]
+    for sec in sections:
+        L.append(f"## {sec.name}")
+        if sec.ran:
+            L.append(f"_ran: {', '.join(sec.ran)}_")
+        for s in sec.skipped:
+            L.append(f"- ⚠️ **SKIPPED** — {s}")
+        if not sec.findings and sec.complete:
+            L.append("- ✅ no findings")
+        for f in sorted(sec.findings, key=lambda x: (SEVERITY_RANK.get(x.severity, 99), x.title)):
+            loc = f" — `{f.location}{':' + f.line if f.line else ''}`" if f.location else ""
+            L.append(f"- **[{f.severity}]** {f.title}{loc}")
+            if f.detail:
+                L.append(f"  - {f.detail}")
+        L.append("")
+    L += ["---", "", "Skipped checks are gaps, not passes — install the named tool and re-run."]
+    return "\n".join(L), counts, total
+
+
+def finding_key(kind: str, scope: str, rule: str, location: str, line: str | None) -> str:
+    """Stable per kind, scope, rule and place, so a rescan files nothing new."""
+    raw = f"{kind}|{scope}|{rule}|{location}|{line or ''}"
+    return "infrascan-" + hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def findings_payload(sec: Section, home: str | None = None) -> list:
+    home = home if home is not None else str(Path.home())
+
+    def clean(s):
+        return s.replace(home, "~") if s and home and home != "/" else s
+    return [{
+        "finding_key": finding_key(sec.kind, sec.scope, f.rule, f.location, f.line),
+        "owasp_category": CATEGORY[sec.kind],
+        "severity": "Low" if f.severity == "info" else f.severity.capitalize(),
+        "title": clean(f.title)[:300],
+        "location_file": clean(f.location) or None,
+        "location_lines": f.line,
+        "remediation": clean(" ".join(x for x in (f.detail, f.remediation) if x)),
+    } for f in sec.findings]
+
+
+# ── copied from ikanban-secscan.py: scope, key-host pinning, API ─────────────────────
+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())
+    if path == url.strip():
+        path = path.split(":", 1)[-1]
+    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:
+    """origin's owner/repo (else the folder name), plus the subfolder: the same scope
+    secscan uses, so a rescan closes only this repository's IaC findings."""
+    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
+
+
+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
+
+
+_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 an unknown route)."""
+    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=60) 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
+        try:
+            detail = json.loads(detail).get("error") or detail
+        except (ValueError, AttributeError):
+            pass
+        return False, f"HTTP {e.code}: {detail}"
+    except Exception as e:  # noqa: BLE001 — surface any transport failure verbatim
+        return False, str(e)
+
+
+def publish(md: str, title: str, sections: list, args) -> int:
+    ok, info = api("POST", "/security/scan-reports", args.base_url, args.token,
+                   {"team_id": args.team, "title": title, "content": md.replace(str(Path.home()), "~")})
+    print(f"\npublished: {(info or {}).get('id', '') if ok else ''}" if ok else f"\npublish FAILED: {info}",
+          file=sys.stderr)
+    if not ok:
+        return 2
+    for sec in sections:
+        if not sec.complete:
+            print(f"{sec.name}: did not run, nothing filed or closed", file=sys.stderr)
+            continue
+        ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token,
+                       {"findings": findings_payload(sec), "scope": sec.scope, "complete": True,
+                        "kind": sec.kind})
+        if not ok:
+            print(f"filing {sec.name} FAILED: {data or 'this iKanban server does not take infrastructure findings yet'}",
+                  file=sys.stderr)
+            return 2
+        print(f"filed {data.get('submitted', 0)} {sec.kind} findings ({data.get('new', 0)} new, reopened "
+              f"{data.get('reopened', 0)}, closed {data.get('closed', 0)} no longer found in {sec.scope})",
+              file=sys.stderr)
+    return 0
+
+
+# ── 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 the report as log chunks. 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)
+PIPE_CHUNK = 15 * 1024  # the server takes 16 KB per chunk
+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:
+    """The report is masked already; mask again before it leaves for Pipelines."""
+    scrub = globals().get("scrub_report")
+    if scrub:
+        return scrub(text)[0]
+    text = re.sub(r"\bvk_[A-Za-z0-9_-]{8,}", lambda m: m.group(0)[:4] + "…[hidden]", text)
+    home = str(Path.home())
+    return text.replace(home, "~") if home and home != "/" else text
+
+
+def log_chunks(text: str) -> list:
+    """Whole lines, each chunk under PIPE_CHUNK bytes (a longer single line is cut)."""
+    chunks, cur = [], ""
+    for line in text.splitlines(keepends=True):
+        while len(line.encode()) > PIPE_CHUNK:
+            head = line.encode()[:PIPE_CHUNK].decode(errors="ignore")
+            chunks.append(head)
+            line = line[len(head):]
+        if len((cur + line).encode()) > PIPE_CHUNK:
+            chunks.append(cur)
+            cur = ""
+        cur += line
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+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",
+                                       "source": "laptop", "actor": f"ikanban-{self.stage}"})
+
+    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,
+                                       "source": "laptop", "actor": f"ikanban-{self.stage}",
+                                       "detail": detail[:300] or None})
+        for chunk in log_chunks(mask_report(LAST_RUN["report"])):
+            self._post("pipeline-logs", {"task": self.task, "stage": self.stage, "text": chunk})
+
+
+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()
+    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="Container image and IaC scan (Trivy) that reports into iKanban.")
+    ap.add_argument("--version", action="version", version=f"ikanban infrascan {INFRASCAN_VERSION}")
+    ap.add_argument("--path", default=".", help="Repository whose IaC files to scan (default: cwd)")
+    ap.add_argument("--image", action="append", default=[], metavar="IMAGE",
+                    help="Also scan this container image (repeat for each image)")
+    ap.add_argument("--no-iac", action="store_true", help="Scan only the --image images")
+    ap.add_argument("--publish", action="store_true", help="File the report and findings into iKanban")
+    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")
+    ap.add_argument("--fail-on", choices=SEVERITIES, default=None,
+                    help="Exit 1 if any finding is at or above this severity")
+    add_pipeline_args(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
+
+    sections = [] if args.no_iac else [scan_iac(root, scan_scope(root))]
+    sections += [scan_image(i) for i in args.image]
+    if not sections:
+        print("error: nothing to scan: drop --no-iac or add --image", file=sys.stderr)
+        return 2
+    md, counts, total = build_report(root.name, sections)
+    nothing_ran = not any(sec.complete for sec in sections)
+    LAST_RUN.update(report=md, skipped=nothing_ran, detail=summary_detail(
+        counts, total, [s for sec in sections for s in sec.skipped] if nothing_ran else []))
+    if args.out:
+        Path(args.out).write_text(md)
+    if args.json:
+        print(json.dumps({"path": str(root), "images": args.image, "total": total, "counts": counts,
+                          "skipped": [s for sec in sections for s in sec.skipped]}, indent=2))
+    else:
+        print(md)
+    sys.stdout.flush()
+
+    if args.publish:
+        title = f"Infrastructure scan — {root.name} — {datetime.now(timezone.utc):%Y-%m-%d %H:%M} UTC"
+        code = publish(md, title, sections, args)
+        if code:
+            return code
+
+    if args.fail_on and any(SEVERITY_RANK.get(s, 99) <= SEVERITY_RANK[args.fail_on] and c
+                            for s, c in counts.items()):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_main("infrascan", main))

package/scanners/ikanban-secscan.py

@@ -64,7 +64,7 @@ from pathlib import Path
 # that npm no longer hosts the package. Starting at 1.0.0 rather than continuing
 # the npm package's 0.1.x line: that counter belonged to the wrapper, not to
 # this file, and reusing it would suggest a continuity that does not exist.
-SECSCAN_VERSION = "1.3.0"
+SECSCAN_VERSION = "1.4.0"
 
 SEVERITIES = ["critical", "high", "medium", "low", "info"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
@@ -859,7 +859,133 @@ def publish(md: str, title: str, base_url: str, token: str, team_id: str,
         return False, str(e)
 
 
-def main():
+# ── 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 the report as log chunks. 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)
+PIPE_CHUNK = 15 * 1024  # the server takes 16 KB per chunk
+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:
+    """The report is masked already; mask again before it leaves for Pipelines."""
+    scrub = globals().get("scrub_report")
+    if scrub:
+        return scrub(text)[0]
+    text = re.sub(r"\bvk_[A-Za-z0-9_-]{8,}", lambda m: m.group(0)[:4] + "…[hidden]", text)
+    home = str(Path.home())
+    return text.replace(home, "~") if home and home != "/" else text
+
+
+def log_chunks(text: str) -> list:
+    """Whole lines, each chunk under PIPE_CHUNK bytes (a longer single line is cut)."""
+    chunks, cur = [], ""
+    for line in text.splitlines(keepends=True):
+        while len(line.encode()) > PIPE_CHUNK:
+            head = line.encode()[:PIPE_CHUNK].decode(errors="ignore")
+            chunks.append(head)
+            line = line[len(head):]
+        if len((cur + line).encode()) > PIPE_CHUNK:
+            chunks.append(cur)
+            cur = ""
+        cur += line
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+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",
+                                       "source": "laptop", "actor": f"ikanban-{self.stage}"})
+
+    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,
+                                       "source": "laptop", "actor": f"ikanban-{self.stage}",
+                                       "detail": detail[:300] or None})
+        for chunk in log_chunks(mask_report(LAST_RUN["report"])):
+            self._post("pipeline-logs", {"task": self.task, "stage": self.stage, "text": chunk})
+
+
+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()
+    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="Standalone security scan that reports into iKanban.")
     # Lets someone who downloaded a copy tell which release it is, and check it
@@ -884,7 +1010,8 @@ def main():
                     help="Print the team's applications (the NAMEs --app takes) and exit")
     ap.add_argument("--fail-on", choices=SEVERITIES, default=None,
                     help="Exit 1 if any finding is at or above this severity")
-    args = ap.parse_args()
+    add_pipeline_args(ap)
+    args = ap.parse_args(argv)
 
     root = Path(args.path).expanduser().resolve()
     if not root.is_dir():
@@ -922,6 +1049,7 @@ def main():
     sections = [audit_dependencies(root), *(s for _, s in app_sections),
                 scan_secrets(root), scan_permissions(root)]
     md, counts, total = build_report(root, sections)
+    LAST_RUN.update(report=md, detail=summary_detail(counts, total, []), skipped=False)
 
     if args.out:
         Path(args.out).write_text(md)
@@ -997,4 +1125,4 @@ def main():
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(run_main("secscan", main))