Sensor Visibility Exclusions Audit documentation and linting

samples/sensor_visibility_exclusions/README.md

@@ -0,0 +1,121 @@
+![CrowdStrike Falcon](https://raw.githubusercontent.com/CrowdStrike/falconpy/main/docs/asset/cs-logo.png)
+[![CrowdStrike Subreddit](https://img.shields.io/badge/-r%2Fcrowdstrike-white?logo=reddit&labelColor=gray&link=https%3A%2F%2Freddit.com%2Fr%2Fcrowdstrike)](https://reddit.com/r/crowdstrike)
+
+# Sensor Visibility Exclusions samples
+The examples within this folder focus on leveraging CrowdStrike Falcon Sensor Visibility Exclusions collection.
+
+- [SVE Audit](#sve-audit)
+
+## SVE Audit
+This program will output a list of sensor visibility exclusions and their details for either the current CID or in a specific / each Child CID (Flight Control scenarios).
+This can be used for regular audits of sensor visibility exclusions across multiple CIDs.
+
+### Running the program
+In order to run this demonstration, you you will need access to CrowdStrike API keys with the following scopes:
+
+| Service Collection | Scope |
+| :---- | :---- |
+| ML Exclusions | __READ__ |
+| Flight Control | __READ__ |
+| Sensor Download | __READ__ |
+
+> [!NOTE]
+> This program can be executed using an API key that is not scoped for the Flight Control (MSSP) and Sensor Download service collections, but will be unable to lookup the current CID (Sensor Download) or access child CIDs (Flight Control).
+
+### Execution syntax
+This sample leverages simple command-line arguments to implement functionality.
+
+#### Basic usage
+Execute the default example. This will output results to a CSV file named `sensor_visibility_exclusions.txt`.
+
+```shell
+python3 sve_audit.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET
+```
+
+> This sample supports [Environment Authentication](https://falconpy.io/Usage/Authenticating-to-the-API.html#environment-authentication), meaning you can execute any of the command lines shown below without providing credentials if you have the values `FALCON_CLIENT_ID` and `FALCON_CLIENT_SECRET` defined in your environment.
+
+```shell
+python3 sve_audit.py
+```
+
+Change the output destination with the `-o` argument.
+
+```shell
+python3 sve_audit.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -o new_exclusions.txt
+```
+
+Enable MSSP mode and audit all Flight Control children with the `-m` argument.
+
+```shell
+python3 sve_audit.py -k $FALCON_CLIENT_ID_PARENT -s $FALCON_CLIENT_SECRET_PARENT -m
+```
+
+Enable MSSP mode and audit a specific Flight Control child with the `-c` argument.
+
+```shell
+python3 sve_audit.py -k $FALCON_CLIENT_ID_PARENT -s $FALCON_CLIENT_SECRET_PARENT -c CHILD_CID
+```
+
+> API debugging can be enabled using the `-d` argument.
+
+```shell
+python3 sve_audit.py -d
+```
+
+#### Command-line help
+Command-line help is available via the `-h` argument.
+
+```shell
+usage: sve_audit.py [-h] [-d] [-m] [-c CHILD] [-o OUTPUT_FILE] [-k CLIENT_ID] [-s CLIENT_SECRET]
+
+ _______                        __ _______ __        __ __
+|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
+|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
+|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
+|:  1   |                         |:  1   |
+|::.. . |                         |::.. . |           FalconPy
+`-------'                         `-------'
+
+   ▄▄▄▄▄   ▄███▄      ▄      ▄▄▄▄▄   ████▄ █▄▄▄▄
+  █     ▀▄ █▀   ▀      █    █     ▀▄ █   █ █  ▄▀
+▄  ▀▀▀▀▄   ██▄▄    ██   █ ▄  ▀▀▀▀▄   █   █ █▀▀▌
+ ▀▄▄▄▄▀    █▄   ▄▀ █ █  █  ▀▄▄▄▄▀    ▀████ █  █
+           ▀███▀   █  █ █                    █
+                   █   ██                   ▀
+
+    ▄   ▄█    ▄▄▄▄▄   ▄█ ███   ▄█ █    ▄█    ▄▄▄▄▀ ▀▄    ▄
+     █  ██   █     ▀▄ ██ █  █  ██ █    ██ ▀▀▀ █      █  █
+█     █ ██ ▄  ▀▀▀▀▄   ██ █ ▀ ▄ ██ █    ██     █       ▀█
+ █    █ ▐█  ▀▄▄▄▄▀    ▐█ █  ▄▀ ▐█ ███▄ ▐█    █        █
+  █  █   ▐             ▐ ███    ▐     ▀ ▐   ▀       ▄▀
+   █▐
+   ▐
+            ▄▄▄          █           ▀
+            █▄▄ ▀▄▀ █▀▀  █  █ █ █▀▀  █  █▀█ █▀█ █▀▀
+            █▄▄ ▄▀▄ █▄▄  █▄ █▄█ ▄▄█  █  █▄█ █ █ ▄▄█
+
+This script outputs the list of active sensor visibility exclusions
+and their details for either the current CID or for a specific / each
+Child CID (Flight Control scenarios). This can be useful for regular
+audits of sensor visibility exclusions across multiple CIDs.
+
+Developed by @Don-Swanson-Adobe
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d, --debug           Enable API debugging
+  -m, --mssp            List exclusions in all child CIDs (MSSP parents only)
+  -c CHILD, --child CHILD
+                        List exclusions in a specific child CID (MSSP parents only)
+  -o OUTPUT_FILE, --output_file OUTPUT_FILE
+                        File to output results to
+
+Required arguments:
+  -k CLIENT_ID, --client_id CLIENT_ID
+                        CrowdStrike Falcon API key
+  -s CLIENT_SECRET, --client_secret CLIENT_SECRET
+                        CrowdStrike Falcon API secret
+```
+
+### Example source code
+The source code for this example can be found [here](sve_audit.py).

samples/sensor_visibility_exclusions/sve_audit.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+ _______                        __ _______ __        __ __
+|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
+|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
+|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
+|:  1   |                         |:  1   |
+|::.. . |                         |::.. . |           FalconPy
+`-------'                         `-------'
+
+   ▄▄▄▄▄   ▄███▄      ▄      ▄▄▄▄▄   ████▄ █▄▄▄▄
+  █     ▀▄ █▀   ▀      █    █     ▀▄ █   █ █  ▄▀
+▄  ▀▀▀▀▄   ██▄▄    ██   █ ▄  ▀▀▀▀▄   █   █ █▀▀▌
+ ▀▄▄▄▄▀    █▄   ▄▀ █ █  █  ▀▄▄▄▄▀    ▀████ █  █
+           ▀███▀   █  █ █                    █
+                   █   ██                   ▀
+
+    ▄   ▄█    ▄▄▄▄▄   ▄█ ███   ▄█ █    ▄█    ▄▄▄▄▀ ▀▄    ▄
+     █  ██   █     ▀▄ ██ █  █  ██ █    ██ ▀▀▀ █      █  █
+█     █ ██ ▄  ▀▀▀▀▄   ██ █ ▀ ▄ ██ █    ██     █       ▀█
+ █    █ ▐█  ▀▄▄▄▄▀    ▐█ █  ▄▀ ▐█ ███▄ ▐█    █        █
+  █  █   ▐             ▐ ███    ▐     ▀ ▐   ▀       ▄▀
+   █▐
+   ▐
+            ▄▄▄          █           ▀
+            █▄▄ ▀▄▀ █▀▀  █  █ █ █▀▀  █  █▀█ █▀█ █▀▀
+            █▄▄ ▄▀▄ █▄▄  █▄ █▄█ ▄▄█  █  █▄█ █ █ ▄▄█
+
+This script outputs the list of active sensor visibility exclusions
+and their details for either the current CID or for a specific / each
+Child CID (Flight Control scenarios). This can be useful for regular
+audits of sensor visibility exclusions across multiple CIDs.
+
+Developed by @Don-Swanson-Adobe
+"""
+import os
+import logging
+from argparse import ArgumentParser, RawTextHelpFormatter, Namespace
+from falconpy import APIHarnessV2, APIError
+
+
+def consume_arguments() -> Namespace:
+    """Consume any provided command line arguments."""
+    parser = ArgumentParser(description=__doc__, formatter_class=RawTextHelpFormatter)
+    parser.add_argument("-d", "--debug",
+                        help="Enable API debugging",
+                        action="store_true",
+                        default=False
+                        )
+    parser.add_argument("-m", "--mssp",
+                        help="List exclusions in all child CIDs (MSSP parents only)",
+                        action="store_true",
+                        default=False
+                        )
+    parser.add_argument("-c", "--child",
+                        help="List exclusions in a specific child CID (MSSP parents only)",
+                        default=None
+                        )
+    parser.add_argument("-o", "--output_file",
+                        help="File to output results to",
+                        default="sensor_visibility_audit.txt"
+                        )
+    req = parser.add_argument_group("Required arguments")
+    req.add_argument("-k", "--client_id",
+                     help="CrowdStrike Falcon API key",
+                     default=os.getenv("FALCON_CLIENT_ID")
+                     )
+    req.add_argument("-s", "--client_secret",
+                     help="CrowdStrike Falcon API secret",
+                     default=os.getenv("FALCON_CLIENT_SECRET")
+                     )
+    parsed = parser.parse_args()
+    if not parsed.client_id or not parsed.client_secret:
+        parser.error("You must provide CrowdStrike API credentials using the '-k' and '-s' arguments.")
+
+    return parsed
+
+
+# Consume any command line arguments
+cmd_line = consume_arguments()
+
+# Activate debugging if requested
+if cmd_line.debug:
+    logging.basicConfig(level=logging.DEBUG)
+
+# Create our base authentication dictionary (parent / child)
+auth = {
+    "client_id": cmd_line.client_id,
+    "client_secret": cmd_line.client_secret,
+    "debug": cmd_line.debug,
+    "pythonic": True
+}
+local = APIHarnessV2(**auth)
+# If we are in MSSP mode, retrieve our child CID details
+if cmd_line.mssp:
+    try:
+        cids = local.command("getChildren", ids=local.command("queryChildren").data)
+    except APIError as api_erorr:
+        # Assume they do not have access to Flight Control
+        raise SystemExit("This API client does not have access to the Flight Control API scope.")
+    if not cids:
+        raise SystemExit("No child CIDs were found within this tenant.")
+elif cmd_line.child:
+    try:
+        cid_name = local.command("getChildren", ids=cmd_line.child)
+    except APIError as api_error:
+        # Throw an error if they provided us an invalid CID or do not have access to Flight Control
+        if api_error.code == 403:
+            raise SystemExit("This API client does not have access to the Flight Control API scope.")
+        elif api_error.code == 400:
+            raise SystemExit("Invalid child CID provided.")
+        else:
+            raise SystemExit(api_error.message)
+    if cid_name:
+        cids = [{"name": cid_name[0]["name"], "child_cid": cmd_line.child}]
+    else:
+        raise SystemExit("The provided child CID was not found within this tenant.")
+else:
+    # If not, we'll just run this in our current tenant
+    try:
+        cid_id = local.command("GetSensorInstallersCCIDByQuery").data[0][:-3].lower()
+    except APIError as api_error:
+        # They do not have access to the sensor downloads service collection with this key
+        cid_id = f"Sensor Download scope required  "
+    cids = [{"name": "My CrowdStrike tenant",
+            "child_cid": cid_id
+            }]
+
+# Open the output file using a context manager so it autocloses
+with open(cmd_line.output_file, 'a+') as file_object:
+    for cid in cids:
+        if cmd_line.mssp or cmd_line.child:
+            # Authenticate to the child if necessary
+            auth["member_cid"] = cid["child_cid"]
+        spot = 38 - len(cid["name"])
+        header = f"\n\n{'*¯'*20}*\n* "+cid["name"]
+        header = f"{header}{' '*spot}*\n* CID: "+cid["child_cid"]+f" *\n{'*¯'*20}*\n"
+        print(header)
+        file_object.write(header)
+        # Connect to the API using a context manager so we autologout
+        with APIHarnessV2(**auth) as falcon:
+            # Query for the list of SVEs in the CID, pull the details and display / log the results
+            response = falcon.command("querySensorVisibilityExclusionsV1")
+            if response:
+                sveresponse = falcon.command("getSensorVisibilityExclusionsV1", ids=response.data)
+                for detail in sveresponse.data:
+                    details = [
+                        "Sensor Visibility Exclusion: " + detail.get("value"),
+                        "Creator: " + detail.get("created_by"),
+                        "Created on: " + detail.get("created_on"),
+                        "Last Modified by: " + detail.get("modified_by"),
+                        "Last Modified on: " + detail.get("last_modified")
+                    ]
+                    print("\n".join(details))
+                    file_object.write("\n".join(details)+"\n")
+            else:
+                print("No exclusions found")
+                file_object.write("No exclusions found\n")