How to use Falconpy

[felipemor]

Hello everyone, everything good ? How do I start with Falconpy in my terminal?

[jshcodes]

Hi @felipemor -

If you've got Python configured, then the next step would be to configure your API client keys (within the CrowdStrike console navigate to Support and resources -> API clients and keys) and then start coding!

Quick Start procedure

If we use the Quick Start from the main README.md for this repository as an example, the steps would be:

1. Configure your API client to provide READ access to the Hosts service collection scope.

   Save these credentials as you will need them later.

2. Click the copy button in the upper right hand corner of the Quick Start code block in the README. Save this contents of your clipboard to a file called example.py.

   I have also pasted the contents of this code below this procedure.

3. In your terminal navigate to the folder where you saved the example.py file.
4. Install FalconPy with the following command:

   python3 -m pip install crowdstrike-falconpy

5. Add your client keys to your running environment (replace {VALUES} with the appropriate values you saved during Step 1):
   Linux / MacOS

   export FALCON_CLIENT_ID={CLIENT_ID_VALUE}
   export FALCON_CLIENT_SECRET={CLIENT_SECRET_VALUE}

   Windows PowerShell

   $env:FALCON_CLIENT_ID={CLIENT_ID_VALUE}
   $env:FALCON_CLIENT_SECRET={CLIENT_SECRET_VALUE}

6. Change the hostname filter to match a host in your environment (line 18).

   SEARCH_FILTER = "hostname-search-string"

7. Execute the example with the following command:

   python3 example.py

Quick Start code

"""CrowdStrike FalconPy Quick Start."""
import os
from falconpy import Hosts

# Use the API Clients and Keys page within your Falcon console to generate credentials.
# You will need to assign the Hosts: READ scope to your client to run this example.

# CrowdStrike does not recommend you hardcode credentials within source code.
# Instead, provide these values as variables that are retrieved from the environment,
# read from an encrypted file or secrets store, provided at runtime, etc.
# This example retrieves credentials from the environment as the variables
# "FALCON_CLIENT_ID" and "FALCON_CLIENT_SECRET".

hosts = Hosts(client_id=os.getenv("FALCON_CLIENT_ID"),
              client_secret=os.getenv("FALCON_CLIENT_SECRET")
              )

SEARCH_FILTER = "hostname-search-string"

# Retrieve a list of hosts that have a hostname that matches our search filter
hosts_search_result = hosts.query_devices_by_filter(filter=f"hostname:*'*{SEARCH_FILTER}*'")

# Confirm we received a success response back from the CrowdStrike API
if hosts_search_result["status_code"] == 200:
    hosts_found = hosts_search_result["body"]["resources"]
    # Confirm our search produced results
    if hosts_found:
        # Retrieve the details for all matches
        hosts_detail = hosts.get_device_details(ids=hosts_found)["body"]["resources"]
        for detail in hosts_detail:
            # Display the AID and hostname for this match
            aid = detail["device_id"]
            hostname = detail["hostname"]
            print(f"{hostname} ({aid})")
    else:
        print("No hosts found matching that hostname within your Falcon tenant.")
else:
    # Retrieve the details of the error response
    error_detail = hosts_search_result["body"]["errors"]
    for error in error_detail:
        # Display the API error detail
        error_code = error["code"]
        error_message = error["message"]
        print(f"[Error {error_code}] {error_message}")