swell

swell is Stairwell's command line tool. It does from a terminal, or from a script, most of what you would otherwise do in the Stairwell app: send files in for analysis, manage YARA rules, run queries against an environment, create assets and environments, tag things, and check whether a network can reach Stairwell before you deploy into it. It ships as a single binary for Linux, macOS, and Windows, and it needs nothing installed alongside it.

What is swell for?

Four jobs come up most often.

The appliance case is the one people underestimate. Network and security appliances run Linux, they are a favorite target, and most of them will not accept an endpoint agent at all. A swell binary and a scheduled job give you file-level visibility on a device that otherwise has none. See Install on a Linux Appliance.

How do I install swell?

Download the binary for your platform and follow the page for it.

What do I need before the first command?

Two things: an auth token, and the ID of the environment you want to work in.

swell auth login gets you the token. It prints a URL, you open it in a browser, Stairwell shows you a token, and you paste it back into the terminal. swell stores it, along with your user and organization, so you do not pass it again.

$ swell auth login

Go to https://app.stairwell.com/generate-auth-token/ in your browser and login if needed.
Paste the generated auth token displayed in your browser here:

The environment ID you can read straight out of Stairwell:

$ swell foundation getenvs

That prints one row per environment you are authorized to reach, with its ID and its default asset ID. Put the one you work in into your config file and every later command picks it up. See swell Configuration.

What is a good first command?

List the YARA rules in your environment. It touches authentication, the environment setting, and the network in one step, and it changes nothing.

$ swell yara list --environment_id=YOUR_ENVIRONMENT_ID

A table of rule names, versions, and active state means you are set up. An error mentioning auth_token means the login did not stick. An error mentioning environment_id means the flag or the config file is missing that value. A network or TLS error means run the pre-deployment check next, because something between you and Stairwell is in the way.

Then upload something. Every upload has to be attributed to an asset, so create one for the machine you are on and note the ID it prints:

$ swell onboard my-build-server --environment_id=YOUR_ENVIRONMENT_ID
Created asset: "my-build-server"
Asset ID: "ASSET_ID"

$ swell objects upload --asset=ASSET_ID /opt/suspicious

swell walks the path, hashes what it finds, and sends it in. What comes back is a sighting on that asset and an object in your environment, which is the same thing a forwarder would have produced.

How do I find out what a command does?

Every command and subcommand takes --help, and that is the fastest answer for a flag you half remember.

$ swell --help
$ swell objects --help
$ swell objects upload --help

swell version prints the build you are running, which is the first thing to check when behavior does not match a page.

For the full list of commands and their flags in one place, use the swell command reference.

What should I read next?

• swell Configuration, for auth, the config file, environment variables, and which one wins when two disagree.
• swell Command Reference, the lookup page for every command and flag.
• Pre-Deployment Check, for the two commands to run before any forwarder rollout.