authentication
Authentication examples
The examples in this folder focus on authentication to CrowdStrike's APIs.
Azure Key Vault Authentication - CrowdStrike API authentication leveraging Azure Key Vault for credential storage.
AES Authentication - Leverage AES/CBC to encrypt credentials for use with authentication to the CrowdStrike API.
AES File Crypt - Encrypt arbitrary files with AES/CBC
AWS Parameter Store - CrowdStrike API authentication leveraging AWS Parameter Store for credential storage
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
This application demonstrates storing CrowdStrike API credentials within the Azure Key Vault 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 with the following scopes:
Hosts
READ
You will also need to ensure you have the following:
An Azure Key Vault
https://docs.microsoft.com/azure/key-vault/quick-create-cli❗ Make note of the Vault URI ❗ You will use this as a command line argument.
Secrets created for your Falcon Client ID and Client Secret
azure-keyvault-secretsandazure-identitylibrariespip install azure-keyvault-secrets azure-identitySet up your environment to use azure-identity's DefaultAzureCredential.
For more information about how to configure the DefaultAzureCredential, refer to https://aka.ms/azsdk/python/identity/docs#azure.identity.DefaultAzureCredential
Command line arguments
This program accepts the following command line arguments.
-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
-u VAULT_URI
--vault_uri VAULT_URI
URI of the Azure Key Vault containing the API credentials
Basic usage
You must provide the Vault URI (-u) in order for this application to execute.
If you choose to omit the Client ID parameter (
-k) and Client Secret parameter (-s), the default valuesfalcon-client-idandfalcon-client-secretwill be used.
Example
Perform a simple API demonstration using the credentials retrieved to list hosts by AID.
python3 azure_key_vault.py -u https://example-kv-name.vault.azure.net/Example result
Client API credentials successfully retrieved from Azure Key Vault.
host1 [a18sdfasdfasdfasafdf7cac44deb8d1]
host2 [asdfasdfuiuiwjkjlhxhjwdfkljh3891]
host3 [jlk2j3klnf289jflskjf02jfoi2j0jj3]
Demonstration completed.Command-line help
Command-line help is available via the -h argument.
usage: azure_key_vault.py [-h] [-k CLIENT_ID_PARAMETER] [-s CLIENT_SECRET_PARAMETER] -u VAULT_URI
CrowdStrike API authentication leveraging Azure Key Vault for credential storage.
_____
/ _ \ __________ _________ ____
/ /_\ \\___ / | \_ __ \_/ __ \
/ | \/ /| | /| | \/\ ___/
\____|__ /_____ \____/ |__| \___ >
\/ \/ \/
____ __. ____ ____ .__ __
| |/ _|____ ___.__. \ \ / /____ __ __| |_/ |_
| <_/ __ < | | \ Y /\__ \ | | \ |\ __\
| | \ ___/\___ | \ / / __ \| | / |_| |
|____|__ \___ > ____| \___/ (____ /____/|____/__|
This application demonstrates storing CrowdStrike API credentials within the
Azure Key Vault service, and retrieving them to access the CrowdStrike API.
options:
-h, --help show this help message 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
-u VAULT_URI, --vault_uri VAULT_URI
URI of the Azure Key Vault containing the API credentialsExample source code
Source code for this example can be found here.
AES Authentication
Leverage AES/CBC to encrypt credentials for use with authentication to the CrowdStrike API.
⚠️ Please note ⚠️
Cryptographic implementation samples should not be seen as recommendations on which encryption algorithms, modes or methods to use in your environment. These examples focus only on the technical aspects of cryptographic authentication scenarios using Python 3 and are provided here to assist developers with their implementation when interacting with the FalconPy SDK.
Running the program
In order to run this demonstration, you will need access to CrowdStrike API keys with the following scopes:
Hosts
READ
Execution syntax
This demonstration was developed to leverage easy to use command-line arguments.
Command line arguments
This program accepts the following command line arguments.
-h
--help
Display command line help and exit
-t TEXT
--text TEXT
Text to encrypt or decrypt
-k KEY
--key KEY
Key to use for encryption operations
-f KEYFILE
--keyfile KEYFILE
File to save your encrypted credentials to
-g
--generate
Generate a new keyfile using a key you specify
-d
--decrypt
Decrypt the value of TEXT using the key provided in KEY.
-e
--encrypt
Encrypt the value of TEXT using the key provided in KEY.
Basic usage
This program has no required command line arguments, and will prompt you to provide parameters expected for the operation requested. For every operation, your secret key (-k) and the location of your key file (-f) can be passed to the program using command line arguments.
Example
Running without any arguments will attempt to consume a credential file and run the demo. Providing a valid encrypted credential file and the correct secret key at this point will start the procedure. This test retrieves the hostname and AID for all hosts within the tenant.
python3 aes_authentication.pyExample result
❓ Please specify the file used to store your encrypted credentials: : credentials.enc
❓ Please provide your secret key :
✅ ID retrieval of 5223 hosts completed, requesting extended host details
⬇️ Downloading host detail from the CrowdStrike API for records 0 to 5000 of 5223 hosts, please wait...
⬇️ Downloading host detail from the CrowdStrike API for records 5000 to 5223 of 5223 hosts, please wait...
✅ Host detail retrieval complete, showing results.
🖥 hostname-lcnhc [8a9337d325a84b4ea9b123456789abcd]
🖥 hostname-h6vgb [c9df0f123456789abcd4313585190107]
🖥 hostname-klz8t [cd5494123456789abcda3e22ba10841b]
🖥 hostname-f4brn [123456789abcda6e8f09ec0f96319154]
🖥 hostname-2zhvt [74b8c123456789abcda5ba60d6788f8e]
🖥 hostname-czqzd [123abcdf160b46e4927ff4ffd3be95be]Generating a new credential file
python3 aes_authentication.py -gExample result
❓ Please provide your CrowdStrike API Client ID :
❓ Please provide your CrowdStrike API Client Secret :
❓ Please specify the file to use for storing your encrypted credentials: : credentials.enc
❓ Please provide your secret key :Encrypting arbitrary text
This application can be used to encrypt arbitrary text. This operation does not interact with your credentials.
python3 aes_authentication.py -e -t "This is my test"Arbitrary encryption result
❓ Please provide your secret key :
🔐 Encrypted: qxbFiGLWpw26lygAqGGvM1Dwz569Ogemu/O+/QMYrxQ=Decrypting arbitrary ciphertext
This application can be used to decrypt ciphertext as long as you have the correct secret key. This operation does not interact with your credentials.
python3 aes_authentication.py -d -t "qxbFiGLWpw26lygAqGGvM1Dwz569Ogemu/O+/QMYrxQ="Ciphertext decryption result
❓ Please provide your secret key :
🔓 Decrypted: This is my testCommand-line help
Command-line help is available via the -h argument.
usage: aes_authentication.py [-h] [-t TEXT] [-k KEY] [-f KEYFILE] [-g] [-d | -e]
Simple AES encryption example leveraging pyCryptodome.
______ __ _______ __ __ __
| |.----.-----.--.--.--.--| | __| |_.----.|__| |--.-----.
| ---|| _| _ | | | | _ |__ | _| _|| | <| -__|
|______||__| |_____|________|_____|_______|____|__| |__|__|__|_____|
** ******** ********
**** /**///// **//////
**//** /** /**
** //** /******* /*********
********** /**//// ////////**
/**//////** /** /** Simple encryption example #3
/** /** /******** ********
// // //////// ////////
This solution leverages pyCryptodome to AES encrypt API credentials
to a static file. This file is then consumed in follow up executions
of the tool to acquire the API credentials used to demonstrate that
connectivity to the CrowdStrike API is functional.
This tool can also be used to AES/CBC encrypt and decrypt regular text.
REQUIRES
click https://click.palletsprojects.com/en/8.1.x/
crowdstrike-falconpy https://github.com/CrowdStrike/falconpy
pycryptodomex https://snyk.io/advisor/python/pycryptodome
RUNNING THE API CONNECTIVITY DEMONSTRATION
Step 1) Generate an encrypted credential file using the `--g` (--generate) argument.
Step 2) Execute the program again, passing the name of your newly created
encrypted credential file using the `-f` argument.
Step 3) Provide the secret key you created in Step 1 when prompted.
Note: You can provide this on the command line with the `-k` argument.
Step 4) Review API results.
ENCRYPTING / DECRYPTING TEXT
These operations do not make use of your encrypted credential file.
Step 1) Use the `-e` (--encrypt) and `-d` (--decrypt) arguments to specify the
operation you wish to perform. If you do not provide a key with the `-k`
argument, you will be asked to provide one. If you do not provide plain
or cipher text using the `-t` argument, you will be ask to supply it.
Step 2) Review cryptographic results.
optional arguments:
-h, --help show this help message and exit
-t TEXT, --text TEXT Text to encrypt or decrypt
-k KEY, --key KEY Key to use for encryption operations
-f KEYFILE, --keyfile KEYFILE
File to save your encrypted credentials too
-g, --generate Generate a new keyfile using a key you specify
-d, --decrypt Decrypt the provided string
-e, --encrypt Encrypt the provided stringExample source code
Source code for this example can be found here.
AES File Crypt
This sample will encrypt and decrypt arbitrary files with AES/CBC using the secret key you provide.
Not exactly useful for most real world scenarios, but I had a lot of fun writing the credential encryption example above and I couldn't stop playing with the code...
Running the program
This application does not require access to the CrowdStrike API.
Execution syntax
This demonstration was developed to leverage easy to use command-line arguments.
Command line arguments
This program accepts the following command line arguments.
-h
--help
Display command line help and exit
-b BUFFER
--buffer BUFFER
Maximum buffer size before the contents in memory are written to the target file.
-c
--checksum
MD5 / SHA256 hash the source / target file and display the result.
-d
--decrypt
Decrypt from the SOURCE to the TARGET.
-e
--encrypt
Encrypt from the SOURCE to the TARGET.
-k KEY
--key KEY
Key to use for encryption and decryption operations.
-s SOURCE
--source SOURCE
Source file to encrypt or decrypt.
-t TARGET
--target TARGET
Target file for the resulting cryptographic operation.
Basic usage
You must provide a key (-k), a source (-s), a target (-t) and an operation (-d or -e) in order for this application to execute.
Example encryption
Encrypting a file can be performed by providing a key, a source and a target file. For our examples, we'll use the following plain text file, plain.txt.
plain.txt
This is my test plain text file.
I keep all my really important secrets in here.
Shhh!The following command line will encrypt the contents of plain.txt to cipher.txt using the key MySuperSecretKey.
python3 aes_file_crypt.py -k MySuperSecretKey -s plain.txt -t cipher.txt -eEncryption result
🔐 Completed encryption of plain.txt to cipher.txt.cipher.txt
09PRhOrhM+kAH5J1fYglRufJc5DKcn0xT8P6XbaS9k13IUGUUsqRA4d16Us6lxeAWHjDYMSSJnTcx8UYgfa2jeRbxkKJJUZlmK2CGk08fcOqIfge42ktIpJQ/aZbCF/QdzYChLBislrh0s+oRAtgUQ==Example decryption
Decrypting a file can be performed by providing a key, a source and a target file. For our examples, we'll use the cipher text file, cipher.txt we created above.
python3 aes_file_crypt.py -k MySuperSecretKey -s cipher.txt -t decrypted.txt -dEncryption result
🔓 Completed decryption of cipher.txt to decrypted.txt.decrypted.txt
This is my test plain text file.
I keep all my really important secrets in here.
Shhh!Calculating checksums
You can hash the file when you encrypt or decrypt by passing the -c argument. For encryption operations, this is performed on the source file. For decryption operations this occurs on the target file after the operation has completed.
Checksum on encryption
python3 aes_file_crypt.py -k MySuperSecretKey -s plain.txt -t cipher.txt -e -cChecksum result on encryption
#️⃣ MD5: e6073879c5e584bbdda5fb10fcac77a1
#️⃣ SHA256: a3778bec2547a12d564a03618ac1e14c87271ad683c547246de520d54439d564
🔐 Completed encryption of plain.txt to cipher.txt.Checksum on decryption
python3 aes_file_crypt.py -k MySuperSecretKey -s cipher.txt -t decrypted.txt -d -cChecksum result on decryption
🔓 Completed decryption of cipher.txt to decrypted.txt.
#️⃣ MD5: e6073879c5e584bbdda5fb10fcac77a1
#️⃣ SHA256: a3778bec2547a12d564a03618ac1e14c87271ad683c547246de520d54439d564Changing the buffer size
You may change the file buffer size to any value greater than or equal to 32. This alters the buffer pool size used when encrypting the file. This impacts cryptographic performance but does not alter the encryption used or the end result.
python3 aes_file_crypt.py -k MySuperSecretKey -s plain.txt -t cipher.txt -e -b 256Command-line help
Command-line help is available via the -h argument.
usage: aes_file_crypt.py [-h] -k KEY [-c] [-d] [-e] [-s SOURCE] [-t TARGET] [-b BUFFER]
Encrypt or decrypt a file with AES256/CBC encryption.
_______ __ _______ __ __ __
| _ .----.-----.--.--.--.--| | _ | |_.----|__| |--.-----.
|. 1___| _| _ | | | | _ | 1___| _| _| | <| -__|
|. |___|__| |_____|________|_____|____ |____|__| |__|__|__|_____|
|: 1 | |: 1 |
|::.. . | |::.. . |
`-------' `-------'
_______ _______ _______ ___ ______ ______ ______
| _ | ___| __| / / | | __ \ |
| | ___|__ | ,' ,' | ---| __ < ---|
|___|___|_______|_______| /__/ |______|______/______|
_______ __ __ ______ __
| ___|__| |.-----. | |.----.--.--.-----.| |_
| ___| | || -__| | ---|| _| | | _ || _|
|___| |__|__||_____| |______||__| |___ | __||____|
|_____|__|
Chunks read and write operations to handle larger file sizes.
optional arguments:
-h, --help show this help message and exit
-b BUFFER, --buffer BUFFER
Max buffer size before the contents are written to the target file.
behavior arguments:
-c, --checksum Print the hash of the target and source file arguments.
-d, --decrypt Decrypt from the source to the target.
-e, --encrypt Encrypt from the source to the target.
required arguments:
-k KEY, --key KEY Key to use for encryption and decryption operations.
file arguments:
-s SOURCE, --source SOURCE
Source file to encrypt or decrypt.
-t TARGET, --target TARGET
Target file for the resulting cryptographic operation.Example source code
Source code for this example can be found here.
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.
-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.
python3 aws_parameter_store.py -k FALCON_CLIENT_ID -s FALCON_CLIENT_SECRETUse this command to activate debugging.
python3 aws_parameter_store.py -k FALCON_CLIENT_ID -s FALCON_CLIENT_SECRET -dCommand-line help
Command-line help is available via the -h argument.
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_SECRETToken Authentication
Token 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 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 and Object Authentication, there are multiple scenarios where it is still the best option for the situation.
Token Authentication support will always be maintained within Falconpy.
⚠️ Please note ⚠️
Token Authentication creates an instance of a FalconPy Service Class that cannot reauthenticate itself as it does not have awareness of your API credentials. You will have to regenerate your bearer token before it expires and update the creds dictionary within the Service Class if you are implementing a long running process.
Running the program
This application is only a proof of concept that is intended to be reviewed as source code. Executing the program will initiate a connectivity test to several CrowdStrike APIs. Credentials used for these test are either stored in the environment (FALCON_CLIENT_ID and FALCON_CLIENT_SECRET) or requested by the application when it starts.
In order for the demonstration to test all six API service collections, you will need access to the following scopes:
CloudConnectAWS
READ
Detects
READ
Hosts
READ
IOC
READ
Incidents
READ
Intel
READ
Execution syntax
This application does not accept command line arguments.
Basic usage
This sample only supports singular execution.
python3 token_authentication_example.pyExample result
CloudConnectAWS [PASSED]
Detects [PASSED]
Hosts [PASSED]
IOC [PASSED]
Incidents [PASSED]
Intel [PASSED]Command-line help
This sample does not implement command line assistance.
Example source code
Source code for this example can be found here.
Last updated
Was this helpful?