Package: crowdstrike-falconpy
FalconPy - The CrowdStrike Falcon SDK for PythonThe FalconPy SDK contains a collection of Python classes that abstract CrowdStrike Falcon OAuth2 API interaction, removing duplicative code and allowing developers to focus on just the logic of their solution requirements.OverviewQuick StartDocumentation and SupportContribute to FalconPyOverview 🔎There are many CrowdStrike Falcon APIservice collectionscollectively containing hundreds ofindividual operations, all of which are accessible to your project via FalconPy.The CrowdStrike Falcon SDK for Python completely abstracts token management, while also supporting interaction with all CrowdStrike regions, custom connection and response timeouts, routing requests through a list of proxies, disabling SSL verification, and custom header configuration.If the CrowdStrike APIs were rings of great power, that the Dark Lord Sauron gifted to the kings of dwarves, elves and men, then CrowdStrike's FalconPy would be the One Ring."One SDK to rule them all, One SDK to find them, One SDK to bring them all and in the darkness bind them."Supported versions of PythonThe CrowdStrike Falcon SDK for Python was developed for Python 3. Current versions of FalconPy provide support for Python versions3.7-3.12. Every commit to the FalconPy code base is unit tested for functionality using all versions of Python the library currently supports.[!NOTE]
Developers working with Python version3.6will need to leverage versions of FalconPy less than1.4.0.Supported Operating SystemsThe FalconPy SDK is unit tested on the following operating systems.FalconPy will also run on any of the following operating systems.Details regarding supported operating systems and Python versions, and project security and testing procedures can be foundhere.ComponentsThe FalconPy SDK provides two distinct methods for interacting with CrowdStrike's API.Service ClassesThe Uber ClassEach Service Class represents a single CrowdStrike API service collection providing an interface to theoperations availablewithin that service collection.An all-in-one class that provides a singular interface forall operationsin every CrowdStrike API service collection.Service ClassesRepresenting a single CrowdStrike Falcon API service collection, each Service Class has a method defined forevery operation availablewithin that service collection.Available Service ClassesFor each CrowdStrike Falcon API service collection, a matching Service Class is available in the FalconPy library. For a complete list of service collections and their related Service Class, please review theOperations by Collectionpage onfalconpy.io.Service Class benefitsClosely follows Python and OpenAPI best practice for code style and syntax. PEP-8 compliant.Completely abstracts token management, automatically refreshing your token when it expires.Provides simple programmatic patterns for interacting with CrowdStrike Falcon APIs.Supportscloud region autodiscoveryfor the CrowdStrikeUS-1,US-2andEU-1regions.Supports dynamicconfigurationbased upon the needs of your environment.Supports CrowdStrike Falcon APIparameter abstractionfunctionality.Supports CrowdStrike Falcon APIbody payload abstractionfunctionality.The Uber ClassOperating as a single harness for interacting with the entire CrowdStrike Falcon API, theUber Classcan accessevery available operationwithinevery API service collection.Uber Class benefitsAccess every CrowdStrike Falcon API service collection with only one import and only one class.Completely abstracts token management, automatically refreshing your token when it expires.Interact with newly released API operations not yet available in the library via theoverridekeyword.Provides simple programmatic patterns for interacting with CrowdStrike Falcon APIs.Supportscloud region autodiscoveryfor the CrowdStrikeUS-1,US-2andEU-1regions.Supports CrowdStrike Falcon APIparameter abstractionfunctionality.Supports allenvironment configurationoptions supported by FalconPy Service Classes.Comparing FalconPy class typesWhile theusage syntaxvaries slightly, the Uber Class provides the same performance andoutputas FalconPy Service Classes, and can perform all of the sameoperations. The Uber Class doesnotsupportbody payload abstraction.Quick Start 💫Stable releases of FalconPy are available on the Python Package Index. In a terminal, execute the following command:python3-mpipinstallcrowdstrike-falconpyOnce installed, you can immediately begin using CrowdStrike functionality in your Python projects."""CrowdStrike FalconPy Quick Start."""importosfromfalconpyimportHosts# 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 filterhosts_search_result=hosts.query_devices_by_filter(filter=f"hostname:*'*{SEARCH_FILTER}*'")# Confirm we received a success response back from the CrowdStrike APIifhosts_search_result["status_code"]==200:hosts_found=hosts_search_result["body"]["resources"]# Confirm our search produced resultsifhosts_found:# Retrieve the details for all matcheshosts_detail=hosts.get_device_details(ids=hosts_found)["body"]["resources"]fordetailinhosts_detail:# Display the AID and hostname for this matchaid=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 responseerror_detail=hosts_search_result["body"]["errors"]forerrorinerror_detail:# Display the API error detailerror_code=error["code"]error_message=error["message"]print(f"[Error{error_code}]{error_message}")More samplesIf you are interested in reviewing more examples of FalconPy usage, this repository also maintains a collection ofsamplesto help get you started with integrating CrowdStrike Falcon into your DevOps processes.Documentation and Support 📖FalconPy is a community-driven, open source project designed to assist developers in leveraging the power of CrowdStrike APIs within their solutions. While not a formal CrowdStrike product, FalconPy is maintained by CrowdStrike and supported in partnership with the open source developer community.Official Project Documentation:falconpy.ioExtended documentation is also available via thewikifor this repository.Issues and QuestionsIs something going wrong? 🔥GitHub Issues are used to report bugs and errors.Have a question you can't find answered in the documentation?Please submit usage questions to the Q&A section of our discussion board.Community forumsThe discussion board for this repository also provides the community with means to communicate regardingenhancements ideas,integration examplesandnew releases.More information regarding FalconPy documentation and support can be foundhere.Contribute to FalconPy ☕Interested inbeing acknowledgedas a member of an elite community of security-focused Python developers thatstop breaches?There aremanyways you can contribute to the FalconPy project!Providing feedbackby opening a GitHub ticket. Even a fly-by "hey, this worked..." is appreciated and helps validate approaches. Ideas on improving the project are most welcome.Documenting, blogging, or creating videos, of how you've used FalconPy. This type of content isinvaluableand helps our community grow. Post these in theShow and Tellcategory of ourdiscussion board.Submit a sampledemonstrating how you're using FalconPy by opening a pull request for inclusion in theSamples Library.Fix a bug or implement a new feature. Check out ouropen issues on GitHubor ourdiscussion boardfor inspiration.Review pull requestsby going through the queue ofopen pull requests on GitHuband giving feedback to the authors.To get started, review theCode of Conductfor community guidelines, and thecontribution guidefor more detail regarding contributing to the CrowdStrike FalconPy project.WE STOP BREACHES