For interacting with the Chariot API
Project description
Praetorian CLI and SDK
:link: Chariot Platform :book: Documentation :bookmark: PyPI :computer: Chariot UI
Table of Contents
- Description
- Getting Started
- Using the CLI
- Developer SDK
- Extending the CLI with script plugins
- Contributing
- Support
- License
Description
Praetorian CLI and SDK are open-source tools for interacting with our products and services. Currently, they support
access to Chariot, our
offensive security platform.
The SDK exposes the full set of APIs that the Chariot UI uses.
The CLI is a fully-featured companion to the Chariot UI.
Getting Started
Prerequisites
- Python v3.8 or above
- pip v23.0 or above
Installation
Install the Python package using this command:
pip install praetorian-cli
Signing up
- Register for an account for Chariot using the instructions in our documentation.
- Download the keychain file using this link.
- Place the keychain file at
~/.praetorian/keychain.ini
. - Add your username and password to the keychain file. Your file should read like this:
[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
Authentication in organizations that use SSO
SSO-enabled accounts can use CLI by inviting password-based accounts as collaborators.
These collaborator accounts can assume into the main account using the --account
option
in the CLI, or including that information in the keychain file. For example, you can assume
into the security.team@acme.com
main account using the account entry:
[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
account = security.team@acme.com
There are two common approaches to manage CLI access in SSO organizations:
- Sign up a service account for CLI access, e.g. security.team+cli@acme.com. In the master account, invite security-team+cli@acme.com as a collaborator. All CLI users share the keychain for the service account.
- Add each CLI user as a collaborator in the master account. Every CLI user signs up using password-based authentication.
We recommend the first approach.
Using the CLI
The CLI is a command and option utility for access to the full suite of Chariot API. See documentation for commands
using the help
option:
praetorian chariot --help
As an example, run the following command to retrieve the list of all assets in your account:
praetorian chariot list assets
To get detailed information about a specific asset, run:
praetorian chariot get asset <ASSET_KEY>
To try one of our plugin scripts, run:
praetorian chariot get asset <ASSET_KEY> --plugin list_assets
For more examples, visit our documentation.
Using plugins
The CLI has a plugin engine for implementing more complex workflows.
There are two types of plugins:
- Scripts: Invoked using the
--plugin
option, they perform additional processing on the data returned by the CLI command. - Commands: Invoked using the
plugin <plugin_name>
command, they are standalone commands that extend the CLI with a relatively complex workflow.
Examples of plugin scripts
For example, this command uses my-process-domain.py
to further process the data from praetorian chariot get asset
:
praetorian chariot get asset <ASSET_KEY> --plugin ~/code/my-process-domain.py
The CLI also comes with some built-in scripts in this directory. They are invoked by name:
praetorian chariot get asset <ASSET_KEY> --plugin list_assets
Examples of plugin commands
Plugin commands add end-to-end functions as commands grouped under plugin
. To see a list
of them:
praetorian chariot plugin --help
Different Praetorian teams extend the CLI using plugin commands. For example this command is used by our team in the creation of client reports using internal templates:
praetorian chariot plugin report
You can find the list of plugin commands that comes with the CLI in this directory
If you have ideas on new plugin commands and scripts, contribute them!
For developing plugins, you can refer to this readme file.
Developer SDK
The Praetorian SDK is installed along with the praetorian-cli
package. Integrate the SDK into your
own Python application with the following steps:
- Include the dependency
praetorian-cli
in your project. - Import the Chariot class
from praetorian_cli.sdk.chariot import Chariot
. - Import the Keychain class
from praetorian_cli.sdk.keychain import Keychain
. - 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('asset', dict(name='example.com', dns='example.com', seed=True))
The best place to explore the SDK is the handlers of the CLI
Contributing
We welcome contributions from the community, from plugins, to the core CLI and SDK. To contribute, fork this repository and following the GitHub instructions to create pull requests.
By contributing, you agree to our Code of Conduct.
Support
If you have any questions or need support, please open an issue here or reach out via support@praetorian.com.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for praetorian_cli-1.2.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e861a3d512c5f9a360efbdc18eff1a1aaed32d5d1c066f64d71ee404b5ce2adf |
|
MD5 | 111408a1287a3bd11248708510772ee2 |
|
BLAKE2b-256 | b5092d205c00d529612fc2a08e480018b75f47c6522f466ff5660e426308822c |