ikanban 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikanban",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "iKanban CLI: AI and security scans of your own repo, with results filed into iKanban",
   "bin": { "ikanban": "bin/ikanban.js" },
   "files": ["bin", "lib", "hooks", "scanners", "README.md", "LICENSE.md"],

package/scanners/ikanban-cloudscan.py

@@ -49,7 +49,7 @@ import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
 
-CLOUDSCAN_VERSION = "1.0.0"
+CLOUDSCAN_VERSION = "1.1.0"
 
 SEVERITIES = ["critical", "high", "medium", "low", "info"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
@@ -210,6 +210,13 @@ def check_id(row: dict) -> str:
     return str((row.get("metadata") or {}).get("event_code") or "")
 
 
+def fail_title(check_title: str) -> str:
+    """Prowler's check title names the passing state ("S3 bucket is not publicly accessible"), so the
+    published title says it fails. Built from the check title only: Prowler's status_detail / message
+    is raw scanner text that can quote resource content, so it stays in the local Prowler output."""
+    return f"Fails: {check_title}"
+
+
 def parse_rows(rows: list, region: str) -> tuple[list, int]:
     """(failed findings, how many RDS resources the run saw). Only plain fields are kept:
     check id, title, resource ARN, region, severity, Prowler's remediation text."""
@@ -230,7 +237,7 @@ def parse_rows(rows: list, region: str) -> tuple[list, int]:
         findings.append({
             "check": cid, "severity": sev, "resource": uid,
             "region": str(res.get("region") or (r.get("cloud") or {}).get("region") or region),
-            "title": str(info.get("title") or cid),
+            "title": fail_title(str(info.get("title") or cid)),
             "remediation": str(fix),
         })
     return findings, len(rds)

package/scanners/ikanban-dastscan.py

@@ -28,7 +28,9 @@ Plan 11 H14: --openapi FILE_OR_URL runs ZAP's API scan instead, from an OpenAPI
         -e ZAP_AUTH_HEADER_SITE] ghcr.io/zaproxy/zaproxy:stable \
         zap-api-scan.py -t SPEC -f openapi -J zap.json -T MAX_MINUTES [-S]
 (zaproxy.org/docs/docker/api-scan: it imports the definition and runs an active scan against
-the URLs found; -S is safe mode, a baseline (passive) scan; exit codes as above.) The findings
+the URLs found; -S is safe mode, a baseline (passive) scan; exit codes as above; -T bounds only
+ZAP's start and passive scan, so the active scan gets -z "-config scanner.maxScanDurationInMins=N",
+and --rate N paces requests with the Network add-on's rate limit rule, see zap_config.) The findings
 file as kind "api". The spec is a URL on the registered target's own origin (downloaded here,
 no redirect, at most 5 MB; ZAP never gets a URL) or a local JSON file. Every servers entry must be
 that origin or a path starting with '/' (no templates or variables); a checked copy with each server
@@ -47,16 +49,18 @@ import hashlib
 import json
 import os
 import re
+import shlex
 import shutil
 import subprocess
 import sys
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
 
-DASTSCAN_VERSION = "1.3.0"
+DASTSCAN_VERSION = "1.4.0"
 
 SEVERITIES = ["critical", "high", "medium", "low", "info"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
@@ -69,6 +73,11 @@ MAX_URL = 2000
 # Plan 11 H14 (owner): an active scan of production is refused; --passive may read it.
 PRODUCTION_HOSTS = ("api.i-kanban.com",)
 MAX_SPEC_BYTES = 5 * 1024 * 1024
+# The scanner waits this long past --max-minutes for ZAP to write its report, then stops it.
+GRACE_MINUTES = 3
+# Requests per second for an active API scan unless --rate says otherwise (the dev API
+# answered 429 643 times without a limit). Passive scans send few requests: no limit.
+DEFAULT_API_RATE = 10
 
 
 def check_url(url: str) -> str | None:
@@ -252,7 +261,8 @@ def findings_payload(url: str, findings: list, kind: str = "dast") -> list:
     } for f in findings]
 
 
-def build_report(url: str, findings: list, skipped: list, ran: list, mode: str = "ZAP baseline, passive") -> tuple:
+def build_report(url: str, findings: list, skipped: list, ran: list, mode: str = "ZAP baseline, passive",
+                 incomplete: str = "") -> tuple:
     counts = {s: 0 for s in SEVERITIES}
     for f in findings:
         counts[f["severity"]] += 1
@@ -268,6 +278,8 @@ def build_report(url: str, findings: list, skipped: list, ran: list, mode: str =
         L.append(f"_ran: {', '.join(ran)}_")
     for s in skipped:
         L.append(f"- ⚠️ **SKIPPED** — {s}")
+    if incomplete:
+        L.append(f"- ⚠️ **INCOMPLETE** — {incomplete}")
     if ran and not findings:
         L.append("- ✅ no findings")
     for f in sorted(findings, key=lambda x: SEVERITY_RANK[x["severity"]]):
@@ -280,11 +292,30 @@ def build_report(url: str, findings: list, skipped: list, ran: list, mode: str =
     return "\n".join(L), counts, total
 
 
+def zap_config(host: str, active_api: bool, max_minutes: int, rate: int) -> list:
+    """ZAP -config options (-z). zaproxy.org/docs/docker/api-scan: -T bounds only ZAP's start and the
+    passive scan, so an active scan is capped by scanner.maxScanDurationInMins (ScannerParam.java),
+    2 minutes under --max-minutes to leave time for the start and the report. The pace is the Network
+    add-on's rate limit (Options → Network → Rate Limit; keys from RateLimitOptions.java): one rule
+    for the target host, `rate` requests per second."""
+    opts = []
+    if active_api:
+        opts += ["-config", f"scanner.maxScanDurationInMins={max(1, max_minutes - 2)}"]
+    if rate:
+        rule = "network.ratelimit.rules.rule(0)."
+        opts += ["-config", rule + "description=ikanban-dastscan", "-config", rule + "enabled=true",
+                 "-config", rule + "regex=false", "-config", rule + f"matchStr={host}",
+                 "-config", rule + f"reqsPerSec={rate}", "-config", rule + "groupBy=RULE"]
+    return opts
+
+
 def run_zap(url: str, minutes: int, max_minutes: int, work: Path,
-            spec_file: Path | None = None, passive: bool = True) -> tuple[dict | None, str]:
-    """(report, "") or (None, why it did not run). ZAP writes zap.json into <work>/zap/.
-    With spec_file: the API scan (active unless passive), the sign-in header from this shell's
-    ZAP_AUTH_HEADER_VALUE passed by name only (`-e NAME`), its value in the process environment."""
+            spec_file: Path | None = None, passive: bool = True, rate: int = 0) -> tuple[dict | None, str]:
+    """(report, "") for a complete run; (report, why) for a partial report (ZAP hit the time limit
+    or failed after writing it: filed as an incomplete run); (None, why) when there is no report.
+    ZAP writes zap.json into <work>/zap/. With spec_file: the API scan (active unless passive), the
+    sign-in header from this shell's ZAP_AUTH_HEADER_VALUE passed by name only (`-e NAME`), its value
+    in the process environment."""
     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;
@@ -292,7 +323,10 @@ def run_zap(url: str, minutes: int, max_minutes: int, work: Path,
     zap_dir = work / "zap"
     zap_dir.mkdir(exist_ok=True)
     os.chmod(zap_dir, 0o777)
-    cmd, env = ["docker", "run", "--rm", "-v", f"{zap_dir}:/zap/wrk/:rw"], None
+    # A name, so a run past the limit can be stopped: killing `docker run` leaves the container going.
+    name = f"ikanban-dastscan-{os.getpid()}-{int(time.time())}"
+    cmd, env = ["docker", "run", "--rm", "--name", name, "-v", f"{zap_dir}:/zap/wrk/:rw"], None
+    host = urllib.parse.urlsplit(url).hostname or ""
     if spec_file is not None:
         # The checked copy, read-only; -O pins every request to the registered host
         # (zap-api-scan.py: "-O the hostname to override in the (remote) OpenAPI spec").
@@ -303,7 +337,7 @@ def run_zap(url: str, minutes: int, max_minutes: int, work: Path,
             # Only what ZAP needs, plus PATH for docker itself: never VIBE_API_TOKEN or other keys.
             env = {k: v for k, v in os.environ.items() if k in ("PATH", "HOME", "DOCKER_HOST", "DOCKER_CONFIG",
                                                                  "DOCKER_CONTEXT", "ZAP_AUTH_HEADER")}
-            env.update(ZAP_AUTH_HEADER_VALUE=auth, ZAP_AUTH_HEADER_SITE=urllib.parse.urlsplit(url).hostname or "")
+            env.update(ZAP_AUTH_HEADER_VALUE=auth, ZAP_AUTH_HEADER_SITE=host)
             cmd += ["-e", "ZAP_AUTH_HEADER_VALUE", "-e", "ZAP_AUTH_HEADER_SITE"]
             if "ZAP_AUTH_HEADER" in env:
                 cmd += ["-e", "ZAP_AUTH_HEADER"]
@@ -311,20 +345,38 @@ def run_zap(url: str, minutes: int, max_minutes: int, work: Path,
                 "-J", "zap.json", "-T", str(max_minutes)] + (["-S"] if passive else [])
     else:
         cmd += [ZAP_IMAGE, "zap-baseline.py", "-t", url, "-J", "zap.json", "-m", str(minutes), "-T", str(max_minutes)]
+    opts = zap_config(host, spec_file is not None and not passive, max_minutes, rate)
+    if opts:
+        cmd += ["-z", shlex.join(opts)]  # zap_common.add_zap_options splits it with shlex
+    limit = max_minutes + GRACE_MINUTES
     try:
-        p = subprocess.run(cmd, capture_output=True, text=True, timeout=(max_minutes + 5) * 60, env=env)
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=limit * 60, env=env)
+        code, tail = p.returncode, (p.stderr or p.stdout or "").strip()[-300:]
     except FileNotFoundError:
         return None, DOCKER_INSTALL
     except subprocess.TimeoutExpired:
-        return None, f"ZAP did not finish within {max_minutes + 5} minutes"
+        code, tail = None, ""
+        try:
+            subprocess.run(["docker", "stop", "-t", "30", name], capture_output=True, text=True, timeout=120)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
     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:
+    report = None
+    if out.exists():
+        try:
+            report = json.loads(out.read_text() or "{}")
+        except ValueError:
+            report = None
+    if report is not None and code in (0, 1, 2):
+        return report, ""
+    if report is not None:
+        how = f"ZAP was stopped at the {limit}-minute limit" if code is None else f"ZAP exited {code}"
+        return report, f"{how}; its report is partial, so this run is filed as incomplete"
+    if code is None:
+        return None, f"ZAP did not finish within {limit} minutes and wrote no report"
+    if code in (0, 1, 2) and out.exists():
         return None, "ZAP wrote no JSON report"
+    return None, f"ZAP failed (exit {code}): {tail or 'no report'}"
 
 
 # ── copied from ikanban-secscan.py: key-host pinning and the API call ──────────────────
@@ -521,9 +573,12 @@ class Pipeline:
         if not ok:
             self._off(data or "this iKanban server has no Pipelines")
 
-    def start(self):
+    def start(self, url=""):
+        # Plan 11 H14: the URL as the running event's detail, so iKASecure's DAST targets list
+        # shows "Scanning…" on that target.
         self._post("pipeline-events", {"task": self.task, "stage": self.stage, "status": "running",
-                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}"})
+                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}",
+                                       "detail": url[:300] or None})
 
     def log(self, line):
         """One progress line, sent as it happens (masked like the report). A failure only turns Pipelines off."""
@@ -553,9 +608,10 @@ def run_main(stage, main_fn, argv=None):
     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"))
+    pre.add_argument("--url", default="")
     known, _ = pre.parse_known_args(raw)
     pl = Pipeline(stage, known.task, known.task_team or known.team, known.base_url, known.token)
-    pl.start()
+    pl.start(known.url.strip())
     global PIPE
     PIPE = pl if pl.on else None
     try:
@@ -581,7 +637,13 @@ def main(argv=None):
     ap.add_argument("--passive", action="store_true",
                     help="With --openapi: no attacks (ZAP -S); the only way to scan the production iKanban API")
     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("--max-minutes", type=int, default=10,
+                    help="Most minutes ZAP may take (default 10): ZAP -T, and for an active API scan "
+                         "scanner.maxScanDurationInMins = this minus 2. The scanner waits 3 minutes more for "
+                         "ZAP's report, then stops it; a late report files as an incomplete run")
+    ap.add_argument("--rate", type=int, default=None, metavar="N",
+                    help="Most requests per second ZAP sends to the target (ZAP's Network rate limit). "
+                         f"Default {DEFAULT_API_RATE} for an active API scan, no limit otherwise; 0 = no limit")
     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")
@@ -624,6 +686,9 @@ def main(argv=None):
         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
+    if args.rate is not None and not 0 <= args.rate <= 1000:
+        print("error: --rate from 0 (no limit) to 1000 requests per second", file=sys.stderr)
+        return 2
     if args.passive and not args.openapi:
         print("error: --passive goes with --openapi (the baseline scan is always passive)", file=sys.stderr)
         return 2
@@ -650,27 +715,32 @@ def main(argv=None):
         write_private(spec_file, json.dumps(doc))
         os.chmod(spec_file, 0o644)  # ZAP reads it as its own user; the run folder above stays 0700
         mode = "ZAP API scan, " + ("passive" if args.passive else "active")
+        rate = args.rate if args.rate is not None else (0 if args.passive else DEFAULT_API_RATE)
         progress(f"dastscan {DASTSCAN_VERSION} · {mode} on {url}: at most {args.max_minutes} min …")
-        report, skipped_why = run_zap(url, args.minutes, args.max_minutes, work, spec_file, args.passive)
+        report, skipped_why = run_zap(url, args.minutes, args.max_minutes, work, spec_file, args.passive, rate)
         ran = [f"zap-api-scan.py -f openapi -O {urllib.parse.urlsplit(url).netloc}"
                + (" -S" if args.passive else "")] if report is not None else []
     else:
         mode = "ZAP baseline, passive"
         progress(f"dastscan {DASTSCAN_VERSION} · ZAP baseline on {url}: spider {args.minutes} min, "
                  f"at most {args.max_minutes} min …")
-        report, skipped_why = run_zap(url, args.minutes, args.max_minutes, work)
+        report, skipped_why = run_zap(url, args.minutes, args.max_minutes, work, None, True, args.rate or 0)
         ran = [f"zap-baseline.py -t {url} -m {args.minutes}"] if report is not None else []
+    # A report with a reason is partial: filed, but as an incomplete run (no control reads Enforced).
+    incomplete = skipped_why if report is not None else ""
+    skipped_why = "" if report is not None else skipped_why
     findings = parse_zap(report) if report is not None else []
-    progress(f"{mode.split(',')[0]} on {url} … " + (f"done, {len(findings)} alerts" if report is not None
-                                                   else "SKIPPED (the reason is in the report)"))
-    md, counts, total = build_report(url, findings, [skipped_why] if skipped_why else [], ran, mode)
+    progress(f"{mode.split(',')[0]} on {url} … " + ("SKIPPED (the reason is in the report)" if report is None else
+                                                   f"done, {len(findings)} alerts" + (" (partial)" if incomplete else "")))
+    md, counts, total = build_report(url, findings, [skipped_why] if skipped_why else [], ran, mode, incomplete)
     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))
+        print(json.dumps({"url": url, "total": total, "counts": counts, "skipped": bool(skipped_why),
+                          "complete": report is not None and not incomplete}, indent=2))
     else:
         print(md)
     sys.stdout.flush()
@@ -688,7 +758,7 @@ def main(argv=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, kind), "scope": url, "complete": True,
+                           {"findings": findings_payload(url, findings, kind), "scope": url, "complete": not incomplete,
                             "kind": kind})
             if not ok:
                 print(f"filing {kind} findings FAILED: {data or 'this iKanban server does not take them yet'}",