Feature/integrations pt1 integrations

[PaperMtn]

Implement All Integration Management Functions - Pt 1: Integration functions & Helpers

Summary

Part of a larger PR to implement all SOAR integration management capabilities to the SecOps SDK. This PR includes:

• Integration functions
• Helper functions
• Models needed for future functions

---

New SDK Modules (src/secops/chronicle/integration/)

Module	Description
integrations.py	List, get, create, delete, download, export, diff, transition (staging/production), and manage integrations
integration_instances.py	CRUD, test execution, affected items, and default instance retrieval for integration instances
marketplace_integrations.py	List, get, diff, install, and uninstall marketplace integrations

---

New Utility Helpers (src/secops/chronicle/utils/)

New helpers added for consistency and deduplication:

• Unit tests added for each

format_utils.py

• format_resource_id() — Extracts the final ID segment from a full Chronicle resource path (e.g. projects/.../instances/.../abc123 → abc123). Safely passes through plain IDs.
  • Allows users to pass either the full resource name or just the ID to functions
• parse_json_list() — Accepts either a list[dict] or a JSON string and returns a parsed list. Used for parameter inputs (e.g. --parameters '[{"name":"p1"}]').
• build_patch_body() — Builds a PATCH request body and updateMask query param from a list of (api_key, mask_key, value) tuples. Auto-generates the update mask from non-None fields, or accepts an explicit override.

request_utils.py

• chronicle_request_bytes() — New helper for endpoints that return raw bytes (used by download_integration and download_integration_dependency).
  • Allows expansion into API functions that download objects

---

New Data Models (src/secops/chronicle/models.py)

Enums:

• PythonVersion — V2_7, V3_7, V3_11
• DiffType — COMMERCIAL, PRODUCTION, STAGING
• TargetMode — PRODUCTION, STAGING
• IntegrationType — RESPONSE, EXTENSION
• IntegrationParamType — BOOLEAN, INT, STRING, PASSWORD, IP, URL, DOMAIN, EMAIL, VALUES_LIST, etc.
• ActionParamType — STRING, BOOLEAN, WFS_REPOSITORY, USER_REPOSITORY, STAGES_REPOSITORY
• ActionType — PING, CONNECTOR, JOB, etc.
• ParamType — For connector parameters
• ConnectorParamMode — REQUIRED, OPTIONAL, etc.
• ConnectorRuleType — Rule types for connector definitions
• ScheduleType — ONE_TIME, DAILY, WEEKLY, MONTHLY, ADVANCED
• DayOfWeek — MONDAY through SUNDAY
• IntegrationParameterType — For integration instance parameters
• ConnectorConnectivityStatus — CONNECTED, DISCONNECTED, etc.
• TransformerType — Transformer definition types
• LogicalOperatorType — Logical operator definition types

Dataclasses:

• IntegrationParam — Integration-level parameter definition
• ActionParameter — Action parameter with type and validation
• ConnectorParameter — Connector parameter with mode and rules
• ConnectorRule — Connector rule definition
• IntegrationJobInstanceParameter — Job instance parameter
• Date, TimeOfDay — Date/time components for scheduling
• OneTimeScheduleDetails, DailyScheduleDetails, WeeklyScheduleDetails, MonthlyScheduleDetails — Schedule configuration
• AdvancedConfig — Advanced scheduling (cron-like)
• JobParameter — Job definition parameter
• IntegrationInstanceParameter — Integration instance parameter
• ConnectorInstanceParameter — Connector instance parameter
• TransformerDefinitionParameter — Transformer parameter
• IntegrationLogicalOperatorParameter — Logical operator parameter

---

CLI Commands (src/secops/cli/commands/integration/)

Added a complete secops integration CLI command tree with 21 subcommand modules, all registered via integration_client.py:

CLI Subcommand	Operations
secops integration integrations	list, get, create, delete, download, download-dependency, export-items, get-affected-items, get-agent, get-diff, get-dependencies, get-restricted-agents, transition, update, update-custom
secops integration instances	list, get, create, update, delete, test, get-affected-items, get-default
secops integration marketplace	list, get, diff, install, uninstall

---

Tests

Unit Tests - SDK Modules (tests/chronicle/integration/)

• test_integrations.py
• test_integration_instances.py
• test_marketplace_integrations.py

Unit Tests - Utility Helpers (tests/chronicle/utils/)

• test_format_utils.py -Tests for format_resource_id, parse_json_list, build_patch_body
• test_request_utils.py - Tests for chronicle_request_bytes and updated request helpers

---

Documentation Updates

README.md

SDK usage examples for every new module, following the established format:

• Integration management (list, get, create, delete, download, export, diff, transition)
• Integration Instances (CRUD, test, affected items, default instance)
• Marketplace Integrations (list, get, diff, install, uninstall)

CLI.md

CLI usage documentation with bash examples for all integration subcommands, including workflow examples for revision-based safe updates.

api_module_mapping.md

• Updated endpoint count: v1: 17, v1beta: 88, v1alpha: 203
• Added CLI command column entries for all implemented integration endpoints across v1beta and v1alpha
• Added all new endpoint-to-module mappings

---

ChronicleClient Updates

• client.py - All new integration module functions added as ChronicleClient methods with full docstrings
• __init__.py - All new functions exported in __all__ and publicly importable from secops.chronicle

---

API Version Support

All integration modules support both v1beta (default) and v1alpha via the api_version parameter

[PaperMtn]

I agree that this is probably the best appraoch, and avoids having users create a new client.

I've refactored this PR into a SOARService that is a namespace feature and has the Integration functions under it.

[mihirvala08]

@PaperMtn, would it be possible to create FR/Issue with endpoints that are implemented for these PRs (all parts)?

It would help to have centralized discussion on common approach and reviews.

Thanks!

[PaperMtn]

I've created a FR: [#207]

[mihirvala08]

/run-integration-tests 20228cd