Package: falcon-toolkit
Falcon Toolkitautomate all the things...remotely!What Is This?Falcon Toolkitis an all in one toolkit designed to make your Falcon life much easier. It is built on top ofCaracara.The toolkit provides:Host searching, with filter support.Multiple profile support, including support for MSSP / Falcon Flight Control configurations.A shell allowing you to interface with many hosts via RTR at once, and get the output via CSV.Scriptability! You can program the shell by providing pre-written routines via a file on disk, and a full Python extensibility API is provided.Prevention policy import and exportResponse policy import and exportMore functionality is coming soon! Want more functionality? Open anIssue!Since this is built on top of Caracara, you get a bunch of great functionality and flexibility free, including the ability to filter hosts using dynamically generated FQL queries, full debug logging where desired, Falcon Flight Control integration, and more! Plus, the tool is lightning quick as it leverages Caracara's parallelisation tricks to pull more information quickly.Getting StartedThere are two supported methods to install Falcon Toolkit.Recommended for Most Users:pipxInstalling Falcon Toolkit withpipxpipxis a tool published the Python Packaging Authority to ease the install of Python tools. It will automatically configure you a virtual environment and make a link thefalconcommand that your shell can work with.Follow the instructions to installpipxand add itsbinfolder to yourPATHvariable. Then, usepipxto install thefalcon-toolkitPyPI package. Your output should look like this:$pipxinstallfalcon-toolkit
installedpackagefalcon-toolkit3.0.1,installedusingPython3.11.0Theseappsarenowgloballyavailable-falconOnce installed, run thefalconcommand to test it.Configuringreadlinewhen installed viapipxIf you see a message like this, read on...$falcon
Readlinefeaturesincludingtabcompletionhavebeendisabledbecause
nosupportedversionofreadlinewasfound.Toresolvethis,install
pyreadline3onWindowsorgnureadlineonLinux/Mac.This is caused by Python installations compiled against a non-supportedreadlinelibrary, such aslibediton macOS. To fix it, run the following command to install a supported readline library.Windows:>pipxinjectfalcon-toolkitpyreadline3
injectedpackagepyreadline3intovenvfalcon-toolkitdone!✨🌟✨Linux or macOS:$pipxinjectfalcon-toolkitgnureadline
injectedpackagegnureadlineintovenvfalcon-toolkitdone!✨🌟✨Upgrading Falcon Toolkit when installed viapipxWhen installed viapipx, you can upgrade Falcon Toolkit by simply running:$pipxupgradefalcon-toolkit
falcon-toolkitisalreadyatlatestversion3.0.1Installing via Poetry (Recommended for Developers and Maintainers)This tool is built usingPoetryand Python 3. Therefore, you must first ensure that you have both Poetry and Python 3.9+ installed to make use of this tool. Ensure you pay attention to Step 3 of thePoetry installation instructionsso that you get Poetry added to your shell'sPATHvariable.Once Poetry is installed and loaded in your shell, simply clone this repository from GitHub and runpoetry installwithin theFalcon-Toolkitdirectory to get all the necessary requirements set up in a virtual environment.Next, runpoetry shellto enter the virtual environment.Finally, run thefalconcommand to get started! If this succeeds and you get some help output, you're ready to go.If you close your shell, simply runpoetry shellto get back in to the virtual environment. This will bring back thefalconcommand.Configuringreadlinewhen installed via PoetryIf you see a message like this, read on...$falcon
Readlinefeaturesincludingtabcompletionhavebeendisabledbecause
nosupportedversionofreadlinewasfound.Toresolvethis,install
pyreadline3onWindowsorgnureadlineonLinux/Mac.This is caused by Python installations compiled against a non-supportedreadlinelibrary, such aslibediton macOS. To fix it, run the following commands to install a supported readline library.Windows:# Enter the Poetry virtual environment>poetryshell# Install pyreadline3 in the virtual environment>pipinstallpyreadline3Linux or macOS:# Enter the Poetry virtual environment$poetryshell# Install gnureadline in the virtual environment$pipinstallgnureadlineUpgrading Falcon Toolkit when installed via PoetryWhen installed via Poetry, you have to follow two steps to upgrade the tool. First update your local copy of the Git repository, then install the updated dependencies.# Update the code$gitpull# Update the requirements$poetryinstall# Enter the virtual environment if you are not already in it$poetryshell# Run Falcon Toolkit$falconProfile ManagementFalcon Toolkit requires you to pre-configure profiles, consisting of:A name (such as for a client or Falcon tenant);An optional description;A Falcon API client ID;A corresponding Falcon API client secret; andOptionally, the desired cloud, although this can be automatically figured out based on magic provided byFalconPyprovided you are not a GovCloud customer.Once these options are configured, you do not need to specify a client ID/secret again for communicating with that client. The configurations are saved in the file~/FalconToolkit/FalconToolkit.json, and the client secret for each corresponding client ID is stored in your host's local secure storage environment (e.g., via DPAPI on Windows, the Keychain on macOS, or Gnome's secret store on Linux). This keeps your client secrets secure and encrypted using your logon password.Creating a New ProfileThe commandfalcon profiles newwill guide you through creating a new configuration. Note that:The name you specify will be the one you use to start a shell, so if you put a space in it remember that you'll need to wrap it in quotes later. Therefore, we do not recommend using a space here.The client ID and secret you specify must have full RTR admin and host querying permissions enabled; otherwise, this tool will not be able to execute any commands.Two types of configuration backends are provided out of the box: the default, which is for an API keypair associated with a standard Falcon tenant, and a Falcon Flight Control backend. Use the Flight Control backend when authenticating to a Parent CID, as you will be able to specify the desired child CID on execution.Your API keys should have the following scopes enabled in the Falcon dashboard:↓ API Scopes // Commands →host_searchshellpolicies(Prevention)policies(Response)Falcon Flight Control: ReadXWhen using parentCID API KeysXWhen using parentCID API KeysXWhen using parentCID API KeysXWhen using parentCID API KeysHosts: ReadXXPrevention Policies: ReadXdescribe/exportsub-commandsPrevention Policies: WriteXimportsub-commandReal Time Response: ReadXReal Time Response: WriteXReal Time Response: AdminXfor admin commandsResponse Policies: ReadXdescribe/exportsub-commandsResponse Policies: WriteXimportsub-commandShowing Your ProfilesThe commandfalcon profiles listwill show you all configurations (if any) you have created using thenewcommand above, listed by the name you specified.Example output:$falconprofileslist
FalconToolkit
ConfigurationDirectory:/Users/username/FalconToolkit
FalconInstanceConfigurations
ServicesTestTestinstanceforServicesDeleting a ProfileThe commandfalcon profiles delete [Profile Name]will delete a configuration for you. Use the name you defined when you created the profile viafalcon profiles new.Selecting a ProfileIf you have configured one profile, Falcon Toolkit will use it by default. If you have multiple profiles, you must select one using-p, like this:$falcon-pProfile2<command><command-specificparams>
FalconToolkit
...Listing FiltersA key part of this tool (as we'll see later) is filter support. To see what filters are supported by the Falcon Toolkit and FalconPy, runfalcon filters. Each filter is listed and explained with examples.Host SearchBefore jumping into an RTR shell, you may wish to see which hosts you would connect to if you used theshellcommand (covered below). To do so, use thefalcon host_searchcommand.As with theshellcommand, you must specify a profile (the name of a configuration you created using thenewcommand above) if you have created more than one, and you can then optionally provide as many filters as you want using succesive-fswitches. Some examples:List all online Windows hosts that are not within theLondonsite, within the one Falcon instance configured earlier.falconhost_search-fOS=Windows-fSite__NOT=London-oonlineList all Windows hosts not within the075e03f5e5c04d83b4831374e7dc01c3Group, within theMyCompanyFalcon tenant.falcon-pMyCompanyhost_search-fOS=Windows-fGroupID__NOT=075e03f5e5c04d83b4831374e7dc01c3List all offlineMyOtherCompanyWindows servers or domain controllers not within an OU calledProtectedfalcon-pMyOtherCompanyhost_search-fOS=Windows-fRole=Server,DC-fOU__NOT=Protected-oofflineList allMyOtherCompanyWindows Workstations that have checked in to Falcon within the past 30 minutesfalcon-pMyOtherCompanyhost_search-fOS=Windows-fRole=Workstation-fLastSeen__GTE=-30mJump into an RTR ShellNow that you know how to filter, you know how to jump into a shell! To get into a batch shell with no special options, just do the same as for ahost_searchbut use theshellcommand instead. For example, to launch an RTR shell with all Windows hosts last seen within the past 30 minutes within theMyCompanyFalcon instance, use this command:falcon-pMyCompanyshell-fOS=Windows-fLastSeen__GTE=-30mYou can also specify an initial timeout to use for all RTR commands. By default, the timeout is 30 seconds, but you can change this to, e.g., 60 seconds, like this:falcon-pMyCompanyshell-fOS=Windows-t60Once you are within an RTR shell, you can run any command that you can run within standard RTR, with full usage, tab completion and examples. However, note that some commands (such asregandrunscript) have been slightly adjusted in their usage to match standard Unix command patterns. There are technical reasons for this; reach out to us if you need support. Furthermore, some commands have been augmented or added, such asrunscript -WorkstationPathwhich allows you to run a local script without making it a cloud file first,get_statusto check on file uploads, anddownloadto pull files retrieved viagetdown to your local system.You can runhelpat any time within the shell to get a list of commands. Every command also supports the-hswitch to find out how it works. Runquitat any time to get back to your command line.All outputs are written to a log file, as well as a CSV alongside it showing the output from every host. If you run this tool against many hosts, you will see the output from the first in the list on screen. However, every host's output (fromstdoutandstderr) is written to the accompanying CSV.All logs and CSVs are written to thelogsfolder within your configuration directory (default:~/FalconToolkit).Specifying Hosts by IDAlthough Falcon Toolkit provides you with plenty of filtering options, sometimes you may wish to connect to hosts by Agent ID (AID) / Device ID. You can do this using two command line options.Specifying Device IDs at the Command Line: The-dOptionTo specify Device IDs at the command line, simply provide the--device-id-list/-doption and a comma-delimited list of IDs. For example, to connect to two hosts with the AIDsabcdef12345andghijkl67890, you could use the following command:falcon-pProfileNameshell-dabcdef12345,ghijkl67890Specifying a File Containing Device IDs: The-dfOptionSometimes it is not practical to provide a list of Device IDs at the command line, often because the length of the string containing all the IDs would exceed the maximum command length allowable within your shell. To get around this, Falcon Toolkit provides another parameter (--device-id-file/-df), which allows you to provide a path to a file containing a list of AIDs, one per line. For example, let's say you wanted to connect to two devices with the AIDsabcdef12345andghijkl67890, you may have a file nameddevice_ids.txtwith the following contents:abcdef12345
ghijkl67890Then, you could jump into a shell with these devices via this Falcon Toolkit command:falcon-pProfileNameshell-dfdevice_ids.txtReal Time Response (RTR) ScriptingThe RTR shell is fully scriptable. There are two different scripting methods supported:Command replay scripts that simulate a human typing commands into the shell; andPython scripts that can interact with the shell programmatically at runtime.Command Replay ScriptIf you have a file on disk with all shell commands you wish to run, you can specify it as a command line switch:falconshell-fOS=Windows-sscript.rtrThis would run a script from disk calledscript.rtr. Scripts should end in thequitcommand if you do not wish to run further commands after your script has run (and therefore return to the shell).Note that scripts contain a list of shell commands,nota list of zsh/PowerShell commands. Therefore, if you need to run a raw script command, write a script containing content like this:runscript-Raw"Get-ChildItem"quitPython Scripting APIThis tool is build on top of the excellentCmd2Python library, which brings with it copious extensibility. It is possible to write Python scripts that run within the context of the Toolkit's shell with programmatic logic applied. This feature is very much in beta, and we are actively seeking feedback on which state data should be made available globally to aid in programmatic scripting of the shell.Information on Cmd2's scripting backend is providedhere. The backend is configured as follows:The RTR Shell's applicationbridge nameisrtr, sortr("runscript -Raw \"Get-ChildItem\"")would execute theGet-ChildItemPowerShell command against all connected systems from within a custom PyScript.Theselffunctionality is enabled, enabling developers to introspect data stored within the RTR Shell itself. In this context,selfwill refer to the instantiatedRTRPromptobject defined infalcon_toolkit/shell/prompt.py.Some example usages of this functionality are as follows:Execute a batchgetcommand and then cache the contents ofself.last_batch_get_successful_requeststo find out how many systems had the file on disk. Then, the script could waitxseconds in a loop up to a maximum amount of time, runningget_statuseach time. On each iteration, the script may queryself.last_batch_get_completed_uploadsto determine whether a minimum threshold of systems have uploaded the requested file, and then once complete executedownload -e /some/output/folderto pull those completed uploads down to a folder of choice (then extract them automatically).Execute a series of commands that differ by target OS, using the contents ofself.connected_devicesto make decisions dynamically.Executeself.send_generic_commanddirectly, then use the returned(stdout, stderr)tuple to make decisions about which command to execute next (best suited to single system connections).Policy ManipulationYou candescribe,importandexporttwo types of policies: Prevention and Response. The three verbs are applied to thefalcon policiescommand to specify what you would like to do with policies, and a command line switch is used to specify the policy type to work with. Exported policies are written to disk as JSON with some Falcon Toolkit-specific data needed to import a policy back again.ExamplesShow all Prevention policies within theMyCompanyFalcon profile:$falcon-pMyCompanypolicies-pdescribe
platform_default(Platform:Windows)Platformdefaultpolicy
...Show all Response policies when only one profile is configured:$falconpolicies-rdescribe
platform_default(Platform:Windows)Platformdefaultpolicy
...Export a Response policy from theMyCompanytenant to disk:$falcon-pMyCompanypolicies-rexportPleasechooseapolicytoexport*MyResponsePolicy[Windows]MyOtherResponsePolicy[Linux]...Import a Prevention policy to the one configured Falcon tenant:$falconpolicies-pimportMyExportedPolicy.json
...Support & Community ForumsFalcon Toolkit is an open source project, and not a formal CrowdStrike product, designed to assist users with managing their Falcon tenants and executing commands at scale. As such, it carries no formal support, express or implied. This project originated out of the CrowdStrike Services Incident Response (IR) team's need to execute commands across Falcon tenants quickly, at scale, and with auditing, and is maintained byChris Hammond.Is something going wrong? GitHub Issues are used to report bugs. Submit anIssueand let us know what is happening.Furthermore, GitHub Discussions provide the community with means to communicate.Security issues should be raised to ourSecurity teamandChris Hammond.Thank you for using the Falcon Toolkit! We hope it is as useful to the Falcon user community as it is to us.