Version 1.3.0 released! #1019

jshcodes · 2023-08-15T04:13:33Z

jshcodes
Aug 15, 2023
Maintainer

FalconPy v1.3.0

Developer Enhancements Edition 🎉

Unit test coverage

Name                                                             Stmts   Miss  Cover
------------------------------------------------------------------------------------
src/falconpy/__init__.py                                            77      0   100%
src/falconpy/_api_request/__init__.py                                7      0   100%
src/falconpy/_api_request/_request.py                              109      0   100%
src/falconpy/_api_request/_request_behavior.py                      55      0   100%
src/falconpy/_api_request/_request_connection.py                    33      0   100%
src/falconpy/_api_request/_request_meta.py                          26      0   100%
src/falconpy/_api_request/_request_payloads.py                      31      0   100%
src/falconpy/_api_request/_request_validator.py                     17      0   100%
src/falconpy/_auth_object/__init__.py                                6      0   100%
src/falconpy/_auth_object/_base_falcon_auth.py                      19      0   100%
src/falconpy/_auth_object/_bearer_token.py                          63      0   100%
src/falconpy/_auth_object/_falcon_interface.py                     245      0   100%
src/falconpy/_auth_object/_interface_config.py                      40      0   100%
src/falconpy/_auth_object/_uber_interface.py                        33      0   100%
src/falconpy/_constant/__init__.py                                  11      0   100%
src/falconpy/_endpoint/__init__.py                                 138      0   100%
src/falconpy/_endpoint/_alerts.py                                    1      0   100%
src/falconpy/_endpoint/_cloud_connect_aws.py                         1      0   100%
src/falconpy/_endpoint/_cspm_registration.py                         1      0   100%
src/falconpy/_endpoint/_custom_ioa.py                                1      0   100%
src/falconpy/_endpoint/_d4c_registration.py                          1      0   100%
src/falconpy/_endpoint/_detects.py                                   1      0   100%
src/falconpy/_endpoint/_device_control_policies.py                   1      0   100%
src/falconpy/_endpoint/_discover.py                                  1      0   100%
src/falconpy/_endpoint/_event_streams.py                             1      0   100%
src/falconpy/_endpoint/_falcon_complete_dashboard.py                 1      0   100%
src/falconpy/_endpoint/_falcon_container.py                          1      0   100%
src/falconpy/_endpoint/_falconx_sandbox.py                           1      0   100%
src/falconpy/_endpoint/_fdr.py                                       1      0   100%
src/falconpy/_endpoint/_filevantage.py                               1      0   100%
src/falconpy/_endpoint/_firewall_management.py                       1      0   100%
src/falconpy/_endpoint/_firewall_policies.py                         1      0   100%
src/falconpy/_endpoint/_host_group.py                                1      0   100%
src/falconpy/_endpoint/_hosts.py                                     1      0   100%
src/falconpy/_endpoint/_identity_protection.py                       1      0   100%
src/falconpy/_endpoint/_incidents.py                                 1      0   100%
src/falconpy/_endpoint/_installation_tokens.py                       1      0   100%
src/falconpy/_endpoint/_intel.py                                     1      0   100%
src/falconpy/_endpoint/_ioa_exclusions.py                            1      0   100%
src/falconpy/_endpoint/_ioc.py                                       1      0   100%
src/falconpy/_endpoint/_iocs.py                                      1      0   100%
src/falconpy/_endpoint/_kubernetes_protection.py                     1      0   100%
src/falconpy/_endpoint/_malquery.py                                  1      0   100%
src/falconpy/_endpoint/_message_center.py                            1      0   100%
src/falconpy/_endpoint/_ml_exclusions.py                             1      0   100%
src/falconpy/_endpoint/_mobile_enrollment.py                         1      0   100%
src/falconpy/_endpoint/_mssp.py                                      1      0   100%
src/falconpy/_endpoint/_oauth2.py                                    1      0   100%
src/falconpy/_endpoint/_ods.py                                       1      0   100%
src/falconpy/_endpoint/_overwatch_dashboard.py                       1      0   100%
src/falconpy/_endpoint/_prevention_policies.py                       1      0   100%
src/falconpy/_endpoint/_quarantine.py                                1      0   100%
src/falconpy/_endpoint/_quick_scan.py                                1      0   100%
src/falconpy/_endpoint/_real_time_response.py                        1      0   100%
src/falconpy/_endpoint/_real_time_response_admin.py                  1      0   100%
src/falconpy/_endpoint/_recon.py                                     1      0   100%
src/falconpy/_endpoint/_report_executions.py                         1      0   100%
src/falconpy/_endpoint/_response_policies.py                         1      0   100%
src/falconpy/_endpoint/_sample_uploads.py                            1      0   100%
src/falconpy/_endpoint/_scheduled_reports.py                         1      0   100%
src/falconpy/_endpoint/_sensor_download.py                           1      0   100%
src/falconpy/_endpoint/_sensor_update_policies.py                    1      0   100%
src/falconpy/_endpoint/_sensor_visibility_exclusions.py              1      0   100%
src/falconpy/_endpoint/_spotlight_evaluation_logic.py                1      0   100%
src/falconpy/_endpoint/_spotlight_vulnerabilities.py                 1      0   100%
src/falconpy/_endpoint/_tailored_intelligence.py                     1      0   100%
src/falconpy/_endpoint/_user_management.py                           1      0   100%
src/falconpy/_endpoint/_zero_trust_assessment.py                     1      0   100%
src/falconpy/_endpoint/deprecated/__init__.py                       32      0   100%
src/falconpy/_endpoint/deprecated/_custom_ioa.py                     1      0   100%
src/falconpy/_endpoint/deprecated/_d4c_registration.py               1      0   100%
src/falconpy/_endpoint/deprecated/_discover.py                       1      0   100%
src/falconpy/_endpoint/deprecated/_fdr.py                            1      0   100%
src/falconpy/_endpoint/deprecated/_firewall_management.py            1      0   100%
src/falconpy/_endpoint/deprecated/_hosts.py                          1      0   100%
src/falconpy/_endpoint/deprecated/_identity_protection.py            1      0   100%
src/falconpy/_endpoint/deprecated/_installation_tokens.py            1      0   100%
src/falconpy/_endpoint/deprecated/_ioc.py                            1      0   100%
src/falconpy/_endpoint/deprecated/_iocs.py                           1      0   100%
src/falconpy/_endpoint/deprecated/_ods.py                            1      0   100%
src/falconpy/_endpoint/deprecated/_real_time_response.py             1      0   100%
src/falconpy/_endpoint/deprecated/_real_time_response_admin.py       1      0   100%
src/falconpy/_endpoint/deprecated/_report_executions.py              1      0   100%
src/falconpy/_endpoint/deprecated/_scheduled_reports.py              1      0   100%
src/falconpy/_endpoint/deprecated/_zero_trust_assessment.py          1      0   100%
src/falconpy/_enum/__init__.py                                       4      0   100%
src/falconpy/_enum/_base_url.py                                      7      0   100%
src/falconpy/_enum/_container_base_url.py                            6      0   100%
src/falconpy/_enum/_token_fail_reason.py                             4      0   100%
src/falconpy/_error/__init__.py                                      3      0   100%
src/falconpy/_error/_exceptions.py                                  68      0   100%
src/falconpy/_error/_warnings.py                                    34      0   100%
src/falconpy/_log/__init__.py                                        2      0   100%
src/falconpy/_log/_facility.py                                      34      0   100%
src/falconpy/_payload/__init__.py                                   26      0   100%
src/falconpy/_payload/_alerts.py                                    11      0   100%
src/falconpy/_payload/_cloud_connect_aws.py                         23      0   100%
src/falconpy/_payload/_container.py                                 27      0   100%
src/falconpy/_payload/_cspm_registration.py                         53      0   100%
src/falconpy/_payload/_d4c_registration.py                          38      0   100%
src/falconpy/_payload/_detects.py                                   15      0   100%
src/falconpy/_payload/_device_control_policy.py                     33      0   100%
src/falconpy/_payload/_falconx.py                                   25      0   100%
src/falconpy/_payload/_firewall.py                                 130      0   100%
src/falconpy/_payload/_generic.py                                   64      0   100%
src/falconpy/_payload/_host_group.py                                31      0   100%
src/falconpy/_payload/_incidents.py                                 15      0   100%
src/falconpy/_payload/_ioa.py                                       35      0   100%
src/falconpy/_payload/_ioc.py                                       52      0   100%
src/falconpy/_payload/_malquery.py                                  56      0   100%
src/falconpy/_payload/_message_center.py                            22      0   100%
src/falconpy/_payload/_mssp.py                                      15      0   100%
src/falconpy/_payload/_ods.py                                       13      0   100%
src/falconpy/_payload/_prevention_policy.py                         19      0   100%
src/falconpy/_payload/_real_time_response.py                        27      0   100%
src/falconpy/_payload/_recon.py                                     84      0   100%
src/falconpy/_payload/_reports.py                                   19      0   100%
src/falconpy/_payload/_response_policy.py                           19      0   100%
src/falconpy/_payload/_sample_uploads.py                             9      0   100%
src/falconpy/_payload/_sensor_update_policy.py                      30      0   100%
src/falconpy/_result/__base_resource.py                             28      0   100%
src/falconpy/_result/__init__.py                                     9      0   100%
src/falconpy/_result/_base_dictionary.py                            31      0   100%
src/falconpy/_result/_errors.py                                      2      0   100%
src/falconpy/_result/_expanded_result.py                             7      0   100%
src/falconpy/_result/_headers.py                                    24      0   100%
src/falconpy/_result/_meta.py                                       27      0   100%
src/falconpy/_result/_resources.py                                  14      0   100%
src/falconpy/_result/_response_component.py                         24      0   100%
src/falconpy/_result/_result.py                                    203      0   100%
src/falconpy/_service_class/__init__.py                              3      0   100%
src/falconpy/_service_class/_base_service_class.py                 118      0   100%
src/falconpy/_service_class/_service_class.py                       73      0   100%
src/falconpy/_util/__init__.py                                       4      0   100%
src/falconpy/_util/_auth.py                                         18      0   100%
src/falconpy/_util/_functions.py                                   359      0   100%
src/falconpy/_util/_uber.py                                         44      0   100%
src/falconpy/_version.py                                            33      0   100%
src/falconpy/alerts.py                                              33      0   100%
src/falconpy/api_complete.py                                        55      0   100%
src/falconpy/cloud_connect_aws.py                                   48      0   100%
src/falconpy/cspm_registration.py                                  135      0   100%
src/falconpy/custom_ioa.py                                          86      0   100%
src/falconpy/d4c_registration.py                                    96      0   100%
src/falconpy/detects.py                                             32      0   100%
src/falconpy/device_control_policies.py                             78      0   100%
src/falconpy/discover.py                                            35      0   100%
src/falconpy/event_streams.py                                       20      0   100%
src/falconpy/falcon_complete_dashboard.py                           77      0   100%
src/falconpy/falcon_container.py                                    53      0   100%
src/falconpy/falconx_sandbox.py                                     86      0   100%
src/falconpy/fdr.py                                                 23      0   100%
src/falconpy/filevantage.py                                         14      0   100%
src/falconpy/firewall_management.py                                139      0   100%
src/falconpy/firewall_policies.py                                   71      0   100%
src/falconpy/host_group.py                                          61      0   100%
src/falconpy/hosts.py                                              106      0   100%
src/falconpy/identity_protection.py                                 16      0   100%
src/falconpy/incidents.py                                           41      0   100%
src/falconpy/installation_tokens.py                                 43      0   100%
src/falconpy/intel.py                                               88      0   100%
src/falconpy/ioa_exclusions.py                                      33      0   100%
src/falconpy/ioc.py                                                 82      0   100%
src/falconpy/iocs.py                                                40      0   100%
src/falconpy/kubernetes_protection.py                               94      0   100%
src/falconpy/malquery.py                                            50      0   100%
src/falconpy/message_center.py                                      81      0   100%
src/falconpy/ml_exclusions.py                                       35      0   100%
src/falconpy/mobile_enrollment.py                                   18      0   100%
src/falconpy/mssp.py                                               164      0   100%
src/falconpy/oauth2.py                                              26      0   100%
src/falconpy/ods.py                                                 68      0   100%
src/falconpy/overwatch_dashboard.py                                 31      0   100%
src/falconpy/prevention_policy.py                                   62      0   100%
src/falconpy/quarantine.py                                          46      0   100%
src/falconpy/quick_scan.py                                          27      0   100%
src/falconpy/real_time_response.py                                 127      0   100%
src/falconpy/real_time_response_admin.py                            75      0   100%
src/falconpy/recon.py                                              128      0   100%
src/falconpy/report_executions.py                                   24      0   100%
src/falconpy/response_policies.py                                   61      0   100%
src/falconpy/sample_uploads.py                                      75      0   100%
src/falconpy/scheduled_reports.py                                   20      0   100%
src/falconpy/sensor_download.py                                     33      0   100%
src/falconpy/sensor_update_policy.py                               110      0   100%
src/falconpy/sensor_visibility_exclusions.py                        33      0   100%
src/falconpy/spotlight_evaluation_logic.py                          23      0   100%
src/falconpy/spotlight_vulnerabilities.py                           31      0   100%
src/falconpy/tailored_intelligence.py                               41      0   100%
src/falconpy/user_management.py                                    138      0   100%
src/falconpy/zero_trust_assessment.py                               23      0   100%
------------------------------------------------------------------------------------
TOTAL                                                             6319      0   100%

Bandit analysis

[main]	INFO	running on Python 3.9.17

Run started:2023-08-09 05:00:42.323720

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 50777
	Total lines skipped (#nosec): 0

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):

Added features and functionality

Added: Developer Extensibility features - Enhanced existing programmatic architecture with new objects and submodules to address technical debt and provide developers with the necessary structures to easily extend core library functionality.
- APIHarness - Derivative and an interface class commonly referred to as the Uber Class, APIHarness has been refactored to inherit common functionality provided by the FalconInterface class, remove technical debt, add typing, and expand available operations and extensibility features.
  - api_complete.py
- APIRequest - Simple interface class comprised of multiple data classes that is leveraged for managing the components of a request sent to the CrowdStrike API. This is a new object.
  - _api_request/__init__.py
  - _api_request/_request.py
  - _api_request/_request_behavior.py
  - _api_request/_request_connection.py
  - _api_request/_request_meta.py
  - _api_request/_request_payloads.py
  - _api_request/_request_validator.py
- Constant submodule - Stores global constants used throughout the library. This is a new module implemented to store new and pre-existing constants.
  - _constant/__init__.py
- Enum submodule - Stores enumerators available within the library. This is a new module implemented to store pre-existing enumerators.
  - _enum/__init__.py
  - _enum/_base_url.py
  - _enum/_container_base_url.py
  - _enum/_token_fail_reason.py
- Error submodule - Provides python native errors and warnings. This is a new module.
  - _error/__init__.py
  - _error/_exceptions.py
  - _error/_warnings.py
- FalconInterface - Interface class that handles authentication and state management, also referred to as the authentication object or the auth_object. Refactored to address technical debt and add new functionality.
  - _auth_object/__init__.py
  - _auth_object/_base_falcon_auth.py
  - _auth_object/_bearer_token.py
  - _auth_object/_falcon_interface.py
  - _auth_object/_interface_config.py
  - _auth_object/_uber_interface.py
- Log submodule - Provides debug logging functionality. This is a new module.
  - _log/__init__.py
  - _log/_facility.py
- Result - Complex interface class that is leveraged to parse and return results received from the CrowdStrike API. This class has been refactored to address technical debt and provide new developer functionality and extensibility. Default behavior for requests received from the CrowdStrike API remains unchanged (results are returned as a Python dictionary). Expanded functionality provides developers the ability to handle received responses as python structures, allowing for easy iteration and processing without having to handle a dictionary.
  - _result/__init__.py
  - _result/_base_resource.py
  - _result/_base_dictionary.py
  - _result/_errors.py
  - _result/_expanded_result.py
  - _result/_headers.py
  - _result/_meta.py
  - _result/_resources.py
  - _result/_response_component.py
  - _result/_result.py
- ServiceClass - Interface class leveraged by Service Classes to provide common functionality. This class has also been refactored to expand on functionality provided by the FalconInterface class, remove technical debt, add typing and expand extensibility features.
  - _service_class/_init__.py
  - _service_class/_base_service_class.py
  - _service_class/_service_class.py
- Util submodule - Functions and utilities library containing both private and public methods. This is a new module implemented to store new and pre-existing functions.
  - _util/__init__.py
  - _util/_auth.py
  - _util/_functions.py
  - _util/_uber.py
Added: Debug logging - Native debug logging can now be activated per class upon construction. Logs are sanitized by default.
```
import logging
from falconpy import Hosts

logging.basicConfig(level=logging.DEBUG)
hosts = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug=True)
result = hosts.query_devices_by_filter_scroll()
```
Log sanitization can also be disabled when instantiating the class.
```
hosts = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug=True, sanitize_log=False)
```
Local unit testing has been expanded to take advantage of this functionality. To activate, set the environment variable FALCONPY_UNIT_TEST_DEBUG to DEBUG.
- _log/__init__.py
- _log/_facility.py
Added: Environment Authentication - New authentication mechanism that retrieves CrowdStrike API credentials that are pre-defined as variables within the runtime environment. These environment variables must be named FALCON_CLIENT_ID and FALCON_CLIENT_SECRET and both must be present in order for this mechanism to be used. Environment Authentication is the last mechanism attempted, meaning all other authentication mechanisms will take precedence.
```
from falconpy import Hosts

hosts = Hosts()
result = hosts.query_devices_by_filter_scroll()
```
- _auth_object/_falcon_interface.py
Added: Pythonic response handling - Allows for the handling of responses received from the CrowdStrike API as pythonic structures as opposed to dictionaries.
```
from falconpy import Hosts

hosts = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, pythonic=True)
host_list = hosts.query_devices_by_filter_scroll()
for device in host_list:
    print(device)
```
- _result/__init__.py
- _result/_base_resource.py
- _result/_base_dictionary.py
- _result/_errors.py
- _result/_expanded_result.py
- _result/_headers.py
- _result/_meta.py
- _result/_resources.py
- _result/_response_component.py
- _result/_result.py

Added: Pythonic errors and warnings - Leverages native Python exceptions to implement error and warning handling.

from falconpy import Hosts, APIError

hosts = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, pythonic=True)
try:
    device_detail = hosts.get_device_details("not-a-real-id")
except APIError as not_found:
    print(not_found)

_error/__init__.py
_error/_exceptions.py
_error/_warnings.py

Added: Typing - Type hints have been added throughout the library. This is an ongoing initiative.

Issues resolved

Fixed: Unusual responses from operations within the Falcon Container service collection.
- _result/_result.py
- _util/_functions.py
Fixed: Uber Class functionality using operations within the OAuth2 service collection. Closes [ BUG ] You cannot call the oauth2AccessToken and oauth2RevokeToken operations directly from the Uber Class command method #835.
- api_complete.py
- _auth_object/_falcon_interface.py
- _auth_object/_uber_interface.py
Fixed: Inbound strings provided to the creds and proxy keywords are not automatically converted to dictionaries. Closes [ ENH ] Detect inbound strings for the creds and proxy keywords and convert them to dictionaries #909.
- _auth_object/_falcon_interface.py
Fixed: Fixed missing facet keyword in follow request for vulnerabilities - Grab CVEs for CID sample. Closes [ BUG ] facet is not specified in second call to query_vulnerabilities_combined in spotlight_grab_cves_for_cid sample #1004.
- samples/spotlight/spotlight_grab_cves_for_cid.py
Fixed: IDs are not being migrated to the body payload when calling the PostEntitiesAlertsV1 operation. Closes [ BUG ] PostEntitiesAlertsV1 is not moving IDs to the correct payload #1016.
- _constant/__init__.py

Other

Expanded: Unit testing expanded to complete code coverage.
Updated: Added column prune keyword to Grab CVEs by CID sample. Closes [ ENH ] Add the ability to drop columns from results in the Grab CVEs by CID sample #1005.
- samples/spotlight/spotlight_grab_cves_for_cid.py
PLEASE NOTE: Python 3.6 support will be discontinued in January 2024.

Installation

You can install this new release by installing the package via the Python Package Index.

python3 -m pip install crowdstrike-falconpy

or

pip3 install crowdstrike-falconpy

Upgrading

You can upgrade to this new release by installing the update via the Python Package Index.

python3 -m pip install crowdstrike-falconpy --upgrade

or

pip3 install crowdstrike-falconpy --upgrade

This discussion was created from the release Version 1.3.0.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Version 1.3.0 released! #1019

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 0 comments

Select a reply

Version 1.3.0 released! #1019

jshcodes Aug 15, 2023 Maintainer

FalconPy v1.3.0

Unit test coverage

Bandit analysis

Added features and functionality

Issues resolved

Other

Installation

Upgrading

Replies: 0 comments

jshcodes
Aug 15, 2023
Maintainer