openhack-cli 0.1.0__py3-none-any.whl

openhack_cli/commands/pentest.py

@@ -0,0 +1,603 @@
+"""`openhack-cli pentest` — manage pentesting engagements and their findings.
+
+Engagements are organization-scoped. Findings live inside an engagement and
+support full CRUD plus cross-references (links) between related findings.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from .. import output
+from ..client import APIError
+from ..context import get_client, resolve_org_id
+
+# Allowed relationship types for linking findings.
+LINK_TYPES = ["related", "chains", "duplicate", "depends"]
+
+
+@click.group()
+def pentest() -> None:
+    """Manage pentesting engagements."""
+
+
+@pentest.command(name="list")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def list_engagements(ctx: click.Context, org: str | None) -> None:
+    """List pentesting engagements for an organization."""
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    data = client.get(f"/api/orgs/{org_id}/pentesting")
+    items = data.get("engagements", []) if isinstance(data, dict) else (data or [])
+
+    def render(rows):
+        if not rows:
+            output.warn("No pentesting engagements found.")
+            return
+        table = output.make_table(
+            "Pentesting Engagements",
+            ["Title", "Status", "Findings", "C", "H", "M", "L", "ID"],
+        )
+        for e in rows:
+            table.add_row(
+                output.short(e.get("title"), 36),
+                output.status_label(e.get("status")),
+                str(e.get("findingCount", 0)),
+                str(e.get("criticalCount", 0)),
+                str(e.get("highCount", 0)),
+                str(e.get("mediumCount", 0)),
+                str(e.get("lowCount", 0)),
+                output.short(e.get("id"), 38),
+            )
+        output.console.print(table)
+
+    output.emit(ctx.obj, items, render)
+
+
+@pentest.command(name="get")
+@click.argument("engagement_id")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def get_engagement(ctx: click.Context, engagement_id: str, org: str | None) -> None:
+    """Show a pentesting engagement and its members."""
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    data = client.get(f"/api/orgs/{org_id}/pentesting/{engagement_id}")
+
+    def render(payload):
+        e = payload.get("engagement", payload) if isinstance(payload, dict) else payload
+        output.console.print(f"[bold]{e.get('title')}[/bold]  "
+                             f"{output.status_label(e.get('status'))}")
+        output.console.print(f"  ID:    {e.get('id')}")
+        if e.get("companyName"):
+            output.console.print(f"  Company: {e['companyName']}")
+        if e.get("scope"):
+            output.console.print(f"  Scope: {output.short(e['scope'], 80)}")
+        output.console.print(
+            f"  Findings: {e.get('findingCount', 0)} — "
+            f"{output.severity_label('critical')} {e.get('criticalCount', 0)}  "
+            f"{output.severity_label('high')} {e.get('highCount', 0)}  "
+            f"{output.severity_label('medium')} {e.get('mediumCount', 0)}  "
+            f"{output.severity_label('low')} {e.get('lowCount', 0)}  "
+            f"{output.severity_label('info')} {e.get('infoCount', 0)}"
+        )
+        members = payload.get("members", []) if isinstance(payload, dict) else []
+        if members:
+            output.console.print(f"  Members: {len(members)}")
+
+    output.emit(ctx.obj, data, render)
+
+
+@pentest.command(name="findings")
+@click.argument("engagement_id", required=False)
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.option("--severity", default=None,
+              type=click.Choice(["critical", "high", "medium", "low", "info"]),
+              help="Filter by severity.")
+@click.pass_context
+def list_findings(ctx: click.Context, engagement_id: str | None,
+                  org: str | None, severity: str | None) -> None:
+    """List vulnerabilities (findings) in a pentest engagement.
+
+    With no ENGAGEMENT_ID, uses the most recent engagement in the org.
+    """
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+
+    # Default to the latest engagement (most recently created).
+    if not engagement_id:
+        data = client.get(f"/api/orgs/{org_id}/pentesting")
+        engagements = data.get("engagements", []) if isinstance(data, dict) else (data or [])
+        if not engagements:
+            raise click.ClickException("No pentest engagements in this org.")
+        latest = max(engagements, key=lambda e: e.get("createdAt") or "")
+        engagement_id = latest["id"]
+        if not ctx.obj.get("json"):
+            output.info(f"Latest engagement: [bold]{latest.get('title')}[/bold]")
+
+    res = client.get(f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings")
+    items = res.get("findings", []) if isinstance(res, dict) else (res or [])
+    if severity:
+        items = [f for f in items if (f.get("severity") or "").lower() == severity]
+    items.sort(key=lambda f: output.SEVERITY_ORDER.get(
+        (f.get("severity") or "").lower(), 9))
+
+    def render(rows):
+        if not rows:
+            output.warn("No findings in this engagement.")
+            return
+        table = output.make_table(
+            "Pentest Findings",
+            ["#", "Severity", "Title", "Category", "Component", "CVSS", "Status"],
+        )
+        for f in rows:
+            table.add_row(
+                str(f.get("number", "-")),
+                output.severity_label(f.get("severity")),
+                output.short(f.get("title"), 46),
+                output.short(f.get("category"), 16),
+                output.short(f.get("affectedComponent"), 18),
+                str(f.get("cvssScore") or "-"),
+                output.status_label(f.get("status")),
+            )
+        output.console.print(table)
+        output.console.print(f"\n[dim]{len(rows)} findings[/dim]")
+
+    output.emit(ctx.obj, items, render)
+
+
+@pentest.group(name="finding")
+def finding() -> None:
+    """Get or create individual pentest findings."""
+
+
+# Maps CLI flags -> API request body fields for finding creation.
+_FINDING_FIELDS = {
+    "title": "title",
+    "severity": "severity",
+    "description": "description",
+    "impact": "impact",
+    "poc": "poc",
+    "recommendation": "recommendation",
+    "relevant_code": "relevantCode",
+    "category": "category",
+    "cwe": "cweId",
+    "cvss_score": "cvssScore",
+    "cvss_vector": "cvssVector",
+    "affected_url": "affectedUrl",
+    "affected_parameter": "affectedParameter",
+    "affected_component": "affectedComponent",
+    "severity_justification": "severityJustification",
+    "internal_notes": "internalNotes",
+    "auth_required": "authRequired",
+    "unguessable_parameter_required": "unguessableParameterRequired",
+    "prerequisites": "prerequisites",
+    "status": "status",
+}
+
+
+@finding.command(name="get")
+@click.argument("engagement_id")
+@click.argument("finding_id")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def get_finding(ctx: click.Context, engagement_id: str, finding_id: str,
+                org: str | None) -> None:
+    """Show full details of a single pentest finding."""
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    res = client.get(
+        f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings/{finding_id}"
+    )
+    finding = res.get("finding", res) if isinstance(res, dict) else res
+    reporter = res.get("reporter") if isinstance(res, dict) else None
+    # relatedFindings may live on the finding or alongside it, depending on the API.
+    related = (finding.get("relatedFindings") if isinstance(finding, dict) else None) \
+        or (res.get("relatedFindings") if isinstance(res, dict) else None) or []
+
+    def render(_payload):
+        f = finding
+        output.console.print(
+            f"[bold]#{f.get('number')} {f.get('title')}[/bold]  "
+            f"{output.severity_label(f.get('severity'))}"
+        )
+        for label, key in [("Category", "category"), ("Component", "affectedComponent"),
+                           ("URL", "affectedUrl"), ("Parameter", "affectedParameter"),
+                           ("CWE", "cweId"), ("CVSS", "cvssScore"),
+                           ("Auth required", "authRequired"),
+                           ("Unguessable param", "unguessableParameterRequired"),
+                           ("Prerequisites", "prerequisites"),
+                           ("Status", "status")]:
+            if f.get(key) is not None:
+                output.console.print(f"  {label}: {f[key]}")
+        if reporter:
+            who = reporter.get("displayName") or reporter.get("email") or "-"
+            email = f" <{reporter['email']}>" if reporter.get("email") else ""
+            output.console.print(f"  Reporter: {who}{email}")
+        for label, key in [("Description", "description"), ("Impact", "impact"),
+                           ("PoC", "poc"), ("Recommendation", "recommendation"),
+                           ("Severity justification", "severityJustification")]:
+            if f.get(key):
+                output.console.print(f"\n[bold]{label}[/bold]\n{f[key]}")
+        if f.get("internalNotes"):
+            output.console.print(
+                f"\n[bold yellow]Internal notes[/bold yellow] "
+                f"[dim](not in report)[/dim]\n{f['internalNotes']}"
+            )
+        _render_related(related)
+
+    # JSON mode returns the full response (finding + reporter) per the spec.
+    output.emit(ctx.obj, res, render)
+
+
+def _finding_field_options(fn):
+    """Shared finding-field flags for `finding create` and `finding update`.
+
+    Booleans are tri-state (default None) so an unset flag is never sent — the
+    fields stay optional and `update` only touches what you pass.
+    """
+    options = [
+        click.option("--from-json", "from_json", default=None,
+                     help="Load the body from a JSON file ('-' for stdin). "
+                          "Keys are API field names (camelCase). Flags override."),
+        click.option("--title", default=None, help="Finding title."),
+        click.option("--severity", default=None,
+                     type=click.Choice(["critical", "high", "medium", "low", "info"]),
+                     help="Severity (analyst-assigned, independent of CVSS)."),
+        click.option("--severity-justification", default=None,
+                     help="Business-impact reasoning for the chosen severity "
+                          "(required by the server when severity doesn't match "
+                          "the CVSS score's band)."),
+        click.option("--description", default=None),
+        click.option("--impact", default=None),
+        click.option("--poc", default=None, help="Proof of concept."),
+        click.option("--recommendation", default=None),
+        click.option("--relevant-code", default=None),
+        click.option("--category", default=None),
+        click.option("--cwe", default=None, help="CWE id, e.g. CWE-200."),
+        click.option("--cvss-score", default=None, help="CVSS score, e.g. 5.3."),
+        click.option("--cvss-vector", default=None),
+        click.option("--affected-url", default=None),
+        click.option("--affected-parameter", default=None),
+        click.option("--affected-component", default=None),
+        click.option("--auth-required/--no-auth-required", "auth_required",
+                     default=None,
+                     help="Whether authentication is required to exploit."),
+        click.option("--unguessable-parameter-required/"
+                     "--no-unguessable-parameter-required",
+                     "unguessable_parameter_required", default=None,
+                     help="Whether an unguessable parameter (e.g. UUID) is required."),
+        click.option("--prerequisites", default=None,
+                     help="Free-text description of other exploitation prerequisites."),
+        click.option("--internal-notes", default=None,
+                     help="Internal notes — documented but excluded from the "
+                          "client-facing PDF report (e.g. redaction reminders)."),
+        click.option("--related", default=None,
+                     help="Comma-separated finding numbers/ids to link to this "
+                          "finding (type 'related'). Use `finding link` for typed "
+                          "or annotated links."),
+        click.option("--status", default=None, help="Finding status."),
+    ]
+    for option in reversed(options):
+        fn = option(fn)
+    return fn
+
+
+def _parse_refs(value: str) -> list[str]:
+    """Split a comma-separated --to/--related value into individual refs."""
+    return [r.strip() for r in str(value).split(",") if r.strip()]
+
+
+def _link_body(ref: str, link_type: str, note: str | None) -> dict:
+    """Build a links-POST body. Numeric refs go as relatedFindingNumber."""
+    body: dict = {"type": link_type}
+    if note:
+        body["note"] = note
+    if ref.isdigit():
+        body["relatedFindingNumber"] = int(ref)
+    else:
+        body["relatedFindingId"] = ref
+    return body
+
+
+def _apply_links(ctx, client, org_id: str, engagement_id: str, finding_id: str,
+                 refs: list[str], link_type: str, note: str | None) -> list[dict]:
+    """POST one link per ref; return per-ref outcomes (never raises on API error)."""
+    base = f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings/{finding_id}/links"
+    outcomes = []
+    for ref in refs:
+        try:
+            client.post(base, json=_link_body(ref, link_type, note))
+            outcomes.append({"ref": ref, "ok": True})
+        except APIError as exc:
+            outcomes.append({"ref": ref, "ok": False, "error": exc.message})
+    return outcomes
+
+
+def _resolve_ref_to_id(client, org_id: str, engagement_id: str, ref: str,
+                       _cache: dict) -> str:
+    """Resolve a finding number to its id (for the DELETE path). Ids pass through."""
+    if not ref.isdigit():
+        return ref
+    if "by_number" not in _cache:
+        data = client.get(
+            f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings"
+        )
+        rows = data.get("findings", []) if isinstance(data, dict) else (data or [])
+        _cache["by_number"] = {str(f.get("number")): f.get("id") for f in rows}
+    fid = _cache["by_number"].get(ref)
+    if not fid:
+        raise click.ClickException(f"No finding #{ref} in this engagement.")
+    return fid
+
+
+def _render_related(related: list[dict]) -> None:
+    """Render the 'Related findings' section of a finding."""
+    if not related:
+        return
+    output.console.print("\n[bold]Related findings[/bold]")
+    for r in related:
+        note = f' ({r.get("type")}: "{r["note"]}")' if r.get("note") \
+            else (f' ({r.get("type")})' if r.get("type") else "")
+        output.console.print(
+            f"  → #{r.get('number')} {output.severity_label(r.get('severity'))} "
+            f"{output.short(r.get('title'), 56)}{note}"
+        )
+
+
+def _report_links(outcomes: list[dict]) -> None:
+    """Report link outcomes to stderr (keeps --json stdout clean)."""
+    for o in outcomes:
+        if o["ok"]:
+            output.success(f"Linked → {o['ref']}")
+        else:
+            output.error(f"Link → {o['ref']} failed: {o['error']}")
+
+
+def _build_finding_body(from_json: str | None, flags: dict) -> dict:
+    """Assemble a finding request body from an optional JSON file + flag overrides."""
+    body: dict = {}
+    if from_json:
+        try:
+            raw = sys.stdin.read() if from_json == "-" else open(from_json).read()
+        except OSError as exc:
+            raise click.ClickException(f"Cannot read --from-json file: {exc}")
+        try:
+            loaded = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise click.ClickException(f"--from-json is not valid JSON: {exc}")
+        if not isinstance(loaded, dict):
+            raise click.ClickException("--from-json must contain a JSON object.")
+        body.update(loaded)
+    # Flags override JSON; map CLI flag names -> API body keys.
+    for flag_name, api_key in _FINDING_FIELDS.items():
+        val = flags.get(flag_name)
+        if val is not None:
+            body[api_key] = val
+    return body
+
+
+@finding.command(name="create")
+@click.argument("engagement_id")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@_finding_field_options
+@click.pass_context
+def create_finding(ctx: click.Context, engagement_id: str, org: str | None,
+                   from_json: str | None, **flags) -> None:
+    """Create a finding in a pentest engagement.
+
+    Supply fields via flags, or load a whole finding with --from-json (handy for
+    reproducing an existing finding verbatim). Flag values override JSON keys.
+    """
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+
+    body = _build_finding_body(from_json, flags)
+    if not body.get("title"):
+        raise click.ClickException("Title is required (--title or JSON 'title').")
+    if not body.get("severity"):
+        raise click.ClickException("Severity is required (--severity or JSON 'severity').")
+
+    res = client.post(
+        f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings", json=body
+    )
+    created = res.get("finding", res) if isinstance(res, dict) else res
+
+    # Optional one-shot linking via --related (type "related").
+    related = flags.get("related")
+    link_outcomes = (
+        _apply_links(ctx, client, org_id, engagement_id, created.get("id"),
+                     _parse_refs(related), "related", None)
+        if related else []
+    )
+
+    def render(f):
+        output.success(
+            f"Created finding #{f.get('number')} "
+            f"[bold]{f.get('title')}[/bold] {output.severity_label(f.get('severity'))}"
+        )
+        output.console.print(f"  ID: {f.get('id')}")
+
+    output.emit(ctx.obj, created, render)
+    _report_links(link_outcomes)
+
+
+@finding.command(name="update")
+@click.argument("engagement_id")
+@click.argument("finding_id")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@_finding_field_options
+@click.pass_context
+def update_finding(ctx: click.Context, engagement_id: str, finding_id: str,
+                   org: str | None, from_json: str | None, **flags) -> None:
+    """Update fields on an existing finding (PATCH; only sends what you pass).
+
+    Use this to enrich existing findings — e.g. set --auth-required,
+    --unguessable-parameter-required, and --prerequisites — without recreating
+    them.
+    """
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+
+    related = flags.get("related")
+    body = _build_finding_body(from_json, flags)
+    if not body and not related:
+        raise click.ClickException(
+            "Nothing to update. Pass at least one field flag, --related, or --from-json."
+        )
+
+    base = f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings/{finding_id}"
+    updated = {"id": finding_id}
+    if body:
+        res = client.patch(base, json=body)
+        updated = res.get("finding", res) if isinstance(res, dict) else res
+
+    link_outcomes = (
+        _apply_links(ctx, client, org_id, engagement_id, finding_id,
+                     _parse_refs(related), "related", None)
+        if related else []
+    )
+
+    def render(f):
+        if body:
+            output.success(
+                f"Updated finding #{f.get('number')} [bold]{f.get('title')}[/bold]"
+            )
+            output.console.print(f"  Fields changed: {', '.join(sorted(body.keys()))}")
+
+    output.emit(ctx.obj, updated, render)
+    # Link outcomes (success/failure per ref) are reported on stderr below.
+    _report_links(link_outcomes)
+
+
+@finding.command(name="delete")
+@click.argument("engagement_id")
+@click.argument("finding_id")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.option("--yes", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_context
+def delete_finding(ctx: click.Context, engagement_id: str, finding_id: str,
+                   org: str | None, yes: bool) -> None:
+    """Delete a finding from an engagement."""
+    org_id = resolve_org_id(ctx, org)
+    if not yes and not ctx.obj.get("json"):
+        click.confirm(f"Delete finding {finding_id}?", abort=True)
+    client = get_client(ctx)
+    res = client.delete(
+        f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings/{finding_id}"
+    )
+
+    def render(_payload):
+        output.success("Finding deleted.")
+
+    output.emit(ctx.obj, res or {"success": True}, render)
+
+
+@finding.command(name="link")
+@click.argument("engagement_id")
+@click.argument("finding_id")
+@click.option("--to", "to_refs", required=True,
+              help="Finding number(s)/id(s) to link to, comma-separated (e.g. 1,3).")
+@click.option("--type", "link_type", type=click.Choice(LINK_TYPES),
+              default="related", show_default=True, help="Relationship type.")
+@click.option("--note", default=None, help="Optional reason for the link.")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def link_finding(ctx: click.Context, engagement_id: str, finding_id: str,
+                 to_refs: str, link_type: str, note: str | None,
+                 org: str | None) -> None:
+    """Link a finding to one or more related findings (bidirectional).
+
+    Links are mirrored by the server, so `link 12 --to 1` also makes finding 1
+    show finding 12. Refs may be finding numbers (preferred) or ids.
+    """
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    refs = _parse_refs(to_refs)
+    if not refs:
+        raise click.ClickException("--to requires at least one finding number or id.")
+
+    outcomes = _apply_links(ctx, client, org_id, engagement_id, finding_id,
+                            refs, link_type, note)
+
+    def render(rows):
+        for o in rows:
+            if o["ok"]:
+                output.success(f"Linked → {o['ref']} ({link_type})")
+            else:
+                output.error(f"Link → {o['ref']} failed: {o['error']}")
+
+    output.emit(ctx.obj, outcomes, render)
+    if any(not o["ok"] for o in outcomes):
+        sys.exit(1)
+
+
+@finding.command(name="unlink")
+@click.argument("engagement_id")
+@click.argument("finding_id")
+@click.option("--to", "to_refs", required=True,
+              help="Finding number(s)/id(s) to unlink, comma-separated.")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def unlink_finding(ctx: click.Context, engagement_id: str, finding_id: str,
+                   to_refs: str, org: str | None) -> None:
+    """Remove a link between findings (either direction)."""
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    refs = _parse_refs(to_refs)
+    if not refs:
+        raise click.ClickException("--to requires at least one finding number or id.")
+
+    base = f"/api/orgs/{org_id}/pentesting/{engagement_id}/findings/{finding_id}/links"
+    cache: dict = {}
+    outcomes = []
+    for ref in refs:
+        try:
+            related_id = _resolve_ref_to_id(client, org_id, engagement_id, ref, cache)
+            client.delete(f"{base}/{related_id}")
+            outcomes.append({"ref": ref, "ok": True})
+        except click.ClickException as exc:
+            outcomes.append({"ref": ref, "ok": False, "error": exc.message})
+        except APIError as exc:
+            outcomes.append({"ref": ref, "ok": False, "error": exc.message})
+
+    def render(rows):
+        for o in rows:
+            if o["ok"]:
+                output.success(f"Unlinked → {o['ref']}")
+            else:
+                output.error(f"Unlink → {o['ref']} failed: {o['error']}")
+
+    output.emit(ctx.obj, outcomes, render)
+    if any(not o["ok"] for o in outcomes):
+        sys.exit(1)
+
+
+@pentest.command()
+@click.option("--title", required=True, help="Engagement title.")
+@click.option("--start-date", default=None, help="Start date (YYYY-MM-DD).")
+@click.option("--end-date", default=None, help="End date (YYYY-MM-DD).")
+@click.option("--org", default=None, help="Org id (defaults to active org).")
+@click.pass_context
+def create(ctx: click.Context, title: str, start_date: str | None,
+           end_date: str | None, org: str | None) -> None:
+    """Create a new pentesting engagement."""
+    org_id = resolve_org_id(ctx, org)
+    client = get_client(ctx)
+    body: dict = {"title": title}
+    if start_date:
+        body["startDate"] = start_date
+    if end_date:
+        body["endDate"] = end_date
+    data = client.post(f"/api/orgs/{org_id}/pentesting", json=body)
+    engagement = data.get("engagement", data) if isinstance(data, dict) else data
+
+    def render(e):
+        output.success(f"Created engagement [bold]{e.get('title')}[/bold]")
+        output.console.print(f"  ID: {e.get('id')}")
+
+    output.emit(ctx.obj, engagement, render)