ikanban 0.3.4 → 0.4.1

package/scanners/ikanban-infrascan.py

@@ -0,0 +1,790 @@
+#!/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                          # inventory + IaC scan of cwd
+    npx ikanban infrascan --path . --path ../infra # infra in another folder or repo too
+    npx ikanban infrascan --image myapp:latest     # also scan a container image
+    npx ikanban infrascan --publish --team TEAM    # file the report and its findings
+
+Plan 11 H12-T10 (owner: assume messy development). It starts with an inventory of each path:
+what infrastructure it found, what Trivy scanned, and what it could not scan and why. Infra
+written as code (CDK, Pulumi, CDK for Terraform, Vagrant, Ansible, cloud-SDK scripts) is listed
+as found but not scannable. Images named in docker-compose files are scanned too. A path with no
+infrastructure-as-code file is never reported complete, so its control stays Missing.
+Raw Trivy JSON and the report go to <first path>/.iKanban/scans/infrascan-<UTC time>/ (or
+--work-dir / IKANBAN_SCAN_DIR); that folder ignores itself in git.
+
+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 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.1.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
+    filed: list | None = None   # what publish sends; None = every finding (plan_filing sets it)
+    notes: list = field(default_factory=list)
+
+
+# The server takes at most this many findings in one publish (security_scan_findings.rs).
+MAX_FILED = 500
+
+
+def plan_filing(sec: Section) -> None:
+    """Plan 11 H12-T10 review: container images file critical and high only (the rest stay in
+    the report); any section over MAX_FILED files the worst MAX_FILED and is published
+    incomplete, so the rescan never closes findings that were only cut."""
+    keep = sec.findings
+    if sec.kind == "container":
+        keep = [f for f in keep if f.severity in ("critical", "high")]
+        if len(keep) < len(sec.findings):
+            sec.notes.append(f"{len(sec.findings) - len(keep)} medium and low findings are in this report only; "
+                             "iKanban files critical and high for container images.")
+    if len(keep) > MAX_FILED:
+        keep = sorted(keep, key=lambda f: (SEVERITY_RANK.get(f.severity, 99), f.title))
+        sec.notes.append(f"Filed the {MAX_FILED} worst; {len(keep) - MAX_FILED} more were left out of iKanban "
+                         "(this run counts as incomplete, so nothing closes).")
+        keep = keep[:MAX_FILED]
+        sec.complete = False
+    sec.filed = keep
+
+
+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, target: str, out: Path) -> tuple[dict | None, str]:
+    """Run `trivy SUBCOMMAND [ARGS] -- TARGET` with --format json into `out`; (report, "") or
+    (None, why skipped). Plan 11 H12-T10 review: trivy runs from the scan's work folder with a
+    scanner-owned --config and --ignorefile (both default to files in the working folder,
+    trivy.dev CLI reference: `-c, --config ... (default "trivy.yaml")`, `--ignorefile ...
+    (default ".trivyignore")`), so a repository's trivy.yaml or .trivyignore changes nothing.
+    The target comes after `--`, so a name starting with '-' can never be read as a flag."""
+    if not shutil.which("trivy"):
+        return None, TRIVY_INSTALL
+    work = out.parent
+    conf, ignore = work / "trivy-config.yaml", work / "trivyignore"
+    if not conf.exists():
+        write_private(conf, "{}\n")
+    if not ignore.exists():
+        write_private(ignore, "")
+    ok, _o, err = run(["trivy", *args[:1], "--config", str(conf), "--ignorefile", str(ignore),
+                       "--format", "json", "--output", str(out), *args[1:], "--", target], cwd=work)
+    if not ok or not out.exists():
+        return None, f"trivy {args[0]} failed: {(err or '').strip()[-300:] or 'no output'}"
+    try:
+        return json.loads(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, inv: dict, work: Path) -> Section:
+    sec = Section(f"IaC misconfiguration — {scope}", "iac", scope)
+    if not any(inv[c] for c in TRIVY_IAC):
+        # Owner: no IaC file found is not a pass. complete stays False: the control stays Missing.
+        sec.skipped.append(f"No infrastructure-as-code files found in {root} — if the infrastructure lives in "
+                           "another folder or repository, add it with another --path")
+        return sec
+    # ponytail: trivy.dev does not say what --skip-dirs is relative to with an absolute target;
+    # the absolute and the ** form are both passed. A miss only means a vendored folder is read too.
+    skip = [x for d in SKIP_DIRS for x in ("--skip-dirs", f"{root.resolve()}/{d}", "--skip-dirs", f"**/{d}")]
+    report, why = trivy_json(["fs", "--scanners", "misconfig", *skip], str(root.resolve()),
+                             work / f"trivy-iac-{slug(scope)}.json")
+    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).removeprefix(str(root.resolve()) + os.sep)
+    sec.complete = True
+    return sec
+
+
+def scan_image(image: str, work: Path) -> Section:
+    sec = Section(f"Container image {image}", "container", image)
+    if not valid_image_ref(image):
+        sec.skipped.append(f"`{image[:80]}` is not a valid image name; not scanned")
+        return sec
+    report, why = trivy_json(["image"], image, work / f"trivy-image-{slug(image)}.json")
+    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
+
+
+# ── Inventory (plan 11 H12-T10) ───────────────────────────────────────────────────────
+# What Trivy's misconfiguration scanner reads, from trivy.dev "IaC" coverage (Kubernetes,
+# Docker: Dockerfile/Containerfile, Terraform: *.tf *.tf.json, CloudFormation, Azure ARM,
+# Helm). docker-compose, Ansible, Bicep, CDK, Pulumi and Vagrant are not in that table.
+TRIVY_IAC = ("Dockerfile", "Kubernetes manifest", "Helm chart", "Terraform", "CloudFormation", "Azure ARM template")
+NOT_SCANNABLE = {
+    "Dockerfile with another name": "Trivy reads files named Dockerfile or Containerfile; this one may not be checked",
+    "docker-compose file": "its images are scanned as containers; the compose settings themselves are not checked",
+    "AWS CDK app": "run `npx cdk synth` and rescan: the templates in cdk.out are scanned as CloudFormation",
+    "CDK for Terraform app": "run `cdktf synth` and rescan: the Terraform JSON in cdktf.out is scanned",
+    "Pulumi program": "found, not scannable: review by hand or audit the cloud account",
+    "Vagrant": "found, not scannable: provisioning by script; review by hand",
+    "Ansible playbook": "found, not scannable by Trivy: review by hand",
+    "Azure Bicep": "run `az bicep build` and rescan: the ARM JSON it writes is scanned",
+    "Cloud SDK code": "found, not scannable: infrastructure created in code; review by hand or audit the cloud account",
+}
+# Imports that mean code talks to a cloud API (examples; the real set is broader).
+SDK_MARKERS = ("import boto3", "from boto3", "from botocore", "@aws-sdk/", "'aws-sdk'", '"aws-sdk"',
+               "github.com/aws/aws-sdk-go", "software.amazon.awssdk", "from google.cloud",
+               "from google.cloud import", "@google-cloud/", "cloud.google.com/go/", "azure.mgmt",
+               "@azure/arm-", "github.com/Azure/azure-sdk-for-go")
+SDK_EXTS = {".py", ".js", ".mjs", ".cjs", ".ts", ".go", ".java", ".kt", ".cs", ".rb"}
+SKIP_DIRS = (".git", "node_modules", "vendor", "dist", "build", ".venv", "venv", "target", ".iKanban/scans",
+             ".terraform", "__pycache__")
+MAX_READ = 512 * 1024
+
+
+def _head(p: Path) -> str:
+    try:
+        with p.open("rb") as f:
+            return f.read(MAX_READ).decode("utf-8", "ignore")
+    except OSError:
+        return ""
+
+
+def _skipped(rel: Path) -> bool:
+    parts = rel.parts
+    return any(d in parts for d in SKIP_DIRS if "/" not in d) or rel.as_posix().startswith(".iKanban/scans")
+
+
+def inventory(root: Path) -> dict:
+    """Infra files under root, by kind (paths relative to root). Never raises."""
+    inv = {k: [] for k in (*TRIVY_IAC, *NOT_SCANNABLE)}
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel_dir = Path(dirpath).relative_to(root)
+        dirnames[:] = [d for d in dirnames if not _skipped(rel_dir / d)]
+        files += [rel_dir / f for f in filenames]
+    charts = {f.parent for f in files if f.name == "Chart.yaml"}
+    inv["Helm chart"] = sorted(c.as_posix() or "." for c in charts)
+    for rel in sorted(files):
+        name, low = rel.name, rel.name.lower()
+        posix = rel.as_posix()
+        in_chart = any(c == rel.parent or c in rel.parents for c in charts)
+        if name in ("Dockerfile", "Containerfile"):
+            inv["Dockerfile"].append(posix)
+        elif low.endswith(".dockerfile") or low.startswith("dockerfile."):
+            inv["Dockerfile with another name"].append(posix)
+        elif re.match(r"^(docker-)?compose[\w.-]*\.ya?ml$", low):
+            inv["docker-compose file"].append(posix)
+        elif low.endswith((".tf", ".tf.json")):
+            inv["Terraform"].append(posix)
+        elif name == "cdk.json":
+            inv["AWS CDK app"].append(posix)
+        elif name == "cdktf.json":
+            inv["CDK for Terraform app"].append(posix)
+        elif name in ("Pulumi.yaml", "Pulumi.yml"):
+            inv["Pulumi program"].append(posix)
+        elif name == "Vagrantfile":
+            inv["Vagrant"].append(posix)
+        elif low.endswith(".bicep"):
+            inv["Azure Bicep"].append(posix)
+        elif low.endswith((".yaml", ".yml", ".json")) and not in_chart:
+            text = _head(root / rel)
+            if "AWSTemplateFormatVersion" in text or re.search(r"""["']?Type["']?\s*:\s*["']?AWS::""", text):
+                inv["CloudFormation"].append(posix)
+            elif low.endswith(".json") and "deploymentTemplate.json" in text:
+                inv["Azure ARM template"].append(posix)
+            elif re.search(r"(?m)^apiVersion:\s*\S", text) and re.search(r"(?m)^kind:\s*\S", text):
+                inv["Kubernetes manifest"].append(posix)
+            elif re.search(r"(?m)^-\s+(name:.*\n\s+)?hosts:\s*\S", text) and re.search(r"(?m)^\s+(tasks|roles):", text):
+                inv["Ansible playbook"].append(posix)
+        elif rel.suffix in SDK_EXTS:
+            text = _head(root / rel)
+            if any(m in text for m in SDK_MARKERS):
+                inv["Cloud SDK code"].append(posix)
+    return inv
+
+
+def cdk_note(inv: dict) -> str:
+    """CDK synth output (cdk.out) holds CloudFormation templates: say they were scanned."""
+    synthed = [p for p in inv["CloudFormation"] if p.split("/")[-2:-1] == ["cdk.out"] or "/cdk.out/" in f"/{p}"]
+    return "synthesized templates in cdk.out are scanned as CloudFormation" if synthed else NOT_SCANNABLE["AWS CDK app"]
+
+
+# Plan 11 H12-T10 review: compose `image:` values come from the repository, so only a plain
+# image reference (registry[:port]/path:tag@sha256:digest, lower case, no leading '-') may
+# reach trivy's command line.
+IMAGE_REF = re.compile(
+    r"^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?(?::[0-9]{1,5})?"        # registry host or first path part
+    r"(?:/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?)*"                     # more path parts
+    r"(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?"                     # tag
+    r"(?:@sha256:[a-f0-9]{64})?$")
+
+
+def valid_image_ref(ref: str) -> bool:
+    return 0 < len(ref) <= 255 and ".." not in ref and bool(IMAGE_REF.match(ref))
+
+
+IMAGE_LINE = re.compile(r"""^\s*image:\s*["']?([^"'\s#]+)["']?\s*(#.*)?$""")
+
+
+def compose_images(root: Path, inv: dict) -> tuple[list, list, list]:
+    """(images named in compose files, names with ${VARS}, names that are not a valid image)."""
+    images, unresolved, rejected = [], [], []
+    for rel in inv["docker-compose file"]:
+        for line in _head(root / rel).splitlines():
+            m = IMAGE_LINE.match(line)
+            if not m:
+                continue
+            name = m.group(1)
+            (unresolved if "$" in name else images if valid_image_ref(name) else rejected).append(name)
+    return sorted(set(images)), sorted(set(unresolved)), sorted(set(rejected))
+
+
+def inventory_rows(inv: dict, scanned_iac: bool, iac_why: str, rejected: list = ()) -> list:
+    """Markdown table rows: what | found | scanned | note."""
+    rows = []
+    if rejected:
+        shown = ", ".join(f"`{r[:60]}`" for r in rejected[:5])
+        rows.append(f"| Image name in a compose file | {len(rejected)}: {shown} | no | not a valid image name, "
+                    "so it was not passed to Trivy; check the compose file |")
+    for kind, paths in inv.items():
+        if not paths:
+            continue
+        shown = ", ".join(f"`{p}`" for p in paths[:5]) + (f" (+{len(paths) - 5} more)" if len(paths) > 5 else "")
+        if kind in TRIVY_IAC:
+            state, note = ("yes", "Trivy misconfiguration checks") if scanned_iac else ("no", iac_why)
+        elif kind == "AWS CDK app":
+            note = cdk_note(inv)
+            state = "yes (cdk.out)" if note.startswith("synthesized") else "no"
+        elif kind == "docker-compose file":
+            state, note = "images only", NOT_SCANNABLE[kind]
+        else:
+            state, note = "no", NOT_SCANNABLE[kind]
+        rows.append(f"| {kind} | {len(paths)}: {shown} | {state} | {note} |")
+    return rows
+
+
+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 scope, rows in INVENTORY:
+        L += [f"## Inventory — {scope}", "", "| What | Found | Scanned | Note |", "|---|---|---|---|"]
+        L += rows or ["| _no infrastructure files found_ | 0 | — | add the folder or repository that holds them with another --path |"]
+        L.append("")
+    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 n in sec.notes:
+            L.append(f"- ℹ️ {n}")
+        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.",
+          "Found but not scannable is a gap too: review it by hand."]
+    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.filed if sec.filed is not None else 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:
+        nothing_found = any(x.startswith("No infrastructure-as-code files found") for x in sec.skipped)
+        cut = any("more were left out" in n for n in sec.notes)
+        if not sec.complete and not nothing_found and not cut:
+            print(f"{sec.name}: did not run, nothing filed or closed", file=sys.stderr)
+            continue
+        # A path with no IaC file is recorded as an incomplete run: iKanban shows when it was
+        # checked, the control stays Missing, and nothing closes.
+        ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token,
+                       {"findings": findings_payload(sec), "scope": sec.scope, "complete": sec.complete,
+                        "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
+
+
+# ── 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)")
+
+
+def scan_work_dir(scanner: str, base: Path, override: str = "") -> Path:
+    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"
+
+
+# ── 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}
+INVENTORY: list = []  # (scope, table rows) per --path, for the report
+
+
+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", action="append", default=[],
+                    help="A folder or repository holding infrastructure files (repeat for each; 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("--no-compose-images", action="store_true",
+                    help="Do not scan the images that docker-compose files name")
+    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)
+    add_work_dir_arg(ap)
+    args = ap.parse_args(argv)
+
+    roots = [Path(p).expanduser().resolve() for p in (args.path or ["."])]
+    for root in roots:
+        if not root.is_dir():
+            print(f"error: {root} is not a directory", file=sys.stderr)
+            return 2
+    root = roots[0]
+    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
+
+    if args.no_iac and not args.image:
+        print("error: nothing to scan: drop --no-iac or add --image", file=sys.stderr)
+        return 2
+    work = scan_work_dir("infrascan", root, args.work_dir)
+    sections, images, unresolved = [], list(args.image), []
+    INVENTORY.clear()
+    for r in roots:
+        inv = inventory(r)
+        rejected = []
+        if not args.no_compose_images:
+            found, skipped_vars, rejected = compose_images(r, inv)
+            images += [i for i in found if i not in images]
+            unresolved += skipped_vars
+        if not args.no_iac:
+            sec = scan_iac(r, scan_scope(r), inv, work)
+            sections.append(sec)
+            INVENTORY.append((sec.scope, inventory_rows(inv, sec.complete, "; ".join(sec.skipped), rejected)))
+        else:
+            INVENTORY.append((scan_scope(r), inventory_rows(inv, False, "--no-iac", rejected)))
+    sections += [scan_image(i, work) for i in images]
+    if unresolved:
+        sections.append(Section("Compose images not scanned", "container", "compose",
+                                skipped=[f"`{i}` uses a ${{VARIABLE}}; pass the real name with --image" for i in unresolved]))
+    for sec in sections:
+        plan_filing(sec)
+    md, counts, total = build_report(", ".join(r.name for r in roots), sections)
+    write_private(work / "report.md", md)
+    nothing_ran = not any(sec.ran for sec in sections)  # a cut section still ran
+    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({"paths": [str(r) for r in roots], "images": images, "total": total, "counts": counts,
+                          "skipped": [s for sec in sections for s in sec.skipped], "work_dir": str(work)}, indent=2))
+    else:
+        print(md)
+    sys.stdout.flush()
+    print(f"scan files: {work}", file=sys.stderr)
+
+    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))