Version 1.3.0 - Developer Enhancements Edition

[jshcodes]

FalconPy v1.3.0

Developer Enhancements Edition 🎉

• Enhancement
• Major Feature update
• Bug fixes
• Updated unit tests
• Documentation
• Code sample

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                    36      0   100%
src/falconpy/_api_request/_request_meta.py                          27      0   100%
src/falconpy/_api_request/_request_payloads.py                      35      0   100%
src/falconpy/_api_request/_request_validator.py                     19      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                          64      0   100%
src/falconpy/_auth_object/_falcon_interface.py                     246      0   100%
src/falconpy/_auth_object/_interface_config.py                      44      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                            27      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                                    204      0   100%
src/falconpy/_service_class/__init__.py                              3      0   100%
src/falconpy/_service_class/_base_service_class.py                 120      0   100%
src/falconpy/_service_class/_service_class.py                       75      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                                                             6336      0   100%

Bandit analysis

[main]	INFO	running on Python 3.9.17
Run started:2023-08-07 13:27:52.363086

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 50788
	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 hosts_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

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.

[ChristopherHammond13]

Let's do this!

There will be some minor stylistic and code simplicity recommendations later down the line, but this code seems functionally great, passes tests, and the only potential issues we found have been sorted and merged to this branch. The code is much more readable than before, and the documentation is great. The type hints are a huge win for our developer community.

Great work @jshcodes!