In addition to our REST API, all Chariot functionality is accessible through our open-source command-line interface. The public GitHub repo is at https://github.com/praetorian-inc/praetorian-cli. Pre-built packages are officially hosted at https://pypi.org/project/praetorian-cli/.

Installation

Python 3.8+ and pip are required:

pip install praetorian-cli

If you have previously installed the CLI, use the following to upgrade to the latest version:

pip install --upgrade praetorian-cli

Authentication to Chariot

The CLI uses a keychain file to authenticate you to the system. Download the keychain template file from https://preview.chariot.praetorian.com/keychain.ini or copy it from the code block below:

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot

Add your username and password to the file. Your file should read something like this when you are done:

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot
username = lara.lynch@acme.com
password = 8epu9bQ2kqb8qwd.GR

The Praetorian CLI will read your keychain file from ~/.praetorian/keychain.ini. Place it there to continue using the CLI.

You can add multiple profiles to your keychain file, which takes a similar form to AWS CLI configuration files. For example: 

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot
username = lara.lynch@acme.com
password = 8epu9bQ2kqb8qwd.GR

[profile2]
...

[profile3]
...

Using the CLI

The CLI is configured as a simple command + option utility. View the help menu for all available commands:

$ praetorian chariot --help
Usage: praetorian chariot [OPTIONS] COMMAND [ARGS]...

Chariot API access in the new and different file

Options:
--help Show this message and exit.

Commands:
add Add a resource to Chariot
delete Delete a resource from Chariot
get Get resource details from Chariot
link Link an account or integration to Chariot
list Get a list of resources from Chariot
search Query the Chariot data store for arbitrary matches
test Run integration test suite
unlink Unlink an account or integration from Chariot
update Update a resource in Chariot

By default, the CLI will use the United States profile. Use the --profile option to specify a different profile.

Developer SDK

The Praetorian SDK is installed along with the praetorian-cli package. You may find the SDK useful for batching large tasks that would be infeasible to complete manually. See the examples below for adding metadata to assets.

Integrate the SDK into your own Python application with the following steps:

  1. Include the dependency praetorian-cli in your project.
  2. Import the Chariot class from praetorian_cli.sdk.chariot import Chariot.
  3. Import the Keychain class from praetorian_cli.sdk.keychain import Keychain.
  4. Call any function of the Chariot class, which expose the full backend API. See example below:
from praetorian_cli.sdk.chariot import Chariot
from praetorian_cli.sdk.keychain import Keychain

chariot = Chariot(Keychain())
chariot.add('seed', dict(dns='example.com', status='AS'))

You can inspect the code of the handlers of the CLI for example usage of the SDK.

 

Extending the CLI with script plugins

The CLI has a plugin engine for you to extend the CLI without changing its internals. Your script is imported to the CLI context so it has full and authenticated access to the SDK.

To write a script, clone this repository and install the CLI locally:

Place your scripts in the praetorian-cli/scripts/ directory in the cloned repository. There are also example scripts in the directory.

Your script needs to implement a process function that takes 4 arguments. They are:

  • controller: This object holds the authentication context and provide functions for accessing the Chariot backend API
  • cmd: This dictionary holds the information of which CLI command is executed. It tells you the product, action, and type of the CLI command. For example, you can use this to find out whether it is a list command on assets.
  • cli_kwargs: This dictionary contains the additional options the user provided to the CLI, such as --details--term--pageASSET_KEY, etc.
  • output: This is the raw output of the CLI.

Try out the hello-world script to have a concrete look at the content of those arguments, using the following command at the root directory of your cloned repository:

praetorian chariot list seeds --details --script hello-world

A typical script uses the arguments in the following manners:

 
  • Check for input correctness using information in cmd and cli_kwargs.
  • Parse the CLI output to extract relevant data.
  • Use the authenticated session in controller to further issue API calls to operate on the data.

See this in action in the list-assets.py and validate-secrets.py scripts.

 
 

More example usages of the CLI and SDK

CLI: Listing assets

You can use the CLI to list the entities in your Chariot account. A common use of CLI is to list all the risks and assets. Here is an example for assets:

praetorian chariot list assets

This command returns a list of asset keys. This is usually useful for quickly identifying whether a specific asset is in the attack surface. To get more details of each asset, which as when they were first discovered and when they were last seen, use the --details option.

praetorian chariot list assets --details

 

CLI: Paging through large result sets

When the result set of a list command is large, the CLI outputs an offset for the next page at the end of the outputs:

$ praetorian chariot list assets 
#asset#example.com#12.1.1.5
#asset#example.com#12.1.1.6
#asset#example.com#12.1.1.7
...
#asset#contoso.com#13.1.1.1
Next offset: { "key": "#asset#contoso.com#13.1.1.1", "username": "lara.lynch@pacme.com" }

You can then use the offset in your next invocation of the CLI to retrieve the next page's worth of results:

praetorian chariot list assets --offset '{ "key": "#asset#contoso.com#13.1.1.1", "username": "lara.lynch@pacme.com" }'

 

SDK: Adding metadata to assets

For example, given an input CSV containing additional metadata about a list of assets, the following script will add the new metadata to the associated asset as attributes:

import sys
import csv

from praetorian_cli.sdk.keychain import Keychain
from praetorian_cli.sdk.chariot import Chariot

filename = 'CSV_Filename' # e.g., ./asset_metadata.csv
profile = 'Keychain Profile' # e.g., "United States"

def main():
client = Chariot(Keychain(profile=profile))
with open(filename, newline='') as f:
reader = csv.DictReader(f)
for row in reader:
client.add('asset/attribute', {
'class': 'organization',
'name': row["organization"],
'key': f'#asset#{row["dns"]}#{row["ip"]}'
})


if __name__ == "__main__":
main()

Example CSV:

organization,dns,ip
imperium,nero.gladiator.systems,34.227.103.169
imperium,marcus.gladiator.systems,54.197.80.240
colosseum,gladiator.systems,3.82.24.233
colosseum,maximus.gladiator.systems,54.175.118.105
senatus,graccus.gladiator.systems,34.203.200.201
senatus,cicero.gladiator.systems,54.234.63.167