Version 1.3.0
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 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
- 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.
- Added: Debug logging - Native debug logging can now be activated per class upon construction. Logs are sanitized by default.
Log sanitization can also be disabled when instantiating the class.
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()
Local unit testing has been expanded to take advantage of this functionality. To activate, set the environment variablehosts = Hosts(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, debug=True, sanitize_log=False)
FALCONPY_UNIT_TEST_DEBUG
toDEBUG
._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
andFALCON_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 #835.
api_complete.py
_auth_object/_falcon_interface.py
_auth_object/_uber_interface.py
- Fixed: Inbound strings provided to the
creds
andproxy
keywords are not automatically converted to dictionaries. Closes #909._auth_object/_falcon_interface.py
- Fixed: Fixed missing facet keyword in follow request for vulnerabilities - Grab CVEs for CID sample. Closes #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 #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 #1005.
samples/spotlight/spotlight_grab_cves_for_cid.py
- PLEASE NOTE: Python 3.6 support will be discontinued in January 2024.