bug(chronicle): nl_search and search_udm drop :udmSearch stats payload and misreport 0 results

Offen
#227 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

@dandye arbeitet bereits daran.

Seit 06.11.2026.

  • #228 von @dandye — offen

Bewertung

Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Anfängerfreundlichkeit
35/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Veraltet
Tech-Stack
python

Rechercherichtung

Start with src/secops/chronicle/search.py and src/secops/chronicle/stats.py, then check the nl_search caller in src/secops/chronicle/nl_search.py and the CLI path in src/secops/cli/commands/search.py. Compare the :udmSearch response handling with ChronicleClient.get_stats and find the existing tests for both event and stats responses. Done means stats queries retain normalized rows and pagination status while plain event queries and as_list=True keep their stated behavior; pull request #228 is already open.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Summary

ChronicleClient.nl_search in src/secops/chronicle/nl_search.py and ChronicleClient.search_udm in src/secops/chronicle/search.py discard result["stats"] from GET /v1alpha/{instance}:udmSearch responses and report total_events: 0 even when matching security telemetry exists.

At the Chronicle REST API layer, :udmSearch handles both plain UDM event filter queries and Chronicle SIEM YARA-L 2.0 statistical queries containing match: and outcome: sections:

  • Plain event filter queries populate events and omit stats.
  • YARA-L 2.0 statistical queries with an outcome: aggregation section return HTTP 200, populate stats, and omit events.

Because src/secops/chronicle/search.py reads only result.get("events", []), two data-loss bugs affect shipped SDK and CLI entry points today:

  1. Natural language search in client.nl_search and secops search --nl-query. When a caller runs an aggregation prompt in plain English such as "Count failed user logins by user in the last 24 hours", Chronicle's :translateUdmQuery endpoint emits a YARA-L 2.0 match: and outcome: query. Both nl_search in src/secops/chronicle/nl_search.py lines 89 through 99 and handle_search_command in src/secops/cli/commands/search.py lines 142 through 149 pass that translated query directly to client.search_udm(...). secops stats has no --nl-query flag. :udmSearch returns HTTP 200 with result["stats"], yet search_udm drops the payload and returns {"events": [], "total_events": 0, "more_data_available": False}, producing a false-negative result during investigations.
  2. Direct client.search_udm and secops search --query calls on outcome: queries. Passing the query returned by client.translate_nl_to_udm(...) into client.search_udm(...) as shown in README.md also hits :udmSearch, receives HTTP 200 with stats, and drops every returned row while reporting total_events: 0.

Steps to reproduce

from datetime import datetime, timedelta, timezone
from secops import SecOpsClient

CUSTOMER_ID = "<CUSTOMER_ID>"
PROJECT_ID = "<PROJECT_ID>"
REGION = "us"

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=24)

sdk = SecOpsClient()
chronicle = sdk.chronicle(
    customer_id=CUSTOMER_ID,
    project_id=PROJECT_ID,
    region=REGION,
)

result = chronicle.nl_search(
    text="Count failed user logins by user in the last 24 hours",
    start_time=start_time,
    end_time=end_time,
)
# :translateUdmQuery emits a YARA-L 2.0 match:/outcome: query and :udmSearch
# returns HTTP 200 with non-empty result["stats"], yet nl_search returns:
# {"events": [], "total_events": 0, "more_data_available": False}

Or from the CLI:

secops search --nl-query "Count failed user logins by user in the last 24 hours" --time-window 24

Expected behavior

When as_list=False and :udmSearch returns a stats dictionary, search_udm keeps its existing keys and attaches normalized stats via process_stats_results from src/secops/chronicle/stats.py so nl_search and search_udm stop losing HTTP 200 response data:

  • response["stats"] matches the columns, rows, and total_rows dictionary structure returned by ChronicleClient.get_stats.
  • more_data_available reflects result.get("moreDataAvailable", False) or result["stats"].get("tooManyResults", False).

Backward compatibility

A fix for this bug is backward compatible across all existing SDK and CLI callers:

  • No signature changes. search_udm, nl_search, get_stats, and secops search keep identical parameters, defaults, and return types.
  • Plain UDM event filter queries unchanged. Responses without stats continue returning the exact 3-key dictionary {"events": [...], "total_events": int, "more_data_available": bool} with no stats key added.
  • as_list=True unchanged. Callers requesting as_list=True continue receiving list[dict[str, Any]].
  • Additive stats key on outcome: queries. Existing top-level keys events, total_events, and more_data_available remain present with identical types, while stats is purely additive and matches ChronicleClient.get_stats 1:1.
  • ChronicleClient.get_stats unchanged. Direct statistical query callers see zero behavioral change.

Maintenance mode scope

This is a backward-compatible bug and stability fix for HTTP 200 response data loss and false-negative zero-result output in existing nl_search, search_udm, and secops search --nl-query code paths. It adds no new endpoints, methods, parameters, or dependencies.

Vorherrschende Sprache
Python
Sterne
94
Forks
49
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus google/secops-wrapper

Alle Issues in google/secops-wrapper

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.