qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/commands/vm.py

@@ -0,0 +1,562 @@
+# Hand-edited — do NOT regenerate from api-model.json (codegen will skip this file).
+# Vulnerability Management API  (Basic auth, XML responses)
+# Originally generated from api-model.json; corrections:
+#   - kb list: --ids (was --qids → wrong API key); fixed published_after suffix;
+#     added id-min/id-max/cve/details/is-patchable/discovery-method/show-* flags
+#   - scan launch: --option-id OR --option-title required (was silently optional);
+#     added --asset-groups, --asset-group-ids, --priority, --ip-network-id
+from __future__ import annotations
+
+import typer
+
+from .. import client as _c
+from ..formatters import DEFAULT_LIMIT, output, output_success
+
+app = typer.Typer(name="vm", help="Vulnerability Management APIs (Basic auth)")
+
+# ── scan ─────────────────────────────────────────────────────────────────────
+_scan = typer.Typer(help="VM scan operations")
+app.add_typer(_scan, name="scan")
+
+
+@_scan.command("list")
+def scan_list(
+    ctx: typer.Context,
+    state: str | None = typer.Option(None, "--state", help="Running|Paused|Cancelled|Finished|Error|Queued|Loading"),
+    type_: str | None = typer.Option(None, "--type", help="On-Demand|Scheduled|API"),
+    target: str | None = typer.Option(None, "--target", help="Target IP/range"),
+    launched_after: str | None = typer.Option(None, "--launched-after", help="Datetime YYYY-MM-DD"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    all_: bool = typer.Option(False, "--all"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List VM scans.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_scans/list_vm_scans.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if state:
+        params["state"] = state
+    if type_:
+        params["type"] = type_
+    if target:
+        params["target"] = target
+    if launched_after:
+        params["launched_after_datetime"] = launched_after
+    if all_:
+        rows: list = []
+        for page in client.paginate_xml("/api/2.0/fo/scan/", params):
+            items = _unwrap_xml_list(page, "SCAN")
+            rows.extend(items)
+        output(rows, format=format, output_file=output_file)
+    else:
+        data = client.get_xml("/api/2.0/fo/scan/", params)
+        output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_scan.command("launch")
+def scan_launch(
+    ctx: typer.Context,
+    title: str = typer.Option(..., "--title", help="Scan title"),
+    ip: str = typer.Option(..., "--ip", help="Target IP(s), ranges or network IDs"),
+    option_id: str | None = typer.Option(
+        None, "--option-id", help="Option profile ID (required if --option-title not given)"
+    ),
+    option_title: str | None = typer.Option(
+        None, "--option-title", help="Option profile title (required if --option-id not given)"
+    ),
+    scanner_name: str | None = typer.Option(
+        None, "--scanner", help="Scanner appliance name(s), comma-separated"
+    ),
+    asset_groups: str | None = typer.Option(
+        None, "--asset-groups", help="Asset group IDs, comma-separated (alternative to --ip)"
+    ),
+    asset_group_ids: str | None = typer.Option(
+        None, "--asset-group-ids", help="Asset group IDs by name, comma-separated"
+    ),
+    priority: int | None = typer.Option(
+        None, "--priority", help="0 (no priority) – 9 (emergency)", min=0, max=9
+    ),
+    ip_network_id: str | None = typer.Option(
+        None, "--ip-network-id", help="Network ID for the target IPs"
+    ),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Launch a VM scan.
+
+    The Qualys API requires an option profile to be selected — either by ID
+    (--option-id) or by exact title (--option-title). Pass at least one.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_scans/launch_vm_scan.htm
+    """
+    if not option_id and not option_title:
+        raise typer.BadParameter(
+            "Provide --option-id or --option-title (one is required by the API)."
+        )
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "launch", "scan_title": title, "ip": ip}
+    if option_id:
+        params["option_id"] = option_id
+    if option_title:
+        params["option_title"] = option_title
+    if scanner_name:
+        params["scanner_appliances"] = scanner_name
+    if asset_groups:
+        params["asset_groups"] = asset_groups
+    if asset_group_ids:
+        params["asset_group_ids"] = asset_group_ids
+    if priority is not None:
+        params["priority"] = str(priority)
+    if ip_network_id:
+        params["ip_network_id"] = ip_network_id
+    data = client.post_xml("/api/2.0/fo/scan/", data=params)
+    output(data, format=format)
+
+
+@_scan.command("cancel")
+def scan_cancel(
+    ctx: typer.Context,
+    scan_ref: str = typer.Argument(..., help="Scan reference (scan/1234567890.12345)"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Cancel a running scan.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_scans/manage_vm_scans.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    data = client.post_xml("/api/2.0/fo/scan/", data={"action": "cancel", "scan_ref": scan_ref})
+    output(data)
+
+
+@_scan.command("fetch")
+def scan_fetch(
+    ctx: typer.Context,
+    scan_ref: str = typer.Argument(..., help="Scan reference"),
+    output_file: str = typer.Option("scan-results.xml", "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Fetch scan results (downloads XML to file).
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_scans/vm_scan_summary.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    resp = client.request("POST", "/api/2.0/fo/scan/",
+                          data={"action": "fetch", "scan_ref": scan_ref})
+    from pathlib import Path
+    Path(output_file).write_bytes(resp.content)
+    output_success(f"Scan results saved to {output_file} ({len(resp.content):,} bytes)")
+
+
+# ── host ─────────────────────────────────────────────────────────────────────
+_host = typer.Typer(help="Host / asset operations")
+app.add_typer(_host, name="host")
+
+
+@_host.command("list")
+def host_list(
+    ctx: typer.Context,
+    ips: str | None = typer.Option(None, "--ips", help="Comma-separated IPs or ranges"),
+    ag_ids: str | None = typer.Option(None, "--ag-ids", help="Asset group IDs"),
+    os_pattern: str | None = typer.Option(None, "--os", help="OS regex pattern"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    all_: bool = typer.Option(False, "--all"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List hosts in the asset inventory.
+
+    Source: https://docs.qualys.com/en/vm/api/assets/host_lists/host_list.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ips:
+        params["ips"] = ips
+    if ag_ids:
+        params["ag_ids"] = ag_ids
+    if os_pattern:
+        params["os_pattern"] = os_pattern
+    if all_:
+        rows: list = []
+        for page in client.paginate_xml("/api/2.0/fo/asset/host/", params):
+            rows.extend(_unwrap_xml_list(page, "HOST"))
+        output(rows, format=format, output_file=output_file)
+    else:
+        data = client.get_xml("/api/2.0/fo/asset/host/", params)
+        output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_host.command("detection")
+def host_detection(
+    ctx: typer.Context,
+    ips: str | None = typer.Option(None, "--ips"),
+    qids: str | None = typer.Option(None, "--qids", help="Comma-separated QIDs"),
+    severities: str | None = typer.Option(None, "--severities", help="1-5 comma-separated"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    all_: bool = typer.Option(False, "--all"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List host vulnerability detections.
+
+    Source: https://docs.qualys.com/en/vm/api/assets/host_lists/host_detection.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ips:
+        params["ips"] = ips
+    if qids:
+        params["qids"] = qids
+    if severities:
+        params["severities"] = severities
+    if all_:
+        rows: list = []
+        for page in client.paginate_xml("/api/2.0/fo/asset/host/vm/detection/", params):
+            rows.extend(_unwrap_xml_list(page, "HOST"))
+        output(rows, format=format, output_file=output_file)
+    else:
+        data = client.get_xml("/api/2.0/fo/asset/host/vm/detection/", params)
+        output(data, format=format, limit=limit, output_file=output_file)
+
+
+# ── knowledgebase ─────────────────────────────────────────────────────────────
+_kb = typer.Typer(help="KnowledgeBase / vulnerability operations")
+app.add_typer(_kb, name="kb")
+
+
+@_kb.command("list")
+def kb_list(
+    ctx: typer.Context,
+    ids: str | None = typer.Option(None, "--ids", help="Comma-separated QID(s)"),
+    id_min: str | None = typer.Option(None, "--id-min", help="Minimum QID in range"),
+    id_max: str | None = typer.Option(None, "--id-max", help="Maximum QID in range"),
+    cve: str | None = typer.Option(None, "--cve", help="Comma-separated CVE IDs"),
+    published_after: str | None = typer.Option(None, "--published-after", help="YYYY-MM-DD[THH:MM:SSZ]"),
+    published_before: str | None = typer.Option(None, "--published-before", help="YYYY-MM-DD[THH:MM:SSZ]"),
+    last_modified_after: str | None = typer.Option(None, "--last-modified-after", help="YYYY-MM-DD[THH:MM:SSZ]"),
+    last_modified_before: str | None = typer.Option(None, "--last-modified-before", help="YYYY-MM-DD[THH:MM:SSZ]"),
+    details: str | None = typer.Option(None, "--details", help="Basic|All|None"),
+    is_patchable: bool | None = typer.Option(None, "--patchable/--not-patchable", help="Filter by whether a patch exists"),
+    discovery_method: str | None = typer.Option(None, "--discovery-method", help="Remote|Authenticated|RemoteOnly|AuthenticatedOnly|RemoteAndAuthenticated"),
+    show_pci_reasons: bool = typer.Option(False, "--show-pci-reasons", help="Include PCI pass/fail reasons"),
+    show_disabled_flag: bool = typer.Option(False, "--show-disabled-flag", help="Include the disabled flag for each QID"),
+    show_supported_modules_info: bool = typer.Option(False, "--show-supported-modules-info", help="Include supported-module info"),
+    show_qid_change_log: bool = typer.Option(False, "--show-qid-change-log", help="Include QID change-log entries"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List vulnerabilities from the KnowledgeBase.
+
+    The full Qualys KnowledgeBase contains hundreds of thousands of QIDs and
+    streaming the entire catalog can exceed the request timeout or the in-memory
+    body cap. Pass at least one scoping flag — --ids, --id-min/--id-max,
+    --cve, --published-after, --last-modified-after, etc. — to keep the
+    response manageable. To pull the full KB, use --output-file with
+    QUALYS_BODY_LIMIT_BYTES=0 and --last-modified-after spanning the desired
+    window.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/kbase/knowledgebase.htm
+    """
+    if not any(
+        [ids, id_min, id_max, cve, published_after, published_before,
+         last_modified_after, last_modified_before]
+    ):
+        raise typer.BadParameter(
+            "vm kb list requires a scoping filter: pass --ids, --id-min/--id-max, "
+            "--cve, --published-after, or --last-modified-after. The full KB "
+            "exceeds the default response size cap."
+        )
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ids:
+        params["ids"] = ids
+    if id_min:
+        params["id_min"] = id_min
+    if id_max:
+        params["id_max"] = id_max
+    if cve:
+        params["cve"] = cve
+    if published_after:
+        params["published_after"] = published_after
+    if published_before:
+        params["published_before"] = published_before
+    if last_modified_after:
+        params["last_modified_after"] = last_modified_after
+    if last_modified_before:
+        params["last_modified_before"] = last_modified_before
+    if details:
+        params["details"] = details
+    if is_patchable is not None:
+        params["is_patchable"] = "1" if is_patchable else "0"
+    if discovery_method:
+        params["discovery_method"] = discovery_method
+    if show_pci_reasons:
+        params["show_pci_reasons"] = "1"
+    if show_disabled_flag:
+        params["show_disabled_flag"] = "1"
+    if show_supported_modules_info:
+        params["show_supported_modules_info"] = "1"
+    if show_qid_change_log:
+        params["show_qid_change_log"] = "1"
+    data = client.get_xml("/api/2.0/fo/knowledge_base/vuln/", params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+# ── option-profile ────────────────────────────────────────────────────────────
+_op = typer.Typer(help="VM option profile operations")
+app.add_typer(_op, name="option-profile")
+
+
+@_op.command("list")
+def op_list(
+    ctx: typer.Context,
+    ids: str | None = typer.Option(None, "--ids"),
+    title_contains: str | None = typer.Option(None, "--title-contains"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    format: str = typer.Option("table", "--format", "-f"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List VM option profiles.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/ops/ops_vm/VM_Option_Profile.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ids:
+        params["ids"] = ids
+    if title_contains:
+        params["title"] = title_contains
+    data = client.get_xml("/api/2.0/fo/subscription/option_profile/vm/", params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_op.command("create")
+def op_create(
+    ctx: typer.Context,
+    title: str = typer.Option(..., "--title"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Create a VM option profile.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/ops/ops_vm/VM_Option_Profile.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    data = client.post_xml("/api/2.0/fo/subscription/option_profile/vm/",
+                           data={"action": "create", "title": title})
+    output(data)
+
+
+@_op.command("delete")
+def op_delete(
+    ctx: typer.Context,
+    ids: str = typer.Argument(..., help="Option profile ID(s)"),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Delete VM option profile(s).
+
+    Source: https://docs.qualys.com/en/vm/api/scans/ops/ops_vm/VM_Option_Profile.htm
+    """
+    if not yes:
+        typer.confirm(f"Delete option profile(s) {ids}?", abort=True)
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    data = client.post_xml("/api/2.0/fo/subscription/option_profile/vm/",
+                           data={"action": "delete", "ids": ids})
+    output(data)
+
+
+# ── report ────────────────────────────────────────────────────────────────────
+_report = typer.Typer(help="VM/PC report operations")
+app.add_typer(_report, name="report")
+
+
+@_report.command("list")
+def report_list(
+    ctx: typer.Context,
+    id_: str | None = typer.Option(None, "--id"),
+    state: str | None = typer.Option(None, "--state", help="Running|Finished|Canceled"),
+    type_: str | None = typer.Option(None, "--type"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    format: str = typer.Option("table", "--format", "-f"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List VM/PC reports.
+
+    Source: https://docs.qualys.com/en/vm/api/reports/reports/list_reports.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if id_:
+        params["id"] = id_
+    if state:
+        params["state"] = state
+    if type_:
+        params["type"] = type_
+    data = client.get_xml("/api/2.0/fo/report/", params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_report.command("launch")
+def report_launch(
+    ctx: typer.Context,
+    template_id: str = typer.Option(..., "--template-id"),
+    report_title: str = typer.Option(..., "--title"),
+    output_format: str = typer.Option("PDF", "--output-format", help="PDF|HTML|XML|CSV|DOCX"),
+    ips: str | None = typer.Option(None, "--ips"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Launch a VM/PC report.
+
+    Source: https://docs.qualys.com/en/vm/api/reports/reports/launch_report.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {
+        "action": "launch",
+        "template_id": template_id,
+        "report_title": report_title,
+        "output_format": output_format,
+    }
+    if ips:
+        params["ips"] = ips
+    data = client.post_xml("/api/2.0/fo/report/", data=params)
+    output(data)
+
+
+@_report.command("fetch")
+def report_fetch(
+    ctx: typer.Context,
+    report_id: str = typer.Argument(...),
+    output_file: str = typer.Option("report.pdf", "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Fetch (download) a completed report.
+
+    Source: https://docs.qualys.com/en/vm/api/reports/reports/fetch_report.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    resp = client.request("GET", "/api/2.0/fo/report/",
+                          params={"action": "fetch", "id": report_id})
+    from pathlib import Path
+    Path(output_file).write_bytes(resp.content)
+    output_success(f"Report saved to {output_file}")
+
+
+@_report.command("delete")
+def report_delete(
+    ctx: typer.Context,
+    report_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Delete a report.
+
+    Source: https://docs.qualys.com/en/vm/api/reports/reports/delete_report.htm
+    """
+    if not yes:
+        typer.confirm(f"Delete report {report_id}?", abort=True)
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    data = client.post_xml("/api/2.0/fo/report/",
+                           data={"action": "delete", "id": report_id})
+    output(data)
+
+
+# ── scan-schedule ─────────────────────────────────────────────────────────────
+_schedule = typer.Typer(help="VM scan schedule operations")
+app.add_typer(_schedule, name="scan-schedule")
+
+
+@_schedule.command("list")
+def schedule_list(
+    ctx: typer.Context,
+    ids: str | None = typer.Option(None, "--ids"),
+    active: bool | None = typer.Option(None, "--active/--inactive"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List VM scan schedules.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_schedules/list_scan_schedules.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ids:
+        params["ids"] = ids
+    if active is not None:
+        params["active"] = "1" if active else "0"
+    data = client.get_xml("/api/2.0/fo/schedule/scan/", params)
+    output(data, format=format, limit=limit)
+
+
+@_schedule.command("delete")
+def schedule_delete(
+    ctx: typer.Context,
+    ids: str = typer.Argument(..., help="Schedule ID(s)"),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Delete scan schedule(s).
+
+    Source: https://docs.qualys.com/en/vm/api/scans/vm_schedules/delete_scan_schedule.htm
+    """
+    if not yes:
+        typer.confirm(f"Delete scan schedule(s) {ids}?", abort=True)
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    data = client.post_xml("/api/2.0/fo/schedule/scan/",
+                           data={"action": "delete", "id": ids})
+    output(data)
+
+
+# ── appliance ─────────────────────────────────────────────────────────────────
+_appliance = typer.Typer(help="Scanner appliance operations")
+app.add_typer(_appliance, name="appliance")
+
+
+@_appliance.command("list")
+def appliance_list(
+    ctx: typer.Context,
+    ids: str | None = typer.Option(None, "--ids"),
+    name: str | None = typer.Option(None, "--name"),
+    limit: int = typer.Option(DEFAULT_LIMIT, "--limit", "-n"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """List scanner appliances.
+
+    Source: https://docs.qualys.com/en/vm/api/scans/appliances/list_appliances.htm
+    """
+    client = _c.make(ctx.obj, auth_type="basic", verbose=verbose)
+    params: dict = {"action": "list"}
+    if ids:
+        params["ids"] = ids
+    if name:
+        params["name"] = name
+    data = client.get_xml("/api/2.0/fo/appliance/", params)
+    output(data, format=format, limit=limit)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _unwrap_xml_list(data: dict, item_key: str) -> list:
+    """Extract a list of items from a nested xmltodict response."""
+    for v in data.values():
+        if isinstance(v, dict):
+            lst = v.get(f"{item_key}_LIST") or v.get("RESPONSE", {}).get(f"{item_key}_LIST")
+            if lst:
+                items = lst.get(item_key, [])
+                return items if isinstance(items, list) else [items]
+            deeper = _unwrap_xml_list(v, item_key)
+            if deeper:
+                return deeper
+    return []