New bleeding edge build (v0.6.0) now available!

[jshcodes]

FalconPy v0.6.0

This update:

• resolves multiple bugs (including an adjustment that speaks to a potential breaking change introduced by v0.5.4)
• introduces an additional method of authentication (Direct authentication)
• updates all service classes to the latest pattern (revision 3)
• refactors several unit tests
• implements two new Service Classes and their related unit tests
  • Report Executions
  • Scheduled Reports
• adds a new operation to the Zero Trust Assessment Service Class (getComplianceV1)

• Enhancement
• Minor Feature update
• Bug fixes
• Updated unit tests

Planned release date

This package will release to the production index on 08.24.2021.

Unit test coverage

Name                                                             Stmts   Miss  Cover
------------------------------------------------------------------------------------
src/falconpy/__init__.py                                            14      0   100%
src/falconpy/_endpoint/__init__.py                                 105      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/_event_streams.py                             1      0   100%
src/falconpy/_endpoint/_falcon_complete_dashboard.py                 1      0   100%
src/falconpy/_endpoint/_falconx_sandbox.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/_ml_exclusions.py                             1      0   100%
src/falconpy/_endpoint/_mssp.py                                      1      0   100%
src/falconpy/_endpoint/_oauth2.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/_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_vulnerabilities.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                       20      0   100%
src/falconpy/_endpoint/deprecated/_custom_ioa.py                     1      0   100%
src/falconpy/_endpoint/deprecated/_firewall_management.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/_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/_result.py                                              8      0   100%
src/falconpy/_service_class.py                                      62      0   100%
src/falconpy/_util.py                                              166      0   100%
src/falconpy/_version.py                                            10      0   100%
src/falconpy/api_complete.py                                        93      0   100%
src/falconpy/cloud_connect_aws.py                                   38      0   100%
src/falconpy/cspm_registration.py                                   76      0   100%
src/falconpy/custom_ioa.py                                          81      0   100%
src/falconpy/d4c_registration.py                                    36      0   100%
src/falconpy/detects.py                                             18      0   100%
src/falconpy/device_control_policies.py                             49      0   100%
src/falconpy/event_streams.py                                       13      0   100%
src/falconpy/falcon_complete_dashboard.py                           54      0   100%
src/falconpy/falconx_sandbox.py                                     56      0   100%
src/falconpy/firewall_management.py                                 69      0   100%
src/falconpy/firewall_policies.py                                   50      0   100%
src/falconpy/host_group.py                                          45      0   100%
src/falconpy/hosts.py                                               49      0   100%
src/falconpy/identity_protection.py                                  8      0   100%
src/falconpy/incidents.py                                           25      0   100%
src/falconpy/installation_tokens.py                                 27      0   100%
src/falconpy/intel.py                                               59      0   100%
src/falconpy/ioa_exclusions.py                                      23      0   100%
src/falconpy/ioc.py                                                 28      0   100%
src/falconpy/iocs.py                                                38      0   100%
src/falconpy/kubernetes_protection.py                               40      0   100%
src/falconpy/malquery.py                                            35      0   100%
src/falconpy/ml_exclusions.py                                       23      0   100%
src/falconpy/mssp.py                                                93      0   100%
src/falconpy/oauth2.py                                              46      0   100%
src/falconpy/overwatch_dashboard.py                                 23      0   100%
src/falconpy/prevention_policy.py                                   42      0   100%
src/falconpy/quick_scan.py                                          19      0   100%
src/falconpy/real_time_response.py                                  82      0   100%
src/falconpy/real_time_response_admin.py                            50      0   100%
src/falconpy/recon.py                                               73      0   100%
src/falconpy/report_executions.py                                   16      0   100%
src/falconpy/response_policies.py                                   42      0   100%
src/falconpy/sample_uploads.py                                      20      0   100%
src/falconpy/scheduled_reports.py                                   12      0   100%
src/falconpy/sensor_download.py                                     31      0   100%
src/falconpy/sensor_update_policy.py                                70      0   100%
src/falconpy/sensor_visibility_exclusions.py                        23      0   100%
src/falconpy/spotlight_vulnerabilities.py                           17      0   100%
src/falconpy/user_management.py                                     49      0   100%
src/falconpy/zero_trust_assessment.py                               12      0   100%
------------------------------------------------------------------------------------
TOTAL                                                             2189      0   100%

Bandit analysis

[main]	INFO	running on Python 3.9.6
Run started:2021-08-16 18:34:13.464428

Test results:
	No issues identified.

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

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

Added features and functionality

• Refactored Cloud Connect AWS Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Cloud Connect AWS Service Class to the latest pattern (Rev 3) #271. cloud_connect_aws.py

• Refactored CSPM Registration Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the CSPM Registration Service Class to the latest pattern (Rev 3) #272. cspm_registration.py

• Refactored Custom IOA Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Custom IOA Service Class to the latest pattern (Rev 3) #258. custom_ioa.py

• Refactored D4C Registration Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the D4C Registration Service Class to the latest pattern (Rev 3) #273. d4c_registration.py

• Refactored Detects Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Detects Service Class to the latest pattern (Rev 3) #274. detects.py

• Refactored Device Control Policies Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Device Control Policies Service Class to the latest pattern (Rev 3) #275. device_control_policies.py

• Refactored Events Streams Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Event Streams Service Class to the latest pattern (Rev 3) #248. event_streams.py

• Refactored Falcon Complete Dashboard Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Falcon Complete Dashboard Service Class to the latest pattern (Rev 3) #294. falcon_complete_dashboard.py

• Refactored Falcon Flight Control Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Falcon Flight Control (MSSP) Service Class to the latest pattern (Rev 3) #292. mssp.py

• Refactored Falcon X Sandbox Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the FalconX Sandbox Service Class to the latest pattern (Rev 3) #259. falconx_sandbox.py

• Refactored Firewall Management Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Firewall Management Service Class to the latest pattern (Rev 3) #257. firewall_management.py

• Refactored Firewall Policies Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Firewall Policies Service Class to the latest pattern (Rev 3) #296. firewall_policies.py

• Refactored Hosts Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Hosts Service Class to the latest pattern (Rev 3) #269. hosts.py

• Refactored Host Group Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Host Group Service Class to the latest pattern (Rev 3) #286. host_group.py

• Refactored Identity Protection Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Identity Protection Service Class to the latest pattern (Rev 3) #299. identity_protection.py

• Refactored Incidents Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Incidents Service Class to the latest pattern (Rev 3) #289. incidents.py

• Refactored Installation Tokens Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Installation Tokens Service Class to the latest pattern (Rev 3) #287. installation_tokens.py

• Refactored Intel Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Intel Service Class to the latest pattern (Rev 3) #264. intel.py

• Refactored IOA Exclusions Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the IOA Exclusions Service Class to the latest pattern (Rev 3) #283. ioa_exclusions.py

• Refactored IOC Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the IOC Service Class to the latest pattern (Rev 3) #267. ioc.py

• Refactored IOCs Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the IOCs Service Class to the latest pattern (Rev 3) [Deprecated Class] #284. iocs.py

• Refactored Kubernetes Protection Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Kubernetes Protection Service Class to the latest pattern (Rev 3) #293. kubernetes_protection.py

• Refactored MalQuery Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the MalQuery Service Class to the latest pattern (Rev 3) #298. malquery.py

• Refactored ML Exclusions Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the ML Exclusions Service Class to the latest pattern (Rev 3) #281. ml_exclusions.py

• Refactored Overwatch Dashboard Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Overwatch Dashboard Service Class to the latest pattern (Rev 3) #278. overwatch_dashboard.py

• Refactored Prevention Policy Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Prevention Policy Service Class to the latest pattern (Rev 3) #290. prevention_policy.py

• Refactored Quick Scan Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Quick Scan Service Class to the latest pattern (Rev 3) #282. quick_scan.py

• Refactored Real Time Response Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Real Time Response Service Class to the latest pattern (Rev 3) #280. real_time_response.py

• Refactored Real Time Response Admin Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Real Time Response Admin Service Class to the latest pattern (Rev 3) #256. real_time_response_admin.py

• Refactored Recon Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Recon Service Class to the latest pattern (Rev 3) #297. recon.py

• Refactored Response Policies Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Response Policies Service Class to the latest pattern (Rev 3) #295. response_policies.py

• Refactored Sample Uploads Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Sample Uploads Service Class to the latest pattern (Rev 3) #255. sample_uploads.py

• Refactored Sensor Download Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Sensor Download Service Class to the latest pattern (Rev 3) #285. sensor_download.py

• Refactored Sensor Update Policy Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Sensor Update Policy Service Class to the latest pattern (Rev 3) #288. sensor_update_policy.py

• Refactored Sensor Visibility Exclusions Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Sensor Visibility Exclusions Service Class to the latest pattern (Rev 3) #279. sensor_visibility_exclusions.py

• Refactored Spotlight Vulnerabilities Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Spotlight Vulnerabilities Service Class to the latest pattern (Rev 3) #277. spotlight_vulnerabilities.py

• Refactored User Management Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the User Management Service Class to the latest pattern (Rev 3) #276. user_management.py

• Refactored Zero Trust Assessment Service Class to the latest pattern (rev 3), aligns syntax to PEP8. Closes [ ENH ] Refactor the Zero Trust Assessment Service Class to the latest pattern (Rev 3) #260. zero_trust_assessment.py

• Added client_id and client_secret as keywords to the base Service Class, Uber Class, and Authentication class. api_complete.py, oauth2.py, _service_class.py

  This change allows you to specify your API ID and secret when you create an instance of any of these classes. (Direct Authentication)

  from falconpy.hosts import Hosts
  falcon = Hosts(client_id="CLIENT_ID_HERE", client_secret="CLIENT_SECRET_HERE")
  results = falcon.query_devices_by_filter(sort="devices.hostname|desc", limit=10)
  print(results)

• Added new Report Executions Service Class. report_executions.py

  • Basic unit test implemented: test_report_executions.py

• Added new Schedule Reports Service Class. scheduled_reports.py

  • Basic unit test implemented: test_scheduled_reports.py

• Added new operation (getComplianceV1) to Zero Trust Assessment Service Class. zero_trust_assessment.py

Issues resolved

• Bug fix: Resolved HTTP status code 415 on calls to refreshActiveStreamSession (refresh_active_stream). Closes [ BUG ] Event Streams service class generates 415 on call to refreshActiveStreamSession #247. event_streams.py

• Bug fix: Resolved header pollution issue within Falcon X Sandbox Service Class. Closes [ BUG ] Header pollution in the FalconX_Sandbox service class #250. falconx_sandbox.py

• Bug fix: Resolved header pollution issue within Firewall Management Service Class. Closes [ BUG ] Header pollution in the Firewall_Management service class #252. firewall_management.py

• Bug fix: Resolved header pollution issue within Custom IOA Service Class. Closes [ BUG ] Header pollution in the Custom_IOA service class #253. custom_ioa.py

• Bug fix: Resolved header pollution issue within Sample Uploads Service Class. Closes [ BUG ] Header pollution in the Sample_Uploads service class #254. sample_uploads.py

• Bug fix: Resolved HTTP status code 500 error on calls to RTR_CreatePut_Files (create_put_files). Closes [ BUG ] 500 error on CreatePut_Files within Real Time Response Admin Service Class #261. real_time_response_admin.py

• Bug fix: Resolved HTTP status code 400 or 500 error on calls to RTR_UpdateScripts (update_scripts) and calls to RTR_CreateScripts (create_scripts). Closes [ BUG ] 400 / 500 error on RTR_UpdateScripts and RTR_CreateScripts when using Real_Time_Response_Admin service class #262. real_time_response_admin.py

• Bug fix: Added handle_single_argument helper to attempt to handle single arguments passed to Service Class methods. Addresses a potential breaking change introduced by v0.5.4. Closes [ BUG ] Parameter abstraction handling impacting calls that use arguments instead of keywords #263. _util.py

  Developers should use keywords, not arguments, when specifying parameters provided to Service Class or the Uber Class command methods.

  Example

  from falconpy.hosts import Hosts
  falcon = Hosts(creds={"client_id": "CLIENT_ID_HERE", "client_secret": "CLIENT_SECRET_HERE"})
  
  result = falcon.GetDeviceDetails(ids="12345"))   # This syntax will always work
  print(result)
  result = falcon.GetDeviceDetails("12345")        # This syntax may fail depending on method
  print(result)                                    # (will work in this example)
  bad_result = falcon.QueryHiddenDevices(1, 0, "devices.hostname|desc", "")
  print(bad_result)                                # This syntax will always fail

  Whenever possible, Service Classes attempt to guess the keyword for the first argument passed (if present). Typically these are aligned to the one required parameter for the method. (Example: the ids parameter)

• Related to [ BUG ] Parameter abstraction handling impacting calls that use arguments instead of keywords #263: Updated Uber class to no longer leverage the force_default helper, allowing users to still use the first argument to specify the action to be performed. api_complete.py

• Bug fix: Added the after parameter to the endpoint parameter definitions for indicator_combined_v1 and indicator_search_v1. Closes [ BUG ] indicator_combined_v1 and indicator_search_v1 do not list or support the after parameter in the IOC Service Class #266. _endpoint/_ioc.py

• Bug fix: Multiple methods within the Flight Control Service Class make use of the wrong HTTP method. Closes [ BUG ] Several functions within Flight Control Service Class reference the wrong HTTP method #291. mssp.py

Other

• Initial refactoring of unit test harnesses for service classes detailed above.
• Reduced token-related API requests performed by unit testing series.
• Minor adjustment to Uber class unit tests to better demonstrate proper method usage.
• Updated unit tests to support US-2 / Gov base URL testing.

Installation

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

python3 -m pip install -i https://test.pypi.org/simple/ crowdstrike-falconpy

or

pip3 install -i https://test.pypi.org/simple/ crowdstrike-falconpy

Upgrading

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

python3 -m pip install -i https://test.pypi.org/simple/ crowdstrike-falconpy --upgrade

or

pip3 install -i https://test.pypi.org/simple/ crowdstrike-falconpy --upgrade