tracebit-python
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.
Installation
pip install tracebit-python
Or from source:
git clone https://github.com/SiteRelEnby/tracebit-python
cd tracebit-python
pip install -e .
Quick Start
1. Get an API token
Log in to community.tracebit.com and create an API token from the web UI.
2. Configure
tracebit configure
# paste your API token when prompted
Or use an environment variable:
export TRACEBIT_API_TOKEN=your-token-here
3. Deploy canaries
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.
4. Test it
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.
5. Keep credentials fresh
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
Commands
tracebit configure [TOKEN]
Save an API token to ~/.config/tracebit/token. Reads from argument, stdin,
or interactive prompt.
tracebit deploy aws
Issue and deploy canary AWS credentials.
| Option | Default | Description |
|---|---|---|
--name |
hostname | Credential name (shown on Tracebit dashboard) |
--profile |
staging |
AWS profile name in ~/.aws/credentials |
--region |
from API | AWS region |
--labels |
Metadata as key=value pairs |
|
--force |
Replace existing profile (expires old canary first) |
tracebit deploy ssh
Issue and deploy a canary SSH private key.
| Option | Default | Description |
|---|---|---|
--name |
hostname | Credential name (shown on Tracebit dashboard) |
--key-file |
from API | Key filename in ~/.ssh/ |
--ssh-host |
honeypot IP | Hostname alias for ~/.ssh/config Host entry |
--ssh-config-file |
~/.ssh/config |
SSH config file to write Host entry into |
--labels |
Metadata as key=value pairs |
|
--force |
Replace existing key/config entry |
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).
tracebit refresh
Re-issue any credentials expiring within the given threshold. Designed to run from cron.
| Option | Default | Description |
|---|---|---|
--hours |
2 |
Refresh credentials expiring within this many hours |
tracebit trigger aws
Test-fire an AWS canary by calling aws sts get-caller-identity with the canary
profile. Requires the AWS CLI to be installed.
| Option | Default | Description |
|---|---|---|
--name |
first found | Credential name to trigger |
tracebit trigger ssh
Test-fire an SSH canary by connecting to Tracebit's honeypot with the canary key.
| Option | Default | Description |
|---|---|---|
--name |
first found | Credential name to trigger |
tracebit show
Display deployed canary credentials, their profiles/keys, and expiration status.
tracebit remove
Remove canary credentials locally and expire them on Tracebit's server.
| Option | Default | Description |
|---|---|---|
--name |
all | Name of credential to remove |
tracebit install-cron
Print or install a cron job that runs tracebit refresh --quiet on a schedule.
| Option | Default | Description |
|---|---|---|
--schedule |
*/30 * * * * |
Cron schedule expression |
--install |
Add entry to current user's crontab | |
--system |
Write /etc/cron.d/tracebit (requires root) |
Global Options
| Option | Description |
|---|---|
--token TOKEN |
API token (overrides env var and config file) |
--base-url URL |
Override Tracebit API URL |
--json |
JSON output (where supported) |
-q / --quiet |
Suppress informational output (errors still go to stderr) |
Token Resolution
The API token is resolved in this order:
--tokencommand-line flagTRACEBIT_API_TOKENenvironment variable~/.config/tracebit/tokenfile
How It Works
AWS canaries:
- Issue — requests canary AWS credentials from the Tracebit API
- Deploy — writes them to
~/.aws/credentialsand~/.aws/config - Confirm — tells Tracebit the credentials are live
- 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:
- Issue — requests a canary SSH private key from the Tracebit API
- Deploy — writes the key to
~/.ssh/<key-file>and adds aHostblock to~/.ssh/configpointing the chosen hostname at Tracebit's honeypot - Confirm — tells Tracebit the key is deployed
- Alert — any SSH connection attempt presenting this key to the honeypot fires a detection
File Permissions
~/.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
License
Metadata
Release files for tracebit-python 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tracebit_python-0.1.2.tar.gz | 24.8 kB | With provenance | Details for tracebit_python-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tracebit_python-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for tracebit_python-0.1.2-py3-none-any.whl |
Total release size: 44.9 kB
Release files / tracebit_python-0.1.2.tar.gz
| Download URL | tracebit_python-0.1.2.tar.gz |
|---|---|
| Size | 24.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2991523b597d783906e56846878fa90a8d873609a2d90b10f974d70f8a482531
|
|
BLAKE2b-256 checksum How to use checksums |
2ccb358344c0c99747586e1b8a4706460c0ad86cbefc3a52d761aef72e92f42e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 5, 2026.
Transparency logRelease files / tracebit_python-0.1.2-py3-none-any.whl
| Download URL | tracebit_python-0.1.2-py3-none-any.whl |
|---|---|
| Size | 20.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fa815a37626344d344b9af2133eb2ac936a6efed8a79a76c8a22ab9ed2ac1751
|
|
BLAKE2b-256 checksum How to use checksums |
a2209a68f9ac3ec5cd246558c9c0a9112c2729a26f894ea2838cbc0521d6bfc0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 5, 2026.
Transparency logSecurity for tracebit-python 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tracebit_python-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.