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 command line and developer access to Chariot, our offensive security platform. The SDK exposes the full set of API 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
Using the CLI
The CLI is a command and option utility for access to the full suite of Chariot API. Get quick help
with the help
command:
praetorian chariot --help
As an example, run the following command to retrieve the list of all seeds in your account:
praetorian chariot list seeds
To get detailed information about a specific seed, run:
praetorian chariot get seed <SEED_KEY>
To try one of our plugin scripts, run:
praetorian chariot get assets --script hello-world
See the Contributing section for more information on how to add your own plugin scripts.
For more examples, visit our documentation.
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('seed', dict(dns='example.com', status='AS'))
You can see example usages of the SDK in the handlers of the CLI
For more examples and API documentation, visit our documentation.
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 run a script, add the --script
option after the CLI command, for example:
$ praetorian chariot list seeds --script ~/code/my-process-seeds.py
For built in scripts you only need the script name:
$ praetorian chariot get seed 'SEED_KEY' --script list-assets
To work with the plugin engine, the script needs to implement a process
function that takes 4 arguments:
controller
: This object holds the authentication context and provide functions for accessing the Chariot backend APIcmd
: 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 alist
command onassets
.cli_kwargs
: This dictionary contains the additional options the user provided to the CLI, such as--details
,--term
,--page
,ASSET_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:
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
andcli_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.
If you think your script will be useful for the offensive security community, contribute it!
Contributing
We welcome contributions from the community, from plugin scripts, 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 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.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 119e9d16940686ee17ac37c986501c50249ec1c46e32f6f898947b7c34dd6b03 |
|
MD5 | 46f4e2571f484cb4eea1c91b258362ee |
|
BLAKE2b-256 | 600c4d2110a6ae8bb249e1a2876249837cc988ebbe486b2909f22b92195432f1 |