Skip to main content

tracebit-python

PyPI Python License transrights enbyware pluralmade

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:

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

How It Works

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

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

Apache License 2.0

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)

Source distribution for tracebit-python 0.1.2
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)

Table of built distributions (wheels) for tracebit-python 0.1.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page