threatcluster-cli 0.1.0__tar.gz

threatcluster_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish threatcluster-cli to PyPI
+
+# Triggered on a tag push like v0.1.0. The tag must match the version in
+# pyproject.toml; the build step fails fast if they drift.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Verify tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF#refs/tags/v}"
+          pkg_version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$tag" != "$pkg_version" ]; then
+            echo "::error ::tag $tag does not match pyproject version $pkg_version"
+            exit 1
+          fi
+
+      - name: Build
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    # The protected `pypi` environment can require manual approval — see
+    # repo Settings -> Environments. Recommended.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/threatcluster-cli
+    permissions:
+      # OIDC token for PyPI Trusted Publishing — no API token stored anywhere.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

threatcluster_cli-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Test threatcluster-cli
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install -e ".[test]"
+      - name: Run tests
+        run: pytest -q

threatcluster_cli-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Caches
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.mypy_cache/
+.ruff_cache/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Editor
+.idea/
+.vscode/
+*.swp
+.DS_Store

threatcluster_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `threatcluster-cli` (the `tc` command) are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning follows [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — TBD
+
+### Added
+- Initial release.
+- `tc auth login | status | logout` — paste-token credential flow with
+  OS-keyring storage (Keychain / SecretService / Credential Manager) and
+  0600-file fallback.
+- Read commands: `tc threats {list,get,iocs,stix}`, `tc iocs {feed,export}`,
+  `tc entities {search,get,related,trending}`, `tc vulns {list,get}`,
+  `tc darkweb {ransomware victims, breaches, keyword-hits}`,
+  `tc feeds {list,get}`.
+- Write command: `tc alerts ack <id>` (only write in v1; idempotent).
+- Bearer-JWT auth model with in-process caching, ~30s pre-expiry refresh,
+  one-shot 401 retry.
+- Plaintext-HTTP rejection to non-loopback hosts.
+- `Authorization` and `X-API-Key` redaction from debug logs.
+- Subprocess auth-env hygiene (`TC_PROPAGATE_AUTH=1` to opt in).
+- `--api-key` flag rejected (process-table leak prevention).

threatcluster_cli-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: threatcluster-cli
+Version: 0.1.0
+Summary: Command-line client for ThreatCluster (`tc`)
+Author: ThreatCluster
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: keyring<26.0,>=24.0
+Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# threatcluster-cli
+
+Command-line client for ThreatCluster. Installs the `tc` command.
+
+## Install
+
+Once published to PyPI:
+
+```
+pipx install threatcluster-cli
+```
+
+Until then, install from source:
+
+```
+git clone <this-repo>
+pipx install ./tc-testing/cli
+```
+
+See `PUBLISHING.md` for the PyPI publish flow.
+
+## Authenticate
+
+```
+tc auth login
+```
+
+This runs an Auth0 device-code flow and mints a scoped `tc_agent_*` refresh
+credential, storing it in your OS keyring (Keychain / SecretService /
+Credential Manager). On headless systems it falls back to a 0600 file at
+`~/.config/tc-cli/credentials`.
+
+## Use
+
+All commands print JSON. Pipe through `jq` for human reading.
+
+```
+tc threats list --limit 5 | jq '.threats[].title'
+tc entities search "lazarus" --type apt_group
+tc darkweb ransomware victims --days 7
+```
+
+## Cookbook
+
+Worked examples for common analyst / agent flows.
+
+### Smart search
+
+`tc search` merges entity hits and threat clusters into one shape so you don't
+have to know which sub-command applies.
+
+```
+tc search "Volt Typhoon" --limit 5
+tc search lockbit --only entities
+tc search cisco --only threats --limit 20
+```
+
+### Stdin chaining
+
+Any command that takes an `id`/`identifier` accepts `-` to read ids from stdin.
+Compose freely:
+
+```
+# IOCs for the top 5 trending threats
+tc threats list --limit 5 \
+  | jq -r '.threats[].cluster_id' \
+  | tc threats iocs - \
+  | jq -r '.iocs[]'
+
+# STIX export of every threat tagged "ransomware"
+tc threats list --query ransomware --limit 50 \
+  | jq -r '.threats[].cluster_id' \
+  | tc threats stix -
+
+# Open every CVE in your browser (xdg-open / open)
+tc vulns list --severity CRITICAL --limit 5 \
+  | jq -r '.cves[].cve_id' \
+  | xargs -I{} echo "https://nvd.nist.gov/vuln/detail/{}"
+```
+
+### Live feeds (`--watch`)
+
+Poll an endpoint and emit only new items as NDJSON. Ctrl+C to stop.
+
+```
+# New ransomware victims as they're posted
+tc darkweb ransomware victims --watch --interval 60
+
+# Pipe live victims into a Slack webhook
+tc darkweb ransomware victims --watch \
+  | while read line; do
+      echo "$line" | jq -r '"new victim: \(.group): \(.name)"' \
+        | curl -X POST -d @- "$SLACK_WEBHOOK_URL"
+    done
+
+# Watch new threats matching a keyword
+tc threats list --query lockbit --watch --interval 30
+```
+
+### Per-session containment for sub-agents
+
+Hand a child process a narrower bearer than your own. The server enforces
+the subset — the child cannot escalate.
+
+```
+# Read-only sub-agent with a 50-request budget per session
+TC_SCOPES=threats:read \
+TC_SESSION_ID="$(uuidgen)" \
+TC_MAX_REQUESTS=50 \
+  tc threats list --limit 5
+```
+
+### Auth diagnostics
+
+```
+tc auth status -v        # storage backend, bearer jti, key id
+tc auth logout           # hard kill: revokes server-side too
+tc auth logout --keep-remote   # local-only clear (you're moving the key)
+```
+
+### Shell completion
+
+```
+tc --install-completion bash      # or zsh / fish
+exec $SHELL                       # restart your shell
+tc thr<TAB>                       # completes to `tc threats`
+```
+
+## Environment
+
+| Var                   | Purpose                                                      |
+|-----------------------|--------------------------------------------------------------|
+| `TC_API_URL`          | Override API base (default `https://api.threatcluster.io`).  |
+| `TC_REFRESH_TOKEN`    | Refresh credential (overrides keyring + file). For CI only.  |
+| `TC_SCOPES`           | Comma-separated subset of refresh scopes for the bearer.     |
+| `TC_PROPAGATE_AUTH`   | Set to `1` to propagate auth env to subprocesses.            |
+| `TC_DEBUG`            | Set to `1` for verbose stderr (auth headers redacted).       |
+
+## Security notes
+
+- Refresh credential is never sent on argv (`--api-key` flag is rejected).
+- Bearer JWTs (15 min ttl) are minted on demand and cached only in memory.
+- The CLI refuses to talk to plaintext `http://` URLs except `127.0.0.1`/`localhost`.
+- Auth env vars are scrubbed from subprocess environments unless
+  `TC_PROPAGATE_AUTH=1` is set.

threatcluster_cli-0.1.0/PUBLISHING.md

@@ -0,0 +1,97 @@
+# Publishing `threatcluster-cli` to PyPI
+
+The PyPI project is `threatcluster-cli`; it installs the `tc` console script.
+
+One-time setup (Phases 1–3), then every release is `git tag` + `git push --tags`.
+
+## One-time setup
+
+### 1. Reserve the name on PyPI
+
+1. Sign in / sign up at https://pypi.org.
+2. Enable 2FA (PyPI requires it for publishing).
+3. You don't need to upload a placeholder — Trusted Publishing creates the
+   project on first successful publish. You're claiming the name by being the
+   first to publish to it.
+
+### 2. Configure Trusted Publishing on PyPI
+
+PyPI → your account → **Publishing** → **Add a new pending publisher**:
+
+| Field            | Value                                                        |
+|------------------|--------------------------------------------------------------|
+| PyPI project     | `threatcluster-cli`                                          |
+| Owner            | the GitHub org or user that holds this repo                  |
+| Repository name  | `threatcluster-cli`                                          |
+| Workflow filename| `publish.yml`                                         |
+| Environment name | `pypi`                                                       |
+
+This binds PyPI to a specific GitHub Actions workflow in a specific repo.
+No API token is created or stored.
+
+### 3. Create the GitHub `pypi` environment
+
+Repo → **Settings** → **Environments** → **New environment** → name it `pypi`.
+
+Highly recommended: enable **Required reviewers** and add yourself. Every
+publish then pauses for a manual click — cheap insurance against an
+accidental tag push.
+
+Optionally restrict to tags matching `v*.*.*` under **Deployment branches**.
+
+## Every release
+
+1. Bump `version` in `cli/pyproject.toml`.
+2. Move the corresponding section in `cli/CHANGELOG.md` from `[Unreleased]`
+   to a dated `[X.Y.Z] - YYYY-MM-DD` heading.
+3. Commit and tag:
+   ```bash
+   git commit -am "threatcluster-cli vX.Y.Z"
+   git tag vX.Y.Z
+   git push && git push --tags
+   ```
+4. The publish workflow fires. It refuses to publish if the tag and the
+   `pyproject.toml` version disagree.
+5. Approve the deploy in the **Actions** tab (if you set up Required
+   reviewers).
+6. After the workflow finishes, `pipx install threatcluster-cli==X.Y.Z`
+   works for anyone.
+
+## What lives where
+
+- `cli/pyproject.toml` — package metadata, version, deps, console script (`tc`).
+- `cli/CHANGELOG.md` — release notes (Keep-a-Changelog format).
+- `.github/workflows/publish.yml` — tag-triggered build + publish.
+- `.github/workflows/test.yml` — pytest on push/PR.
+
+## Repo layout
+
+This repo is the entire `threatcluster-cli` Python package. `python -m build`
+at the repo root produces a self-contained wheel. Tests live in `tests/`.
+
+## Yanking a bad release
+
+PyPI → project → Manage → Releases → **Yank**. Yank doesn't delete the file
+(downloads still work for pinned versions) but hides it from `pip install`
+without a version pin. Always prefer yank over delete.
+
+## TestPyPI dry run (optional, recommended for first release)
+
+TestPyPI is a sandbox — same flow, throwaway:
+
+1. Sign up at https://test.pypi.org/ (separate account from PyPI).
+2. Add a **pending publisher** there with the same settings as Phase 2.
+3. Temporarily edit the publish step in `publish.yml`:
+   ```yaml
+   - uses: pypa/gh-action-pypi-publish@release/v1
+     with:
+       packages-dir: dist/
+       repository-url: https://test.pypi.org/legacy/
+   ```
+4. Tag a pre-release: `git tag v0.1.0rc1 && git push --tags`.
+5. After it succeeds, install from TestPyPI:
+   ```bash
+   pipx install --pip-args="--index-url https://test.pypi.org/simple/" \
+     threatcluster-cli==0.1.0rc1
+   ```
+6. If happy, revert the workflow change.

threatcluster_cli-0.1.0/README.md

@@ -0,0 +1,145 @@
+# threatcluster-cli
+
+Command-line client for ThreatCluster. Installs the `tc` command.
+
+## Install
+
+Once published to PyPI:
+
+```
+pipx install threatcluster-cli
+```
+
+Until then, install from source:
+
+```
+git clone <this-repo>
+pipx install ./tc-testing/cli
+```
+
+See `PUBLISHING.md` for the PyPI publish flow.
+
+## Authenticate
+
+```
+tc auth login
+```
+
+This runs an Auth0 device-code flow and mints a scoped `tc_agent_*` refresh
+credential, storing it in your OS keyring (Keychain / SecretService /
+Credential Manager). On headless systems it falls back to a 0600 file at
+`~/.config/tc-cli/credentials`.
+
+## Use
+
+All commands print JSON. Pipe through `jq` for human reading.
+
+```
+tc threats list --limit 5 | jq '.threats[].title'
+tc entities search "lazarus" --type apt_group
+tc darkweb ransomware victims --days 7
+```
+
+## Cookbook
+
+Worked examples for common analyst / agent flows.
+
+### Smart search
+
+`tc search` merges entity hits and threat clusters into one shape so you don't
+have to know which sub-command applies.
+
+```
+tc search "Volt Typhoon" --limit 5
+tc search lockbit --only entities
+tc search cisco --only threats --limit 20
+```
+
+### Stdin chaining
+
+Any command that takes an `id`/`identifier` accepts `-` to read ids from stdin.
+Compose freely:
+
+```
+# IOCs for the top 5 trending threats
+tc threats list --limit 5 \
+  | jq -r '.threats[].cluster_id' \
+  | tc threats iocs - \
+  | jq -r '.iocs[]'
+
+# STIX export of every threat tagged "ransomware"
+tc threats list --query ransomware --limit 50 \
+  | jq -r '.threats[].cluster_id' \
+  | tc threats stix -
+
+# Open every CVE in your browser (xdg-open / open)
+tc vulns list --severity CRITICAL --limit 5 \
+  | jq -r '.cves[].cve_id' \
+  | xargs -I{} echo "https://nvd.nist.gov/vuln/detail/{}"
+```
+
+### Live feeds (`--watch`)
+
+Poll an endpoint and emit only new items as NDJSON. Ctrl+C to stop.
+
+```
+# New ransomware victims as they're posted
+tc darkweb ransomware victims --watch --interval 60
+
+# Pipe live victims into a Slack webhook
+tc darkweb ransomware victims --watch \
+  | while read line; do
+      echo "$line" | jq -r '"new victim: \(.group): \(.name)"' \
+        | curl -X POST -d @- "$SLACK_WEBHOOK_URL"
+    done
+
+# Watch new threats matching a keyword
+tc threats list --query lockbit --watch --interval 30
+```
+
+### Per-session containment for sub-agents
+
+Hand a child process a narrower bearer than your own. The server enforces
+the subset — the child cannot escalate.
+
+```
+# Read-only sub-agent with a 50-request budget per session
+TC_SCOPES=threats:read \
+TC_SESSION_ID="$(uuidgen)" \
+TC_MAX_REQUESTS=50 \
+  tc threats list --limit 5
+```
+
+### Auth diagnostics
+
+```
+tc auth status -v        # storage backend, bearer jti, key id
+tc auth logout           # hard kill: revokes server-side too
+tc auth logout --keep-remote   # local-only clear (you're moving the key)
+```
+
+### Shell completion
+
+```
+tc --install-completion bash      # or zsh / fish
+exec $SHELL                       # restart your shell
+tc thr<TAB>                       # completes to `tc threats`
+```
+
+## Environment
+
+| Var                   | Purpose                                                      |
+|-----------------------|--------------------------------------------------------------|
+| `TC_API_URL`          | Override API base (default `https://api.threatcluster.io`).  |
+| `TC_REFRESH_TOKEN`    | Refresh credential (overrides keyring + file). For CI only.  |
+| `TC_SCOPES`           | Comma-separated subset of refresh scopes for the bearer.     |
+| `TC_PROPAGATE_AUTH`   | Set to `1` to propagate auth env to subprocesses.            |
+| `TC_DEBUG`            | Set to `1` for verbose stderr (auth headers redacted).       |
+
+## Security notes
+
+- Refresh credential is never sent on argv (`--api-key` flag is rejected).
+- Bearer JWTs (15 min ttl) are minted on demand and cached only in memory.
+- The CLI refuses to talk to plaintext `http://` URLs except `127.0.0.1`/`localhost`.
+- Auth env vars are scrubbed from subprocess environments unless
+  `TC_PROPAGATE_AUTH=1` is set.

threatcluster_cli-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "threatcluster-cli"
+version = "0.1.0"
+description = "Command-line client for ThreatCluster (`tc`)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ThreatCluster" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "typer>=0.12,<1.0",
+  "httpx>=0.27,<1.0",
+  "pydantic>=2.6,<3.0",
+  "keyring>=24.0,<26.0",
+]
+
+[project.scripts]
+tc = "tc_cli.main:_run"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["tc_cli"]

threatcluster_cli-0.1.0/tc_cli/__init__.py

@@ -0,0 +1,2 @@
+"""ThreatCluster CLI."""
+__version__ = "0.1.0"