ikanban 0.3.4 → 0.4.1

package/scanners/ikanban-dastscan.py

@@ -0,0 +1,491 @@
+#!/usr/bin/env python3
+"""
+ikanban-dastscan — a passive DAST (dynamic application security testing) scan of a web app
+YOUR TEAM HAS REGISTERED in iKanban, reporting into the Infrastructure tab (plan 11 H12).
+
+    npx ikanban dastscan --url https://staging.example.com --team TEAM --publish
+
+It runs the OWASP ZAP baseline scan (Apache-2.0, https://github.com/zaproxy/zaproxy) in
+Docker, which must already be installed:
+    docker run --rm -v DIR:/zap/wrk/:rw ghcr.io/zaproxy/zaproxy:stable \\
+        zap-baseline.py -t URL -J zap.json -m MINUTES -T MAX_MINUTES
+(zaproxy.org/docs/docker/baseline-scan: it "runs the ZAP spider against the specified
+target for (by default) 1 minute and then waits for the passive scanning to complete";
+it "doesn't perform any actual 'attacks'". -J writes the JSON report, -m the spider
+minutes, -T the maximum minutes; exit 0 ok, 1 FAIL, 2 WARN, 3 any other failure.)
+
+Safety: the URL must be one of the team's registered DAST targets (iKASecure →
+Infrastructure, set by an owner or admin); the scanner checks the list before Docker
+starts, so it always needs --team and a key. A URL on this machine is reached from Docker
+as http://host.docker.internal:PORT, and that is the form to register.
+
+JSON read (zaproxy.org traditional JSON report): site[].alerts[]: pluginid, alertRef, name
+(or alert), riskcode (a string: "3" High, "2" Medium, "1" Low, "0" Informational), desc,
+solution, reference, cweid, count, instances[].uri.
+
+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 datetime import datetime, timezone
+from pathlib import Path
+
+DASTSCAN_VERSION = "1.1.0"
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+RISK = {"3": "high", "2": "medium", "1": "low"}  # "0" Informational is not filed
+ZAP_IMAGE = "ghcr.io/zaproxy/zaproxy:stable"
+DOCKER_INSTALL = ("Docker is not installed or not running — install Docker Desktop "
+                  "(https://docs.docker.com/get-docker/), start it, and re-run")
+CATEGORY = "A05 — Security Misconfiguration"
+MAX_URL = 2000
+
+
+def check_url(url: str) -> str | None:
+    """Why this URL is refused, or None. http(s) only, no user:pass@, no fragment."""
+    if not url or len(url) > MAX_URL or any(c.isspace() for c in url):
+        return "give a full http or https URL of at most 2000 characters"
+    u = urllib.parse.urlsplit(url)
+    if u.scheme not in ("http", "https") or not u.hostname:
+        return "only http and https URLs can be scanned"
+    if u.username is not None or u.password is not None:
+        return "a URL with a user name or password is refused; register the plain URL"
+    if u.fragment:
+        return "remove the #fragment"
+    return None
+
+
+def strip_html(s: str) -> str:
+    return re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", s or "")).strip()
+
+
+def parse_zap(report: dict) -> list:
+    """One finding per alert; informational alerts are left out."""
+    out = []
+    for site in report.get("site") or []:
+        for a in site.get("alerts") or []:
+            sev = RISK.get(str(a.get("riskcode", "")))
+            if not sev:
+                continue
+            uris = [i.get("uri") for i in a.get("instances") or [] if i.get("uri")]
+            cwe = str(a.get("cweid") or "")
+            detail = strip_html(a.get("desc"))[:500]
+            fix = strip_html(a.get("solution"))[:800]
+            ref = strip_html(a.get("reference")).split(" ")[0]
+            out.append({
+                "severity": sev,
+                "title": a.get("name") or a.get("alert") or f"ZAP rule {a.get('pluginid')}",
+                "rule": str(a.get("alertRef") or a.get("pluginid") or ""),
+                "location": uris[0] if uris else site.get("@name", ""),
+                "count": int(a.get("count") or len(uris) or 1),
+                "detail": detail + (f" (CWE-{cwe})" if cwe and cwe not in ("0", "-1") else ""),
+                "remediation": " ".join(x for x in (fix, ref) if x) or "See the ZAP rule for the fix.",
+            })
+    return out
+
+
+def finding_key(url: str, rule: str, title: str) -> str:
+    """Stable per target URL and ZAP rule, so a rescan files nothing new."""
+    return "dastscan-" + hashlib.sha256(f"dast|{url}|{rule}|{title}".encode()).hexdigest()[:16]
+
+
+def findings_payload(url: str, findings: list) -> list:
+    return [{
+        "finding_key": finding_key(url, f["rule"], f["title"]),
+        "owasp_category": CATEGORY,
+        "severity": f["severity"].capitalize(),
+        "title": f["title"][:300],
+        "location_file": f["location"][:500] or None,
+        "location_lines": None,
+        "remediation": " ".join(x for x in (f["detail"], f["remediation"]) if x),
+    } for f in findings]
+
+
+def build_report(url: str, findings: list, skipped: list, ran: list) -> tuple:
+    counts = {s: 0 for s in SEVERITIES}
+    for f in findings:
+        counts[f["severity"]] += 1
+    total = sum(counts.values())
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    L = [f"# DAST scan — {url}", "", f"_{stamp} · `ikanban-dastscan` (ZAP baseline, passive)_", "",
+         "| 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).**", "", "## Passive web scan"]
+    if ran:
+        L.append(f"_ran: {', '.join(ran)}_")
+    for s in skipped:
+        L.append(f"- ⚠️ **SKIPPED** — {s}")
+    if ran and not findings:
+        L.append("- ✅ no findings")
+    for f in sorted(findings, key=lambda x: SEVERITY_RANK[x["severity"]]):
+        L.append(f"- **[{f['severity']}]** {f['title']} — `{f['location']}` ({f['count']} place(s))")
+        if f["detail"]:
+            L.append(f"  - {f['detail']}")
+    L += ["", "---", "", "A passive scan reads responses only; it does not attack. Skipped checks are gaps, not passes."]
+    return "\n".join(L), counts, total
+
+
+def run_zap(url: str, minutes: int, max_minutes: int, work: Path) -> tuple[dict | None, str]:
+    """(report, "") or (None, why it did not run). ZAP writes zap.json into <work>/zap/."""
+    if not shutil.which("docker"):
+        return None, DOCKER_INSTALL
+    # The ZAP image writes as its own user, so it gets its own zap/ subfolder it may write to;
+    # the run folder stays 0700, so nobody else on this machine can reach zap/ through it.
+    zap_dir = work / "zap"
+    zap_dir.mkdir(exist_ok=True)
+    os.chmod(zap_dir, 0o777)
+    cmd = ["docker", "run", "--rm", "-v", f"{zap_dir}:/zap/wrk/:rw", ZAP_IMAGE, "zap-baseline.py",
+           "-t", url, "-J", "zap.json", "-m", str(minutes), "-T", str(max_minutes)]
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=(max_minutes + 5) * 60)
+    except FileNotFoundError:
+        return None, DOCKER_INSTALL
+    except subprocess.TimeoutExpired:
+        return None, f"ZAP did not finish within {max_minutes + 5} minutes"
+    out = zap_dir / "zap.json"
+    if p.returncode not in (0, 1, 2) or not out.exists():
+        why = (p.stderr or p.stdout or "").strip()[-300:]
+        return None, f"ZAP failed (exit {p.returncode}): {why or 'no report'}"
+    try:
+        return json.loads(out.read_text() or "{}"), ""
+    except ValueError:
+        return None, "ZAP wrote no JSON report"
+
+
+# ── copied from ikanban-secscan.py: key-host pinning and the API call ──────────────────
+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 registered(url: str, args) -> str | None:
+    """Why the URL may not be scanned (not registered, or the list could not be read), or None."""
+    ok, data = api("GET", f"/teams/{args.team}/security/dast-targets", args.base_url, args.token)
+    if not ok:
+        return f"could not read the team's DAST targets: {data or 'this iKanban server has none yet'}"
+    if url not in [t.get("url") for t in data or []]:
+        return (f"{url} is not a registered DAST target of this team; an owner or admin registers it "
+                "in iKASecure → Infrastructure first")
+    return None
+
+
+# ── 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}
+
+
+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", "--list-targets") 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="Passive DAST scan (OWASP ZAP baseline) of a registered URL.")
+    ap.add_argument("--version", action="version", version=f"ikanban dastscan {DASTSCAN_VERSION}")
+    ap.add_argument("--url", help="The web app to scan: one of the team's registered DAST targets")
+    ap.add_argument("--list-targets", action="store_true",
+                    help="Print the team's registered DAST targets (the URLs --url takes) and exit")
+    ap.add_argument("--minutes", type=int, default=1, help="Spider minutes (ZAP -m, default 1)")
+    ap.add_argument("--max-minutes", type=int, default=10, help="Most minutes ZAP may take (ZAP -T, default 10)")
+    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 (or IKANBAN_TEAM_ID); always needed, to check the URL is registered")
+    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)
+
+    if args.list_targets:
+        if not args.token or not args.team:
+            print("error: --list-targets needs --token (or VIBE_API_TOKEN) and --team (or IKANBAN_TEAM_ID)", file=sys.stderr)
+            return 2
+        ok, data = api("GET", f"/teams/{args.team}/security/dast-targets", args.base_url, args.token)
+        if not ok:
+            print(f"error: could not read the team's DAST targets: {data}", file=sys.stderr)
+            return 2
+        for t in data or []:
+            print(t.get("url"))
+        if not data:
+            print("no DAST targets: an owner or admin adds one in iKASecure → Infrastructure", file=sys.stderr)
+        return 0
+    if not args.url:
+        ap.error("--url is required (or --list-targets)")
+
+    url = args.url.strip()
+    why = check_url(url)
+    if why:
+        print(f"error: {why}", file=sys.stderr)
+        return 2
+    if not 1 <= args.minutes <= 60 or not args.minutes <= args.max_minutes <= 120:
+        print("error: --minutes 1–60 and --max-minutes from --minutes up to 120", file=sys.stderr)
+        return 2
+    if not args.token or not args.team:
+        print("error: dastscan needs --token (or VIBE_API_TOKEN) and --team (or IKANBAN_TEAM_ID) "
+              "to check the URL is a registered target", file=sys.stderr)
+        return 2
+    why = registered(url, args)
+    if why:
+        print(f"error: {why}", file=sys.stderr)
+        return 2
+
+    work = scan_work_dir("dastscan", Path.cwd(), args.work_dir)
+    report, skipped_why = run_zap(url, args.minutes, args.max_minutes, work)
+    findings = parse_zap(report) if report is not None else []
+    ran = [f"zap-baseline.py -t {url} -m {args.minutes}"] if report is not None else []
+    md, counts, total = build_report(url, findings, [skipped_why] if skipped_why else [], ran)
+    LAST_RUN.update(report=md, detail=summary_detail(counts, total, [] if ran else [skipped_why]),
+                    skipped=not ran)
+    write_private(work / "report.md", md)
+    if args.out:
+        Path(args.out).write_text(md)
+    if args.json:
+        print(json.dumps({"url": url, "total": total, "counts": counts, "skipped": bool(skipped_why)}, indent=2))
+    else:
+        print(md)
+    sys.stdout.flush()
+    print(f"scan files: {work}", file=sys.stderr)
+
+    if args.publish:
+        ok, info = api("POST", "/security/scan-reports", args.base_url, args.token,
+                       {"team_id": args.team, "title": f"DAST scan — {url} — "
+                        f"{datetime.now(timezone.utc):%Y-%m-%d %H:%M} UTC", "content": md})
+        print(f"\npublished: {(info or {}).get('id', '')}" if ok else f"\npublish FAILED: {info}",
+              file=sys.stderr)
+        if not ok:
+            return 2
+        if report is None:
+            print("ZAP did not run: nothing filed or closed", file=sys.stderr)
+        else:
+            ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token,
+                           {"findings": findings_payload(url, findings), "scope": url, "complete": True,
+                            "kind": "dast"})
+            if not ok:
+                print(f"filing DAST findings FAILED: {data or 'this iKanban server does not take them yet'}",
+                      file=sys.stderr)
+                return 2
+            print(f"filed {data.get('submitted', 0)} dast findings ({data.get('new', 0)} new, reopened "
+                  f"{data.get('reopened', 0)}, closed {data.get('closed', 0)} no longer found at {url})",
+                  file=sys.stderr)
+
+    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("dastscan", main))