Version 1.6.7 - New Operations, Service Collections

.github/wordlist.txt

@@ -16,6 +16,8 @@ BatchGetCmd
 BatchGetCmdStatus
 BatchInitSessions
 BatchRefreshSessions
+booleans
+CAs
 CCID
 CID
 CIDs
@@ -1999,6 +2001,7 @@ AgentTemplates
 AgentInvocation
 AgentStudio
 AgenticStudio
+Charlotte
 Khaitan
 Yashvardhan
 MRX
@@ -2008,3 +2011,38 @@ ManuelFCastillo
 khaitan
 yashvardhan
 Agentic
+Eval
+eval
+GetAgentInvocationV
+PatchAgentInvocationV
+GetAgentVersionsV
+QueryAgentVersionsV
+CreateOrEditAgentExternalV
+DeleteAgentV
+GetAgentsV
+PatchAgentExternalV
+QueryAgentsV
+CombinedKnowledgeBaseAuditEventsV
+EntitiesKnowledgeBaseAuditEventsV
+QueriesKnowledgeBaseAuditEventsV
+EntitiesKnowledgeBaseFilesCreateV
+EntitiesKnowledgeBaseFilesDeleteV
+EntitiesKnowledgeBaseFilesDownloadV
+EntitiesKnowledgeBaseFilesUpdateV
+EntitiesKnowledgeBaseFilesV
+QueriesKnowledgeBaseFilesV
+CombinedKnowledgeBasesV
+EntitiesKnowledgeBasesUpdateV
+EntitiesKnowledgeBasesV
+QueriesKnowledgeBasesV
+EntitiesSkillsCreateV
+EntitiesSkillsDeleteV
+EntitiesSkillsDownloadV
+EntitiesSkillsUpdateV
+EntitiesSkillsV
+QueriesSkillsV
+EntitiesSpansV
+QueriesSpansV
+StreamInvocationResponseV
+EntitiesToolsV
+QueriesToolsV

CHANGELOG.md

@@ -1,3 +1,230 @@
+# Version 1.6.7
+## Added features and functionality
++ Updated: Renamed the __AgenticStudio__ parent service collection to __Charlotte__, since every one of its sub-services requires a Charlotte AI scope, and added __Eval Cases__, __Eval Dataset Entries__, __Eval Datasets__, __Eval Evaluators__ and __Eval Runs__ to it. `AgenticStudio` remains available as a backward compatible alias, including from `falconpy.agentic_studio`.
+    - `__init__.py`
+    - `agentic_studio.py`
+    - `charlotte.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _GetAgentInvocationV3_ and _PatchAgentInvocationV3_ operations within the __Agent Invocation__ service collection.
+    - `_endpoint/_agent_invocation.py`
+    - `_payload/_agent_invocation.py`
+    - `agent_invocation.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _GetAgentVersionsV1_ and _QueryAgentVersionsV1_ operations within the __Agent Versions__ service collection.
+    - `_endpoint/_agent_versions.py`
+    - `agent_versions.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _DeleteAgentV1_, _GetAgentsV2_, _PatchAgentExternalV3_, and _QueryAgentsV2_ operations and added `wait_for_ready` as an allowed parameter in the _CreateOrEditAgentExternalV3_ and _PatchAgentExternalV3_ operations within the __Agents__ service collection.
+    - `_endpoint/_agents.py`
+    - `_payload/_agents.py`
+    - `agents.py`
+
++ Added: Added five new operations to the __Browser Security__ service collection.
+    - _get_sensitive_data_profiles_
+    - _create_sensitive_data_profile_
+    - _delete_sensitive_data_profile_
+    - _update_sensitive_data_profile_
+    - _query_sensitive_data_profiles_
+    - `_endpoint/_browser_security.py`
+    - `_payload/__init__.py`
+    - `_payload/_browser_security.py`
+    - `browser_security.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_browser_security.py`
+
++ Added: Added five new operations to the __Case Management__ service collection.
+    - _add_case_alert_evidence_v2_
+    - _add_case_access_tags_
+    - _remove_case_access_tags_
+    - _add_case_custom_evidence_
+    - _add_case_user_evidence_
+    - `_endpoint/_case_management.py`
+    - `_payload/__init__.py`
+    - `_payload/_case_management.py`
+    - `case_management.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_case_management.py`
+
++ Added: New __Eval Cases__ service collection with two operations.
+    - _get_eval_cases_
+    - _query_eval_cases_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_eval_cases.py`
+    - `_payload/__init__.py`
+    - `__init__.py`
+    - `eval_cases.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_eval_cases.py`
+
++ Added: New __Eval Dataset Entries__ service collection with five operations.
+    - _get_eval_dataset_entries_
+    - _update_eval_dataset_entry_
+    - _create_eval_dataset_entry_
+    - _delete_eval_dataset_entry_
+    - _query_eval_dataset_entries_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_eval_dataset_entries.py`
+    - `_payload/__init__.py`
+    - `_payload/_eval_dataset_entries.py`
+    - `__init__.py`
+    - `eval_dataset_entries.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_eval_dataset_entries.py`
+
++ Added: New __Eval Datasets__ service collection with six operations.
+    - _download_eval_dataset_
+    - _get_eval_datasets_
+    - _update_eval_dataset_
+    - _create_eval_dataset_
+    - _delete_eval_dataset_
+    - _query_eval_datasets_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_eval_datasets.py`
+    - `_payload/__init__.py`
+    - `_payload/_eval_datasets.py`
+    - `__init__.py`
+    - `eval_datasets.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_eval_datasets.py`
+
++ Added: New __Eval Evaluators__ service collection with five operations.
+    - _get_eval_evaluators_
+    - _update_eval_evaluator_
+    - _create_eval_evaluator_
+    - _delete_eval_evaluator_
+    - _query_eval_evaluators_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_eval_evaluators.py`
+    - `_payload/__init__.py`
+    - `_payload/_eval_evaluators.py`
+    - `__init__.py`
+    - `eval_evaluators.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_eval_evaluators.py`
+
++ Added: New __Eval Runs__ service collection with five operations.
+    - _get_eval_runs_
+    - _create_eval_run_
+    - _delete_eval_run_
+    - _perform_eval_run_action_
+    - _query_eval_runs_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_eval_runs.py`
+    - `_payload/__init__.py`
+    - `_payload/_eval_runs.py`
+    - `__init__.py`
+    - `eval_runs.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_eval_runs.py`
+
++ Updated: Added `device_policies.cloud-container-workload.applied`, `device_policies.cloud-container-workload.policy_id`, `device_policies.cloud-container-workload.policy_type` as allowed `sort` values in the _CombinedHiddenDevicesByFilter_ and _CombinedDevicesByFilter_ operations and added `skip_membership_validation` as an allowed parameter in the _entities_perform_action_ operation within the __Hosts__ service collection.
+    - `_endpoint/_hosts.py`
+    - `hosts.py`
+
++ Added: Added 13 new operations to the __IT Automation__ service collection.
+    - _aggregate_patch_deployment_configs_
+    - _aggregate_patch_deployment_executions_
+    - _aggregate_patch_host_deployments_
+    - _query_combined_patch_deployment_configs_
+    - _query_combined_patch_deployment_executions_
+    - _query_combined_host_deployment_patches_
+    - _query_combined_host_deployments_
+    - _query_combined_os_assessment_scan_
+    - _query_combined_os_assessments_
+    - _create_patch_deployment_config_
+    - _delete_patch_deployment_configs_
+    - _update_patch_deployment_config_
+    - _cancel_patch_deployment_executions_
+    - `_endpoint/_it_automation.py`
+    - `_payload/__init__.py`
+    - `_payload/_it_automation.py`
+    - `it_automation.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_it_automation.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _CombinedKnowledgeBaseAuditEventsV1_, _EntitiesKnowledgeBaseAuditEventsV1_, and _QueriesKnowledgeBaseAuditEventsV1_ operations within the __Knowledge Base Audit Events__ service collection.
+    - `_endpoint/_knowledge_base_audit_events.py`
+    - `knowledge_base_audit_events.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _EntitiesKnowledgeBaseFilesDownloadV1_, _EntitiesKnowledgeBaseFilesV1_, _EntitiesKnowledgeBaseFilesUpdateV1_, _EntitiesKnowledgeBaseFilesCreateV1_, _EntitiesKnowledgeBaseFilesDeleteV1_, and _QueriesKnowledgeBaseFilesV1_ operations within the __Knowledge Base Files__ service collection.
+    - `_endpoint/_knowledge_base_files.py`
+    - `knowledge_base_files.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _CombinedKnowledgeBasesV1_, _EntitiesKnowledgeBasesV1_, _EntitiesKnowledgeBasesUpdateV1_, and _QueriesKnowledgeBasesV1_ operations within the __Knowledge Bases__ service collection.
+    - `_endpoint/_knowledge_bases.py`
+    - `_payload/_knowledge_bases.py`
+    - `knowledge_bases.py`
+
++ Added: Added five new operations to the __NGSIEM__ service collection.
+    - _get_scheduled_report_
+    - _create_scheduled_report_
+    - _delete_scheduled_report_
+    - _update_scheduled_report_
+    - _query_scheduled_reports_
+    - `_endpoint/_ngsiem.py`
+    - `_payload/__init__.py`
+    - `_payload/_ngsiem.py`
+    - `ngsiem.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_ngsiem.py`
+
++ Updated: Added `scan_mode` as an allowed parameter and updated the `file` and `scan` parameter descriptions in the _UploadFileQuickScanPro_ operation within the __Quick Scan Pro__ service collection.
+    - `_endpoint/_quick_scan_pro.py`
+    - `quick_scan_pro.py`
+
++ Added: Added two new operations to the __SaaS Security__ service collection.
+    - _set_check_impact_
+    - _get_security_check_change_log_
+    - `_endpoint/_saas_security.py`
+    - `_payload/__init__.py`
+    - `_payload/_saas_security.py`
+    - `saas_security.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_saas_security.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _EntitiesSkillsDownloadV2_, _EntitiesSkillsV1_, _EntitiesSkillsUpdateV1_, _EntitiesSkillsCreateV1_, _EntitiesSkillsDeleteV1_, and _QueriesSkillsV1_ operations within the __Skills__ service collection.
+    - `_endpoint/_skills.py`
+    - `skills.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _EntitiesSpansV1_ and _QueriesSpansV1_ operations within the __Spans__ service collection.
+    - `_endpoint/_spans.py`
+    - `spans.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _StreamInvocationResponseV1_ operation within the __Stream__ service collection.
+    - `_endpoint/_stream.py`
+    - `stream.py`
+
++ Updated: Added `project_id` as an allowed parameter in the _EntitiesToolsV1_ and _QueriesToolsV1_ operations within the __Tools__ service collection.
+    - `_endpoint/_tools.py`
+    - `tools.py`
+
++ Added: Added four new operations to the __User Management__ service collection.
+    - _get_permission_groups_
+    - _get_permissions_
+    - _get_role_permissions_
+    - _query_permissions_
+    - `_endpoint/_user_management.py`
+    - `_payload/__init__.py`
+    - `_payload/_user_management.py`
+    - `user_management.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_user_management.py`
+
+## Issues resolved
++ Fixed: A CA_BUNDLE path (file or directory of trusted certificates) provided to the `ssl_verify` keyword was silently discarded and replaced with `True` when passed to the constructor of the Uber Class (`APIHarnessV2`), the __OAuth2__ class, or any Service Class. Requests were then verified against the default trust store, breaking connectivity behind TLS-inspecting proxies and private CAs. This was a regression introduced in v1.3.0; the legacy Uber Class and v1.2.x Service Classes accepted a path. The constructor and the `ssl_verify` property setter now share the same handling: booleans and CA_BUNDLE paths (`str` or `os.PathLike`) are passed to requests, while empty strings and unsupported types fall back to `True` so verification is never disabled unintentionally. Closes #1521.
+    - `_api_request/_request.py`
+    - `_api_request/_request_connection.py`
+    - `_auth_object/_falcon_interface.py`
+    - `_auth_object/_interface_config.py`
+    - `_auth_object/_uber_interface.py`
+    - `_service_class/_base_service_class.py`
+    - `_service_class/_service_class.py`
+    - `_util/_functions.py`
+    - `oauth2.py`
+    > Unit testing expanded to cover `ssl_verify` normalization and CA_BUNDLE path handling.
+    - `tests/test_ssl_verify.py`
+    - Thanks go out to @tsullivan06 for identifying and reporting this issue! 🙇
+
 # Version 1.6.6
 ## Added Features and functionality
 + Added: New __AgenticStudio__ parent service collection aggregating all 12 Agentic Studio sub-services via multiple inheritance.

README.md

@@ -81,6 +81,35 @@ Representing a single CrowdStrike Falcon API service collection, each Service Cl
 For each CrowdStrike Falcon API service collection, a matching Service Class is available in the FalconPy library. For a complete list of service collections and their related Service Class, please review the [Operations by Collection](https://developer.crowdstrike.com/api-reference/operations-by-collection/) page on the [CrowdStrike Developer Center](https://developer.crowdstrike.com).
 
 
+#### Parent Service Classes
+Some CrowdStrike Falcon API service collections are closely related. A _Parent Service Class_ combines these service collections into a single class using multiple inheritance, providing a method for [every operation available](https://developer.crowdstrike.com/api-reference/operations-by-collection/) within each of the service collections it includes. The Service Class for each individual service collection remains available.
+
+<!-- specter: parent service classes -->
+| Parent Service Class | Included Service Classes |
+| :-- | :-- |
+| `Charlotte` | `Agents`, `AgentInvocation`, `AgentTemplates`, `AgentVersions`, `KnowledgeBases`, `KnowledgeBaseFiles`, `KnowledgeBaseAuditEvents`, `Models`, `Skills`, `Spans`, `Tools`, `Stream`, `EvalCases`, `EvalDatasetEntries`, `EvalDatasets`, `EvalEvaluators`, `EvalRuns` |
+| `ContainerSecurity` | `ContainerAlerts`, `ContainerDetections`, `ContainerImageCompliance`, `ContainerImages`, `ContainerVulnerabilities`, `DriftIndicators`, `ImageAssessmentPolicies` |
+| `Firewall` | `FirewallPolicies`, `FirewallManagement` |
+| `Foundry` | `FoundryLookupFiles`, `FoundryLogScale`, `CustomStorage`, `FaaSExecution` |
+| `NetworkScan` | `NetworkScanGlobalConfigs`, `NetworkScanScanRunReports`, `NetworkScanScanRuns`, `NetworkScanScanners`, `NetworkScanTemplates`, `NetworkScanNetworks`, `NetworkScanScans`, `NetworkScanZones`, `NetworkScanDetections` |
+| `Serverless` | `ServerlessExports`, `ServerlessVulnerabilities` |
+| `Spotlight` | `SpotlightVulnerabilities`, `SpotlightVulnerabilityMetadata`, `SpotlightEvaluationLogic` |
+<!-- /specter: parent service classes -->
+
+```python
+import os
+from falconpy import Charlotte
+
+charlotte = Charlotte(client_id=os.getenv("FALCON_CLIENT_ID"),
+                      client_secret=os.getenv("FALCON_CLIENT_SECRET")
+                      )
+
+# Operations from the Agents and Eval Datasets service collections are available from the same class
+agents = charlotte.query_studio_agents(limit=10)
+datasets = charlotte.query_eval_datasets(limit=10)
+```
+
+
 #### Service Class benefits
 
 - Closely follows Python and OpenAPI best practice for code style and syntax. PEP-8 compliant.

src/falconpy/__init__.py

@@ -111,7 +111,7 @@
 from .agent_invocation import AgentInvocation
 from .agent_templates import AgentTemplates
 from .agent_versions import AgentVersions
-from .agentic_studio import AgenticStudio
+from .charlotte import Charlotte
 from .agents import Agents
 from .aidr import AIDR
 from .alerts import Alerts
@@ -164,6 +164,11 @@
 from .discover import Discover
 from .downloads import Downloads
 from .drift_indicators import DriftIndicators
+from .eval_cases import EvalCases
+from .eval_dataset_entries import EvalDatasetEntries
+from .eval_datasets import EvalDatasets
+from .eval_evaluators import EvalEvaluators
+from .eval_runs import EvalRuns
 from .event_streams import EventStreams
 from .exposure_management import ExposureManagement
 from .faas_execution import FaaSExecution
@@ -328,13 +333,17 @@
     "CodeSecurity", "NetworkContainment",
     "NetworkScanDetections", "Skills",
     "Guardian", "Seraphic",
-    "AgenticStudio",
+    "Charlotte",
     "ContainerSecurity",
     "Spotlight",
     "Serverless",
     "Firewall",
-    "Foundry"
+    "Foundry", "EvalCases",
+    "EvalDatasetEntries", "EvalDatasets",
+    "EvalEvaluators", "EvalRuns",
+    "AgenticStudio"
     ]
+AgenticStudio = Charlotte
 Seraphic = BrowserSecurity
 Guardian = AIDR
 """

src/falconpy/_api_request/_request.py

@@ -278,6 +278,6 @@ def timeout(self) -> Optional[Union[int, tuple]]:
         return self.connection.timeout
 
     @property
-    def verify(self) -> bool:
+    def verify(self) -> Union[bool, str]:
         """Return the SSL verification setting."""
         return self.connection.verify

src/falconpy/_api_request/_request_connection.py

@@ -49,7 +49,7 @@ class RequestConnection:
     # |  |  |   |  |  \ | |__] |__|  |  |___ ___]
     #
     user_agent: Optional[str] = None
-    verify: bool = True
+    verify: Union[bool, str] = True
     timeout: Optional[Union[int, tuple]] = None
     proxy: Optional[Dict[str, str]] = None
     session: Optional[requests.Session] = None