Python CLI for deploying Tracebit canary credentials on headless servers.

Tracebit provides canary tokens — fake credentials that trigger alerts when used by an attacker. Their official CLI requires browser-based OAuth, which doesn't work on headless servers. This tool uses the Tracebit API directly with pre-generated API tokens.

pip install tracebit-python

Or from source:

git clone https://github.com/SiteRelEnby/tracebit-python
cd tracebit-python
pip install -e .

Log in to community.tracebit.com and create an API token from the web UI.

tracebit configure
# paste your API token when prompted

Or use an environment variable:

export TRACEBIT_API_TOKEN=your-token-here

AWS credentials:

tracebit deploy aws --profile staging

Writes canary AWS credentials to ~/.aws/credentials under the given profile. Any AWS API call using these credentials triggers an alert.

SSH key:

tracebit deploy ssh --key-file id_backup --ssh-host backup-server.internal

Writes a canary SSH private key to ~/.ssh/id_backup and adds a Host block to ~/.ssh/config pointing backup-server.internal at Tracebit's honeypot. Any SSH connection attempt using this key triggers an alert.

Choose names that look realistic to an attacker — staging, id_backup, backup-server.internal. The whole point is that they look like real credentials.

tracebit trigger aws    # uses aws sts get-caller-identity
tracebit trigger ssh    # connects to Tracebit's honeypot

You should see an alert on the Tracebit dashboard within a few minutes.

Canary credentials expire after ~12 hours. Set up a cron job:

tracebit install-cron           # prints a ready-to-paste crontab line
tracebit install-cron --install # adds it to your crontab automatically

Save an API token to ~/.config/tracebit/token. Reads from argument, stdin, or interactive prompt.

Issue and deploy canary AWS credentials.

Issue and deploy a canary SSH private key.

The --ssh-host alias is what makes the canary effective: an attacker finding ~/.ssh/config with Host backup-server.internal pointing somewhere will try to connect there, firing the alert. If omitted, the honeypot IP is used directly.

Use --ssh-config-file if your ~/.ssh/config is tracked in git and you keep local overrides in a separate file (e.g. ~/.ssh/config.local).

Re-issue any credentials expiring within the given threshold. Designed to run from cron.

Test-fire an AWS canary by calling aws sts get-caller-identity with the canary profile. Requires the AWS CLI to be installed.

Test-fire an SSH canary by connecting to Tracebit's honeypot with the canary key.

Display deployed canary credentials, their profiles/keys, and expiration status.

Remove canary credentials locally and expire them on Tracebit's server.

Print or install a cron job that runs tracebit refresh --quiet on a schedule.

The API token is resolved in this order:

1. --token command-line flag
2. TRACEBIT_API_TOKEN environment variable
3. ~/.config/tracebit/token file

AWS canaries:

1. Issue — requests canary AWS credentials from the Tracebit API
2. Deploy — writes them to ~/.aws/credentials and ~/.aws/config
3. Confirm — tells Tracebit the credentials are live
4. Alert — any AWS API call using these credentials fires a detection

The credentials have an explicit deny policy — they can't actually do anything in AWS. But any attempt to use them is logged and alerted on.

SSH canaries:

1. Issue — requests a canary SSH private key from the Tracebit API
2. Deploy — writes the key to ~/.ssh/<key-file> and adds a Host block to ~/.ssh/config pointing the chosen hostname at Tracebit's honeypot
3. Confirm — tells Tracebit the key is deployed
4. Alert — any SSH connection attempt presenting this key to the honeypot fires a detection

• ~/.aws/ directory: 0700
• ~/.aws/credentials, ~/.aws/config: 0600
• ~/.ssh/ directory: 0700
• ~/.ssh/<key-file>: 0600
• ~/.ssh/config: 0600
• ~/.config/tracebit/token: 0600
• ~/.config/tracebit/state.json: 0600

Apache License 2.0