About CLI

Command-line interface to the Prelude Service API

The Prelude Command Line Interface (CLI) supplies programmatic access to the full suite of APIs. It is written in Python and as such, is multi-platform and can install anywhere Python exists through PIP.

pip3 install prelude-cli

# Confirm it's installed correctly
prelude --help

# In order to activate shell completion, you can add the following to your shell's rc file:
# For Bash, add this line to ~/.bashrc:
eval "$(_PRELUDE_COMPLETE=bash_source prelude)"

# For Zsh, add this line to ~/.zshrc:
eval "$(_PRELUDE_COMPLETE=zsh_source prelude)"

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 entering prelude iam create-account. If you are using Build and have a Prelude Account, connect your terminal to it using prelude configure.

Prelude Service

The CLI is designed to interact with any route on the Prelude Service API.

The Prelude Service is broken down into the following modules:

  • IAM: management of your Prelude Account
  • Build: create, edit and store security tests
  • Detect: manage your continuous security testing pipeline

You can engage with these API endpoints manually (think cURL), semi-automated (through the CLI) or fully automated (through the Prelude SDK).

Prelude SDK

The CLI is built on top of the Prelude SDK, a Python wrapper around the Prelude Service. The SDK contains the same functions (IAM, Build, Detect) as the CLI - but it also includes the actual REST API code too.

There is also a JavaScript SDK available for integration into web applications. All SDK’s are open-source, made available on GitHub.

The SDK can be used to build your own programmatic access to the Prelude Service.

Prelude CLI

Quickstart

Register a new Prelude account. This will automatically configure your local keychain with your new account credentials.

prelude iam create-account

List the security tests available to your account. Every new account is provisioned with a collection of Prelude's open-source security tests.

prelude build tests

Download the tests to your local machine and take a look at them. They will be written to a prelude/ folder in your current directory.

prelude build clone
ls prelude/

Create a new security test of your own. Check out Writing security tests for guidance on how to write a Prelude security test.

prelude build create-test <RULE>

Open and edit your new code file. Upload any changes.

prelude build upload <PATH>

Compile and validate your test.

prelude build compute <TEST ID>

List all tests again and validate your new VSTs are available.

prelude build tests

Generate a URL to download your new VST. Use the resulting URL to download it. Alternatively, check out Prelude Detect for an easy way to run your security tests at scale.

prelude build url <VST>

Clean up

Delete the security test you created.

prelude build delete-test <TEST ID>

Reference

Engage with the CLI by referencing the service name, desired module and optional parameters.

For example, to register a new Prelude Account enter:

prelude iam create-account

Type --help after any service or module to get usage information for the command.

Each module is protected by a specific permission. Consult the Prelude Account documentation for more details.

IAM

  • [no permission] create-account: register a new Prelude Account
  • [admin] create-user: add a user to your account
  • [admin] delete-user: remove a user from your account
  • [admin] purge: delete your account
  • [admin] list-users: display all the users in your account

Build

  • [build] clone: download all tests from your account to your local machine
  • [build] tests: display all the tests in your account
  • [build] test: list properties of a specific test
  • [build] create-test: create a test in your account
  • [build] delete-test: remove a test in your account
  • [build] upload: upload test source code
  • [build] url: generate a pre-signed URL to a VST, good for 10 minutes
  • [build] compute: send a code file through a compile-and-validation cycle to see where it works

Detect

  • [service] create-endpoint: register a new endpoint on your Account
  • [admin] delete-endpoint: delete a probe from your account
  • [executive] activity: display aggregate results from your endpoints
  • [executive] probes: view all endpoint probes currently associated to your account
  • [admin] queue: display the tests in your active queue
  • [admin] disable-test: remove a test from your active queue
  • [admin] enable-test: add a test to your active queue, so it will be picked up by applicable endpoints
  • [executive] observe: mark a result as observed in your SIEM
  • [executive] social-stats: show global pass/fail numbers for a given test
  • [executive] rules: print out the full list of Verified Security Rules