tracebit-python 0.1.0__tar.gz → 0.1.2__tar.gz

{tracebit_python-0.1.0/src/tracebit_python.egg-info → tracebit_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracebit-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: CLI for managing Tracebit canary credentials on headless servers
 License: Apache-2.0
 Project-URL: Repository, https://github.com/SiteRelEnby/tracebit-python
@@ -21,6 +21,8 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
 Dynamic: license-file
 
 # tracebit-python
@@ -74,33 +76,46 @@ Or use an environment variable:
 export TRACEBIT_API_TOKEN=your-token-here
 ```
 
-### 3. Deploy a canary
+### 3. Deploy canaries
+
+**AWS credentials:**
 
 ```bash
 tracebit deploy aws --profile staging
 ```
 
-This issues canary AWS credentials from Tracebit, writes them to
-`~/.aws/credentials` under the specified profile, and confirms the
-deployment. If anyone (or anything) uses these credentials, Tracebit
-fires an alert.
+Writes canary AWS credentials to `~/.aws/credentials` under the given profile.
+Any AWS API call using these credentials triggers an alert.
+
+**SSH key:**
+
+```bash
+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
 
 ```bash
-tracebit trigger aws
+tracebit trigger aws    # uses aws sts get-caller-identity
+tracebit trigger ssh    # connects to Tracebit's honeypot
 ```
 
-Runs `aws sts get-caller-identity` against the canary profile. You should
-see an alert on the Tracebit dashboard within a few minutes.
+You should see an alert on the Tracebit dashboard within a few minutes.
 
 ### 5. Keep credentials fresh
 
-Canary credentials expire after ~24 hours. Set up a cron job to refresh them:
+Canary credentials expire after ~12 hours. Set up a cron job:
 
 ```bash
-# crontab -e
-0 */12 * * * /path/to/tracebit refresh
+tracebit install-cron           # prints a ready-to-paste crontab line
+tracebit install-cron --install # adds it to your crontab automatically
 ```
 
 ## Commands
@@ -122,8 +137,25 @@ Issue and deploy canary AWS credentials.
 | `--labels` | | Metadata as `key=value` pairs |
 | `--force` | | Replace existing profile (expires old canary first) |
 
-Choose a realistic profile name — `staging`, `backup`, `legacy-admin`, etc.
-The whole point is for these to look like real credentials to an attacker.
+### `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`
 
@@ -132,23 +164,28 @@ from cron.
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--hours` | `13` | Refresh credentials expiring within this many hours |
-
-With 24h credentials and a 12h cron, the default of 13 hours ensures every
-cron run refreshes credentials.
+| `--hours` | `2` | Refresh credentials expiring within this many hours |
 
 ### `tracebit trigger aws`
 
-Test-fire a canary by calling `aws sts get-caller-identity` with the canary
+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, and expiration status.
+Display deployed canary credentials, their profiles/keys, and expiration status.
 
 ### `tracebit remove`
 
@@ -158,6 +195,16 @@ Remove canary credentials locally and expire them on Tracebit's server.
 |--------|---------|-------------|
 | `--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 |
@@ -165,6 +212,7 @@ Remove canary credentials locally and expire them on Tracebit's server.
 | `--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
 
@@ -176,22 +224,32 @@ The API token is resolved in this order:
 
 ## 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`
-   under the chosen profile name
-3. **Confirm** — tells Tracebit the credentials were deployed, so it starts
-   monitoring for usage
-4. **Alert** — any AWS API call using these credentials triggers a detection
-   on the Tracebit dashboard
+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 (by an attacker who found them on disk,
-in a config file, etc.) is logged and alerted on.
+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`
 

{tracebit_python-0.1.0 → tracebit_python-0.1.2}/README.md

@@ -49,33 +49,46 @@ Or use an environment variable:
 export TRACEBIT_API_TOKEN=your-token-here
 ```
 
-### 3. Deploy a canary
+### 3. Deploy canaries
+
+**AWS credentials:**
 
 ```bash
 tracebit deploy aws --profile staging
 ```
 
-This issues canary AWS credentials from Tracebit, writes them to
-`~/.aws/credentials` under the specified profile, and confirms the
-deployment. If anyone (or anything) uses these credentials, Tracebit
-fires an alert.
+Writes canary AWS credentials to `~/.aws/credentials` under the given profile.
+Any AWS API call using these credentials triggers an alert.
+
+**SSH key:**
+
+```bash
+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
 
 ```bash
-tracebit trigger aws
+tracebit trigger aws    # uses aws sts get-caller-identity
+tracebit trigger ssh    # connects to Tracebit's honeypot
 ```
 
-Runs `aws sts get-caller-identity` against the canary profile. You should
-see an alert on the Tracebit dashboard within a few minutes.
+You should see an alert on the Tracebit dashboard within a few minutes.
 
 ### 5. Keep credentials fresh
 
-Canary credentials expire after ~24 hours. Set up a cron job to refresh them:
+Canary credentials expire after ~12 hours. Set up a cron job:
 
 ```bash
-# crontab -e
-0 */12 * * * /path/to/tracebit refresh
+tracebit install-cron           # prints a ready-to-paste crontab line
+tracebit install-cron --install # adds it to your crontab automatically
 ```
 
 ## Commands
@@ -97,8 +110,25 @@ Issue and deploy canary AWS credentials.
 | `--labels` | | Metadata as `key=value` pairs |
 | `--force` | | Replace existing profile (expires old canary first) |
 
-Choose a realistic profile name — `staging`, `backup`, `legacy-admin`, etc.
-The whole point is for these to look like real credentials to an attacker.
+### `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`
 
@@ -107,23 +137,28 @@ from cron.
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--hours` | `13` | Refresh credentials expiring within this many hours |
-
-With 24h credentials and a 12h cron, the default of 13 hours ensures every
-cron run refreshes credentials.
+| `--hours` | `2` | Refresh credentials expiring within this many hours |
 
 ### `tracebit trigger aws`
 
-Test-fire a canary by calling `aws sts get-caller-identity` with the canary
+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, and expiration status.
+Display deployed canary credentials, their profiles/keys, and expiration status.
 
 ### `tracebit remove`
 
@@ -133,6 +168,16 @@ Remove canary credentials locally and expire them on Tracebit's server.
 |--------|---------|-------------|
 | `--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 |
@@ -140,6 +185,7 @@ Remove canary credentials locally and expire them on Tracebit's server.
 | `--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
 
@@ -151,22 +197,32 @@ The API token is resolved in this order:
 
 ## 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`
-   under the chosen profile name
-3. **Confirm** — tells Tracebit the credentials were deployed, so it starts
-   monitoring for usage
-4. **Alert** — any AWS API call using these credentials triggers a detection
-   on the Tracebit dashboard
+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 (by an attacker who found them on disk,
-in a config file, etc.) is logged and alerted on.
+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`
 

{tracebit_python-0.1.0 → tracebit_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tracebit-python"
-version = "0.1.0"
+version = "0.1.2"
 description = "CLI for managing Tracebit canary credentials on headless servers"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -28,6 +28,9 @@ classifiers = [
 ]
 dependencies = ["requests>=2.20"]
 
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
 [project.urls]
 Repository = "https://github.com/SiteRelEnby/tracebit-python"
 Issues = "https://github.com/SiteRelEnby/tracebit-python/issues"
@@ -37,3 +40,6 @@ tracebit = "tracebit.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tracebit_python-0.1.2/src/tracebit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

{tracebit_python-0.1.0 → tracebit_python-0.1.2}/src/tracebit/aws.py

@@ -10,6 +10,14 @@ CONFIG_FILE = AWS_DIR / "config"
 
 def _ensure_aws_dir():
     AWS_DIR.mkdir(mode=0o700, exist_ok=True)
+    mode = AWS_DIR.stat().st_mode & 0o777
+    if mode != 0o700:
+        import sys
+        print(
+            f"Warning: ~/.aws/ has permissions {oct(mode)} (expected 0700). "
+            f"Consider running: chmod 700 ~/.aws",
+            file=sys.stderr,
+        )
 
 
 def _read_ini(path):