The Prelude Command Line Interface (CLI) supplies programmatic access to the full suite of Prelude APIs. It is written in Python and will run on any machine with Python installed.
Run the following command to install the Prelude CLI:
pip3 install prelude-cli
# Confirm it's installed correctly
prelude --help
If you have an older version of the Prelude CLI, run the following command to update to the latest version:
pip3 install prelude-cli --upgrade
Once installed, you can engage the CLI through the prelude
command.
The CLI reads credentials from a ~/.prelude/keychain.ini file, which auto-generates when creating an account.
If you do not have a Prelude Account, you can create one by running prelude iam create-account
. If you are using the web-based UI and already have a Prelude Account, you can import your existing credentials by running prelude configure
. This command will request that you provide your account credentials, which you can retrieve from the web-based UI's top-right menu action "Export credentials." That action will save a credentials file (by default named keychain.ini) to the location you select.
1. Install the Prelude CLI
The Prelude CLI is an open-source command line interface to the entire Prelude stack. You can install it via PIP.
pip install prelude-cli
2. Getting help
The CLI is broken down into modules and commands. The modules are:
- IAM, for account management
- Detect, for continuous security testing
- Build, for creating custom tests
- Partner, for managing integrations
The command is the keyword that you write after the module. Use --help to learn the various options.
prelude --help
prelude detect --help
prelude detect activity --help
3. Register for an account
A Prelude account is free and can be created from the command line. You will be prompted for an email address, which will need to be validated before you move on to the next step.
This step will create a ~/.prelude/keychain.ini file on your computer which stores the credentials to your new account.
prelude iam create-account
4. Your security tests
Every account has access to the open-source security tests available in the Prelude GitHub. You can see the tests available to you through the Detect module. Note that each test is identified by a UUID.
prelude detect tests
5. Enable your first test
You can schedule a test by providing a test ID and a run code, representing how often you want to run it. By default, a test runs against all endpoints - but you can limit your test through the use of tags (optional).
prelude detect enable-test 39de298a-911d-4a3b-aed4-1e8281010a9a --run_code daily
6. Deploy your first endpoint
A probe is a 1 kilobyte process that knows how to run security tests.
You can deploy probes either through the pre-built installers or by creating an endpoint from the CLI and starting a probe as an executable.
Registering an endpoint from the CLI requires a hostname and serial number, to uniquely identify the device.
prelude detect create-endpoint -h hostname -s 1-2-3-4
export PRELUDE_TOKEN=<TOKEN>
curl -sL -X GET "https://api.preludesecurity.com/download/nocturnal" -H "dos:darwin-arm64" > probe
chmod +x probe
./probe
7. View results
You can get a JSON dump of all test results through the powerful "activity" command. There are many filtering options available but one is shown here: days. This will show you all results for the last 3 days.
prelude detect activity --days 3
8. Add teammates
Prelude accounts are meant for teams - so add as many teammates as you'd like! Use the IAM module to invite valid email addresses to your account. User accounts follow a strict permission scheme, so read up on the options.
The EXECUTIVE permission is chosen here, which allows read-only access to the web dashboard.
prelude iam create-user ducky@example.com --permission EXECUTIVE
9. Attach a partner
Prelude includes several partner integrations, which allow you to attach your EDR or SIEM to your account.
Here, we are attaching a CrowdStrike account. This integration supports deploying probes through the Falcon EDR as well as automated resolutions for any failed tests.
prelude partner attach crowdstrike --api https://api.us-2.crowdstrike.com --user <USER> --secret <SECRET>