Merge branch 'CrowdStrike:dev' into dev

Author: alhumaw

.github/wordlist.txt

@@ -1836,3 +1836,11 @@ pipenv
 STIX
 jayy
 Prajapati
+TestParserFromTemplate
+CloneParser
+Configs
+configs
+combinedqueryinstalledpatches
+combinedQueryInstalledPatches
+vratiskol
+JSONDecodeError

.gitignore

@@ -2,6 +2,7 @@
 *.pyc
 *.swp
 *.egg
+.idea/*
 env/
 .venv/
 .eggs/

CHANGELOG.md

@@ -1,3 +1,188 @@
+# Version 1.6.2
+## Added features and functionality
++ Added: New __Network Scan Global Configs__ service collection with two operations.
+    - _get_global_configs_
+    - _update_global_configs_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_global_configs.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_global_configs.py`
+    - `__init__.py`
+    - `network_scan_global_configs.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_global_configs.py`
+
++ Added: New __Network Scan Scan Run Reports__ service collection with one operation.
+    - _get_scan_run_reports_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_scan_run_reports.py`
+    - `__init__.py`
+    - `network_scan_scan_run_reports.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_scan_run_reports.py`
+
++ Added: New __Network Scan Scan Runs__ service collection with five operations.
+    - _aggregate_scan_runs_
+    - _get_scan_runs_
+    - _create_scan_runs_
+    - _update_scan_runs_
+    - _query_scan_runs_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_scan_runs.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_scan_runs.py`
+    - `__init__.py`
+    - `network_scan_scan_runs.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_scan_runs.py`
+
++ Added: New __Network Scan Scanners__ service collection with four operations.
+    - _aggregate_scanners_
+    - _get_scanners_
+    - _update_scanners_
+    - _query_scanners_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_scanners.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_scanners.py`
+    - `__init__.py`
+    - `network_scan_scanners.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_scanners.py`
+
++ Added: New __Network Scan Templates__ service collection with six operations.
+    - _get_template_configs_
+    - _get_templates_
+    - _create_templates_
+    - _update_templates_
+    - _delete_templates_
+    - _query_templates_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_templates.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_templates.py`
+    - `__init__.py`
+    - `network_scan_templates.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_templates.py`
+
++ Added: New __Network Scan Networks__ service collection with six operations.
+    - _aggregate_networks_
+    - _get_networks_
+    - _create_networks_
+    - _update_networks_
+    - _delete_networks_
+    - _query_networks_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_networks.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_networks.py`
+    - `__init__.py`
+    - `network_scan_networks.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_networks.py`
+
++ Added: New __Network Scan Scans__ service collection with six operations.
+    - _aggregate_scans_
+    - _get_scans_
+    - _create_scans_
+    - _update_scans_
+    - _delete_scans_
+    - _query_scans_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_scans.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_scans.py`
+    - `__init__.py`
+    - `network_scan_scans.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_scans.py`
+
++ Added: New __Network Scan Zones__ service collection with seven operations.
+    - _aggregate_zones_
+    - _combined_zones_
+    - _get_zones_
+    - _create_zones_
+    - _update_zones_
+    - _delete_zones_
+    - _query_zones_
+    - `_endpoint/__init__.py`
+    - `_endpoint/_network_scan_zones.py`
+    - `_payload/__init__.py`
+    - `_payload/_network_scan_zones.py`
+    - `__init__.py`
+    - `network_scan_zones.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_network_scan_zones.py`
+
++ Added: New __Network Scan__ parent service collection aggregating all eight Network Scan sub-services via multiple inheritance.
+    - `__init__.py`
+    - `network_scan.py`
+
++ Added: Added one new operation to the __Spotlight Vulnerabilities__ service collection.
+    - _combinedQueryInstalledPatches_
+    - `_endpoint/_spotlight_vulnerabilties.py`
+    - `spotlight_vulnerabilities.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_spotlight_vulnerabilities.py`
+    - Thanks to @vratiskol for their contribution!
+
++ Added: Added two new operations to the __NGSIEM__ service collection.
+    - _CloneParser_
+    - _TestParserFromTemplate_
+    - `_endpoint/_ngsiem.py`
+    - `_endpoint/deprecated/_ngsiem.py`
+    - `_payload/__init__.py`
+    - `_payload/_ngsiem.py`
+    - `ngsiem.py`
+    > Unit testing expanded to complete code coverage.
+    - `tests/test_ngsiem.py`
+
++ Added: Added `device_policies.data-protection.applied`, `device_policies.data-protection.policy_id`, `device_policies.data-protection.policy_type`, `device_policies.data-protection-cloud.applied`, `device_policies.data-protection-cloud.policy_id`, `device_policies.data-protection-cloud.policy_type`, `device_policies.network-scan-content.applied`, `device_policies.network-scan-content.policy_id`, and `device_policies.network-scan-content.policy_type` as allowed filter and sort fields in the _CombinedHiddenDevicesByFilter_, _QueryDevicesByFilter_, and _QueryDevicesByFilterScroll_ operations within the __Hosts__ service collection.
+    - `_endpoint/_hosts.py`
+    - `_endpoint/deprecated/_hosts.py`
+    - `hosts.py`
+
++ Added: Added `multi_arch` as an allowed filter keyword in the _AggregateImageCountByBaseOS_, _AggregateImageCountByState_, _AggregateImageCount_, _GetCombinedImages_, _CombinedImageByVulnerabilityCount_, _CombinedImageDetail_, and _ReadCombinedImagesExport_ operations within the __Container Images__ service collection.
+    - `_endpoint/_container_images.py`
+    - `container_images.py`
+
++ Updated: Updated available FQL filter fields documentation in the _combinedQueryVulnerabilities_ operation within the __Spotlight Vulnerabilities__ service collection.
+    - `_endpoint/_spotlight_vulnerabilities.py`
+    - `_endpoint/deprecated/_spotlight_vulnerabilities.py`
+    - `spotlight_vulnerabilities.py`
+
++ Updated: Updated available sort fields documentation in the _query_scheduled_scans_ operation within the __ODS__ service collection.
+    - `_endpoint/_ods.py`
+    - `_endpoint/deprecated/_ods.py`
+    - `ods.py`
+
+## Issues resolved
++ Fixed: JSONDecodeError import bug.
+    - `util/_functions.py`
+    - `util/_auth.py`
+
++ Fixed: Added missing parameters `is_enabled` and `host_groups` to the _entities_policy_patch_v2_ operation from the __Data Protection Configuration__ service collection.
+    - `_payload/_data_protection_configuration.py`
+    - `data_protection_configuration.py`
+
++ Fixed: Added backward compatibility for `file` and `lookup_file` parameters. Closes #1372.
+    - `ngsiem.py`
+    > Unit testing updated to reflect modified operations.
+    - `tests/test_ngsiem.py`
+
++ Fixed: Fixed `case_id` and `description` not being sent as form data in the _upload_file_ operation within the __Case Management__ service collection. Closes #1445.
+    - `case_management.py`
+
++ Fixed: Added missing `anomaly`, `guardrail_notifications`, `mitre_attack`, and `template_id` parameters to the correlation rules payload builder. List parameters now accept comma-delimited strings or lists. Closes #1450.
+    - `_payload/_correlation_rules.py`
+
++ Fixed: Added missing `facet` keyword argument documentation to the _query_combined_hosts_ operation within the __Discover__ service collection. Closes #1382.
+    - `discover.py`
+
++ Fixed: Fixed _upload_file_ operation in the __NGSIEM__ service collection not returning the file ID on successful upload.
+    - `ngsiem.py`
+
 # Version 1.6.1
 ## Added features and functionality
 + Added: New __Admission Control Policies__ service collection with 15 operations.
@@ -170,6 +355,12 @@
     > Unit testing expanded to complete code coverage.
     - `tests/test_cloud_policies.py`
 
++ Removed: Removed `GetCSPMGCPUserScriptsAttachment` operation from the __D4CRegistration__ service collection.
+
++ Removed: Removed `GetCombinedImages` operation from the __FalconContainer__ service collection.
+
++ Removed: Removed `getCombinedAssessmentsQuery` operation from the __ZeroTrustAssessment__ service collection.
+
 + Added: Added `rule_category`, `rule_cloneable`, `rule_compliance_benchmark_uuid`, `rule_resource_type_name`, and `rule_risk_factor` as allowed filter and sort fields in the _QueryRules_ operation within the __Cloud Policies__ service collection.
     - `_endpoint/_cloud_policies.py`
     - `cloud_policies.py`

samples/README.md

@@ -94,7 +94,7 @@ The following samples are categorized by CrowdStrike product, and further catego
 | Topic | Samples |
 | :-- | :-- |
 | [Asset Management (Discover)](#asset-management-samples) | List discovered hosts<BR/>Spyglass |
-| [Vulnerability Management (Spotlight)](#vulnerability-management-samples) | Find vulnerable hosts by CVE ID<BR/>CISA DHS Known Exploited Vulnerabilities<BR/>Spotlight Quick Report |
+| [Vulnerability Management (Spotlight)](#vulnerability-management-samples) | Find vulnerable hosts by CVE ID<BR/>CISA DHS Known Exploited Vulnerabilities<BR/>Query installed patches<BR/>Spotlight Quick Report |
 
 <a id="fusion-and-foundry-toc"></a>
 
@@ -1750,6 +1750,7 @@ These samples discuss leveraging the CrowdStrike Spotlight Evaluation Logic and
 
 - [Find vulnerable hosts by CVE ID](#find-vulnerable-hosts-by-cve-id)
 - [CISA DHS Known Exploited Vulnerabilities](#cisa-dhs-known-exploited-vulnerabilities)
+- [Query installed patches](#query-installed-patches)
 - [Spotlight Quick Report](#spotlight-quick-report)
 
 #### Find vulnerable hosts by CVE ID
@@ -1782,6 +1783,20 @@ This sample demonstrates the following CrowdStrike Spotlight Vulnerability API o
 
 ---
 
+#### Query installed patches
+In this [example](spotlight#query-installed-patches) we demonstrate retrieving installed patch data from Spotlight and printing the JSON response.
+
+[![Spotlight Vulnerabilities](https://img.shields.io/badge/Service%20Class-Spotlight_Installed_Patches-silver?style=for-the-badge&labelColor=C30A16&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAAOCAYAAAAi2ky3AAABhWlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw1AUhU9TpaIVBzuIOGSoDmJBVEQ3rUIRKoRaoVUHk5f+CE0akhQXR8G14ODPYtXBxVlXB1dBEPwBcXNzUnSREu9LCi1ifPB4H+e9c7jvXkColZhmtY0Cmm6bqURczGRXxNAruhAEMI1hmVnGrCQl4bu+7hHg512MZ/m/+3N1qzmLAQGReIYZpk28Tjy5aRuc94kjrCirxOfEIyYVSPzIdcXjN84FlwWeGTHTqTniCLFYaGGlhVnR1IgniKOqplO+kPFY5bzFWStVWKNO/sNwTl9e4jrtASSwgEVIEKGggg2UYCNGp06KhRTdx338/a5fIpdCrg0wcsyjDA2y6wefwe/eWvnxMS8pHAfaXxznYxAI7QL1quN8HztO/QQIPgNXetNfrgFTn6RXm1r0COjZBi6um5qyB1zuAH1PhmzKrsTnL+TzwPsZjSkL9N4Cnate3xr3OH0A0tSr5A1wcAgMFSh7zeffHa19+/dNo38/hq9yr+iELI0AAAAGYktHRAAAAAAAAPlDu38AAAAJcEhZcwAACxMAAAsTAQCanBgAAAAHdElNRQflDAsTByz7Va2cAAAAGXRFWHRDb21tZW50AENyZWF0ZWQgd2l0aCBHSU1QV4EOFwAAAYBJREFUKM+lkjFIlVEYht/zn3sFkYYUyUnIRcemhCtCU6JQOLiIU+QeJEQg6BBIm0s4RBCBLjq5OEvgJC1uOniJhivesLx17/97/vO9b4NK4g25157hfHCGB773/cA0HZIEAKiMj+LWiOxljG/i96pnCFP58XHnrWX2+9cj0dYl9Yu2FE9/9rXrcAAgs2eSyiBfOe/XRD503h/CuffOubQVUXL+Jh9BllzBbyJJBgDclVkO4Kukd8zzkXJbeUljIldFTstsmSHM6S81ma2KfPKlFdkGAMY4wzx/bbXapMy21My+YizdKNq5mDzLkrxafSxySFKjSWX2oTmjKzz4vN0r2lOFcL/Q3V0/mX95ILMXTTGYVfaut/aP2+oCMAvnZgCcsF5fcR0dg65YHAdwB+QApADvu0AuOe/ftlJAD7Nsgmm6yBjDtfWORJZlNtFyo/lR5Z7MyheKA5ktSur7sTAHazSG27pehjAiaVfkN8b4XFIJ/wOzbOx07VNRUuHy7w98CzCcGPyWywAAAABJRU5ErkJggg==)](spotlight#query-installed-patches)
+
+##### Spotlight Vulnerabilities API operations discussed
+This sample demonstrates the following CrowdStrike Spotlight Vulnerability API operations:
+
+| Operation | Description |
+| :--- | :--- |
+| [combinedQueryInstalledPatches](https://www.falconpy.io/Service-Collections/Spotlight-Vulnerabilities.html#combinedqueryinstalledpatches) | Get installed patch records for hosts by providing a FQL filter and paging details. |
+
+---
+
 #### Spotlight Quick Report
 In this [example](spotlight#spotlight-quick-report) we demonstrate generating a report of CVE matches within a Falcon tenant using the Spotlight and Hosts service collections.
 

samples/spotlight/README.md

@@ -8,6 +8,7 @@ The examples within this folder focus on leveraging CrowdStrike's Falcon Spotlig
 
 - [Identify hosts with vulnerabilities by CVE](#identify-hosts-with-vulnerabilities-by-cve)
 - [CISA Known exploited vulnerabilities](CISA_known_exploited_vulns)
+- [Query installed patches](#query-installed-patches)
 - [Spotlight Quick Report](#spotlight-quick-report)
 
 ## Identify hosts with vulnerabilities by CVE
@@ -183,6 +184,49 @@ optional arguments:
 ### Example source code
 The source code for this example can be found [here](find_hosts_by_cve.py).
 
+## Query installed patches
+Retrieve Falcon Spotlight installed patch records and output the JSON response structure.
+
+### Running the program
+In order to run this demonstration, you will need access to CrowdStrike API keys with the following scopes:
+
+| Service Collection | Scope |
+| :---- | :---- |
+| Spotlight Vulnerabilities | __READ__ |
+
+### Execution syntax
+The following command will query installed patch data with the specified FQL filter.
+
+#### Basic usage
+```shell
+python3 spotlight_installed_patches.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f "hostname:'my-hostname'"
+```
+
+#### Saving output to file
+```shell
+python3 spotlight_installed_patches.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f "hostname:'my-hostname'" -o installed_patches.json
+```
+
+#### Retrieving all pages
+```shell
+python3 spotlight_installed_patches.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f "hostname:'my-hostname'" -a
+```
+
+#### Sorting and limiting
+```shell
+python3 spotlight_installed_patches.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f "hostname:'my-hostname'" --sort "hostname|asc" -l 200
+```
+
+#### Command-line help
+Command-line help is available via the `-h` argument.
+
+```shell
+python3 spotlight_installed_patches.py -h
+```
+
+### Example source code
+The source code for this example can be found [here](spotlight_installed_patches.py).
+
 ## Spotlight Quick Report
 Produce a quick report of CVE vulnerabilities discovered within your Falcon tenant.