Stairwell Swell CLI Utility
Our cross-platform command-line interface (Swell) is the recommended approach for programmatically interacting with the Stairwell Platform
Swell is a cross-platform utility (written in Go) that affords the ability to programmatically interface with the Stairwell platform. You can simply run swell to see its usage:
Usage:
swell [flags]
swell [command]
Available Commands:
auth Tools to manage swell auth
completion Generates bash completion scripts
config Prints the current configuration
edr Tools related to EDR integrations with foundation
foundation Tools for interacting with foundation
help Help about any command
objects Tools for interacting with objects
onboard create an asset for the local machine and create a config with its ID
query Queries resources within an environment.
tags Tools for interacting with tags on different entities
version Prints out version information
yara Tools for interacting with yara rules
Flags:
--auth_server_address string address of the auth server (default "auth.auth.svc.cluster.local:80")
--auth_token string authentication token
--config_file string config file to use (default ~/.config/swell/swell.yaml)
--environment_id string environment to interact with
--foundation_server_address string address of the foundation GRPC server (default "api.app.stairwell.com:443")
--grpc_intake_server_address string address of the intakeFlag GRPC server (default "grpc.intake.app.stairwell.com:443")
-h, --help help for swell
--insecure skip server certificate and domain verification. (NOT SECURE!)
--intake_server_address string address of the intakeFlag HTTP server (default "<https://http.intake.app.stairwell.com:443">)
-p, --parallel int how many goroutines to use (default 2)
--plaintext Use plain-text HTTP/2 when connecting to server (no TLS).
Use "swell [command] --help" for more information about a command.
There are a handful of primary commands:
- auth
- completion
- config
- edr
- foundation
- help
- objects
- onboard
- query
- tags
- version
- yara
Getting started
There are two pieces of data that you'll primarily need when using swell:
-
auth token (learn how to grab auth token here)
-
environment ID (learn how to grab environment id here)
You can interact with the auth command in order to issue your auth token to swell:
Note: Each primary command has its own set of command line arguments and help information. For example, we can learn more about the auth command by running:
./swell_linux auth --help
The following is the output of running auth command with the "--help" argument:
Tools to manage swell auth
Usage:
swell auth [flags]
swell auth [command]
Available Commands:
login Authenticate the swell CLI, by going through the login steps
logout Remove the stored auth token
We can see that there are to commands that are compatible with auth:
-
login
-
logout
We can simply run the auth command with the "login" option, and by doing so, will be prompted for an API key:
swell auth login
The API key will now be loaded into swell and we won't need to explicitly pass it as an argument to any subsequent command that will be responsible for pulling data from the Stairwell platform.
Let's take a look at the "yara" command
Similarly to before, we can make use of the "--help" argument to better understand how the yara command works:
swell yara --help
Output:
Tools for interacting with yara rules
Usage:
swell yara [flags]
swell yara [command]
Available Commands:
delete Deletes a yara rule from an environment
download Download yara rules
list Prints a table of each rule in the HEAD state
upload Upload yara rules to foundation
Let's try leveraging the list command to print a table of the rules we have associated with our tenant.
We have two options for querying our rules with a specified environment ID:
Option 1: we can simply issue the "yara list" command and pass the "enviornment_id" argument.
Example:
swell yara list --environment_id "YOUR_ENVIORNMENT_ID"
Option 2: we can insert our "environment_id" into the Swell config file so that we don't have to manually specify it as an argument with each command.
Swell creates a default YAML config file that is located at: ~/.config/swell/swell.yaml
You can simply edit this file and insert your environment ID into the "environment_id" YAML property:
Example snippet:
auth_token: YOUR_AUTH_TOKEN
As a result, you can issue swell commands without explicitly passing the global "enviornment_id" argument.
Thus, listing YARA rules would be as simple as:
swell yara list
Updated 11 months ago