Introduce centralised request helpers for Chronicle APIs

[PaperMtn]

Summary

This PR introduces a centralised request helper for SecOps API calls and establishes a consistent, reusable pattern for:

• HTTP request execution
• error handling
• pagination
• response shape normalisation by providing the optional ability to return a list when the SecOps API returns a dict (Addresses what was raised here: Inconsistent return types #149)

The goal is to reduce duplicated request logic across modules, make behaviour predictable for users, and provide a single place to maintain request-related functionality going forward.

Why

Individual modules previously implemented their own request logic using client.session.get/post, leading to:

• inconsistent error handling and messaging, which needed implementing for each request
• duplicated & inconsistent pagination code
• bugs around pagination tokens and response shapes
• tests tightly coupled to HTTP details and error checking rather than module behaviour

This PR creates a single, well-tested abstraction that all modules can build on.

What’s included

New request helpers

• secops.chronicle.utils.request_utils.chronicle_request()

  • Standardises URL construction (including legacy: and :rpcMethod endpoints)
  • Handles authentication and network errors consistently
  • Supports multiple expected HTTP status codes
  • Parses JSON safely and provides truncated body previews on error
  • Produces a single exception type (APIError) for callers

• secops.chronicle.utils.request_utils.chronicle_paginated_request()

  • Centralises pagination logic
  • Preserves upstream response shape by default
  • Adds an opt-in as_list=True flag to return flat lists when desired
  • Avoids mutating caller-provided parameters

Test coverage

• Comprehensive unit tests for both helpers covering:
  • success paths
  • error conditions
  • pagination behaviour
  • as_list semantics
  • URL construction for all API versions and types of endpoints, including legacy/RPC-style

Behavioural notes

• Default behaviour remains unchanged: callers receive whatever shape the upstream API returns.
• as_list=True is opt-in and returns a Python list instead of a dict for list_... functions.
  • This option intentionally discards pagination metadata. This is fully explained in the docstrings.
• Error handling is now consistent across all request paths.

Scope of this PR

This PR focuses on introducing and validating the request helpers, and implementing them on some modules.

In order to test the implementation, a number of modules have been migrated to using the helper functions:

• secops.chronicle.rule_set.py
• secops.chronicle.watchlist.py
• secops.chronicle.validate.py
• secops.chronicle.udm_search.py
• secops.chronicle.udm_mapping.py

Tests for these modules have been included, and moved into their own modules where they were previously in test.chronicle.test_client.py

The plan is for future migrations to use the helpers being done incrementally in follow-up PRs per-module, to keep changes small and reviewable.

Testing

• Added unit tests for all new helper functionality
• Existing tests continue to pass
  • Existing tests have been moved to their own test modules, and updated to test only module functionality, not HTTP/request logic.

Follow-up work

• Migrate remaining Chronicle modules to use the helper in future PRs
• Remove duplicated request logic once migrations are complete

[mihirvala08]

/run-integration-tests ee63889