[DEPLOY] v0.8.0 - Uber class parameter abstraction, Minor docstring f…

…ixes (#407) * Bump version - 0.8.0 * Remove ids QS placeholder from endpoint module. * Remove deprecated methods, expand args_to_params * Implements QS parameter abstraction. Linting. * Remove unnecessary pylint directive * PEP-257 docstring formatting. * PEP-257 docstring formatting. * PEP-257 docstring formatting. * PEP-257 docstring formatting. * Add docstring lint workflow * PEP-257 docstring formatting. * Docstring validation helper script. * Adjust workflow config. * Update README.md * Update README.md * Create README.md * Create README.md * Friendlier syntax * Add coverage reporting to single unit test helper * Update comments * Fix typo * Unit test adjustment to cover new code paths * Add PEP-8 friendly app_id parameter * Update CHANGELOG.md * Comment formatting * Fixup: incorrect data type for body payload * Fixup: incorrect body payload datatype * Fixup: Missing rules topic param. Docstring typo. * Expanded unit testing to cover new code paths. * Update CHANGELOG.md * Update wordlist.txt
CrowdStrike · Nov 1, 2021 · 8875d09 · 8875d09
1 parent 445c6ce
commit 8875d09
Show file tree

Hide file tree

Showing 137 changed files with 1,215 additions and 962 deletions.
diff --git a/.github/wordlist.txt b/.github/wordlist.txt
@@ -409,6 +409,7 @@ platformsMixin
 powershell
 pre
 py
+pydocstyle
 pylint
 pytest
 queryCIDGroupMembers

diff --git a/.github/workflows/pydocstyle.yml b/.github/workflows/pydocstyle.yml
@@ -0,0 +1,33 @@
+name: Check Docstrings
+on:
+  push:
+    paths:
+      - '**.py'
+    branches:
+      - main
+      - 'ver_*'
+  pull_request:
+    paths:
+      - '**.py'
+    branches: 
+      - main
+      - 'ver_*'
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install pydocstyle
+        pip install -r requirements.txt
+    - name: Check package docstrings with pydocstyle
+      run: |
+        # Check docstring syntax
+        pydocstyle src/falconpy --count
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,26 @@
+# Version 0.8.0
+## Added features and functionality
++ Added: Parameter abstraction for the Uber Class.
+    * Provides: Query string parameter payload abstraction for calls made using the Uber class.
+    - `api_complete.py`
+    - `_util.py`
++ Added: PEP-8 friendly `app_id` keyword for the `appId` parameter used by methods within the EventStreams Service Class.
+    - `event_streams.py`
+
+## Issues resolved
++ Fixed: Aggregate payload datatype mismatches in Recon Service Class methods.
+    - `recon.py`
++ Fixed: Missing payload parameter in recon rule payload handler.
+    - `_payload/_recon.py`
++ Fixed: Minor formatting issues within docstrings in all package files.
+
+## Other
++ Added: Docstring syntax validation workflow leveraging pydocstyle.
++ Removed: Deprecated `calc_url_from_args` method
+    - `_util.py`
++ Removed: Deprecated `parse_id_list` method
+    - `_util.py`
+
 # Version 0.7.4
 ## Added features and functionality
 + Updated: Service Class Refactoring (Rev 4) 

diff --git a/src/falconpy/README.md b/src/falconpy/README.md
@@ -1,9 +1,11 @@
-![CrowdStrike Falcon](../../docs/asset/cs-logo.png)
+![CrowdStrike Falcon](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/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
+Each class defined below represents a single CrowdStrike Falcon API service collection, with methods defined
+for every single operation available within that service collection.
 | Source file | Swagger documentation |
 | :--- | :--- |
 | `cloud_connect_aws.py` | https://assets.falcon.crowdstrike.com/support/api/swagger.html#/cloud-connect-aws |
@@ -52,7 +54,9 @@ This folder contains the FalconPy project, a Python 3 interface handler for the
 
 ## The Uber Class
 #### A single class to interface with the entire API
-The Uber class is harness that leverages the operation IDs provided by swagger to interact with the entire API.
+The Uber class is a harness that leverages operation IDs to look up the necessary detail to interact with the entire API.
+You can also leverage the Uber Class to interact with operations not yet defined within the private endpoint submodule by
+making use of the `override` keyword.
 | Source file | Swagger documentation |
 | :--- | :--- |
 | `api_complete.py` | https://assets.falcon.crowdstrike.com/support/api/swagger.html |
diff --git a/src/falconpy/__init__.py b/src/falconpy/__init__.py
@@ -1,4 +1,4 @@
-"""The CrowdStrike Falcon OAuth2 API SDK
+"""The CrowdStrike Falcon OAuth2 API SDK.
 
  @@@@@@@  @@@@@@@    @@@@@@   @@@  @@@  @@@  @@@@@@@    @@@@@@   @@@@@@@  @@@@@@@   @@@  @@@  @@@  @@@@@@@@
 @@@@@@@@  @@@@@@@@  @@@@@@@@  @@@  @@@  @@@  @@@@@@@@  @@@@@@@   @@@@@@@  @@@@@@@@  @@@  @@@  @@@  @@@@@@@@

diff --git a/src/falconpy/_base_url.py b/src/falconpy/_base_url.py
@@ -1,4 +1,4 @@
-"""CrowdStrike API Base URL Enumerator
+"""CrowdStrike API Base URL Enumerator.
 
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
@@ -39,9 +39,13 @@
 
 
 class BaseURL(Enum):
-    """This enum enables developers to specify base URL by
+    """Base URL enumerator.
+
+    This enum enables developers to specify base URL by
     name instead of URL. Case insensitive. Passing a URL
-    with or without https:// is still supported."""
+    with or without https:// is still supported.
+    """
+
     US1 = "api.crowdstrike.com"
     US2 = "api.us-2.crowdstrike.com"
     EU1 = "api.eu-1.crowdstrike.com"

diff --git a/src/falconpy/_endpoint/README.md b/src/falconpy/_endpoint/README.md
@@ -0,0 +1,5 @@
+![CrowdStrike Falcon](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/docs/asset/cs-logo.png)
+# FalconPy - The CrowdStrike Falcon SDK for Python 3
+## Endpoint module
+This module contains a complete listing of all endpoints within the CrowdStrike Falcon API,
+as well as the necessary parameter definitions to interact with them.
diff --git a/src/falconpy/_endpoint/__init__.py b/src/falconpy/_endpoint/__init__.py
@@ -1,4 +1,4 @@
-"""The CrowdStrike Falcon OAuth2 API SDK endpoints module
+"""The CrowdStrike Falcon OAuth2 API SDK endpoints module.
 
  @@@@@@@  @@@@@@@    @@@@@@   @@@  @@@  @@@  @@@@@@@    @@@@@@   @@@@@@@  @@@@@@@   @@@  @@@  @@@  @@@@@@@@
 @@@@@@@@  @@@@@@@@  @@@@@@@@  @@@  @@@  @@@  @@@@@@@@  @@@@@@@   @@@@@@@  @@@@@@@@  @@@  @@@  @@@  @@@@@@@@

diff --git a/src/falconpy/_endpoint/_cloud_connect_aws.py b/src/falconpy/_endpoint/_cloud_connect_aws.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -9,8 +10,6 @@
 
 OAuth2 API - Customer SDK
 
-_endpoint._cloud_connect_aws - Internal API endpoint constant library
-
 This is free and unencumbered software released into the public domain.
 
 Anyone is free to copy, modify, publish, use, compile, sell, or
@@ -86,7 +85,7 @@
   [
     "GetAWSAccounts",
     "GET",
-    "/cloud-connect-aws/entities/accounts/v1?ids={}",
+    "/cloud-connect-aws/entities/accounts/v1",
     "Retrieve a set of AWS Accounts by specifying their IDs",
     "cloud_connect_aws",
     [
@@ -148,7 +147,7 @@
   [
     "DeleteAWSAccounts",
     "DELETE",
-    "/cloud-connect-aws/entities/accounts/v1?ids={}",
+    "/cloud-connect-aws/entities/accounts/v1",
     "Delete a set of AWS Accounts by specifying their IDs",
     "cloud_connect_aws",
     [
@@ -184,7 +183,7 @@
   [
     "VerifyAWSAccountAccess",
     "POST",
-    "/cloud-connect-aws/entities/verify-account-access/v1?ids={}",
+    "/cloud-connect-aws/entities/verify-account-access/v1",
     "Performs an Access Verification check on the specified AWS Account IDs",
     "cloud_connect_aws",
     [

diff --git a/src/falconpy/_endpoint/_cspm_registration.py b/src/falconpy/_endpoint/_cspm_registration.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -9,8 +10,6 @@
 
 OAuth2 API - Customer SDK
 
-_endpoint._cspm_registration - Internal API endpoint constant library
-
 This is free and unencumbered software released into the public domain.
 
 Anyone is free to copy, modify, publish, use, compile, sell, or
@@ -41,7 +40,7 @@
   [
     "GetCSPMAwsAccount",
     "GET",
-    "/cloud-connect-cspm-aws/entities/account/v1?ids={}",
+    "/cloud-connect-cspm-aws/entities/account/v1",
     "Returns information about the current status of an AWS account.",
     "cspm_registration",
     [
@@ -141,7 +140,7 @@
   [
     "DeleteCSPMAwsAccount",
     "DELETE",
-    "/cloud-connect-cspm-aws/entities/account/v1?ids={}",
+    "/cloud-connect-cspm-aws/entities/account/v1",
     "Deletes an existing AWS account or organization in our system.",
     "cspm_registration",
     [
@@ -190,7 +189,7 @@
   [
     "GetCSPMAzureAccount",
     "GET",
-    "/cloud-connect-cspm-azure/entities/account/v1?ids={}",
+    "/cloud-connect-cspm-azure/entities/account/v1",
     "Return information about Azure account registration",
     "cspm_registration",
     [
@@ -259,7 +258,7 @@
   [
     "DeleteCSPMAzureAccount",
     "DELETE",
-    "/cloud-connect-cspm-azure/entities/account/v1?ids={}",
+    "/cloud-connect-cspm-azure/entities/account/v1",
     "Deletes an Azure subscription from the system.",
     "cspm_registration",
     [
@@ -496,7 +495,7 @@
   [
     "GetCSPMPolicy",
     "GET",
-    "/settings/entities/policy-details/v1?ids={}",
+    "/settings/entities/policy-details/v1",
     "Given a policy ID, returns detailed policy information.",
     "cspm_registration",
     [

diff --git a/src/falconpy/_endpoint/_custom_ioa.py b/src/falconpy/_endpoint/_custom_ioa.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -9,8 +10,6 @@
 
 OAuth2 API - Customer SDK
 
-_endpoint._custom_ioa - Internal API endpoint constant library
-
 This is free and unencumbered software released into the public domain.
 
 Anyone is free to copy, modify, publish, use, compile, sell, or
@@ -41,7 +40,7 @@
   [
     "get_patterns",
     "GET",
-    "/ioarules/entities/pattern-severities/v1?ids={}",
+    "/ioarules/entities/pattern-severities/v1",
     "Get pattern severities by ID.",
     "custom_ioa",
     [
@@ -61,7 +60,7 @@
   [
     "get_platformsMixin0",
     "GET",
-    "/ioarules/entities/platforms/v1?ids={}",
+    "/ioarules/entities/platforms/v1",
     "Get platforms by ID.",
     "custom_ioa",
     [
@@ -81,7 +80,7 @@
   [
     "get_rule_groupsMixin0",
     "GET",
-    "/ioarules/entities/rule-groups/v1?ids={}",
+    "/ioarules/entities/rule-groups/v1",
     "Get rule groups by ID.",
     "custom_ioa",
     [
@@ -129,7 +128,7 @@
   [
     "delete_rule_groupsMixin0",
     "DELETE",
-    "/ioarules/entities/rule-groups/v1?ids={}",
+    "/ioarules/entities/rule-groups/v1",
     "Delete rule groups by ID.",
     "custom_ioa",
     [
@@ -155,7 +154,7 @@
   [
     "get_rule_types",
     "GET",
-    "/ioarules/entities/rule-types/v1?ids={}",
+    "/ioarules/entities/rule-types/v1",
     "Get rule types by ID.",
     "custom_ioa",
     [
@@ -190,7 +189,7 @@
   [
     "get_rulesMixin0",
     "GET",
-    "/ioarules/entities/rules/v1?ids={}",
+    "/ioarules/entities/rules/v1",
     "Get rules by ID and optionally version in the following format: `ID[:version]`. "
     "The max number of IDs is constrained by URL size.",
     "custom_ioa",
@@ -239,7 +238,7 @@
   [
     "delete_rules",
     "DELETE",
-    "/ioarules/entities/rules/v1?ids={}",
+    "/ioarules/entities/rules/v1",
     "Delete rules from a rule group by ID.",
     "custom_ioa",
     [

diff --git a/src/falconpy/_endpoint/_d4c_registration.py b/src/falconpy/_endpoint/_d4c_registration.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -41,7 +42,7 @@
   [
     "GetCSPMAzureAccount",
     "GET",
-    "/cloud-connect-azure/entities/account/v1?ids={}",
+    "/cloud-connect-azure/entities/account/v1",
     "Return information about Azure account registration",
     "d4c_registration",
     [
@@ -126,7 +127,7 @@
   [
     "GetCSPMCGPAccount",
     "GET",
-    "/cloud-connect-gcp/entities/account/v1?ids={}",
+    "/cloud-connect-gcp/entities/account/v1",
     "Returns information about the current status of an GCP account.",
     "d4c_registration",
     [

diff --git a/src/falconpy/_endpoint/_detects.py b/src/falconpy/_endpoint/_detects.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -9,8 +10,6 @@
 
 OAuth2 API - Customer SDK
 
-_endpoint._detects - Internal API endpoint constant library
-
 This is free and unencumbered software released into the public domain.
 
 Anyone is free to copy, modify, publish, use, compile, sell, or

diff --git a/src/falconpy/_endpoint/_device_control_policies.py b/src/falconpy/_endpoint/_device_control_policies.py
@@ -1,4 +1,5 @@
-"""
+"""Internal API endpoint constant library.
+
  _______                        __ _______ __        __ __
 |   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
 |.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
@@ -9,8 +10,6 @@
 
 OAuth2 API - Customer SDK
 
-_endpoint._device_control_policies - Internal API endpoint constant library
-
 This is free and unencumbered software released into the public domain.
 
 Anyone is free to copy, modify, publish, use, compile, sell, or
@@ -182,7 +181,7 @@
   [
     "getDeviceControlPolicies",
     "GET",
-    "/policy/entities/device-control/v1?ids={}",
+    "/policy/entities/device-control/v1",
     "Retrieve a set of Device Control Policies by specifying their IDs",
     "device_control_policies",
     [
@@ -232,7 +231,7 @@
   [
     "deleteDeviceControlPolicies",
     "DELETE",
-    "/policy/entities/device-control/v1?ids={}",
+    "/policy/entities/device-control/v1",
     "Delete a set of Device Control Policies by specifying their IDs",
     "device_control_policies",
     [
-Original file line number
+Diff line change
@@ Expand Up / @@ -409,6 +409,7 @@ platformsMixin @@
     powershell
     pre
     py
+    pydocstyle
     pylint
     pytest
     queryCIDGroupMembers
@@ Expand Down @@