crowdstrike-falconpy
pypi i crowdstrike-falconpy

crowdstrike-falconpy

The CrowdStrike Falcon SDK for Python

by CrowdStrike

1.1.5 (see all)
pypi i crowdstrike-falconpy
Readme

CrowdStrike FalconPy

Twitter URL

FalconPy - The CrowdStrike Falcon SDK for Python

Package Status PyPI Release date Repo status Commit activity

The 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.

Overview 🔎

There are many CrowdStrike Falcon API service collections collectively containing hundreds of individual 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."

PyPI - Downloads

Supported versions of Python

The CrowdStrike Falcon SDK for Python was developed for Python 3, and does not support versions of Python below 3.6. Every commit to the FalconPy code base is unit tested for functionality using all versions of Python the library currently supports.

While Python 3.5 should not have problems running FalconPy, as of February 2021 this version is no longer analyzed as part of our unit testing.

PyPI - Implementation PyPI - Wheel PyPI - Python Version

Supported Operating Systems

The FalconPy SDK is unit tested on the following operating systems.

macOS Ubuntu Windows

FalconPy will also run on any of the following operating systems.

Amazon Linux CentOS Fedora RedHat Arch

Debian Kali Pop! OS SUSE openSUSE

Details regarding supported operating systems and Python versions, and project security and testing procedures can be found here.

Components

The FalconPy SDK provides two distinct methods for interacting with CrowdStrike's API.

Service ClassesThe Uber Class

Service Classes
The Uber Class
Each Service Class represents a single CrowdStrike API service collection providing an interface to the operations available within that service collection.An all-in-one class that provides a singular interface for all operations in every CrowdStrike API service collection.

Service Classes

Representing a single CrowdStrike Falcon API service collection, each Service Class has a method defined for every operation available within that service collection.

Available Service Classes

For each CrowdStrike Falcon API service collection, a matching Service Class is available in the FalconPy library.

Service CollectionCode LocationClass Name
CrowdStrike Device Controldevice_control_policies.pyDeviceControlPolicies
CrowdStrike Custom Indicators of Attack (IOAs)custom_ioa.py
ioa_exclusions.py
CustomIOA
IOAExclusions
CrowdStrike Custom Indicators of Compromise (IOCs)ioc.py
iocs.py Deprecated
IOC
Iocs
CrowdStrike Detectionsdetects.pyDetects
CrowdStrike Falcon Discoverdiscover.pyDiscover
Discover for Cloud and Containers
AWS Accounts
Azure Subscriptions, GCP Projects

cloud_connect_aws.py
d4c_registration.py

CloudConnectAWS
D4CRegistration
CrowdStrike Event Streamsevent_streams.pyEventStreams
CrowdStrike Falcon Containerfalcon_container.pyFalconContainer
CrowdStrike Falcon Horizoncspm_registration.pyCSPMRegistration
CrowdStrike FileVantagefilevantage.pyFileVantage
CrowdStrike Firewall Managementfirewall_management.pyFirewallManagement
CrowdStrike Firewall Policy Managementfirewall_policies.pyFirewallPolicies
CrowdStrike Falcon Complete Dashboardfalcon_complete_dashboard.pyFalconCompleteDashboard
CrowdStrike Falcon Flight Controlmssp.pyFlightControl
CrowdStrike Falcon Sandboxsample_uploads.py
falconx_sandbox.py
quick_scan.py
SampleUploads
FalconXSandbox
QuickScan
CrowdStrike Falcon Xintel.py
recon.py
Intel
Recon
CrowdStrike Host Groupshost_group.pyHostGroup
CrowdStrike Hostshosts.pyHosts
CrowdStrike Incident and Detection Monitoringincidents.pyIncidents
CrowdStrike Identity Protectionsidentity_protection.pyIdentityProtection
CrowdStrike Installation Tokensinstallation_tokens.pyInstallationTokens
CrowdStrike Kubernetes Protectionkubernetes_protection.pyKubernetesProtection
CrowdStrike MalQuerymalquery.pyMalQuery
CrowdStrike Message Centermessage_center.pyMessageCenter
CrowdStrike ML Exclusionsml_exclusions.pyMLExclusions
CrowdStrike OAuth2 Auth Tokenoauth2.pyOAuth2
CrowdStrike Overwatch Dashboardoverwatch_dashboard.pyOverwatchDashboard
CrowdStrike Prevention Policyprevention_policy.pyPreventionPolicy
CrowdStrike Quarantinequarantine.pyQuarantine
CrowdStrike Real Time Response (RTR)real_time_response.pyRealTimeResponse
CrowdStrike Realtime Response (RTR) Administrationreal_time_response_admin.pyRealTimeResponseAdmin
CrowdStrike Realtime Response (RTR) Policiesresponse_policies.pyResponsePolicies
CrowdStrike Report Executionsreport_executions.pyReportExecutions
CrowdStrike Scheduled Reportsscheduled_reports.pyScheduledReports
CrowdStrike Sensor Downloadsensor_download.pySensorDownload
CrowdStrike Sensor Visibility Exclusionssensor_visibility_exclusions.pySensorVisibilityExclusions
CrowdStrike Sensor Update Policy Managementsensor_update_policy.pySensorUpdatePolicy
CrowdStrike Spotlightspotlight_evaluation_logic.py
spotlight_vulnerabilities.py
SpotlightEvaluationLogic
SpotlightVulnerabilities
CrowdStrike User and Rolesuser_management.pyUserManagement
CrowdStrike Falcon Zero Trust Assessmentzero_trust_assessment.pyZeroTrustAssessment

Service Class benefits

  • Closely 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.
  • Supports cloud region autodiscovery for the CrowdStrike US-1, US-2 and EU-1 regions.
  • Supports dynamic configuration based upon the needs of your environment.
  • Supports CrowdStrike Falcon API parameter abstraction functionality.
  • Supports CrowdStrike Falcon API body payload abstraction functionality.

The Uber Class

Operating as a single harness for interacting with the entire CrowdStrike Falcon API, the Uber Class can access every available operation within every API service collection.

Code Location
api_complete.pyThe Uber Class provides an interface to all CrowdStrike APIs with a single handler. This solution supports communicating with API endpoints that do not have an available Service Class or are recently released.

Uber Class benefits

  • Access 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 the override keyword.
  • Provides simple programmatic patterns for interacting with CrowdStrike Falcon APIs.
  • Supports cloud region autodiscovery for the CrowdStrike US-1, US-2 and EU-1 regions.
  • Supports CrowdStrike Falcon API parameter abstraction functionality.
  • Supports all environment configuration options supported by FalconPy Service Classes.

Comparing FalconPy class types

While the usage syntax varies slightly, the Uber Class provides the same performance and output as FalconPy Service Classes, and can perform all of the same operations. The Uber Class does not support body payload abstraction but does provide unique override functionality that is not available when you are using Service Classes.

CrowdStrike Divider

Quick Start 💫

Stable releases of FalconPy are available on the Python Package Index. In a terminal, execute the following command:

python3 -m pip install crowdstrike-falconpy

Once installed, you can immediately begin using CrowdStrike functionality in your Python projects.

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

hosts = Hosts(client_id="CROWDSTRIKE_API_CLIENT_ID", client_secret="CROWDSTRIKE_API_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}")

More samples

If you are interested in reviewing more examples of FalconPy usage, this repository also maintains a collection of samples to 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 with implementing CrowdStrike's APIs within their applications, and is not a formal CrowdStrike product. As such it carries no formal support, expressed or implied.

Official Project Documentation: falconpy.io

Website Documentation Version

Extended documentation is also available via the wiki for this repository.

Issues and Questions

Is something going wrong? 🔥

GitHub Issues are used to report bugs and errors.

Report Issue

Have a question you can't find answered in the documentation?

Please submit usage questions to the Q&A section of our discussion board.

Discussions

Community forums

The discussion board for this repository also provides the community with means to communicate regarding enhancements ideas, integration examples and new releases.

Discussions

Additional content

The following materials have been produced by the maintainers and members of the community regarding FalconPy.

ContentDescription
API Office Hour 03.23.21API Office Hour 03-23-21
Presentation deck used to discuss FalconPy functionality, structure and roadmap for a virtual API office hour event in March 2021.
Fal.Con 2021Fal.Con 2021
Virtual presentation given by @jshcodes at Fal.Con 2021. Focused on basic functionality and usage, existing integrations that leverage FalconPy, available library documentation, and the FalconPy community.

More information regarding FalconPy documentation and support can be found here.

Contribute to FalconPy ☕

Interested in being acknowledged as a member of an elite community of security-focused Python developers that stop breaches?

There are many ways you can contribute to the FalconPy project!

Providing feedback by 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 is invaluable and helps our community grow. Open a pull request for inclusion in the Additional content section of this page.

Fix a bug or implement a new feature. Check out our open issues on GitHub or our discussion board for inspiration.

Review pull requests by going through the queue of open pull requests on GitHub and giving feedback to the authors.

To get started, review the Code of Conduct for community guidelines, and the contribution guide for more detail regarding contributing to the CrowdStrike FalconPy project.



WE STOP BREACHES

GitHub Stars

144

LAST COMMIT

5mos ago

MAINTAINERS

1

CONTRIBUTORS

16

OPEN ISSUES

3

OPEN PRs

1
VersionTagPublished
1.1.5
1mo ago
1.1.4
2mos ago
1.1.3
2mos ago
1.1.2
3mos ago
No alternatives found
No tutorials found
Add a tutorial