ikanban 0.4.5 → 0.4.6

package/README.md

@@ -9,6 +9,8 @@ npx ikanban aiscan --help           # red-team scan of your AI app (OWASP LLM To
 npx ikanban secscan --publish       # also file the report and findings into iKanban
 npx ikanban infrascan --image app:1 # IaC misconfiguration and container image scan (Trivy)
 npx ikanban dastscan --url URL      # passive web scan of a registered URL (OWASP ZAP in Docker)
+npx ikanban dastscan --url URL --openapi openapi.json   # API scan of a registered URL (ZAP, active)
+npx ikanban cloudscan --aws-profile P --region R --account ID   # read-only AWS account audit (Prowler)
 npx ikanban secscan --task IKA-123  # also show the run in that task's Pipelines
 npx ikanban roadmap sync plan.json  # make the Roadmap plan match the plan file
 npx ikanban hooks install           # sync plan files on every agent write and git push
@@ -33,6 +35,19 @@ No CI is needed.
 [OWASP ZAP](https://www.zaproxy.org/docs/docker/baseline-scan/) baseline scan in Docker: it reads
 the site's responses and does not attack. It scans only a URL the team registered in iKASecure →
 Infrastructure, so it always needs `--team` and a key. Findings show on the Infrastructure tab.
+With `--openapi FILE_OR_URL`, `dastscan` runs ZAP's [API scan](https://www.zaproxy.org/docs/docker/api-scan/)
+instead: an active scan of the routes the OpenAPI 3 description lists (`--passive` makes it read-only).
+The description is a JSON file whose `servers` are the registered URL's origin, or a URL on that origin.
+The production iKanban API is scanned only with `--passive`. A sign-in header comes from
+`ZAP_AUTH_HEADER_VALUE` in your shell and reaches ZAP through the container's environment only.
+
+`cloudscan` runs [Prowler](https://github.com/prowler-cloud/prowler) (`prowlercloud/prowler:5.44.0`)
+in Docker against one AWS account and region with your own profile. It checks the account first
+(`aws sts get-caller-identity`, refused if it is not `--account`), passes short-lived credentials
+from `aws configure export-credentials` by name in the container environment, and never mounts
+`~/.aws`. Use a read-only role (SecurityAudit plus ViewOnlyAccess). Only findings are filed: the
+AWS infrastructure audit, Database network isolation and Database security review rows.
+
 Without a `trivy` command, `infrascan` runs Trivy's official container (`aquasec/trivy:0.76.0`)
 when Docker is running: the repository is mounted read-only, and the Docker socket only for an
 image that exists on this machine alone. The report names the Trivy that ran. With neither Trivy
@@ -75,7 +90,7 @@ line as each step starts and ends. A plan without Pipelines never fails the scan
 
 - Node.js 18 or newer.
 - Python 3.9 or newer. The scanners are Python; `ikanban` finds `python3`, `python` or `py -3`.
-- `infrascan`: Trivy (macOS `brew install trivy`; other systems: a release binary), or Docker running. `dastscan`: Docker.
+- `infrascan`: Trivy (macOS `brew install trivy`; other systems: a release binary), or Docker running. `dastscan`: Docker. `cloudscan`: the AWS CLI v2 and Docker.
 
 ## Free and paid
 

package/bin/ikanban.js

@@ -11,7 +11,8 @@ const COMMANDS = {
   aiscan: { file: "ikanban-aiscan.py", about: "Red-team scan of your AI app (OWASP LLM Top 10)" },
   secscan: { file: "ikanban-secscan.py", about: "Dependency, secret and file-permission scan of a repo" },
   infrascan: { file: "ikanban-infrascan.py", about: "Container image and IaC scan (needs Trivy)" },
-  dastscan: { file: "ikanban-dastscan.py", about: "Passive web scan of a registered URL (needs Docker)" },
+  dastscan: { file: "ikanban-dastscan.py", about: "Web or API scan of a registered URL (needs Docker)" },
+  cloudscan: { file: "ikanban-cloudscan.py", about: "Read-only AWS account audit (needs AWS CLI, Docker)" },
 };
 
 function help() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikanban",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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

@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""
+ikanban-cloudscan — a read-only audit of YOUR OWN AWS account, reporting into iKanban's
+Infrastructure tab (plan 11 H14): AWS infrastructure audit, Database network isolation and
+Database security review.
+
+    npx ikanban cloudscan --aws-profile NAME --region ap-southeast-1 --account 123456789012
+    npx ikanban cloudscan ... --publish --team TEAM      # file the report and findings
+
+It runs Prowler (Apache-2.0, https://github.com/prowler-cloud/prowler) from its pinned image in
+Docker, which must already be running:
+    docker run --rm --env AWS_ACCESS_KEY_ID --env AWS_SECRET_ACCESS_KEY --env AWS_SESSION_TOKEN \
+        -v DIR:/out prowlercloud/prowler:5.44.0 aws -f REGION -s SERVICES... -M json-ocsf -o /out -z
+(docs.prowler.com, Prowler CLI: -f region, -s services, -M output mode, -o output folder,
+-z ignore exit code 3, which only means failed checks were found.)
+
+Credential safety (h14-design.md):
+- The AWS CLI on this machine exports short-lived credentials for the named profile
+  (`aws configure export-credentials --profile NAME --format process`). They go into the
+  container's environment by name (`--env NAME`); their values are never on a command line,
+  in a file, in the report or in a progress line. ~/.aws is never mounted: this machine may
+  hold other profiles.
+- `aws sts get-caller-identity` runs first; a different account than --account stops the scan.
+- Prowler makes read calls only. A role whose name has none of ReadOnly, SecurityAudit or
+  ViewOnly gets a warning, because write access cannot be proved absent.
+- Only findings leave this machine: check id, resource ARN, region, severity and Prowler's
+  plain remediation text. Never the credentials, never Prowler's raw output.
+
+One run files three kinds: "cloud" (every failed check), "db-network" and "db-config" (only the
+check ids listed below). An account with no RDS resource publishes the two database kinds as
+incomplete, so those controls never read Enforced on an empty account.
+
+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
+
+CLOUDSCAN_VERSION = "1.0.0"
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
+# Pinned released tag (hub.docker.com prowlercloud/prowler tags: 5.44.0, amd64 and arm64).
+PROWLER_IMAGE = "prowlercloud/prowler:5.44.0"
+SERVICES = ["iam", "s3", "ec2", "rds", "cloudtrail", "kms"]
+CRED_VARS = ("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN")
+READ_ONLY_HINTS = ("readonly", "securityaudit", "viewonly")
+DOCKER_INSTALL = ("Docker is not installed or not running — install Docker Desktop "
+                  "(https://docs.docker.com/get-docker/), start it, and re-run")
+AWS_INSTALL = ("the AWS CLI is not installed — install it (macOS: brew install awscli; others: "
+               "https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), "
+               "sign in with `aws sso login --profile NAME`, and re-run")
+
+# h14-design.md: the checks that decide each database row.
+DB_NETWORK_CHECKS = (
+    "rds_instance_no_public_access",
+    "rds_instance_inside_vpc",
+    "rds_snapshots_public_access",
+    "ec2_securitygroup_allow_ingress_from_internet_to_tcp_port_postgres_5432",
+)
+DB_CONFIG_CHECKS = (
+    "rds_instance_storage_encrypted",
+    "rds_cluster_storage_encrypted",
+    "rds_snapshots_encrypted",
+    "rds_instance_transport_encrypted",
+    "rds_instance_backup_enabled",
+    "rds_instance_protected_by_backup_plan",
+    "rds_instance_deletion_protection",
+    "rds_cluster_deletion_protection",
+    "rds_instance_iam_authentication_enabled",
+    "rds_cluster_iam_authentication_enabled",
+    "rds_instance_minor_version_upgrade_enabled",
+    "rds_cluster_minor_version_upgrade_enabled",
+    "rds_instance_enhanced_monitoring_enabled",
+    "rds_instance_multi_az",
+    "rds_instance_deprecated_engine_version",
+    "rds_instance_default_admin",
+)
+KINDS = (("cloud", "AWS infrastructure audit", None),
+         ("db-network", "Database network isolation", DB_NETWORK_CHECKS),
+         ("db-config", "Database security review", DB_CONFIG_CHECKS))
+CATEGORY = {"cloud": "A05 — Security Misconfiguration",
+            "db-network": "A01 — Broken Access Control",
+            "db-config": "A02 — Cryptographic Failures"}
+OCSF_SEVERITY = {"critical": "critical", "high": "high", "medium": "medium", "low": "low"}  # Informational: report only
+MAX_FILED = 500  # the server takes at most this many findings in one publish
+
+PROFILE_RE = re.compile(r"^[A-Za-z0-9_.+=,@-]{1,64}$")
+REGION_RE = re.compile(r"^[a-z]{2}(-[a-z]+)+-\d{1,2}$")
+ACCOUNT_RE = re.compile(r"^\d{12}$")
+SECRETS: list = []  # this run's credential values, cut from anything printed or sent
+
+
+def run(cmd, env=None, timeout=900):
+    """(exit code, stdout, stderr). Never raises."""
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, env=env)
+        return p.returncode, p.stdout, p.stderr
+    except FileNotFoundError:
+        return 127, "", "not-installed"
+    except subprocess.TimeoutExpired:
+        return 124, "", f"timed out after {timeout}s"
+
+
+def scrub_report(text: str) -> tuple:
+    """Cut this run's credential values, any AWS access key id, iKanban keys and the home folder."""
+    for s in SECRETS:
+        if s:
+            text = text.replace(s, "[hidden]")
+    text = re.sub(r"\b(AKIA|ASIA)[A-Z0-9]{16}\b", "[hidden key id]", text)
+    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), 0
+
+
+def check_args(args) -> str | None:
+    if not PROFILE_RE.match(args.aws_profile or ""):
+        return "--aws-profile takes a profile name from your AWS config (letters, digits, . _ - + = , @)"
+    if not REGION_RE.match(args.region or ""):
+        return "--region takes an AWS region such as ap-southeast-1"
+    if not ACCOUNT_RE.match(args.account or ""):
+        return "--account takes the 12-digit AWS account id the profile must belong to"
+    bad = [s for s in args.services if not re.match(r"^[a-z0-9-]{2,40}$", s)]
+    return f"--services: not a Prowler service name: {bad[0]}" if bad else None
+
+
+def credentials(profile: str) -> tuple[dict | None, str]:
+    """The profile's short-lived credentials as environment values, or (None, why)."""
+    code, out, _err = run(["aws", "configure", "export-credentials", "--profile", profile, "--format", "process"],
+                          timeout=120)
+    if code == 127:
+        return None, AWS_INSTALL
+    try:
+        c = json.loads(out) if code == 0 else {}
+    except ValueError:
+        c = {}
+    vals = {"AWS_ACCESS_KEY_ID": c.get("AccessKeyId"), "AWS_SECRET_ACCESS_KEY": c.get("SecretAccessKey"),
+            "AWS_SESSION_TOKEN": c.get("SessionToken")}
+    if not vals["AWS_ACCESS_KEY_ID"] or not vals["AWS_SECRET_ACCESS_KEY"]:
+        return None, (f"the AWS CLI gave no credentials for profile {profile}: sign in "
+                      f"(`aws sso login --profile {profile}`) and re-run")
+    SECRETS.extend(v for v in vals.values() if v)
+    return {k: v for k, v in vals.items() if v}, ""
+
+
+def caller(profile: str) -> tuple[dict | None, str]:
+    code, out, _err = run(["aws", "sts", "get-caller-identity", "--profile", profile, "--output", "json"], timeout=120)
+    if code == 127:
+        return None, AWS_INSTALL
+    try:
+        ident = json.loads(out) if code == 0 else None
+    except ValueError:
+        ident = None
+    return (ident, "") if isinstance(ident, dict) else (None, f"`aws sts get-caller-identity` failed for profile {profile}")
+
+
+def role_name(arn: str) -> str:
+    """The role (or user) in a caller ARN: assumed-role/NAME/session → NAME."""
+    tail = arn.split(":", 5)[-1]
+    parts = tail.split("/")
+    return parts[1] if parts[0] == "assumed-role" and len(parts) > 1 else parts[-1]
+
+
+def run_prowler(region: str, services: list, creds: dict, work: Path) -> tuple[list | None, str]:
+    """(OCSF rows, "") or (None, why it did not run). Prowler writes into <work>/prowler/."""
+    if not shutil.which("docker") or run(["docker", "info"], timeout=30)[0] != 0:
+        return None, DOCKER_INSTALL
+    out = work / "prowler"
+    out.mkdir(exist_ok=True)
+    os.chmod(out, 0o777)  # the image writes as its own user; the run folder above stays 0700
+    cmd = ["docker", "run", "--rm"]
+    for name in CRED_VARS:
+        if name in creds:
+            cmd += ["--env", name]
+    cmd += ["-v", f"{out}:/out", PROWLER_IMAGE, "aws", "-f", region, "-s", *services,
+            "-M", "json-ocsf", "-o", "/out", "-z"]
+    env = {k: v for k, v in os.environ.items() if k in ("PATH", "HOME", "DOCKER_HOST", "DOCKER_CONFIG", "DOCKER_CONTEXT")}
+    env.update(creds)
+    code, _o, err = run(cmd, env=env, timeout=3600)
+    if code != 0:
+        print(f"prowler: {scrub_report((err or '').strip()[-300:])[0]}", file=sys.stderr)
+        return None, f"Prowler failed (exit {code}); its error is on this terminal"
+    files = sorted(out.rglob("*.ocsf.json"))
+    if not files:
+        return None, "Prowler wrote no json-ocsf file"
+    rows = []
+    for f in files:
+        try:
+            data = json.loads(f.read_text() or "[]")
+        except ValueError:
+            return None, "Prowler wrote a json-ocsf file that is not JSON"
+        rows += data if isinstance(data, list) else []
+    return rows, ""
+
+
+def check_id(row: dict) -> str:
+    return str((row.get("metadata") or {}).get("event_code") or "")
+
+
+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."""
+    findings, rds = [], set()
+    for r in rows:
+        cid = check_id(r)
+        res = (r.get("resources") or [{}])[0] or {}
+        uid = str(res.get("uid") or "")
+        if cid.startswith("rds_") and uid:
+            rds.add(uid)
+        if str(r.get("status_code", "")).upper() != "FAIL":
+            continue
+        sev = OCSF_SEVERITY.get(str(r.get("severity", "")).lower())
+        if not sev or not cid:
+            continue
+        info = r.get("finding_info") or {}
+        fix = (r.get("remediation") or {}).get("desc") or "See the Prowler check for the fix."
+        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),
+            "remediation": str(fix),
+        })
+    return findings, len(rds)
+
+
+def finding_key(kind: str, scope: str, f: dict) -> str:
+    raw = f"{kind}|{scope}|{f['check']}|{f['resource']}"
+    return "cloudscan-" + hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def section(kind: str, findings: list, checks) -> tuple[list, bool]:
+    """The findings a kind files (the worst MAX_FILED), and whether that is all of them."""
+    keep = [f for f in findings if checks is None or f["check"] in checks]
+    keep.sort(key=lambda f: (SEVERITY_RANK[f["severity"]], f["check"], f["resource"]))
+    return keep[:MAX_FILED], len(keep) <= MAX_FILED
+
+
+def findings_payload(kind: str, scope: str, findings: list) -> list:
+    return [{
+        "finding_key": finding_key(kind, scope, f),
+        "owasp_category": CATEGORY[kind],
+        "severity": f["severity"].capitalize(),
+        "title": scrub_report(f"{f['title']} ({f['check']})")[0][:300],
+        "location_file": f["resource"][:500] or None,
+        "location_lines": None,
+        "remediation": scrub_report(f"Region {f['region']}. Check {f['check']}. {f['remediation']}")[0][:2000],
+    } for f in findings]
+
+
+def build_report(scope: str, findings: list, skipped: list, ran: list, rds: int, notes: 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"# Cloud account audit — {scope}", "", f"_{stamp} · `ikanban-cloudscan` (Prowler, read-only)_", "",
+         "| Severity | Count |", "|---|---|"]
+    L += [f"| {s} | {counts[s]} |" for s in SEVERITIES if counts[s]]
+    if not total:
+        L.append("| _none_ | 0 |")
+    L += ["", f"**{total} failed check(s).**", ""]
+    if ran:
+        L.append(f"_ran: {', '.join(ran)}_")
+    for s in skipped:
+        L.append(f"- ⚠️ **SKIPPED** — {s}")
+    for n in notes:
+        L.append(f"- {n}")
+    for kind, name, checks in KINDS:
+        rows = [f for f in findings if checks is None or f["check"] in checks]
+        L += ["", f"## {name} ({kind})"]
+        if not ran:
+            L.append("- not checked")
+        elif kind != "cloud" and not rds:
+            L.append("- no RDS resource in this region: not counted as a pass")
+        elif not rows:
+            L.append("- ✅ no failed checks")
+        for f in sorted(rows, key=lambda x: SEVERITY_RANK[x["severity"]]):
+            L.append(f"- **[{f['severity']}]** {f['title']} (`{f['check']}`) — `{f['resource']}`")
+    L += ["", "---", "", "Read-only checks with your own AWS profile; only findings are filed. Skipped checks are gaps, not passes."]
+    return scrub_report("\n".join(L))[0], counts, total
+
+
+# ── 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)
+
+
+# ── 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)
+# Every iKanban scanner reports into one named lane, not the server's "legacy" lane.
+PIPE_RUN = "security-scan"
+PIPE_CHUNK = 15 * 1024  # the server takes 16 KB per 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
+
+# The running Pipeline (set by run_main with --task). Owner: Pipelines showed nothing while a
+# scan ran, so each step also sends one line as it starts and ends; the full report follows at the end.
+# Progress lines are fixed status text: never raw tool output or an error body (it can carry
+# secrets or text an attacker wrote). Those stay on local stderr and in the masked report.
+PIPE = None
+
+
+def progress(text: str) -> None:
+    if PIPE:
+        PIPE.log(text)
+
+
+
+class Pipeline:
+    def __init__(self, stage, task, team, base_url, token):
+        self.stage, self.task, self.team, self.base, self.token = stage, task, team, base_url, token
+        self.on = bool(task and team and token)
+        self.tid = None
+
+    def _off(self, why):
+        self.on = False
+        note = "the plan does not include Pipelines" if "402" in str(why) else why
+        print(f"ikanban: Pipelines not updated ({note}); the scan goes on", file=sys.stderr)
+
+    def _call(self, method, path, body=None):
+        try:
+            return api(method, path, self.base, self.token, body)
+        except SystemExit as e:  # ikanban_api refuses a base URL that is not iKanban's
+            return False, str(e)
+
+    def _post(self, path, body):
+        if not self.on:
+            return
+        if self.tid is None:
+            if _UUID.match(self.team):
+                self.tid = self.team
+            else:
+                ok, teams = self._call("GET", "/teams")
+                if not ok:
+                    return self._off(teams)
+                found = [t.get("id") for t in teams or [] if (t.get("identifier") or "").lower() == self.team.lower()]
+                if not found:
+                    return self._off(f"team {self.team} not found among your teams")
+                self.tid = found[0]
+        ok, data = self._call("POST", f"/teams/{self.tid}/{path}", body)
+        if not ok:
+            self._off(data or "this iKanban server has no Pipelines")
+
+    def start(self):
+        self._post("pipeline-events", {"task": self.task, "stage": self.stage, "status": "running",
+                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}"})
+
+    def log(self, line):
+        """One progress line, sent as it happens (masked like the report). A failure only turns Pipelines off."""
+        self._post("pipeline-logs", {"task": self.task, "run": PIPE_RUN, "stage": self.stage,
+                                     "text": mask_report(line.rstrip("\n"))[:PIPE_CHUNK - 1] + "\n"})
+
+    def finish(self, code):
+        status = "failed" if code else ("skipped" if LAST_RUN["skipped"] else "passed")
+        detail = LAST_RUN["detail"] or ("the scan stopped with an error" if code == 2 else "")
+        if code == 1 and not LAST_RUN["skipped"]:
+            detail = (detail + " (at or above --fail-on)").strip()
+        self._post("pipeline-events", {"task": self.task, "stage": self.stage, "status": status,
+                                       "run": PIPE_RUN, "source": "laptop", "actor": f"ikanban-{self.stage}",
+                                       "detail": detail[:300] or None})
+        for chunk in log_chunks(mask_report(LAST_RUN["report"])):
+            self._post("pipeline-logs", {"task": self.task, "run": PIPE_RUN, "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()
+    global PIPE
+    PIPE = pl if pl.on else None
+    try:
+        code = main_fn(argv)
+    except SystemExit as e:
+        if not isinstance(e.code, int):
+            print(e.code, file=sys.stderr)
+        code = e.code if isinstance(e.code, int) else 2
+    pl.finish(code)
+    return code
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Read-only AWS account audit (Prowler) that reports into iKanban.")
+    ap.add_argument("--version", action="version", version=f"ikanban cloudscan {CLOUDSCAN_VERSION}")
+    ap.add_argument("--aws-profile", required=True, help="The AWS CLI profile to audit with (read-only role)")
+    ap.add_argument("--region", required=True, help="The AWS region to audit, e.g. ap-southeast-1")
+    ap.add_argument("--account", required=True, help="The 12-digit account id the profile must belong to")
+    ap.add_argument("--services", nargs="+", default=SERVICES,
+                    help=f"Prowler services to check (default: {' '.join(SERVICES)})")
+    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)
+
+    why = check_args(args)
+    if why:
+        print(f"error: {why}", 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
+    scope = f"aws:{args.account}:{args.region}"
+    progress(f"cloudscan {CLOUDSCAN_VERSION} · checking the AWS account for profile {args.aws_profile} …")
+    ident, why = caller(args.aws_profile)
+    if ident is not None and str(ident.get("Account")) != args.account:
+        print(f"error: profile {args.aws_profile} belongs to account {ident.get('Account')}, not {args.account}; "
+              "nothing was scanned", file=sys.stderr)
+        progress("account check … refused: the profile belongs to another account")
+        return 2
+    rows, skipped, ran = None, [], []
+    work = scan_work_dir("cloudscan", Path.cwd(), args.work_dir)
+    if ident is None:
+        skipped.append(why)
+    else:
+        role = role_name(str(ident.get("Arn", "")))
+        if not any(h in role.lower() for h in READ_ONLY_HINTS):
+            print(f"warning: role {role} has none of ReadOnly, SecurityAudit or ViewOnly in its name; Prowler only "
+                  "reads, but write access cannot be ruled out. Use a read-only role.", file=sys.stderr)
+        creds, why = credentials(args.aws_profile)
+        if creds is None:
+            skipped.append(why)
+        else:
+            progress(f"Prowler {PROWLER_IMAGE.split(':')[-1]} in {args.region}: {' '.join(args.services)} …")
+            rows, why = run_prowler(args.region, args.services, creds, work)
+            if rows is None:
+                skipped.append(why)
+            else:
+                ran.append(f"prowler aws -f {args.region} -s {' '.join(args.services)}")
+    findings, rds = parse_rows(rows or [], args.region)
+    progress("Prowler … " + (f"done, {len(findings)} failed checks" if ran else "SKIPPED (the reason is in the report)"))
+    sections, notes = [], []
+    for kind, name, checks in KINDS:
+        keep, whole = section(kind, findings, checks)
+        if not whole:
+            notes.append(f"{name}: filed the {MAX_FILED} worst; the rest are in this report only "
+                         "(this run counts as incomplete, so nothing closes).")
+        sections.append((kind, keep, whole))
+    md, counts, total = build_report(scope, findings, skipped, ran, rds, notes)
+    LAST_RUN.update(report=md, detail=summary_detail(counts, total, [] if ran else skipped), skipped=not ran)
+    write_private(work / "report.md", md)
+    if args.out:
+        Path(args.out).write_text(md)
+    if args.json:
+        print(json.dumps({"scope": scope, "total": total, "counts": counts, "rds_resources": rds,
+                          "skipped": skipped}, 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"Cloud account audit — {scope} — "
+                        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 not ran:
+            print("Prowler did not run: nothing filed or closed", file=sys.stderr)
+        for kind, keep, whole in sections if ran else []:
+            db = kind != "cloud"
+            body = {"findings": findings_payload(kind, scope, keep), "scope": scope,
+                    "complete": whole and (rds > 0 or not db), "kind": kind}
+            if db:
+                body["resources"] = rds
+            ok, data = api("POST", f"/teams/{args.team}/security/scan-findings", args.base_url, args.token, body)
+            if not ok:
+                print(f"filing {kind} findings FAILED: {data or 'this iKanban server does not take them yet'}",
+                      file=sys.stderr)
+                return 2
+            print(f"filed {data.get('submitted', 0)} {kind} findings ({data.get('new', 0)} new, reopened "
+                  f"{data.get('reopened', 0)}, closed {data.get('closed', 0)} no longer found in {scope})"
+                  + ("; no RDS resource, so not counted as checked" if db and not rds else ""), 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("cloudscan", main))

package/scanners/ikanban-dastscan.py

@@ -23,6 +23,20 @@ JSON read (zaproxy.org traditional JSON report): site[].alerts[]: pluginid, aler
 (or alert), riskcode (a string: "3" High, "2" Medium, "1" Low, "0" Informational), desc,
 solution, reference, cweid, count, instances[].uri.
 
+Plan 11 H14: --openapi FILE_OR_URL runs ZAP's API scan instead, from an OpenAPI description:
+    docker run --rm -v DIR:/zap/wrk/:rw [-v SPEC:/zap/spec/NAME:ro] [-e ZAP_AUTH_HEADER_VALUE
+        -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
+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
+pinned to the target goes into the run folder, mounted read-only, and -O pins the host. The production iKanban API is
+scanned only with --passive. A sign-in header comes from ZAP_AUTH_HEADER_VALUE (and
+ZAP_AUTH_HEADER, default Authorization) in this shell; it reaches ZAP through the container's
+environment only (zaproxy.org: handling authentication yourself), never a command line or file.
+
 Helpers below are copied from ikanban-secscan.py (the scanners ship as single files).
 """
 
@@ -42,7 +56,7 @@ import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
 
-DASTSCAN_VERSION = "1.2.0"
+DASTSCAN_VERSION = "1.3.0"
 
 SEVERITIES = ["critical", "high", "medium", "low", "info"]
 SEVERITY_RANK = {s: i for i, s in enumerate(SEVERITIES)}
@@ -52,6 +66,9 @@ DOCKER_INSTALL = ("Docker is not installed or not running — install Docker Des
                   "(https://docs.docker.com/get-docker/), start it, and re-run")
 CATEGORY = "A05 — Security Misconfiguration"
 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
 
 
 def check_url(url: str) -> str | None:
@@ -68,6 +85,127 @@ def check_url(url: str) -> str | None:
     return None
 
 
+def origin(url: str) -> str:
+    u = urllib.parse.urlsplit(url)
+    return f"{u.scheme}://{(u.netloc or '').lower()}"
+
+
+def server_problem(entry, target: str, passive: bool) -> str | None:
+    """Why one `servers` entry is refused, or None. Only an http(s) URL on the target's own
+    origin, or a path starting with a single '/'. No template, no variables, no user info."""
+    if not isinstance(entry, dict) or not isinstance(entry.get("url"), str):
+        return "is not a {url: ...} object"
+    url = entry["url"]
+    if "variables" in entry or "{" in url or "}" in url:
+        return f"{url!r} uses server variables or a template"
+    if url.startswith("/") and not url.startswith("//"):
+        return None
+    u = urllib.parse.urlsplit(url)
+    if u.scheme not in ("http", "https") or not u.hostname or u.username is not None or "@" in u.netloc:
+        return f"{url!r} is not a plain http(s) URL or a path starting with '/'"
+    if u.hostname in PRODUCTION_HOSTS and not passive:
+        return f"{url!r} is the production API; scan it only with --passive"
+    if origin(url) != origin(target):
+        return f"{url!r} is not {origin(target)}, the registered target"
+    return None
+
+
+def walk(node, where="$"):
+    """Every (where, key, value) in the document, at any depth."""
+    if isinstance(node, dict):
+        for k, v in node.items():
+            yield f"{where}.{k}", k, v
+            yield from walk(v, f"{where}.{k}")
+    elif isinstance(node, list):
+        for n, v in enumerate(node):
+            yield from walk(v, f"{where}[{n}]")
+
+
+BAD_PATH = re.compile(r"//|[@\\#?\s\x00-\x1f\x7f]")
+
+
+def path_problem(key) -> str | None:
+    if not isinstance(key, str) or not key.startswith("/") or BAD_PATH.search(key):
+        return (f"path {key!r} must start with one '/' and hold no '//', '@', '\\', '#', '?', "
+                "spaces or control characters")
+    return None
+
+
+def fetch_spec(url: str) -> tuple[bytes | None, str]:
+    """Download the spec ourselves: same origin checked by the caller, no redirect (_OPENER),
+    a 5 MB cap and a timeout. ZAP is never handed a URL to fetch."""
+    try:
+        with _OPENER.open(urllib.request.Request(url, headers={"Accept": "application/json"}), timeout=30) as r:
+            body = r.read(MAX_SPEC_BYTES + 1)
+    except urllib.error.HTTPError as e:
+        return None, f"--openapi: {url} answered HTTP {e.code} (a redirect is not followed)"
+    except Exception as e:  # noqa: BLE001 — any transport failure stops the scan
+        return None, f"--openapi: could not download {url}: {type(e).__name__}"
+    return (None, "--openapi: the description is over 5 MB") if len(body) > MAX_SPEC_BYTES else (body, "")
+
+
+def load_spec(spec: str, target: str, passive: bool) -> tuple[str | None, dict | None]:
+    """(why the OpenAPI description is refused, or None; the checked document with every server
+    pinned to the target). A URL must be on the target's origin and is downloaded here; a file
+    must be JSON. Every servers entry must pass server_problem."""
+    if spec.startswith(("http://", "https://")):
+        why = check_url(spec)
+        if why:
+            return f"--openapi: {why}", None
+        if origin(spec) != origin(target):
+            return f"--openapi must be on {origin(target)}, the registered target's own address", None
+        raw, why = fetch_spec(spec)
+        if raw is None:
+            return why, None
+    else:
+        p = Path(spec).expanduser()
+        if not p.is_file():
+            return f"--openapi: {spec} is not a file", None
+        if p.stat().st_size > MAX_SPEC_BYTES:
+            return "--openapi: the description is over 5 MB", None
+        raw = p.read_bytes()
+    try:
+        doc = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return "--openapi: write the OpenAPI description as JSON (openapi.json)", None
+    if not isinstance(doc, dict) or not str(doc.get("openapi", "")).startswith("3"):
+        return "--openapi: the description is not OpenAPI 3", None
+    # One walk over the whole document (security review): every $ref stays inside it, and every
+    # server object, wherever it sits (servers lists, links' server, callbacks), passes the
+    # origin rule. Relative servers are pinned to the target as origin + path.
+    entries = []
+    for where, key, value in list(walk(doc)):
+        if key == "$ref" and not (isinstance(value, str) and value.startswith("#/")):
+            return f"--openapi: {where} {value!r} points outside the document; only '#/...' references", None
+        if key == "servers":
+            if not isinstance(value, list):
+                return f"--openapi: {where} is not a list", None
+            entries += [(f"{where}[{n}]", e) for n, e in enumerate(value)]
+        elif key == "server":
+            entries.append((where, value))
+    for where, entry in entries:
+        why = server_problem(entry, target, passive)
+        if why:
+            return f"--openapi: {where} {why}", None
+        if entry["url"].startswith("/"):
+            entry["url"] = origin(target) + entry["url"].rstrip("/")
+    paths = doc.get("paths") or {}
+    if not isinstance(paths, dict):
+        return "--openapi: paths is not an object", None
+    for key in paths:
+        why = path_problem(key)
+        if why:
+            return f"--openapi: {why}", None
+    if not doc.get("servers"):
+        doc["servers"] = [{"url": origin(target)}]
+    # Last check: every server + path URL ZAP can build is on the registered origin.
+    for server in [e["url"] for _, e in entries] + [s["url"] for s in doc["servers"]]:
+        for key in list(paths) or ["/"]:
+            if origin(server + key) != origin(target):
+                return f"--openapi: {server}{key} leaves {origin(target)}", None
+    return None, doc
+
+
 def strip_html(s: str) -> str:
     return re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", s or "")).strip()
 
@@ -97,14 +235,14 @@ def parse_zap(report: dict) -> list:
     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 finding_key(url: str, rule: str, title: str, kind: str = "dast") -> str:
+    """Stable per kind, target URL and ZAP rule, so a rescan files nothing new."""
+    return "dastscan-" + hashlib.sha256(f"{kind}|{url}|{rule}|{title}".encode()).hexdigest()[:16]
 
 
-def findings_payload(url: str, findings: list) -> list:
+def findings_payload(url: str, findings: list, kind: str = "dast") -> list:
     return [{
-        "finding_key": finding_key(url, f["rule"], f["title"]),
+        "finding_key": finding_key(url, f["rule"], f["title"], kind),
         "owasp_category": CATEGORY,
         "severity": f["severity"].capitalize(),
         "title": f["title"][:300],
@@ -114,18 +252,18 @@ def findings_payload(url: str, findings: list) -> list:
     } for f in findings]
 
 
-def build_report(url: str, findings: list, skipped: list, ran: list) -> tuple:
+def build_report(url: str, findings: list, skipped: list, ran: list, mode: str = "ZAP baseline, passive") -> 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)_", "",
+    L = [f"# DAST scan — {url}", "", f"_{stamp} · `ikanban-dastscan` ({mode})_", "",
          "| 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"]
+    L += ["", f"**{total} finding(s).**", "", "## Passive web scan" if "passive" in mode else "## API scan"]
     if ran:
         L.append(f"_ran: {', '.join(ran)}_")
     for s in skipped:
@@ -136,12 +274,17 @@ def build_report(url: str, findings: list, skipped: list, ran: list) -> tuple:
         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."]
+    L += ["", "---", "", ("A passive scan reads responses only; it does not attack." if "passive" in mode else
+                          "An active API scan sends attack requests to the registered target.")
+          + " 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/."""
+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."""
     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;
@@ -149,10 +292,27 @@ def run_zap(url: str, minutes: int, max_minutes: int, work: Path) -> tuple[dict
     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)]
+    cmd, env = ["docker", "run", "--rm", "-v", f"{zap_dir}:/zap/wrk/:rw"], None
+    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").
+        target = "/zap/spec/openapi.json"
+        cmd += ["-v", f"{spec_file}:{target}:ro"]
+        auth = os.environ.get("ZAP_AUTH_HEADER_VALUE", "")
+        if auth:
+            # 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 "")
+            cmd += ["-e", "ZAP_AUTH_HEADER_VALUE", "-e", "ZAP_AUTH_HEADER_SITE"]
+            if "ZAP_AUTH_HEADER" in env:
+                cmd += ["-e", "ZAP_AUTH_HEADER"]
+        cmd += [ZAP_IMAGE, "zap-api-scan.py", "-t", target, "-f", "openapi", "-O", urllib.parse.urlsplit(url).netloc,
+                "-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)]
     try:
-        p = subprocess.run(cmd, capture_output=True, text=True, timeout=(max_minutes + 5) * 60)
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=(max_minutes + 5) * 60, env=env)
     except FileNotFoundError:
         return None, DOCKER_INSTALL
     except subprocess.TimeoutExpired:
@@ -409,11 +569,17 @@ def run_main(stage, main_fn, argv=None):
 
 
 def main(argv=None):
-    ap = argparse.ArgumentParser(description="Passive DAST scan (OWASP ZAP baseline) of a registered URL.")
+    ap = argparse.ArgumentParser(description="DAST scan of a registered URL: OWASP ZAP baseline (passive), "
+                                 "or with --openapi ZAP's API scan.")
     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("--openapi", default="", metavar="FILE_OR_URL",
+                    help="Run ZAP's API scan (active) from this OpenAPI 3 description: a JSON file whose "
+                         "servers are the --url origin, or a URL on that origin. Files as kind 'api'.")
+    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("--publish", action="store_true", help="File the report and findings into iKanban")
@@ -458,20 +624,46 @@ 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.passive and not args.openapi:
+        print("error: --passive goes with --openapi (the baseline scan is always passive)", file=sys.stderr)
+        return 2
+    kind = "api" if args.openapi else "dast"
+    if kind == "api" and urllib.parse.urlsplit(url).hostname in PRODUCTION_HOSTS and not args.passive:
+        print(f"error: an active scan of the production API ({url}) is refused; scan the dev API, "
+              "or add --passive", file=sys.stderr)
+        return 2
     why = registered(url, args)
     if why:
         print(f"error: {why}", file=sys.stderr)
         return 2
+    doc = None
+    if kind == "api":
+        # Checked (and, for a URL, downloaded) only once the target is known to be registered.
+        why, doc = load_spec(args.openapi.strip(), url, args.passive)
+        if why:
+            print(f"error: {why}", file=sys.stderr)
+            return 2
 
     work = scan_work_dir("dastscan", Path.cwd(), args.work_dir)
-    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)
+    if kind == "api":
+        spec_file = work / "openapi.json"
+        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")
+        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)
+        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)
+        ran = [f"zap-baseline.py -t {url} -m {args.minutes}"] if report is not None else []
     findings = parse_zap(report) if report is not None else []
-    progress(f"ZAP baseline on {url} … " + (f"done, {len(findings)} alerts" if report is not None
-                                             else "SKIPPED (the reason is in the report)"))
-    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)
+    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)
     LAST_RUN.update(report=md, detail=summary_detail(counts, total, [] if ran else [skipped_why]),
                     skipped=not ran)
     write_private(work / "report.md", md)
@@ -486,7 +678,7 @@ def main(argv=None):
 
     if args.publish:
         ok, info = api("POST", "/security/scan-reports", args.base_url, args.token,
-                       {"team_id": args.team, "title": f"DAST scan — {url} — "
+                       {"team_id": args.team, "title": f"{'API scan' if kind == 'api' else '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)
@@ -496,13 +688,13 @@ 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), "scope": url, "complete": True,
-                            "kind": "dast"})
+                           {"findings": findings_payload(url, findings, kind), "scope": url, "complete": True,
+                            "kind": kind})
             if not ok:
-                print(f"filing DAST findings FAILED: {data or 'this iKanban server does not take them yet'}",
+                print(f"filing {kind} 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 "
+            print(f"filed {data.get('submitted', 0)} {kind} 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)