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:

  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

      --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 "")  
      --grpc_intake_server_address string   address of the intakeFlag GRPC server (default "")  
  -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 "<">)  
  -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:

  1. auth token (learn how to grab auth token here)

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

  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:

  1. login

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


Tools for interacting with yara rules

  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.


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