v0.4.3 Update - Sample_Uploads service class, Fixes, Documentation

.github/workflows/linting.yml

@@ -39,8 +39,9 @@ jobs:
         DEBUG_API_ID: ${{ secrets.DEBUG_API_ID }}
         DEBUG_API_SECRET: ${{ secrets.DEBUG_API_SECRET }}
       run: |
-        coverage run --source src -m pytest -s
+        coverage run --source=src --omit=src/falconpy/debug.py -m pytest -s
         coverage report
-    - name: Analyze with Bandit
+    - name: Analyze with bandit
       run: |
         bandit -r src
+

README.md

@@ -1,16 +1,25 @@
-![PyPI - Status](https://img.shields.io/pypi/status/crowdstrike-falconpy) ![PyPI - Implementation](https://img.shields.io/pypi/implementation/crowdstrike-falconpy) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/crowdstrike-falconpy) ![PyPI - Wheel](https://img.shields.io/pypi/wheel/crowdstrike-falconpy)<br/>
-![PyPI](https://img.shields.io/pypi/v/crowdstrike-falconpy) ![PyPI - Downloads](https://img.shields.io/pypi/dm/crowdstrike-falconpy) ![CI Tests](https://github.com/CrowdStrike/falconpy/workflows/Python%20package/badge.svg) ![CI Test Coverage](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/tests/coverage.svg)<br/>
-![Twitter URL](https://img.shields.io/twitter/url?label=Follow%20%40CrowdStrike&style=social&url=https%3A%2F%2Ftwitter.com%2FCrowdStrike)<br/>
-
-# FalconPy
+![CrowdStrike Falcon](./docs/asset/cs-logo.png) [![Twitter URL](https://img.shields.io/twitter/url?label=Follow%20%40CrowdStrike&style=social&url=https%3A%2F%2Ftwitter.com%2FCrowdStrike)](https://twitter.com/CrowdStrike)<br/>
+
+# FalconPy - The CrowdStrike Falcon SDK for Python 3
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/crowdstrike-falconpy)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/crowdstrike-falconpy)
+![CI lines tested](https://img.shields.io/tokei/lines/github/CrowdStrike/falconpy)
+[![CodeQL](https://github.com/CrowdStrike/falconpy/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/CrowdStrike/falconpy/actions/workflows/codeql-analysis.yml)
+![CI Test Coverage](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/tests/coverage.svg)
+![Maintained](https://img.shields.io/maintenance/yes/2021)<br/>
 The FalconPy SDK contains a collection of Python classes that abstract CrowdStrike Falcon OAuth2 API interaction, removing duplicative code and allowing developers to focus on just the logic of their solution requirements.
 
 This SDK provides two distinct methods for interacting with CrowdStrike's Falcon OAuth2 APIs:
   * ***Service classes***, representing a single service collection, with methods defined for every available operation.
   * ***The Uber class***, which provides a single harness for interacting with the entire API, covering every available operation within every service collection.
 
-## Quick Install / Uninstall
-Stable releases of FalconPy are available on PyPI:
+## Installation & Removal
+![PyPI - Status](https://img.shields.io/pypi/status/crowdstrike-falconpy)
+![PyPI](https://img.shields.io/pypi/v/crowdstrike-falconpy)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/crowdstrike-falconpy) 
+![PyPI - Downloads](https://img.shields.io/pypi/dm/crowdstrike-falconpy)
+![CI Tests](https://github.com/CrowdStrike/falconpy/workflows/Python%20package/badge.svg)<br/>
+Stable releases of FalconPy are available on the Python Package Index:
 ```shell
 $ python3 -m pip install crowdstrike-falconpy
 ```
@@ -28,35 +37,36 @@ $ python3 -m pip uninstall crowdstrike-falconpy
 # Service classes
 | OAuth2-Based API<br>*(CrowdStrike documentation, requires CrowdStrike customer login)* | Code Location |
 |:-|:-|
-| CrowdStrike Device Control API | [./src/falconpy/device_control_policies.py](./src/falconpy/device_control_policies.py) |
-| CrowdStrike Falcon Sandbox API | [./src/falconpy/falconx_sandbox.py](./src/falconpy/falconx_sandbox.py) |
-| CrowdStrike Sensor Policy Management API | [./src/falconpy/sensor_update_policy.py](./src/falconpy/sensor_update_policy.py) |
-| [CrowdStrike Custom Indicators of Compromose (IOCs) APIs](https://falcon.crowdstrike.com/support/documentation/88/custom-ioc-apis) | [./src/falconpy/iocs.py](./src/falconpy/iocs.py) |
-| [CrowdStrike Detections APIs](https://falcon.crowdstrike.com/support/documentation/85/detection-and-prevention-policies-apis) | [./src/falconpy/detects.py](./src/falconpy/detects.py) |
-| [CrowdStrike Event Streams API](https://falcon.crowdstrike.com/support/documentation/89/event-streams-apis)| [./src/falconpy/event_streams.py](./src/falconpy/event_streams.py) |
-| [CrowdStrike Falcon Horizon APIs](https://falcon.crowdstrike.com/support/documentation/137/falcon-horizon-apis) | [./src/falconpy/cspm_registration.py](./src/falconpy/cspm_registration.py) |
+| CrowdStrike Device Control API | [device_control_policies.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/device_control_policies.py) |
+| CrowdStrike Falcon Sandbox API | [falconx_sandbox.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/falconx_sandbox.py) |
+| CrowdStrike Sensor Policy Management API | [sensor_update_policy.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/sensor_update_policy.py) |
+| [CrowdStrike Custom Indicators of Compromose (IOCs) APIs](https://falcon.crowdstrike.com/support/documentation/88/custom-ioc-apis) | [iocs.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/iocs.py) |
+| [CrowdStrike Detections APIs](https://falcon.crowdstrike.com/support/documentation/85/detection-and-prevention-policies-apis) | [detects.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/detects.py) |
+| [CrowdStrike Event Streams API](https://falcon.crowdstrike.com/support/documentation/89/event-streams-apis)| [event_streams.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/event_streams.py) |
+| [CrowdStrike Falcon Horizon APIs](https://falcon.crowdstrike.com/support/documentation/137/falcon-horizon-apis) | [cspm_registration.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/cspm_registration.py) |
 | [CrowdStrike Falcon X APIs](https://falcon.crowdstrike.com/support/documentation/92/falcon-x-apis) | *Coming Soon* |
-| [CrowdStrike Firewall Management API](https://falcon.crowdstrike.com/support/documentation/107/falcon-firewall-management-apis) | [./src/falconpy/firewall_management.py](./src/falconpy/firewall_management.py) |
-| [CrowdStrike Firewall Policy Management](https://falcon.crowdstrike.com/support/documentation/107/falcon-firewall-management-apis) | [./src/falconpy/firewall_policies.py](./src/falconpy/firewall_policies.py) |
-| [CrowdStrike Host Groups API](https://falcon.crowdstrike.com/support/documentation/84/host-and-host-group-management-apis) | [./src/falconpy/host_group.py](./src/falconpy/host_group.py) |
-| [CrowdStrike Hosts API](https://falcon.crowdstrike.com/support/documentation/84/host-and-host-group-management-apis) | [./src/falconpy/hosts.py](./src/falconpy/hosts.py) |
-| [CrowdStrike Incident and Detection Monitoring APIs](https://falcon.crowdstrike.com/support/documentation/86/detections-monitoring-apis) | [./src/falconpy/incidents.py](./src/falconpy/incidents.py) |
+| [CrowdStrike Firewall Management API](https://falcon.crowdstrike.com/support/documentation/107/falcon-firewall-management-apis) | [firewall_management.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/firewall_management.py) |
+| [CrowdStrike Firewall Policy Management](https://falcon.crowdstrike.com/support/documentation/107/falcon-firewall-management-apis) | [firewall_policies.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/firewall_policies.py) |
+| [CrowdStrike Host Groups API](https://falcon.crowdstrike.com/support/documentation/84/host-and-host-group-management-apis) | [host_group.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/host_group.py) |
+| [CrowdStrike Hosts API](https://falcon.crowdstrike.com/support/documentation/84/host-and-host-group-management-apis) | [hosts.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/hosts.py) |
+| [CrowdStrike Incident and Detection Monitoring APIs](https://falcon.crowdstrike.com/support/documentation/86/detections-monitoring-apis) | [incidents.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/incidents.py) |
 | [CrowdStrike Installation Token APIs](https://falcon.crowdstrike.com/support/documentation/120/Installation-token-APIs) | *Coming Soon* | 
-| [CrowdStrike Intel API](https://falcon.crowdstrike.com/support/documentation/72/intel-apis) | [./src/falconpy/intel.py](./src/falconpy/intel.py) | 
+| [CrowdStrike Intel API](https://falcon.crowdstrike.com/support/documentation/72/intel-apis) | [intel.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/intel.py) | 
 | [CrowdStrike MalQuery API](https://falcon.crowdstrike.com/support/documentation/113/malquery-apis) | *Coming Soon* |
-| [CrowdStrike OAuth2 Auth Token APIs](https://falcon.crowdstrike.com/support/documentation/93/oauth2-auth-token-apis) | [./src/falconpy/oauth2.py](./src/falconpy/oauth2.py) |
-| [CrowdStrike Prevention Policy APIs](https://falcon.crowdstrike.com/support/documentation/85/detection-and-prevention-policies-apis) | [./src/falconpy/prevention_policy.py](./src/falconpy/prevention_policy.py) |
-| [CrowdStrike Real Time Response (RTR) APIs](https://falcon.crowdstrike.com/support/documentation/90/real-time-response-apis) | [./src/falconpy/real_time_response.py](./src/falconpy/real_time_response.py) |
-| [CrowdStrike Realtime Response (RTR) Administration API](https://falcon.crowdstrike.com/support/documentation/90/real-time-response-apis) | [./src/falconpy/real_time_response_admin.py](./src/falconpy/real_time_response_admin.py) |
+| [CrowdStrike OAuth2 Auth Token APIs](https://falcon.crowdstrike.com/support/documentation/93/oauth2-auth-token-apis) | [oauth2.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/oauth2.py) |
+| [CrowdStrike Prevention Policy APIs](https://falcon.crowdstrike.com/support/documentation/85/detection-and-prevention-policies-apis) | [prevention_policy.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/prevention_policy.py) |
+| [CrowdStrike Real Time Response (RTR) APIs](https://falcon.crowdstrike.com/support/documentation/90/real-time-response-apis) | [real_time_response.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/real_time_response.py) |
+| [CrowdStrike Realtime Response (RTR) Administration API](https://falcon.crowdstrike.com/support/documentation/90/real-time-response-apis) | [real_time_response_admin.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/real_time_response_admin.py) |
+| CrowdStrike Sample Uploads API | [sample_uploads.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/sample_uploads.py) |
 | [CrowdStrike Sensor Download APIs](https://falcon.crowdstrike.com/support/documentation/109/sensor-download-apis) | *Coming Soon* |
-| [CrowdStrike Spotlight APIs](https://falcon.crowdstrike.com/support/documentation/98/spotlight-apis) | [./src/falconpy/spotlight_vulnerabilities.py](./src/falconpy/spotlight_vulnerabilities.py) |
-| [CrowdStrike User and Roles API](https://falcon.crowdstrike.com/support/documentation/87/users-and-roles-apis) | [./src/falconpy/user_management.py](./src/falconpy/user_management.py) | 
-| [Falcon Discover for Cloud and Containers - AWS Accounts APIs](https://falcon.crowdstrike.com/support/documentation/91/discover-for-aws-apis) | [./src/falconpy/cloud_connect_aws.py](./src/falconpy/cloud_connect_aws.py) |
+| [CrowdStrike Spotlight APIs](https://falcon.crowdstrike.com/support/documentation/98/spotlight-apis) | [spotlight_vulnerabilities.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/spotlight_vulnerabilities.py) |
+| [CrowdStrike User and Roles API](https://falcon.crowdstrike.com/support/documentation/87/users-and-roles-apis) | [user_management.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/user_management.py) | 
+| [Falcon Discover for Cloud and Containers - AWS Accounts APIs](https://falcon.crowdstrike.com/support/documentation/91/discover-for-aws-apis) | [cloud_connect_aws.py](https://github.com/CrowdStrike/falconpy/blob/main/src/falconpy/cloud_connect_aws.py) |
 | [Falcon Discover for Cloud and Containers - Azure Subscriptions APIs](https://falcon.crowdstrike.com/support/documentation/118/falcon-discover-for-cloud-and-containers-azure-subscription-apis) | *Coming Soon* |
 | [Falcon Discover for Cloud and Containers - GCP Projects APIs](https://falcon.crowdstrike.com/support/documentation/117/falcon-discover-for-cloud-and-containers-gcp-projects-apis) | *Coming Soon* |
 
 ## Uber class
-+ [./src/falconpy/api_complete.py](./src/falconpy/api_complete.py) - Provides an interface to all CrowdStrike APIs with a single handler.
++ [api_complete.py](./src/falconpy/api_complete.py) - Provides an interface to all CrowdStrike APIs with a single handler.
 
 # Contributing
 There are *many* ways you can contribute to the FalconPy project!
@@ -65,7 +75,9 @@ There are *many* ways you can contribute to the FalconPy project!
   * ***Fix a bug or implement a new feature***. Check out our [open issues on GitHub](https://github.com/CrowdStrike/falconpy/issues) for inspiration.
   * ***Review pull requests*** by going through the queue of [open pull requests on GitHub](https://github.com/CrowdStrike/falconpy/pulls) and giving feedback to the authors
 
-Open to do something else but not sure where to start? Try [opening an issue](https://github.com/CrowdStrike/falconpy/issues/new) and introducing yourself and your interests. We look forward to chatting with you!
+  > Review [CONTRIBUTING.md](CONTRIBUTING.md) for more details regarding contributing to the FalconPy project.
+
+Open to do something else but not sure where to start? Try [opening an issue](https://github.com/CrowdStrike/falconpy/issues/new), or posting a topic in our [discussion board](https://github.com/CrowdStrike/falconpy/discussions), to introduce yourself and your interests. We look forward to chatting with you!
 
 # Support & Community Forums
 FalconPy is an open source project, not a formal CrowdStrike product, to assist developers implement CrowdStrike's APIs within their applications. As such it carries no formal support, express or implied. 
@@ -90,7 +102,7 @@ See the wiki for extended documentation: [https://github.com/CrowdStrike/falconp
 *Coming soon*.
 
 ## Conference Presentations
-*Coming soon*.
+[![API Office Hour 03.23.21](docs/asset/api_office_hour_preso_thumbnail.png)](docs/asset/api_office_hour_032321.pptx)
 
 ## Blogs/Articles/Prose
 *Coming soon*.

requirements-dev.txt

@@ -7,12 +7,12 @@
 # These packages are not necessary in order to 
 # communicate with the CrowdStrike Falcon OAuth2 API.
 #
-# These packages are only required if you intend
-# on using FalconShell, or are a contributor and are
-# developing unit tests for the project.
+# These packages are only required if you are a contributor,
+# or wish to use FalconDebug.
 #
+bandit>=1.7.0       # via -r requirements-dev.in
 coverage>=5.5       # via -r requirements-dev.in
 flake8>=3.9.0       # via -r requirements-dev.in
-ipython>=7.21.0     # via -r requirements-dev.in
 pytest-cov>=2.11.1  # via -r requirements-dev.in
 pytest>=6.2.2       # via -r requirements-dev.in
+ipython>=7.21.0     # via -r requirements-dev.in

requirements.txt

@@ -6,3 +6,4 @@
 #
 requests==2.25.1          # via -r requirements.in
 urllib3==1.26.4           # via -r requirements.in, requests
+

setup.py

@@ -48,6 +48,11 @@
 with open("README.md", "r") as fh:
     long_description = fh.read()
 
+# Remove GitHub's emoji
+emojis = [":speech_balloon: ", ":bulb: ", ":pray: ", ":raised_hands: ", " :fire:", ":fire: "]
+for emoji in emojis:
+    long_description = long_description.replace(emoji, "")
+
 setup(
     name=_title,
     version=_version,
@@ -66,6 +71,15 @@
         "requests",
         "urllib3"
     ],
+    extras_require={
+        "dev": [
+            "flake8",
+            "coverage",
+            "pytest-cov",
+            "pytest",
+            "bandit",
+        ],
+    },
     classifiers=[
         "Development Status :: 4 - Beta",
         "Intended Audience :: Developers",

src/falconpy/README.MD → src/falconpy/README.md

@@ -1,6 +1,8 @@
-# falconpy - Falcon Complete API Service classes
-These classes are part of the falconpy project, a python interface handler to the CrowdStrike Falcon Complete OAuth2 API.
+![CrowdStrike Falcon](../../docs/asset/cs-logo.png)
+# FalconPy - The CrowdStrike Falcon SDK for Python 3
+This folder contains the FalconPy project, a Python 3 interface handler for the CrowdStrike Falcon OAuth2 API.
 
+## Service Classes
 ### Currently implemented:
 + `cloud_connect_aws.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/cloud-connect-aws
 + `cspm-registration.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/cspm-registration
@@ -19,19 +21,22 @@ These classes are part of the falconpy project, a python interface handler to th
 + `prevention_policy.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/prevention-policies
 + `real_time_response_admin.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/real-time-response-admin
 + `real_time_response.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/real-time-response
++ `sample_uploads.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sample-uploads
 + `sensor_update_policy.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sensor-update-policies
 + `spotlight_vulnerabilities.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/spotlight-vulnerabilities
 + `user_management.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/user-management
 
 ### Planned
-+ `d4c-registration.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/d4c-registration
-+ `installation-tokens.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/installation-tokens
-+ `custom-ioa.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/custom-ioa
++ `d4c_registration.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/d4c-registration
++ `installation_tokens.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/installation-tokens
++ `custom_ioa.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/custom-ioa
 + `malquery.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/malquery
-+ `ioa-exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/ioa-exclusions
-+ `ml-exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/ml-exclusions
-+ `sensor-visibility-exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sensor-visibility-exclusions
-+ `sample-uploads.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sample-uploads
-+ `quick-scan.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/quick-scan
-+ `sensor-download.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sensor-download
++ `ioa_exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/ioa-exclusions
++ `ml_exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/ml-exclusions
++ `sensor_visibility_exclusions.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sensor-visibility-exclusions
++ `quick_scan.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/quick-scan
++ `sensor_download.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html#/sensor-download
 
+## The Uber Class
+### A single class to interface with the entire API
++ `api_complete.py` https://assets.falcon.crowdstrike.com/support/api/swagger.html

src/falconpy/_version.py

@@ -36,7 +36,7 @@
 
 For more information, please refer to <https://unlicense.org>
 """
-_version = '0.4.2'
+_version = '0.4.3'
 _maintainer = 'Joshua Hiller'
 _author = 'CrowdStrike'
 _author_email = '[email protected]'