qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/commands/csam.py

@@ -0,0 +1,752 @@
+# Hand-edited — do NOT regenerate from api-model.json (codegen will skip this file).
+# Cyber Security Asset Management (CSAM) APIs  (JWT Bearer auth, JSON responses)
+# Originally generated from api-model.json; extended with: software components,
+# business metadata import, third-party connector ingest, organization search,
+# EASM status / PATCH update, and ServiceNow-style asset export.
+# Corrections:
+#   - asset get: v2 endpoint is GET /rest/2.0/get/am/asset?assetId=<id>
+#     (was incorrectly GET /rest/2.0/am/asset/<id> — Spring "no static resource" 404)
+#   - vuln list-easm: POST /rest/2.0/search/am/easm/vulns
+#     (was incorrectly GET /rest/2.0/am/easm/vuln — Spring "no static resource" 404)
+#   - vuln list-scan: POST /rest/2.0/search/am/easm/scan/vulns
+#     (was incorrectly GET /rest/2.0/am/easm/scan/vuln — Spring "no static resource" 404)
+#     Both now accept --filter field=op=value (repeatable) + --last-seen-id for pagination.
+from __future__ import annotations
+
+import typer
+
+from .. import client as _c
+from ..formatters import DEFAULT_LIMIT, output, output_success
+
+app = typer.Typer(name="csam", help="Cyber Security Asset Management APIs — assets, EASM, vulnerabilities, domains, reports")
+
+# ── asset ─────────────────────────────────────────────────────────────────────
+_asset = typer.Typer(help="Asset host data operations")
+app.add_typer(_asset, name="asset")
+
+
+@_asset.command("count")
+def asset_count(
+    ctx: typer.Context,
+    filter_: list[str] | None = typer.Option(
+        None, "--filter",
+        help="Repeatable filter as field=op=value (e.g. asset.riskScore=GREATER=500)",
+    ),
+    asset_last_updated: str | None = typer.Option(None, "--updated-after", help="yyyy-MM-ddTHH:mmZ"),
+    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),
+):
+    """Get the count of assets matching filter criteria.
+
+    Examples:
+        csam asset count
+        csam asset count --filter asset.riskScore=GREATER=500
+
+    Source: https://docs.qualys.com/en/csam/api/asset_host_data/count_of_assets.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body = _build_filter_body(filter_)
+    if asset_last_updated:
+        body["assetLastUpdated"] = asset_last_updated
+    data = client.post_json("/rest/2.0/count/am/asset", body)
+    output(data, format=format, output_file=output_file)
+
+
+@_asset.command("list")
+def asset_list(
+    ctx: typer.Context,
+    filter_: list[str] | None = typer.Option(
+        None, "--filter",
+        help="Repeatable filter as field=op=value (e.g. asset.riskScore=GREATER=500)",
+    ),
+    asset_last_updated: str | None = typer.Option(None, "--updated-after", help="yyyy-MM-ddTHH:mmZ"),
+    last_seen_asset_id: int | None = typer.Option(None, "--last-seen-id", help="Paginate from this asset ID"),
+    include_fields: str | None = typer.Option(None, "--include-fields", help="Comma-separated fields to include"),
+    exclude_fields: str | None = typer.Option(None, "--exclude-fields", help="Comma-separated fields to exclude"),
+    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),
+):
+    """Get host details for all assets (max 100 per call, use --last-seen-id to paginate).
+
+    Examples:
+        csam asset list --limit 10
+        csam asset list --filter asset.riskScore=GREATER=500
+        csam asset list --filter asset.riskScore=GREATER=700 --limit 10
+
+    Source: https://docs.qualys.com/en/csam/api/asset_host_data/get_host_details_of_all_assets.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body = _build_filter_body(filter_)
+    if asset_last_updated:
+        body["assetLastUpdated"] = asset_last_updated
+    # These must be query params (API ignores them in body)
+    params: dict = {}
+    if last_seen_asset_id is not None:
+        params["lastSeenAssetId"] = str(last_seen_asset_id)
+    if include_fields:
+        params["includeFields"] = include_fields
+    if exclude_fields:
+        params["excludeFields"] = exclude_fields
+    data = client.post_json("/rest/2.0/search/am/asset", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_asset.command("get")
+def asset_get(
+    ctx: typer.Context,
+    asset_id: str = typer.Argument(..., help="Asset ID"),
+    include_fields: str | None = typer.Option(None, "--include-fields"),
+    exclude_fields: str | None = typer.Option(None, "--exclude-fields"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Get host details for a specific asset.
+
+    Source: https://docs.qualys.com/en/csam/api/asset_host_data/get_host_details_of_specific_asset.htm
+
+    Note: the v2 CSAM endpoint takes assetId as a *query* parameter at
+    /rest/2.0/get/am/asset, not as a path segment.
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"assetId": asset_id}
+    if include_fields:
+        params["includeFields"] = include_fields
+    if exclude_fields:
+        params["excludeFields"] = exclude_fields
+    data = client.get_json("/rest/2.0/get/am/asset", params)
+    output(data, format=format)
+
+
+# ── easm ──────────────────────────────────────────────────────────────────────
+_easm = typer.Typer(help="External Attack Surface Management profile operations")
+app.add_typer(_easm, name="easm")
+
+
+@_easm.command("list")
+def easm_list(
+    ctx: typer.Context,
+    profile_name: str | None = typer.Option(None, "--name", help="Filter by profile name"),
+    page_number: int = typer.Option(0, "--page-number"),
+    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 EASM profiles.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/get_easm_profile_data.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"pageNumber": page_number}
+    if profile_name:
+        params["profileName"] = profile_name
+    data = client.get_json("/easm/v2/profile", params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_easm.command("create")
+def easm_create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", help="Profile name"),
+    default_profile: bool = typer.Option(False, "--default", help="Set as default profile"),
+    enable_domain_security: bool = typer.Option(False, "--domain-security"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Create an EASM profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/create_easm_profile.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body: dict = {"name": name, "defaultProfile": default_profile, "enableDomainSecurity": enable_domain_security}
+    data = client.post_json("/easm/v2/profile", body)
+    output(data, format=format)
+
+
+@_easm.command("update")
+def easm_update(
+    ctx: typer.Context,
+    profile_id: str = typer.Argument(..., help="EASM profile ID"),
+    name: str | None = typer.Option(None, "--name"),
+    active: bool | None = typer.Option(None, "--active/--inactive"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Update an EASM profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/update_easm_profile_data.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body: dict = {}
+    if name:
+        body["name"] = name
+    if active is not None:
+        body["active"] = active
+    data = client.post_json(f"/easm/v2/profile/{profile_id}", body)
+    output(data, format=format)
+
+
+@_easm.command("delete")
+def easm_delete(
+    ctx: typer.Context,
+    profile_id: str = typer.Argument(..., help="EASM profile ID"),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Delete an EASM profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/delete_easm_profile.htm
+    """
+    if not yes:
+        typer.confirm(f"Delete EASM profile {profile_id}?", abort=True)
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    client.delete_json(f"/easm/v2/profile/{profile_id}")
+    output_success(f"EASM profile {profile_id} deleted.")
+
+
+@_easm.command("activate")
+def easm_activate(
+    ctx: typer.Context,
+    profile_id: str = typer.Argument(..., help="EASM profile ID"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Activate an EASM profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/activate_deactive_easm_profile.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.post_json(f"/easm/v2/profile/{profile_id}/activate", {})
+    output(data)
+
+
+@_easm.command("deactivate")
+def easm_deactivate(
+    ctx: typer.Context,
+    profile_id: str = typer.Argument(..., help="EASM profile ID"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Deactivate an EASM profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/activate_deactive_easm_profile.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.post_json(f"/easm/v2/profile/{profile_id}/deactivate", {})
+    output(data)
+
+
+@_easm.command("orgs")
+def easm_orgs(
+    ctx: typer.Context,
+    page_number: int = typer.Option(0, "--page-number"),
+    page_size: int = typer.Option(50, "--page-size"),
+    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 EASM organizations/subsidiaries.
+
+    Calls POST /rest/2.0/am/organization/list — the legacy GET /easm/v2/org
+    endpoint returns 404 on current pods. Same data as `csam org list`.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/org_list_api.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"pageNumber": page_number, "pageSize": page_size}
+    data = client.post_json("/rest/2.0/am/organization/list", {}, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+# ── vuln ──────────────────────────────────────────────────────────────────────
+_vuln = typer.Typer(help="Vulnerability operations")
+app.add_typer(_vuln, name="vuln")
+
+
+def _build_filter_body(filters: list[str] | None) -> dict:
+    """Translate repeatable ``--filter field=op=value`` flags into the
+    Qualys filter body shape ``{"filters": [{field, operator, value}, …]}``.
+
+    Operator is case-normalised to upper (the API expects e.g. ``EQUALS``,
+    ``CONTAINS``, ``IN``, ``GREATER``, ``LESSER``). An empty/None list returns
+    ``{}`` so the API's "no filter = match all" semantics are preserved.
+    """
+    out: dict = {}
+    if not filters:
+        return out
+    parsed: list[dict] = []
+    for entry in filters:
+        # Allow either "field=op=value" or "field:op:value" for ergonomics.
+        sep = "=" if entry.count("=") >= 2 else (":" if entry.count(":") >= 2 else "=")
+        parts = entry.split(sep, 2)
+        if len(parts) != 3:
+            raise typer.BadParameter(
+                f"--filter expects field{sep}op{sep}value, got {entry!r}",
+            )
+        field, op, value = (p.strip() for p in parts)
+        if not field or not op or value == "":
+            raise typer.BadParameter(f"--filter has empty field/op/value: {entry!r}")
+        parsed.append({"field": field, "operator": op.upper(), "value": value})
+    out["filters"] = parsed
+    return out
+
+
+@_vuln.command("list-easm")
+def vuln_list_easm(
+    ctx: typer.Context,
+    filter_: list[str] | None = typer.Option(
+        None, "--filter",
+        help="Repeatable filter as field=op=value (e.g. vulnerabilities.severity=EQUALS=2)",
+    ),
+    last_seen_id: str | None = typer.Option(
+        None, "--last-seen-id",
+        help="Pagination cursor — pass the lastSeenId from the previous response",
+    ),
+    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 EASM-discovered vulnerabilities.
+
+    The API is POST /rest/2.0/search/am/easm/vulns (max 1000 records per page,
+    paginate with the lastSeenId from each response).
+
+    Source: https://docs.qualys.com/en/csam/api/vulnerabilities/get_list_easm_discovered_vuln.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body = _build_filter_body(filter_)
+    params: dict = {}
+    if last_seen_id is not None:
+        params["lastSeenId"] = last_seen_id
+    data = client.post_json("/rest/2.0/search/am/easm/vulns", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_vuln.command("list-scan")
+def vuln_list_scan(
+    ctx: typer.Context,
+    filter_: list[str] | None = typer.Option(
+        None, "--filter",
+        help="Repeatable filter as field=op=value (e.g. vulnerabilities.severity=EQUALS=2)",
+    ),
+    last_seen_id: str | None = typer.Option(
+        None, "--last-seen-id",
+        help="Pagination cursor — pass the lastSeenId from the previous response",
+    ),
+    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 vulnerabilities discovered by EASM scan.
+
+    The API is POST /rest/2.0/search/am/easm/scan/vulns (max 1000 records per
+    page, paginate with the lastSeenId from each response).
+
+    Source: https://docs.qualys.com/en/csam/api/vulnerabilities/vulns_discovered_easm_scan.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body = _build_filter_body(filter_)
+    params: dict = {}
+    if last_seen_id is not None:
+        params["lastSeenId"] = last_seen_id
+    data = client.post_json("/rest/2.0/search/am/easm/scan/vulns", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_vuln.command("data")
+def vuln_data(
+    ctx: typer.Context,
+    cpe_ids: str = typer.Option(..., "--cpe-ids", help="Comma-separated CPE IDs (max 100)"),
+    cpe_type: str | None = typer.Option(None, "--cpe-type", help="Qualys|NIST"),
+    page_number: int = typer.Option(0, "--page-number"),
+    page_size: int = typer.Option(50, "--page-size"),
+    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),
+):
+    """Fetch vulnerability data for software/OS CPEs across assets.
+
+    Source: https://docs.qualys.com/en/csam/api/vulnerabilities/vuln_data_sw_os_across_assets.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"cpeIds": cpe_ids, "pageNumber": page_number, "pageSize": page_size}
+    if cpe_type:
+        params["cpeType"] = cpe_type
+    data = client.post_json("/rest/2.0/am/catalog/cve/detail", params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+# ── domain ────────────────────────────────────────────────────────────────────
+_domain = typer.Typer(help="Domain operations")
+app.add_typer(_domain, name="domain")
+
+
+@_domain.command("list")
+def domain_list(
+    ctx: typer.Context,
+    domain_type: str | None = typer.Option(None, "--type", help="UNRESOLVED_DOMAINS"),
+    domain_filter_type: str | None = typer.Option(None, "--filter-type", help="ALL|DOMAIN|SUBDOMAIN"),
+    page_size: int = typer.Option(5000, "--page-size"),
+    last_fetch_domain_id: int | None = typer.Option(None, "--last-id", help="Paginate from this domain ID"),
+    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 unresolved and typosquatted domains discovered by EASM.
+
+    Source: https://docs.qualys.com/en/csam/api/domains/get_list_of_unresolved_domains.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body: dict = {"pageSize": page_size}
+    if domain_type:
+        body["domainType"] = domain_type
+    if domain_filter_type:
+        body["domainFilterType"] = domain_filter_type
+    if last_fetch_domain_id is not None:
+        body["lastFetchDomainID"] = last_fetch_domain_id
+    data = client.post_json("/rest/2.0/am/domain/list", body)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_domain.command("count")
+def domain_count(
+    ctx: typer.Context,
+    domain_type: str | None = typer.Option(None, "--type", help="UNRESOLVED_DOMAINS"),
+    domain_filter_type: str | None = typer.Option(None, "--filter-type", help="ALL|DOMAIN|SUBDOMAIN"),
+    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),
+):
+    """Get count of unresolved domains.
+
+    Source: https://docs.qualys.com/en/csam/api/domains/get_count_of_unresolved_domains.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body: dict = {}
+    if domain_type:
+        body["domainType"] = domain_type
+    if domain_filter_type:
+        body["domainFilterType"] = domain_filter_type
+    data = client.post_json("/rest/2.0/am/domain/count", body)
+    output(data, format=format, output_file=output_file)
+
+
+# ── report ────────────────────────────────────────────────────────────────────
+_report = typer.Typer(help="Report operations")
+app.add_typer(_report, name="report")
+
+
+@_report.command("create")
+def report_create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", help="Report name"),
+    report_format: str = typer.Option(..., "--format-type", help="Output format e.g. PDF"),
+    template_name: str = typer.Option(..., "--template", help="e.g. EASM_LEAD"),
+    report_type: str = typer.Option(..., "--report-type", help="e.g. EASM_LEAD"),
+    description: str | None = typer.Option(None, "--description"),
+    query: str | None = typer.Option(None, "--query"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Create an EASM summary report.
+
+    Source: https://docs.qualys.com/en/csam/api/reports/create_reports_api.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body: dict = {
+        "name": name,
+        "format": report_format,
+        "templateName": template_name,
+        "reportType": report_type,
+    }
+    if description:
+        body["description"] = description
+    if query:
+        body["query"] = query
+    data = client.post_json("/rest/2.0/am/report", body)
+    output(data, format=format)
+
+
+@_report.command("download")
+def report_download(
+    ctx: typer.Context,
+    report_name: str = typer.Option(..., "--name", help="Exact report name"),
+    output_file: str = typer.Option("csam-report.pdf", "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Download a completed report by name.
+
+    Source: https://docs.qualys.com/en/csam/api/reports/download_reports.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    resp = client.request("GET", f"/rest/2.0/am/report/download?reportName={report_name}")
+    from pathlib import Path
+    Path(output_file).write_bytes(resp.content)
+    output_success(f"Report saved to {output_file} ({len(resp.content):,} bytes)")
+
+
+# ── component (software components on assets) ────────────────────────────────
+_component = typer.Typer(help="Software component (SwCA) operations across assets")
+app.add_typer(_component, name="component")
+
+
+def _filter_body(filter_json: str | None) -> dict:
+    """Parse a --filter argument as JSON (object or array) into a request body."""
+    body: dict = {}
+    if not filter_json:
+        return body
+    import json as _json
+    try:
+        parsed = _json.loads(filter_json)
+    except _json.JSONDecodeError:
+        body["filterXml"] = filter_json
+        return body
+    if isinstance(parsed, list):
+        body["filters"] = parsed
+    elif isinstance(parsed, dict):
+        body.update(parsed)
+    return body
+
+
+@_component.command("list")
+def component_list(
+    ctx: typer.Context,
+    filter_json: str | None = typer.Option(None, "--filter", help="JSON filter body"),
+    page_number: int = typer.Option(0, "--page-number"),
+    page_size: int = typer.Option(50, "--page-size"),
+    last_seen_id: int | None = typer.Option(None, "--last-seen-id", help="Paginate from this component ID"),
+    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 software components (SwCA) discovered across assets.
+
+    Source: https://docs.qualys.com/en/csam/api/software_component/get_list_of_all_software_components.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"pageNumber": page_number, "pageSize": page_size}
+    if last_seen_id is not None:
+        params["lastSeenComponentId"] = last_seen_id
+    body = _filter_body(filter_json)
+    data = client.post_json("/rest/2.0/am/asset/component", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_component.command("list-by-asset")
+def component_list_by_asset(
+    ctx: typer.Context,
+    asset_id: str = typer.Argument(..., help="Asset ID to fetch components for"),
+    filter_json: str | None = typer.Option(None, "--filter", help="JSON filter body"),
+    page_number: int = typer.Option(0, "--page-number"),
+    page_size: int = typer.Option(50, "--page-size"),
+    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 software components (SwCA) for a single asset.
+
+    Source: https://docs.qualys.com/en/csam/api/software_component/get_list_of_software_components_for_specific_asset.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"pageNumber": page_number, "pageSize": page_size}
+    body = _filter_body(filter_json)
+    data = client.post_json(f"/rest/2.0/am/asset/component/{asset_id}", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+# ── business (business metadata import for assets / business apps) ───────────
+_business = typer.Typer(help="Business metadata import (asset criticality, owner, etc.)")
+app.add_typer(_business, name="business")
+
+
+@_business.command("import-asset")
+def business_import_asset(
+    ctx: typer.Context,
+    input_file: str = typer.Argument(..., help="CSV/JSON file with asset business metadata"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Import business metadata (criticality, owner, environment, etc.) for assets.
+
+    Source: https://docs.qualys.com/en/csam/api/business_information/import_asset_business_metadata.htm
+    """
+    if not yes:
+        typer.confirm(f"Import asset business metadata from '{input_file}'?", abort=True)
+    from pathlib import Path
+    p = Path(input_file)
+    payload = p.read_bytes()
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    mime = "text/csv" if p.suffix.lower() == ".csv" else "application/json"
+    resp = client.request(
+        "POST", "/rest/2.0/update/am/asset/business/metadata",
+        files={"file": (p.name, payload, mime)},
+    )
+    if resp.content:
+        try:
+            output(resp.json())
+        except ValueError:
+            output_success(f"Imported {len(payload):,} bytes from '{input_file}'.")
+    else:
+        output_success(f"Imported {len(payload):,} bytes from '{input_file}'.")
+
+
+@_business.command("import-app")
+def business_import_app(
+    ctx: typer.Context,
+    input_file: str = typer.Argument(..., help="CSV/JSON file with business application metadata"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Upsert business application metadata (apps and asset linkages).
+
+    Source: https://docs.qualys.com/en/csam/api/business_information/import_business_app_metadata.htm
+    """
+    if not yes:
+        typer.confirm(f"Import business app metadata from '{input_file}'?", abort=True)
+    from pathlib import Path
+    p = Path(input_file)
+    payload = p.read_bytes()
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    mime = "text/csv" if p.suffix.lower() == ".csv" else "application/json"
+    resp = client.request(
+        "POST", "/rest/2.0/upsert/am/businessapp/metadata",
+        files={"file": (p.name, payload, mime)},
+    )
+    if resp.content:
+        try:
+            output(resp.json())
+        except ValueError:
+            output_success(f"Imported {len(payload):,} bytes from '{input_file}'.")
+    else:
+        output_success(f"Imported {len(payload):,} bytes from '{input_file}'.")
+
+
+# ── connector (third-party / webhook asset ingest) ────────────────────────────
+_connector = typer.Typer(help="Third-party connector ingestion (webhook asset/finding sync)")
+app.add_typer(_connector, name="connector")
+
+
+@_connector.command("sync")
+def connector_sync(
+    ctx: typer.Context,
+    input_file: str = typer.Argument(..., help="JSON payload describing third-party assets/findings"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Push third-party assets/findings into CSAM via the webhook connector.
+
+    Source: https://docs.qualys.com/en/csam/api/third_party/import_third_party_assets.htm
+    """
+    import json as _json
+    from pathlib import Path
+    payload_text = Path(input_file).read_text()
+    body = _json.loads(payload_text)
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.post_json("/rest/2.0/am/connector/asset/data/sync", body)
+    output(data)
+
+
+# ── org (organization / subsidiary search) ───────────────────────────────────
+_org = typer.Typer(help="Organization / subsidiary search (CSAM 3.7+)")
+app.add_typer(_org, name="org")
+
+
+@_org.command("list")
+def org_list(
+    ctx: typer.Context,
+    filter_json: str | None = typer.Option(None, "--filter", help="JSON filter body"),
+    page_number: int = typer.Option(0, "--page-number"),
+    page_size: int = typer.Option(50, "--page-size"),
+    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),
+):
+    """Search organizations and subsidiaries (POST search).
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/org_list_api.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    params: dict = {"pageNumber": page_number, "pageSize": page_size}
+    body = _filter_body(filter_json)
+    data = client.post_json("/rest/2.0/am/organization/list", body, params=params)
+    output(data, format=format, limit=limit, output_file=output_file)
+
+
+@_org.command("count")
+def org_count(
+    ctx: typer.Context,
+    filter_json: str | None = typer.Option(None, "--filter", help="JSON filter body"),
+    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),
+):
+    """Count organizations and subsidiaries matching a filter.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/org_count_api.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    body = _filter_body(filter_json)
+    data = client.post_json("/rest/2.0/am/organization/count", body)
+    output(data, format=format, output_file=output_file)
+
+
+# ── easm: additive (status + PATCH partial update; existing commands untouched)
+@_easm.command("status")
+def easm_status(
+    ctx: typer.Context,
+    profile_name: str = typer.Option(..., "--name", help="EASM profile name"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Get EASM discovery status for a profile.
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/get_easm_profile_discovery_status.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.get_json("/easm/v2/profile/status", {"profileName": profile_name})
+    output(data, format=format)
+
+
+@_easm.command("patch")
+def easm_patch(
+    ctx: typer.Context,
+    profile_name: str = typer.Argument(..., help="EASM profile name"),
+    body_json: str = typer.Option(..., "--body", help="Raw JSON body for the PATCH request"),
+    format: str = typer.Option("table", "--format", "-f"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Partially update an EASM profile via PATCH (additive — does not affect `easm update`).
+
+    Source: https://docs.qualys.com/en/csam/api/easm_apis/patch_easm_profile_data.htm
+    """
+    import json as _json
+    body = _json.loads(body_json)
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.patch_json(f"/easm/v2/profile/{profile_name}", body)
+    output(data, format=format)
+
+
+# ── asset: additive ServiceNow-style export ──────────────────────────────────
+@_asset.command("sn-export")
+def asset_sn_export(
+    ctx: typer.Context,
+    asset_id: str = typer.Argument(..., help="Asset ID"),
+    format: str = typer.Option("json", "--format", "-f"),
+    output_file: str | None = typer.Option(None, "--output-file", "-o"),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+):
+    """Export an asset in ServiceNow-style format including software-instance details.
+
+    Source: https://docs.qualys.com/en/csam/release-notes/cybersecurity_asset_management/release_3_7_api.htm
+    """
+    client = _c.make(ctx.obj, auth_type="jwt", verbose=verbose, use_gateway=True)
+    data = client.get_json(f"/am/v2/sn/assets/host/{asset_id}")
+    output(data, format=format, output_file=output_file)