Sample Updates

.github/wordlist.txt

@@ -1380,4 +1380,12 @@ Destom
 ValueError
 QueryCasesIdsByFilter
 SDKDEMO
-
+kube
+KPA
+argparse
+colorama
+Oke
+Okumo
+Moomaw
+Esha
+Kumar

AUTHORS.md

@@ -97,6 +97,9 @@ This has been a critical element in the development of the FalconPy project.
 + Nick, `nickforsythbarr`
 + `nesies`
 + `David-M-Berry`
++ Oke Okumo, `@okewoma`
++ Alexander Moomaw, `@alhumaw`
++ Esha Kumar, `@exk200006` 
 
 
 ## Sponsors

samples/authentication/README.md

@@ -7,7 +7,8 @@ The examples in this folder focus on authentication to CrowdStrike's APIs.
 
 - [Azure Key Vault Authentication](#azure-key-vault-authentication) - CrowdStrike API authentication leveraging Azure Key Vault for credential storage.
 - [AES Authentication](#aes-authentication) - Leverage AES/CBC to encrypt credentials for use with authentication to the CrowdStrike API.
-- [AES File Crypt](#aes-file-crypt) - Encrypt arbitrary files with AES/CBC.
+- [AES File Crypt](#aes-file-crypt) - Encrypt arbitrary files with AES/CBC
+- [AWS Parameter Store](#aws-parameter-store) - CrowdStrike API authentication leveraging AWS Parameter Store for credential storage
 - [Token Authentication](#token-authentication) - Token Authentication is the original solution for authenticating to a Service Class, and is still fully supported. This example demonstrates how to use Token Authentication to interact with multiple Service Classes.
 
 ## Azure Key Vault Authentication
@@ -458,6 +459,64 @@ file arguments:
 Source code for this example can be found [here](aes_file_crypt.py).
 
 ---
+## AWS Parameter store
+This application demonstrates storing CrowdStrike API credentials within the AWS Parameter Store service, and retrieving them to access the CrowdStrike API.
+
+### Running the program
+In order to run this demonstration, you will need access to CrowdStrike API keys. You will also need to set your specific AWS location
+
+#### Command line arguments
+This program accepts the following command line arguments.
+
+| Argument | Long Argument | Description |
+| :-- | :-- | :-- |
+| `-h` | `--help` | Display command line help and exit |
+|  `-k` _CLIENT_ID_PARAMETER_ | `--client_id_parameter` _CLIENT_ID_PARAMETER_ | Name of the Key Vault Secrets parameter storing your API client ID |
+|  `-s` _CLIENT_SECRET_PARAMETER_ | `--client_secret_parameter` _CLIENT_SECRET_PARAMETER_ | Name of the Key Vault Secrets parameter storing your API client secret |
+|  `-d`  | `--debug`| Enables debugging functionality |
+
+#### Basic usage
+
+##### Use this command to test out the sample.
+
+```shell
+python3 aws_parameter_store.py -k FALCON_CLIENT_ID -s FALCON_CLIENT_SECRET
+```
+##### Use this command to activate debugging.
+
+```shell
+python3 aws_parameter_store.py -k FALCON_CLIENT_ID -s FALCON_CLIENT_SECRET -d
+```
+#### Command-line help
+Command-line help is available via the `-h` argument.
+
+```shell
+usage: aws_parameter_store.py [-h] [-k] CLIENT_ID [-s] CLIENT_SECRET [-d] DEGUG
+
+
+  ___   ____    __    ____   _______.
+    /   \  \   \  /  \  /   /  /       |
+   /  ^  \  \   \/    \/   /  |   (----`
+  /  /_\  \  \            /    \   \
+ /  _____  \  \    /\    / .----)   |
+/__/     \__\  \__/  \__/  |_______/
+
+        ____                                  __               _____ __
+       / __ \____ __________ _____ ___  ___  / /____  _____   / ___// /_____  ________
+      / /_/ / __ `/ ___/ __ `/ __ `__ \/ _ \/ __/ _ \/ ___/   \__ \/ __/ __ \/ ___/ _ \
+     / ____/ /_/ / /  / /_/ / / / / / /  __/ /_/  __/ /      ___/ / /_/ /_/ / /  /  __/
+    /_/    \__,_/_/   \__,_/_/ /_/ /_/\___/\__/\___/_/      /____/\__/\____/_/   \___/
+
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d, --debug           enables degugging 
+
+required arguments:
+  -k CLIENT_ID, --client_id_parameter CLIENT_ID    
+  -s CLIENT_SECRET, --client_secret_parameter CLIENT_SECRET
+```
+
 
 ## Token Authentication
 [Token authentication](https://www.falconpy.io/Usage/Authenticating-to-the-API.html#legacy-authentication) (also referred to as _legacy authentication_) is the process of authenticating to a FalconPy Service Class by providing a previously assigned bearer token directly to the [`auth_token`](https://www.falconpy.io/Usage/Basic-Service-Class-usage.html#legacy-authentication) keyword when instantiating the Service Class. This is the original method of authentication provided by Service Classes, and while it is frequently eschewed in preference to [Direct](https://www.falconpy.io/Usage/Authenticating-to-the-API.html#direct-authentication) and [Object](https://www.falconpy.io/Usage/Authenticating-to-the-API.html#object-authentication) [Authentication](https://www.falconpy.io/Usage/Authenticating-to-the-API.html), there are multiple scenarios where it is still the best option for the situation.

samples/authentication/aws_parameter_store.py

@@ -34,6 +34,7 @@
 This application demonstrates storing CrowdStrike API credentials within the
 AWS Parameter Store service, and retrieving them to access the CrowdStrike API.
 """
+import logging
 from argparse import ArgumentParser, RawTextHelpFormatter, Namespace
 try:
     import boto3
@@ -64,8 +65,19 @@ def consume_arguments() -> Namespace:
                         default="FALCON_CLIENT_SECRET",
                         dest="client_secret_parameter"
                         )
+    parser.add_argument("-d", "--debug",
+                        help="Enable API debugging",
+                        action="store_true",
+                        default=False
+                        )
+
+    parsed = parser.parse_args()
+    if parsed.debug:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+    return parsed
 
-    return parser.parse_args()
 
 
 def get_parameter_store_params(cmd_line: Namespace):
@@ -101,9 +113,9 @@ def get_parameter_store_params(cmd_line: Namespace):
     return returned_client_id, returned_client_secret
 
 
-def perform_simple_demonstration(client_id: str, client_secret: str):
+def perform_simple_demonstration(client_id: str, client_secret: str, debug: bool):
     """Perform a simple API demonstration using the credentials retrieved."""
-    falcon = Hosts(client_id=client_id, client_secret=client_secret)
+    falcon = Hosts(client_id=client_id, client_secret=client_secret, debug=debug)
     # Retrieve 500 hosts and sort ascending by hostname
     aid_lookup = falcon.query_devices_by_filter_scroll(sort="hostname.asc", limit=500)
     if not aid_lookup["status_code"] == 200:
@@ -120,6 +132,9 @@ def perform_simple_demonstration(client_id: str, client_secret: str):
 
 
 if __name__ == "__main__":
-    # Consume our command line, retrieve our credentials from AWS parameter store
+    # Consume our command line arguments 
+    args = consume_arguments()
+    # retrieve our credentials from AWS parameter store
+    client_id, client_secret = get_parameter_store_params(args)
     # and then execute a simple API demonstration to prove functionality.
-    perform_simple_demonstration(*get_parameter_store_params(consume_arguments()))
+    perform_simple_demonstration(client_id, client_secret)

samples/authentication/requirements_aws_parameter_store.txt

@@ -0,0 +1,2 @@
+boto3
+crowdstrike-falconpy

samples/authentication/requirements_token_authentication_example.txt

@@ -0,0 +1,4 @@
+boto3
+click
+colorama
+crowdstrike-falconpy

samples/authentication/token_authentication_example.py

@@ -34,9 +34,11 @@
 
 This sample should run using any version of FalconPy and requires the colorama and click libraries.
 """
+import logging
 import os
 import click
 import colorama
+from argparse import ArgumentParser, RawTextHelpFormatter, Namespace 
 from falconpy import (
     CloudConnectAWS,
     Detects,
@@ -54,9 +56,27 @@
 BOLD = colorama.Style.BRIGHT
 ENDMARK = colorama.Style.RESET_ALL
 
-
+def consume_arguments() -> Namespace:
+    parser = ArgumentParser(description=__doc__, fromatter_class=RawTextHelpFormatter)
+    parser.add_argument("-d", "--debug",
+                        help="Enable API debugging",
+                        action="store_true",
+                        default=False
+                        )
+    parser.add_argument("-b", "--base-url",
+                        dest="base_url",
+                        help="CrowdStrike cloud region. (auto or usgov1, Default: auto)",
+                        required=False,
+                        default="usgov1"
+                        )
+    parsed = parser.parse_args()
+    if parsed.debug:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+    return parsed
 # ### BEGIN token simulation
-def get_token():
+def get_token(debug=False):
     """
     Generate a token to use for authentication.
 
@@ -95,7 +115,8 @@ def get_token():
                                             )
     auth = OAuth2(
         client_id=falcon_client_id,
-        client_secret=falcon_client_secret
+        client_secret=falcon_client_secret,
+        debug=debug 
         )
     # Generate a token
     auth.token()
@@ -176,6 +197,10 @@ def passed(svc_class: str):
 
 
 if __name__ == "__main__":
+    # Parse command-line arguments and retrieve debug mode setting
+    args = consume_arguments()
+    # Authenticate using Falcon API OAuth2 with debug mode enabled if specified
+    get_token(debug=args.debug)
     # Test each of these classes to confirm cross collection authentication for Service Classes
     classes_to_test = [CloudConnectAWS, Detects, Hosts, IOC, Incidents, Intel]
     # Grab a simulated token and execute the test series

samples/containers/README.md

@@ -0,0 +1,105 @@
+![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)
+
+# Container examples
+The examples in this folder focus on leveraging CrowdStrike's Container APIs to discover and manage your container assets.
+- [kube_map - Discover your Kubernetes Attack Surface](#Discover-your-Kubernetes-Attack-Surface)
+
+## Discover your Kubernetes Attack Surface
+Discovers Kubernetes assets that are monitored by the Falcon Sensor (clusters, nodes, pods, and containers).
+
+> [!IMPORTANT]
+> Installing the __Kubernetes Protection Agent (KPA)__ on your clusters will result in the most accurate information. 
+
+
+### Running the program
+In order to run this demonstration, you will need access to CrowdStrike API keys with the following scopes:
+| Service Collection | Scope |
+| :---- | :---- |
+| Kubernetes Protection | __READ__|
+
+### Execution syntax
+This example accepts the following input parameters.
+| Parameter | Purpose |
+| :--- | :--- |
+| `-d`, `--debug` | Enable API debugging. |
+| `-c`, `--cluster` | Display all clusters and the number of attached nodes. |
+| `-n`, `--node` | Display all nodes including the number of attached, active pods. |
+| `-nn`, `--node_name` | Displays pods connected to a specific node. |
+| `-t`, `--thread` | Enables asynchronous API calls for faster returns. |
+| `-k`, `--key` | Your CrowdStrike Falcon API Client ID |
+| `-s`, `--secret` | Your CrowdStrike Falcon API Client Secret |
+
+Displays the number of clusters, nodes, pods, and containers detected by the Falcon Sensor.
+```shell
+python3 kube_map.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET
+```
+
+Displays a table of cluster information.
+```shell
+python3 kube_map.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -c
+```
+
+Displays a table of node information.
+```shell
+python3 kube_map.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -n
+```
+
+Displays a table of pods based on it's parent node name using the optional threading feature.
+```shell
+python3 kube_map.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -nn "node_name" -t
+```
+
+Displays API debug logging.
+```shell
+python3 kube_map.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -d
+```
+
+#### Command-line help
+Command-line help is available using the `-h` or `--help` parameters.
+
+```shell
+% python3 kube_map.py -h
+usage: kube_map.py [-h] -k CLIENT_ID -s CLIENT_SECRET [-d] [-c] [-n] [-nn NODE_NAME] [-t]
+
+ _______                        __ _______ __        __ __
+|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
+|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
+|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
+|:  1   |                         |:  1   |
+|::.. . |                         |::.. . |           FalconPy
+`-------'                         `-------'
+
+         _  ___   _ ____  _____
+        | |/ / | | | __ )| ____|
+        | ' /| | | |  _ \|  _|
+        | . \| |_| | |_) | |___
+  __  __|_|\_\\___/|____/|_____|__ ____
+ |  \/  |  / \  |  _ \|  _ \| ____|  _ \
+ | |\/| | / _ \ | |_) | |_) |  _| | |_) |
+ | |  | |/ ___ \|  __/|  __/| |___|  _ <
+ |_|  |_/_/   \_\_|   |_|   |_____|_| \_\
+
+This sample utilizes the Kubernetes Protection service collection to map out
+your kubernetes assets. Kubernetes assets are found via the Falcon Sensor.
+
+Creation date: 06.26.23 - alhumaw
+
+options:
+  -h, --help            show this help message and exit
+  -d, --debug           Enable API debugging
+  -c, --cluster         Display clusters and it's nodes
+  -n, --node            Display nodes and it's pods
+  -nn NODE_NAME, --node_name NODE_NAME
+                        Display pods connected to a specific node
+  -t, --thread          Enables asynchronous API calls for faster returns
+
+required arguments:
+  -k CLIENT_ID, --client_id CLIENT_ID
+                        CrowdStrike API client ID
+  -s CLIENT_SECRET, --client_secret CLIENT_SECRET
+                        CrowdStrike API client secret
+```
+
+### Example source code
+The source code for this example can be found [here](kube_map.py).