threatcluster-cli 0.1.0__py3-none-any.whl

tc_cli/__init__.py

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

tc_cli/client.py

@@ -0,0 +1,225 @@
+"""HTTP client for threatcluster-cli (the `tc` command).
+
+Responsibilities:
+  - Resolve API base URL; refuse plaintext to non-loopback hosts.
+  - Mint a bearer JWT from the refresh credential and cache it in-process
+    until ~30s before expiry.
+  - Send Authorization: Bearer on data calls.
+  - Strip auth headers from any logged request.
+  - Reject the --api-key flag (callers must use env / keyring / file).
+"""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import sys
+import time
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+import httpx
+
+from . import credentials
+
+logger = logging.getLogger("tc_cli")
+
+DEFAULT_BASE = "https://api.threatcluster.io"
+
+# Headers we never want to see in logs.
+_REDACT_HEADERS = {"authorization", "x-api-key"}
+
+
+class CLIError(Exception):
+    """Surface a clean error message to the user without a traceback."""
+
+
+def _is_loopback(host: str) -> bool:
+    return host in {"localhost", "127.0.0.1", "::1"}
+
+
+def _resolve_base() -> str:
+    base = os.environ.get("TC_API_URL", DEFAULT_BASE).rstrip("/")
+    parsed = urlparse(base)
+    if parsed.scheme == "http" and not _is_loopback(parsed.hostname or ""):
+        raise CLIError(
+            f"refusing plaintext HTTP to non-loopback host: {base!r}. "
+            "Use https:// or set TC_API_URL=http://127.0.0.1:..."
+        )
+    if parsed.scheme not in {"http", "https"}:
+        raise CLIError(f"TC_API_URL must be http(s): {base!r}")
+    return base
+
+
+def _redact_request_for_log(request: httpx.Request) -> dict:
+    headers = {
+        k: ("<redacted>" if k.lower() in _REDACT_HEADERS else v)
+        for k, v in request.headers.items()
+    }
+    return {"method": request.method, "url": str(request.url), "headers": headers}
+
+
+def _decode_bearer_exp(token: str) -> int:
+    """Pull `exp` out of a JWT without verifying signature. Used only for
+    cache TTL — the server is the only authority on validity."""
+    try:
+        payload_b64 = token.split(".")[1]
+        # JWT base64url, no padding
+        padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(padded))
+        return int(payload.get("exp", 0))
+    except Exception:
+        return 0
+
+
+class TCClient:
+    """Synchronous httpx wrapper. One per process."""
+
+    def __init__(self, base: Optional[str] = None) -> None:
+        self.base = base or _resolve_base()
+        self._refresh: Optional[str] = None
+        self._bearer: Optional[str] = None
+        self._bearer_exp: int = 0
+        # Strict TLS: system trust store. No pinning (plan §6).
+        self._http = httpx.Client(timeout=30.0, follow_redirects=False)
+
+    # -- credential plumbing -------------------------------------------------
+
+    def _get_refresh(self) -> str:
+        if self._refresh:
+            return self._refresh
+        token = credentials.load()
+        if not token:
+            raise CLIError(
+                "no refresh credential — run `tc auth login` first."
+            )
+        self._refresh = token
+        return token
+
+    def set_refresh(self, token: str) -> None:
+        self._refresh = token
+        self._bearer = None
+        self._bearer_exp = 0
+
+    # -- bearer mint ---------------------------------------------------------
+
+    def _mint_bearer(self) -> str:
+        refresh = self._get_refresh()
+        body: dict[str, Any] = {}
+        scope_override = os.environ.get("TC_SCOPES")
+        if scope_override:
+            body["scopes"] = [s.strip() for s in scope_override.split(",") if s.strip()]
+        if os.environ.get("TC_SESSION_ID"):
+            body["session_id"] = os.environ["TC_SESSION_ID"]
+        if os.environ.get("TC_MAX_REQUESTS"):
+            try:
+                body["max_requests"] = int(os.environ["TC_MAX_REQUESTS"])
+            except ValueError:
+                raise CLIError("TC_MAX_REQUESTS must be an integer")
+
+        try:
+            resp = self._http.post(
+                f"{self.base}/api/auth/agent/token",
+                headers={"X-API-Key": refresh, "Content-Type": "application/json"},
+                content=json.dumps(body),
+            )
+        except httpx.ConnectError as e:
+            raise CLIError(
+                f"could not reach {self.base}: {e}. "
+                "Set TC_API_URL to your backend (e.g. http://localhost:8000)."
+            )
+        except httpx.TimeoutException as e:
+            raise CLIError(f"timed out contacting {self.base}: {e}")
+        except httpx.RequestError as e:
+            raise CLIError(f"network error contacting {self.base}: {e}")
+        if resp.status_code != 200:
+            raise CLIError(self._format_error(resp))
+        token = resp.json()["access_token"]
+        self._bearer = token
+        self._bearer_exp = _decode_bearer_exp(token)
+        return token
+
+    def _bearer_is_fresh(self) -> bool:
+        if not self._bearer:
+            return False
+        # Refresh ~30s early so we don't race the server clock.
+        return self._bearer_exp - int(time.time()) > 30
+
+    def _bearer_token(self) -> str:
+        if self._bearer_is_fresh():
+            return self._bearer  # type: ignore[return-value]
+        return self._mint_bearer()
+
+    # -- error formatting ----------------------------------------------------
+
+    @staticmethod
+    def _format_error(resp: httpx.Response) -> str:
+        try:
+            j = resp.json()
+            detail = j.get("detail", j)
+            if isinstance(detail, dict):
+                msg = detail.get("message") or detail.get("error") or str(detail)
+                return f"HTTP {resp.status_code}: {msg}"
+            return f"HTTP {resp.status_code}: {detail}"
+        except Exception:
+            return f"HTTP {resp.status_code}: {resp.text[:200]}"
+
+    # -- request -------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        json_body: Optional[dict] = None,
+        auth: bool = True,
+    ) -> Any:
+        url = f"{self.base}{path}"
+        headers = {"Accept": "application/json"}
+        if auth:
+            headers["Authorization"] = f"Bearer {self._bearer_token()}"
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        if os.environ.get("TC_DEBUG") == "1":
+            req = self._http.build_request(method, url, params=params, headers=headers,
+                                           content=json.dumps(json_body) if json_body is not None else None)
+            print(json.dumps(_redact_request_for_log(req)), file=sys.stderr)
+
+        try:
+            resp = self._http.request(
+                method, url,
+                params=params, headers=headers,
+                content=json.dumps(json_body) if json_body is not None else None,
+            )
+            # Bearer expired between cache refresh and request — mint once and retry.
+            if resp.status_code == 401 and auth:
+                self._bearer = None
+                self._bearer_exp = 0
+                headers["Authorization"] = f"Bearer {self._bearer_token()}"
+                resp = self._http.request(
+                    method, url,
+                    params=params, headers=headers,
+                    content=json.dumps(json_body) if json_body is not None else None,
+                )
+        except httpx.ConnectError as e:
+            raise CLIError(
+                f"could not reach {self.base}: {e}. "
+                "Set TC_API_URL to your backend (e.g. http://localhost:8000)."
+            )
+        except httpx.TimeoutException as e:
+            raise CLIError(f"timed out contacting {self.base}: {e}")
+        except httpx.RequestError as e:
+            raise CLIError(f"network error contacting {self.base}: {e}")
+
+        if resp.status_code >= 400:
+            raise CLIError(self._format_error(resp))
+        if resp.headers.get("content-type", "").startswith("application/json"):
+            return resp.json()
+        return resp.text
+
+    def get(self, path: str, **kw):  return self.request("GET",  path, **kw)
+    def post(self, path: str, **kw): return self.request("POST", path, **kw)
+    def delete(self, path: str, **kw): return self.request("DELETE", path, **kw)

tc_cli/commands/auth.py

@@ -0,0 +1,160 @@
+"""tc auth — login, status, logout.
+
+v1 login flow is paste-token: the user mints an agent key in the web UI
+(Settings -> API keys -> "Mint agent key"), copies it once, and pastes it
+here. The CLI stores it in keyring (or a 0600 file), validates it by
+minting one bearer, and is ready to use.
+
+We deliberately avoid implementing the Auth0 device-code flow until the
+server-side endpoints for it are wired and tested — see plan §2.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+
+from .. import credentials
+from ..client import CLIError, TCClient
+from ..output import emit
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("login")
+def login(
+    paste: bool = typer.Option(
+        True,
+        "--paste/--no-paste",
+        help="Paste a refresh credential minted from the web UI.",
+    ),
+) -> None:
+    """Store a refresh credential for future commands."""
+    if not paste:
+        raise typer.BadParameter("--no-paste login is not implemented in v1.")
+
+    typer.echo(
+        "1. Visit https://threatcluster.io/settings?tab=cli\n"
+        "2. Click \"Mint key\", choose scopes, copy the key.\n"
+        "3. Paste it below (input hidden).",
+        err=True,
+    )
+    token = typer.prompt("refresh token", hide_input=True, err=True)
+    token = token.strip()
+    if not (token.startswith("tc_agent_") or token.startswith("tc_live_")):
+        typer.secho(
+            "rejected: token must start with 'tc_agent_' or 'tc_live_'.",
+            fg=typer.colors.RED, err=True,
+        )
+        raise typer.Exit(2)
+
+    # Validate by minting one bearer.
+    client = TCClient()
+    client.set_refresh(token)
+    try:
+        client._mint_bearer()  # raises CLIError on failure
+    except CLIError as e:
+        typer.secho(f"validation failed: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    where = credentials.save(token)
+    typer.secho(f"saved to {where}.", fg=typer.colors.GREEN, err=True)
+
+
+def _decode_bearer_claims(bearer: str) -> dict:
+    import base64, json as _json
+    payload_b64 = bearer.split(".")[1]
+    padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+    return _json.loads(base64.urlsafe_b64decode(padded))
+
+
+@app.command("status")
+def status(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Include storage backend details and bearer cache state."),
+) -> None:
+    """Show current credential status (no secret values printed)."""
+    try:
+        token = credentials.load()
+    except credentials.CredentialError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(2)
+
+    if not token:
+        emit({"authenticated": False})
+        return
+
+    client = TCClient()
+    client.set_refresh(token)
+    bearer = client._mint_bearer()
+    claims = _decode_bearer_claims(bearer)
+
+    out = {
+        "authenticated": True,
+        "storage": "env" if os.environ.get(credentials.ENV_VAR) else "keyring_or_file",
+        "token_prefix": token[:12] + "…",
+        "key_id": claims.get("kid"),
+        "scopes": claims.get("scopes", []),
+        "org_id": claims.get("org_id"),
+        "org_name": claims.get("org_name"),
+        "bearer_expires_in": claims.get("exp", 0) - claims.get("iat", 0),
+        "api_url": client.base,
+    }
+
+    if verbose:
+        # Storage detail — best-effort; some keyring backends expose name.
+        backend = "env" if os.environ.get(credentials.ENV_VAR) else None
+        if backend is None:
+            kr = credentials._keyring()
+            if kr is not None:
+                try:
+                    backend = f"keyring:{type(kr.get_keyring()).__name__}"
+                except Exception:
+                    backend = "keyring:unknown"
+            else:
+                backend = f"file:{credentials.CRED_FILE}"
+        out["storage_detail"] = backend
+        out["bearer_jti"] = claims.get("jti")
+        out["bearer_session_id"] = claims.get("session_id")
+        out["bearer_max_requests"] = claims.get("max_requests")
+
+    emit(out)
+
+
+@app.command("logout")
+def logout(
+    keep_remote: bool = typer.Option(
+        False, "--keep-remote",
+        help="Clear local credential only; leave the key valid server-side.",
+    ),
+) -> None:
+    """Revoke the credential server-side and clear local storage.
+
+    Default: hard logout — the credential dies everywhere. Pass --keep-remote
+    if you only want to clear this machine (e.g. you're moving the key).
+    """
+    try:
+        token = credentials.load()
+    except credentials.CredentialError:
+        token = None
+
+    revoked = None
+    if token and not keep_remote:
+        client = TCClient()
+        client.set_refresh(token)
+        try:
+            client.post("/api/auth/agent/self-revoke")
+            revoked = True
+        except CLIError as e:
+            typer.secho(f"server-side revoke failed: {e}", fg=typer.colors.YELLOW, err=True)
+            revoked = False
+
+    credentials.clear()
+    msg = "local credential cleared"
+    if revoked is True:
+        msg += "; server-side revoked"
+    elif revoked is False:
+        msg += "; server-side revoke FAILED — revoke at https://threatcluster.io/settings?tab=cli"
+    elif keep_remote:
+        msg += " (--keep-remote: server-side credential still valid)"
+    typer.secho(msg, fg=typer.colors.GREEN if revoked is not False else typer.colors.YELLOW, err=True)

tc_cli/commands/cluster.py

@@ -0,0 +1,48 @@
+"""tc cluster — analyst-pivot helpers.
+
+Today: `tc cluster open <id>` prints (and optionally opens) the web URL.
+Future: `tc cluster timeline`, `tc cluster compare`, etc.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import typer
+
+from ..stdin_helper import expand_id
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+def _web_base() -> str:
+    api = os.environ.get("TC_API_URL", "https://api.threatcluster.io").rstrip("/")
+    # Convention: web frontend is the same origin minus an `api.` subdomain.
+    if "://api." in api:
+        return api.replace("://api.", "://", 1)
+    return api  # local dev (http://localhost:8000) serves both
+
+
+@app.command("open")
+def cluster_open(
+    identifier: str,
+    no_browser: bool = typer.Option(False, "--no-browser", help="Print URL only, don't open."),
+) -> None:
+    """Print (and open) the web URL for a cluster. Pass `-` for stdin ids."""
+    base = _web_base()
+    for ident in expand_id(identifier):
+        url = f"{base}/threat/{ident}"
+        print(url)
+        if no_browser:
+            continue
+        # Best-effort opener; silent if not available (CI, headless).
+        for opener in ("xdg-open", "open"):
+            try:
+                subprocess.Popen(
+                    [opener, url],
+                    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                )
+                break
+            except FileNotFoundError:
+                continue

tc_cli/commands/darkweb.py

@@ -0,0 +1,67 @@
+"""tc darkweb — ransomware, breaches, keyword-hits."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+ransomware = typer.Typer(no_args_is_help=True, add_completion=False)
+app.add_typer(ransomware, name="ransomware")
+
+
+@ransomware.command("victims")
+def ransomware_victims(
+    ctx: typer.Context,
+    group: Optional[str] = typer.Option(None, "--group", help="Filter by ransomware group (e.g. lockbit, akira)."),
+    days: int = typer.Option(30, "--days", min=1, max=90),
+    limit: int = typer.Option(50, "--limit", "-n", min=1, max=500),
+    watch: bool = typer.Option(False, "--watch", help="Poll forever and emit new victims as NDJSON."),
+    interval: float = typer.Option(60.0, "--interval"),
+) -> None:
+    """List ransomware victims. Use --watch for a live feed."""
+    params: dict = {"limit": limit, "days": days}
+    if group: params["group"] = group
+    c = _client(ctx)
+    if watch:
+        from ..watch import watch_loop
+        watch_loop(
+            fetch=lambda: c.get("/api/public/v1/darkweb/ransomware/victims", params=params),
+            extract=lambda r: r.get("victims") or [],
+            dedupe_key="id",
+            interval=interval,
+        )
+        return
+    emit(c.get("/api/public/v1/darkweb/ransomware/victims", params=params))
+
+
+@app.command("breaches")
+def breaches(
+    ctx: typer.Context,
+    since: Optional[str] = typer.Option(None, "--since"),
+    watch: bool = typer.Option(False, "--watch", help="Poll forever and emit new breaches as NDJSON."),
+    interval: float = typer.Option(60.0, "--interval"),
+) -> None:
+    """List dark-web breaches. Use --watch for a live feed."""
+    params: dict = {}
+    if since: params["since"] = since
+    c = _client(ctx)
+    if watch:
+        from ..watch import watch_loop
+        watch_loop(
+            fetch=lambda: c.get("/api/public/v1/darkweb/breaches", params=params),
+            extract=lambda r: r.get("breaches") or [],
+            dedupe_key="id",
+            interval=interval,
+        )
+        return
+    emit(c.get("/api/public/v1/darkweb/breaches", params=params))
+
+
+@app.command("keyword-hits")
+def keyword_hits(ctx: typer.Context) -> None:
+    emit(_client(ctx).get("/api/public/v1/darkweb/keyword-hits"))

tc_cli/commands/entities.py

@@ -0,0 +1,41 @@
+"""tc entities — search, get, related, trending."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("search")
+def entities_search(
+    ctx: typer.Context,
+    query: str,
+    type: Optional[str] = typer.Option(None, "--type"),
+) -> None:
+    params = {"q": query}
+    if type: params["type"] = type
+    emit(_client(ctx).get("/api/public/v1/entities/search", params=params))
+
+
+@app.command("get")
+def entities_get(ctx: typer.Context, type: str, value: str) -> None:
+    emit(_client(ctx).get(f"/api/public/v1/entities/{type}/{value}"))
+
+
+@app.command("related")
+def entities_related(ctx: typer.Context, type: str, value: str) -> None:
+    emit(_client(ctx).get(f"/api/public/v1/entities/{type}/{value}/related"))
+
+
+@app.command("trending")
+def entities_trending(
+    ctx: typer.Context,
+    window: str = typer.Option("24h", "--window"),
+) -> None:
+    emit(_client(ctx).get("/api/public/v1/entities/trending",
+                                  params={"window": window}))

tc_cli/commands/feeds.py

@@ -0,0 +1,23 @@
+"""tc feeds — list, get."""
+from __future__ import annotations
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+from ..stdin_helper import expand_id
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("list")
+def feeds_list(ctx: typer.Context) -> None:
+    emit(_client(ctx).get("/api/public/v1/feeds"))
+
+
+@app.command("get")
+def feeds_get(ctx: typer.Context, feed_id: str) -> None:
+    """Get a feed's entities. Pass `-` to read feed ids from stdin."""
+    c = _client(ctx)
+    for fid in expand_id(feed_id):
+        emit(c.get(f"/api/public/v1/feeds/{fid}/entities"))

tc_cli/commands/iocs.py

@@ -0,0 +1,41 @@
+"""tc iocs — feed, export."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("feed")
+def ioc_feed(
+    ctx: typer.Context,
+    type: Optional[str] = typer.Option(None, "--type", help="ip, domain, sha256, url, ..."),
+    since: Optional[str] = typer.Option(None, "--since"),
+) -> None:
+    """Stream IOC feed. Server returns one IOC per line as text/plain."""
+    params: dict = {}
+    if type: params["type"] = type
+    if since: params["since"] = since
+    result = _client(ctx).get("/api/public/v1/iocs/feed", params=params)
+    # Endpoint returns text/plain (one IOC per line). Print raw, not JSON.
+    if isinstance(result, str):
+        import sys; sys.stdout.write(result if result.endswith("\n") else result + "\n")
+    else:
+        emit(result)
+
+
+@app.command("export")
+def ioc_export(
+    ctx: typer.Context,
+    fmt: str = typer.Option("json", "--format", help="json, csv, stix"),
+) -> None:
+    result = _client(ctx).get("/api/public/v1/iocs/export", params={"format": fmt})
+    if isinstance(result, str):
+        import sys; sys.stdout.write(result if result.endswith("\n") else result + "\n")
+    else:
+        emit(result)

tc_cli/commands/search.py

@@ -0,0 +1,61 @@
+"""tc search — smart router across entities + threats.
+
+Single command (no sub-commands) so flags like --limit parse cleanly.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+
+# A bare Typer with one default callback is the cleanest "command with args"
+# shape that still composes via add_typer in main.py.
+app = typer.Typer(no_args_is_help=False, add_completion=False)
+
+
+def search(
+    ctx: typer.Context,
+    query: str = typer.Argument(..., help="Search term."),
+    limit: int = typer.Option(10, "--limit", "-n", min=1, max=100),
+    only: Optional[str] = typer.Option(
+        None, "--only",
+        help="Restrict to one source: entities | threats",
+    ),
+) -> None:
+    """Search threats and entities, merged. Use `--only entities|threats` to narrow."""
+    c = _client(ctx)
+    out: list = []
+
+    if only in (None, "entities"):
+        try:
+            r = c.get("/api/public/v1/entities/search", params={"q": query})
+            for e in (r.get("entities") or r.get("results") or []):
+                out.append({
+                    "kind": "entity",
+                    "type": e.get("entity_type") or e.get("type") or e.get("category"),
+                    "value": e.get("entity_value") or e.get("value") or e.get("name"),
+                    "score": e.get("score") or e.get("relevance") or e.get("article_count"),
+                    "raw": e,
+                })
+        except Exception as e:
+            out.append({"kind": "error", "source": "entities", "message": str(e)})
+
+    if only in (None, "threats"):
+        try:
+            r = c.get("/api/public/v1/threats", params={"keyword": query, "limit": limit})
+            for t in (r.get("threats") or []):
+                out.append({
+                    "kind": "threat",
+                    "id": t.get("cluster_id"),
+                    "title": t.get("ai_title") or t.get("title"),
+                    "score": t.get("threat_score"),
+                    "summary": (t.get("ai_summary") or "")[:200],
+                })
+        except Exception as e:
+            out.append({"kind": "error", "source": "threats", "message": str(e)})
+
+    out = out[:limit]
+    emit({"query": query, "count": len(out), "results": out})

tc_cli/commands/threats.py

@@ -0,0 +1,75 @@
+"""tc threats — list, get, iocs, stix."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+from ..stdin_helper import expand_id
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("list")
+def list_threats(
+    ctx: typer.Context,
+    query: Optional[str] = typer.Option(None, "--query", "-q"),
+    since: Optional[str] = typer.Option(None, "--since", help="ISO date or relative (e.g. 24h)"),
+    limit: int = typer.Option(20, "--limit", "-n", min=1, max=200),
+    watch: bool = typer.Option(False, "--watch", help="Poll forever and emit new clusters as NDJSON."),
+    interval: float = typer.Option(60.0, "--interval", help="Watch poll interval (seconds)."),
+) -> None:
+    """List threat clusters."""
+    params: dict = {"limit": limit}
+    if query: params["keyword"] = query
+    if since: params["since"] = since
+    c = _client(ctx)
+    if watch:
+        from ..watch import watch_loop
+        watch_loop(
+            fetch=lambda: c.get("/api/public/v1/threats", params=params),
+            extract=lambda r: r.get("threats") or [],
+            dedupe_key="cluster_id",
+            interval=interval,
+        )
+        return
+    emit(c.get("/api/public/v1/threats", params=params))
+
+
+@app.command("get")
+def get_threat(ctx: typer.Context, identifier: str) -> None:
+    """Get one threat cluster by id or short_id. Pass `-` to read ids from stdin."""
+    c = _client(ctx)
+    for ident in expand_id(identifier):
+        emit(c.get(f"/api/public/v1/threats/{ident}"))
+
+
+@app.command("iocs")
+def threat_iocs(
+    ctx: typer.Context,
+    identifier: str,
+    types: str = typer.Option("all", "--types"),
+    fmt: str = typer.Option("json", "--format"),
+) -> None:
+    """List IOCs for a threat cluster. Pass `-` to read ids from stdin."""
+    c = _client(ctx)
+    for ident in expand_id(identifier):
+        emit(c.get(
+            f"/api/public/v1/threats/{ident}/iocs",
+            params={"types": types, "format": fmt},
+        ))
+
+
+@app.command("stix")
+def threat_stix(ctx: typer.Context, identifier: str) -> None:
+    """STIX 2.1 export. Pass `-` to read ids from stdin."""
+    import sys
+    c = _client(ctx)
+    for ident in expand_id(identifier):
+        result = c.get(f"/api/public/v1/threats/{ident}/stix")
+        if isinstance(result, str):
+            sys.stdout.write(result if result.endswith("\n") else result + "\n")
+        else:
+            emit(result)

tc_cli/commands/vulns.py

@@ -0,0 +1,46 @@
+"""tc vulns — list, get."""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import client as _client
+from ..output import emit
+from ..stdin_helper import expand_id
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+@app.command("list")
+def vulns_list(
+    ctx: typer.Context,
+    severity: Optional[str] = typer.Option(None, "--severity"),
+    since: Optional[str] = typer.Option(None, "--since"),
+    limit: int = typer.Option(20, "--limit", "-n", min=1, max=200),
+    watch: bool = typer.Option(False, "--watch", help="Poll forever and emit new CVEs as NDJSON."),
+    interval: float = typer.Option(120.0, "--interval", help="CVE feed updates slowly; default 2 min."),
+) -> None:
+    """List CVEs. Use --watch for a live feed."""
+    params: dict = {"limit": limit}
+    if severity: params["severity"] = severity
+    if since: params["since"] = since
+    c = _client(ctx)
+    if watch:
+        from ..watch import watch_loop
+        watch_loop(
+            fetch=lambda: c.get("/api/public/v1/vulnerabilities", params=params),
+            extract=lambda r: r.get("cves") or [],
+            dedupe_key="cve_id",
+            interval=interval,
+        )
+        return
+    emit(c.get("/api/public/v1/vulnerabilities", params=params))
+
+
+@app.command("get")
+def vulns_get(ctx: typer.Context, cve_id: str) -> None:
+    """Get one CVE. Pass `-` to read CVE ids from stdin."""
+    c = _client(ctx)
+    for cid in expand_id(cve_id):
+        emit(c.get(f"/api/public/v1/vulnerabilities/{cid}"))

tc_cli/context.py

@@ -0,0 +1,16 @@
+"""Helper for command modules to lazily fetch the shared TCClient.
+
+Lives in its own module to avoid circular imports between main.py and
+the command modules.
+"""
+from __future__ import annotations
+
+import typer
+
+from .client import TCClient
+
+
+def client(ctx: typer.Context) -> TCClient:
+    if ctx.obj.get("client") is None:
+        ctx.obj["client"] = TCClient()
+    return ctx.obj["client"]

tc_cli/credentials.py

@@ -0,0 +1,102 @@
+"""Refresh-credential storage.
+
+Storage priority on read:
+    1. TC_REFRESH_TOKEN env var (intended for CI / one-shot)
+    2. OS keyring (default for interactive use)
+    3. 0600 file at ~/.config/tc-cli/credentials (fallback when keyring is
+       unavailable, e.g. headless Linux without a secret service)
+
+Storage on write: keyring if available, otherwise 0600 file.
+"""
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+from typing import Optional
+
+KEYRING_SERVICE = "tc-cli"
+KEYRING_USER = "default"
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))) / "tc-cli"
+CRED_FILE = CONFIG_DIR / "credentials"
+ENV_VAR = "TC_REFRESH_TOKEN"
+
+
+class CredentialError(Exception):
+    """Raised on storage policy violations (bad file mode, missing keyring)."""
+
+
+def _keyring():
+    try:
+        import keyring  # type: ignore
+        return keyring
+    except Exception:
+        return None
+
+
+def load() -> Optional[str]:
+    """Return the refresh credential, or None if absent. Raises on bad mode."""
+    val = os.environ.get(ENV_VAR)
+    if val:
+        return val
+
+    kr = _keyring()
+    if kr is not None:
+        try:
+            v = kr.get_password(KEYRING_SERVICE, KEYRING_USER)
+            if v:
+                return v
+        except Exception:
+            # keyring backend may be present but unusable; fall through to file
+            pass
+
+    if CRED_FILE.exists():
+        st = CRED_FILE.stat()
+        if (st.st_mode & 0o777) != 0o600:
+            raise CredentialError(
+                f"{CRED_FILE} has insecure mode {oct(st.st_mode & 0o777)}; "
+                "run `chmod 0600` on it or delete and re-login."
+            )
+        if hasattr(os, "geteuid") and st.st_uid != os.geteuid():
+            raise CredentialError(
+                f"{CRED_FILE} is not owned by the current user; refusing to load."
+            )
+        return CRED_FILE.read_text().strip() or None
+    return None
+
+
+def save(refresh_token: str) -> str:
+    """Persist the refresh credential. Returns 'keyring' or path of file used."""
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.set_password(KEYRING_SERVICE, KEYRING_USER, refresh_token)
+            return "keyring"
+        except Exception:
+            pass
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    # Write atomically with strict mode from the start.
+    tmp = CRED_FILE.with_suffix(".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, refresh_token.encode())
+    finally:
+        os.close(fd)
+    os.replace(str(tmp), str(CRED_FILE))
+    return str(CRED_FILE)
+
+
+def clear() -> None:
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.delete_password(KEYRING_SERVICE, KEYRING_USER)
+        except Exception:
+            pass
+    if CRED_FILE.exists():
+        try:
+            CRED_FILE.unlink()
+        except Exception:
+            pass

tc_cli/main.py

@@ -0,0 +1,80 @@
+"""tc — ThreatCluster CLI entrypoint."""
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+
+from .client import CLIError, TCClient
+from .commands import (
+    auth as auth_cmd,
+    cluster as cluster_cmd,
+    darkweb as darkweb_cmd,
+    entities as entities_cmd,
+    feeds as feeds_cmd,
+    iocs as iocs_cmd,
+    search as search_cmd,
+    threats as threats_cmd,
+    vulns as vulns_cmd,
+)
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=True,  # exposes --install-completion / --show-completion
+    pretty_exceptions_enable=False,  # we handle our own; tracebacks leak detail
+    help="Command-line client for ThreatCluster.",
+)
+
+app.add_typer(auth_cmd.app,     name="auth",     help="Authentication.")
+app.add_typer(threats_cmd.app,  name="threats",  help="Threat clusters.")
+app.add_typer(iocs_cmd.app,     name="iocs",     help="Indicators of Compromise.")
+app.add_typer(entities_cmd.app, name="entities", help="Entities (actors, malware, tools).")
+app.add_typer(vulns_cmd.app,    name="vulns",    help="Vulnerabilities (CVEs).")
+app.add_typer(darkweb_cmd.app,  name="darkweb",  help="Dark web (ransomware, breaches, markets).")
+app.add_typer(feeds_cmd.app,    name="feeds",    help="Custom intel feeds.")
+app.add_typer(cluster_cmd.app,  name="cluster",  help="Analyst pivots: open cluster URLs, etc.")
+
+# `tc search <query>` is a flat command, not a sub-group, so flags parse cleanly.
+app.command("search", help="Smart search across threats + entities.")(search_cmd.search)
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    api_key: str = typer.Option(
+        None,
+        "--api-key",
+        hidden=True,
+        help="REJECTED: pass refresh credential via TC_REFRESH_TOKEN env or `tc auth login`.",
+    ),
+):
+    """Build a single TCClient and stash on ctx.obj."""
+    if api_key is not None:
+        # Refuse rather than silently use it — argv leaks via /proc/<pid>/cmdline.
+        typer.secho(
+            "--api-key is not supported (process-table leak). "
+            "Set TC_REFRESH_TOKEN or run `tc auth login`.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    # Subprocess hygiene: by default, do not propagate auth env to children.
+    if os.environ.get("TC_PROPAGATE_AUTH") != "1":
+        for k in ("TC_REFRESH_TOKEN",):
+            os.environ.pop(k + "_PROPAGATE", None)
+
+    ctx.obj = {"client": None}  # client is built lazily by commands that need it
+
+
+def _run() -> None:
+    try:
+        app()
+    except CLIError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    _run()

tc_cli/output.py

@@ -0,0 +1,9 @@
+"""JSON output. No table mode in v1 (plan §6 cuts)."""
+import json
+import sys
+from typing import Any
+
+
+def emit(data: Any) -> None:
+    json.dump(data, sys.stdout, default=str, indent=2, sort_keys=True)
+    sys.stdout.write("\n")

tc_cli/stdin_helper.py

@@ -0,0 +1,34 @@
+"""Stdin helpers for command chaining.
+
+Convention: any command that takes a positional `id`/`identifier` accepts the
+literal `-` to mean "read whitespace-separated ids from stdin." Each input is
+yielded one at a time so the command can fan out.
+
+Used like:
+    tc threats list --json | jq -r '.threats[].cluster_id' | tc threats get -
+"""
+from __future__ import annotations
+
+import sys
+from typing import Iterable
+
+
+def expand_id(arg: str) -> Iterable[str]:
+    """Yield ids: a single literal, or many from stdin if arg == '-'.
+
+    For multi-id stdin we strip JSON quoting and ignore blanks/comments.
+    """
+    if arg != "-":
+        yield arg
+        return
+    if sys.stdin.isatty():
+        # Friendlier than waiting silently for input.
+        raise SystemExit(
+            "error: '-' was given but stdin is a TTY. "
+            "Pipe ids in, e.g. `echo cluster-uuid | tc threats get -`."
+        )
+    for raw in sys.stdin.read().splitlines():
+        line = raw.strip().strip('",[] ')
+        if not line or line.startswith("#"):
+            continue
+        yield line

tc_cli/watch.py

@@ -0,0 +1,51 @@
+"""--watch helper: re-poll a list endpoint and emit only new items.
+
+Dedupe key is configurable per command (cluster_id, cve_id, victim_id, ...).
+On Ctrl+C, exits cleanly.
+
+Polling cadence default is 60s — high enough to be polite to the server,
+low enough that an analyst keeping a tab open feels live.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import time
+from typing import Any, Callable, Iterable
+
+
+def watch_loop(
+    *,
+    fetch: Callable[[], Any],     # returns parsed response
+    extract: Callable[[Any], Iterable[dict]],  # returns the items list
+    dedupe_key: str,              # key on each item
+    interval: float = 60.0,
+) -> None:
+    seen: set = set()
+    first = True
+    try:
+        while True:
+            try:
+                resp = fetch()
+                items = list(extract(resp) or [])
+            except Exception as e:
+                print(f"watch: fetch failed: {e}", file=sys.stderr)
+                time.sleep(interval)
+                continue
+
+            new = [it for it in items if it.get(dedupe_key) not in seen]
+            for it in items:
+                key = it.get(dedupe_key)
+                if key is not None:
+                    seen.add(key)
+
+            # First tick: emit nothing (just seed). Subsequent: emit new items only.
+            if not first:
+                for it in new:
+                    json.dump(it, sys.stdout, default=str)
+                    sys.stdout.write("\n")
+                    sys.stdout.flush()
+            first = False
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        sys.exit(0)

threatcluster_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+tc_cli/__init__.py,sha256=cm1f22oWXay_2lVBv7rce-GxIwLHSbpIxHY9_xnEp_c,47
+tc_cli/client.py,sha256=hz9aWGKZEj1wuLtXRxO84xF8-0xOfZwDjip54HLvoUw,8302
+tc_cli/context.py,sha256=XGlEKS8HHbqMzGhLX__HSDcsTVR5kJDORnIAf8KVdCM,394
+tc_cli/credentials.py,sha256=tLOMawKnNTD33UeaTlOBHkJJQZ1_LNqxdQHy2uOvpz8,2963
+tc_cli/main.py,sha256=zUSG_dK1dXFHdoAMoWO7dGUlux-_C1Z00tSksgerJOY,2673
+tc_cli/output.py,sha256=7j6ATCwXLv8GxyC_qGXw2pf_5SorY5CnOnjYu9WuENw,231
+tc_cli/stdin_helper.py,sha256=uidPp8Rdi2N-LaQG5f7x3GXk3I9Etftaqekoo0d2dis,1081
+tc_cli/watch.py,sha256=jo6vc5K8TlrnrW1D2qMxx17JUnLvvSfluWnRCg2ypJ8,1611
+tc_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tc_cli/commands/auth.py,sha256=v1qrq0_60lxmx7gAOWRX3b8K8XsA8pUs8BCPr66-W4I,5384
+tc_cli/commands/cluster.py,sha256=YftwUqEP2J3wJhg9hxWo6FL3SPfX62odlDN2NWYdMiE,1479
+tc_cli/commands/darkweb.py,sha256=9xho-fEbroyMmsR7IfCx3x-YcEKTW80Sh_nn6toEhe0,2371
+tc_cli/commands/entities.py,sha256=NCXOi2cQF-_aDxwIW5WUm1SIveLepkukWDMaw3KWLcA,1150
+tc_cli/commands/feeds.py,sha256=ZbMDJqk9rSSAOCcTvIQJlZ0Y-Pdy6DZ0iFRVu1DiISw,630
+tc_cli/commands/iocs.py,sha256=WPYQflMaDadz_5xJo1OuxxZf3G8RIY4w6q6cnAsAcRI,1317
+tc_cli/commands/search.py,sha256=UWd8Wup9XDTQ-OnBccqwC0_oUQRqVXwvZJL_RqB5s9U,2299
+tc_cli/commands/threats.py,sha256=kdAq_iSeYPOdUXJlhJJptNAuLQeN8DQoVx6Ov0mHv5E,2501
+tc_cli/commands/vulns.py,sha256=-P1DVyreBuGTcXzGwzrqZeabHyyr9t1TRarnyQeZnLc,1550
+threatcluster_cli-0.1.0.dist-info/METADATA,sha256=0MkQpXQkOzJtttJabUKW0s7Y7SNPi9eIr2qtHfcAOhM,4695
+threatcluster_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+threatcluster_cli-0.1.0.dist-info/entry_points.txt,sha256=CoNnm1CriTmauH1ywlcTibsVA7k7PbrNfLhasvgNzRE,40
+threatcluster_cli-0.1.0.dist-info/RECORD,,

threatcluster_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

threatcluster_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tc = tc_cli.main:_run