Operations Overview

API Operations Overview

Throughout this repository, we frequently make references to Operations or Operation IDs. The usage of these terms is specific with regards to FalconPy and originates from the contents of the CrowdStrike API swagger, which the library is based on.

Operation

An operation is the act of performing a request against a specific endpoint within the CrowdStrike API. This is done by providing payloads using an allowed HTTP method to a specific API endpoint. Operations may use the same endpoint, or the same HTTP method as other operations, but no two combinations are ever duplicated. Although every operation will have it's own unique payload requirements, many operations will have matching payload formats or require no payload whatsoever.

For ease of use purposes, FalconPy intentionally abstracts the API endpoint and HTTP method for all API operations. Developers only need the ID of the operation they wish to perform in order to find documentation or use the operation.

Operation IDs

All operations within all API service collections have a unique string identifier that is specific to the one operation only. This ID is present within the CrowdStrike API swagger and is leveraged in several places within the FalconPy library.

• Operation IDs are used to define the operation within this wiki, and to detail how it can be properly used.

• Operation IDs can be used as methods within Service Classes. This is referred to as Operation ID Syntax.

• Operation IDs are used to tell the Uber Class's command method which operation to perform. This can be provided as the first argument to the method, or as the keyword action.
  Example: These two statements are functionally the same.

  from falconpy import APIHarness
  
  # Do not hardcode credentials!
  # These values are ingested as strings.
  falcon = APIHarness(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )
  
  # This example passes the operation ID as a positional argument
  result = falcon.command("QueryDetects")

  from falconpy import APIHarness
  
  # Do not hardcode credentials!
  # These values are ingested as strings.
  falcon = APIHarness(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )
  
  # This example passes the operation ID as a keyword argument
  result = falcon.command(action="QueryDetects")

This is the only accepted positional argument when using the Uber class. Check individual service collection documentation for details regarding accepted arguments and keywords for each available method.

Operation ID Syntax

The FalconPy library, documentation and samples follow PEP8 syntax wherever possible, but depending on individual developer requirements, PEP8 syntax may not be necessary (or desired). An additional option within Service Classes, Operation ID Syntax, allows developers to use operation IDs to specify API operations similar to the Uber class.

This is handled by creating a method alias within the Service Class for every method that aligns to an operation ID that does not match PEP8 syntax. When the operation ID uses Python reserved characters (ex: - or .), the operation ID is updated to use _. (Operation IDs deprecated in this fashion are still available within the Uber class.)

Examples

While the syntax differs slightly, there is no functional difference between PEP8 and Operation ID syntax with regards to API results or performance.

PEP8 Syntax

from falconpy import Hosts

# Do not hardcode credentials!
# These values are ingested as strings.
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

result = falcon.query_devices_by_filter(limit=100)
print(result)

Operation ID Syntax

from falconpy import Hosts

# Do not hardcode credentials!
# These values are ingested as strings.
falcon = Hosts(client_id=CLIENT_ID,
               client_secret=CLIENT_SECRET
               )

result = falcon.QueryDevicesByFilter(limit=100)
print(result)