#!/usr/bin/env python3
"""threatera — the Threatera API from a terminal or a pipeline.

One file and the Python standard library (3.10 or newer); nothing to install.
Download it from your instance's guide, at /guide/threatera.py. Where a machine
has no Python — most Windows servers — the same program is served built, with
Python inside it, at /guide/collector/ (``threatera --version`` says
"standalone"); everything below applies to it, without the ``python3``.

    export THREATERA_URL=https://app.threatera.eu
    export THREATERA_KEY=ttk_...            # Organisation › API keys

    threatera upload invoice.exe --wait --fail-on malicious
    threatera file 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    threatera ioc evil-c2.example.com
    threatera blocklist 14 --format txt --type domain > blocked-domains.txt
    threatera inbox --mine
    threatera watch /srv/quarantine --name mail-gateway

`watch` keeps sending: every new file that appears in the folder is uploaded,
once, after asking which ones the organisation already holds (those are not
sent). It checks in every interval, so the Collectors page says when it stopped.
A mail message it finds (`.eml`, `.msg`, or a file that starts with mail
headers) goes to the mail analysis instead, and lands in the Email tab; `--mail`
sends every file that way, for a mail gateway's quarantine export.

`service` writes what keeps a collector running — a systemd unit, a launchd
daemon or a Windows scheduled task, started at boot and restarted when it
stops — and `save-key` puts its key in a file only the machine's
administrators can read, so the key is never on a command line:

    sudo python3 threatera.py save-key /etc/threatera/mail-gateway.key
    sudo python3 threatera.py --url https://app.threatera.eu \
        --key-file /etc/threatera/mail-gateway.key \
        service /srv/quarantine --name mail-gateway --install

`federate` joins your organisation's early warnings without uploading anything:
each value in a file (domains, IP addresses, SHA-256s, one a line) is blinded on
this machine, and what the platform stores is a token and a secret share it
cannot read. A value is revealed only once three organisations hold it, and
`warnings` lists those:

    threatera federate blocked-domains.txt
    threatera warnings

`--json` prints what the API answered instead of the summary, for scripts.

Exit codes: 0 done; 1 the request failed or was refused (the reason is on
stderr); 2 the command line was wrong; 3 `--fail-on` was met; 4 `--wait` ran
out before the analysis finished. A pipeline can therefore tell "this file is
malicious" from "the service could not say", which is the difference that
matters when the answer gates a release.

The key is sent in the `x-api-key` header and never printed, and TLS is
verified — there is no option to turn that off.
"""
from __future__ import annotations

import argparse
import hashlib
import hmac
import ipaddress
import json
import mimetypes
import ntpath
import os
import re
import secrets
import socket
import ssl
import subprocess
import sys
import time
import uuid
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen

__version__ = "1.7"
# True in the standalone build (PyInstaller sets it): the program is the
# executable itself, and there is no script for a service to name.
FROZEN = bool(getattr(sys, "frozen", False))

DEFAULT_URL = "https://app.threatera.eu"
# Worst last: `--fail-on suspicious` is met by suspicious and by malicious.
_SEVERITY = ("undetected", "unknown", "suspicious", "malicious")
_POLL_SECONDS = 3.0


class Failed(Exception):
    """A request that did not succeed, with the reason a person should read.
    ``status`` is the HTTP status, or None when the platform was not reached."""

    def __init__(self, message: str, status: int | None = None):
        super().__init__(message)
        self.status = status

    @property
    def transient(self) -> bool:
        """Worth trying again later: not reached, the platform failing (a
        deploy restarts it), or asked to slow down. A refusal is a 4xx."""
        return self.status is None or self.status >= 500 or self.status in (408, 429)


# Where a system keeps its trusted certificates, tried in order when the
# Python running this has none of its own. A built collector carries an
# OpenSSL that looks only where its build machine kept them, and python.org's
# macOS Python looks in its own folder until "Install Certificates" is run, so
# both failed every https request with CERTIFICATE_VERIFY_FAILED (measured on
# 1.6, 2026-11-19: macOS, and Rocky Linux with its bundle in place). The
# system's own store rather than a bundled list, so a company's own CA — the
# one its TLS inspection signs with — keeps working.
_CA_BUNDLES = (
    "/etc/ssl/certs/ca-certificates.crt",   # Debian, Ubuntu, Alpine
    "/etc/pki/tls/certs/ca-bundle.crt",     # RHEL, Fedora, Rocky, Alma
    "/etc/ssl/ca-bundle.pem",               # SUSE
    "/etc/ssl/cert.pem",                    # macOS, the BSDs
)
_TLS: list = []


def tls_context() -> ssl.SSLContext:
    """Python's default context when it can verify anything (Windows' own
    store, a Python whose certificates are installed, SSL_CERT_FILE or
    SSL_CERT_DIR), else the system's bundle from ``_CA_BUNDLES``."""
    if _TLS:
        return _TLS[0]
    context = ssl.create_default_context()
    paths = ssl.get_default_verify_paths()
    has_own = (paths.cafile and os.path.isfile(paths.cafile)) or (
        paths.capath and os.path.isdir(paths.capath) and any(os.scandir(paths.capath)))
    if not has_own and not context.get_ca_certs():
        for bundle in _CA_BUNDLES:
            if os.path.isfile(bundle):
                context.load_verify_locations(cafile=bundle)
                break
    _TLS.append(context)
    return context


def send(method: str, url: str, headers: dict, body: bytes | None):
    """One HTTP exchange: ``(status, content type, body bytes)``.

    The only function that touches the network — replaced in the tests, which
    route it into the real application instead.
    """
    request = Request(url, data=body, headers=headers, method=method)
    try:
        with urlopen(request, timeout=120, context=tls_context()) as response:
            return (response.status, response.headers.get("content-type", ""),
                    response.read())
    except HTTPError as error:
        return error.code, error.headers.get("content-type", ""), error.read()
    except URLError as error:
        raise Failed(f"cannot reach {url.split('/api/')[0]}: {error.reason}") from None


class Client:
    def __init__(self, url: str, key: str, org: str | None = None):
        self.base = url.rstrip("/")
        self.headers = {"x-api-key": key, "user-agent": f"threatera-cli/{__version__}"}
        if org:
            self.headers["x-tenant"] = org

    def call(self, method: str, path: str, *, params: dict | None = None,
             json_body: dict | None = None, body: bytes | None = None,
             content_type: str | None = None, raw: bool = False):
        url = f"{self.base}/api{path}"
        if params:
            url += "?" + urlencode({k: v for k, v in params.items() if v is not None})
        headers = dict(self.headers)
        if json_body is not None:
            body = json.dumps(json_body).encode()
            content_type = "application/json"
        if content_type:
            headers["content-type"] = content_type
        status, kind, data = send(method, url, headers, body)
        if status >= 400:
            raise Failed(f"{status}: {_detail(data, kind)}", status)
        if raw:
            return data
        return json.loads(data) if data and "json" in kind else data


def _detail(data: bytes, kind: str) -> str:
    """The server's own explanation, never a stack of bytes."""
    if "json" in kind:
        try:
            detail = json.loads(data).get("detail")
        except (ValueError, AttributeError):
            detail = None
        if isinstance(detail, list):
            return "; ".join(
                str(d.get("msg", d)) if isinstance(d, dict) else str(d) for d in detail
            )
        if detail:
            return str(detail)
    text = data.decode("utf-8", "replace").strip()
    return text[:300] or "no reason given"


def _multipart(path: Path, fields: dict) -> tuple[bytes, str]:
    boundary = f"threatera-{uuid.uuid4().hex}"
    parts: list[bytes] = []
    for name, value in fields.items():
        if value is None:
            continue
        parts.append(
            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"'
            f"\r\n\r\n{value}\r\n".encode()
        )
    kind = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
    # The filename is the user's, so a quote in it must not end the header.
    safe = path.name.replace('"', "_").replace("\r", "_").replace("\n", "_")
    parts.append(
        f'--{boundary}\r\nContent-Disposition: form-data; name="file"; '
        f'filename="{safe}"\r\nContent-Type: {kind}\r\n\r\n'.encode()
        + path.read_bytes() + b"\r\n"
    )
    parts.append(f"--{boundary}--\r\n".encode())
    return b"".join(parts), f"multipart/form-data; boundary={boundary}"


def _verdict_line(record: dict) -> str:
    verdict = record.get("verdict") or "not analysed"
    line = f"verdict: {verdict}"
    if record.get("analyst_verdict"):
        line += (f"   analyst: {record['analyst_verdict'].replace('_', ' ')}"
                 f" ({record.get('decided_by') or 'someone'})")
    return line


def _meets(verdict: str | None, threshold: str | None) -> bool:
    if not threshold or verdict not in _SEVERITY:
        return False
    return _SEVERITY.index(verdict) >= _SEVERITY.index(threshold)


def _print(args, data, summary: str) -> None:
    print(json.dumps(data, indent=2, default=str) if args.json else summary)


# --- commands -----------------------------------------------------------------


def cmd_upload(api: Client, args) -> int:
    path = Path(args.path)
    if not path.is_file():
        raise Failed(f"no such file: {path}")
    body, kind = _multipart(path, {
        "scan_type": "deep" if args.deep else "quick",
        "tags": ",".join(args.tag) if args.tag else None,
    })
    uploaded = api.call("POST", "/files/upload", body=body, content_type=kind)
    sha256 = uploaded["hash"]
    if not args.wait:
        _print(args, uploaded, f"{sha256}  {path.name}  queued: "
               f"{', '.join(uploaded.get('queued') or []) or 'nothing'}")
        return 0
    if "analysis" not in (uploaded.get("queued") or []):
        api.call("POST", f"/files/{sha256}/analyze", json_body={})
    deadline = time.monotonic() + args.wait
    analysis: dict = {}
    while time.monotonic() < deadline:
        try:
            analysis = api.call("GET", f"/files/{sha256}/analysis")
        except Failed:
            analysis = {}
        if analysis.get("status") in ("completed", "failed"):
            break
        time.sleep(_POLL_SECONDS)
    else:
        print(f"{sha256}  analysis not finished after {args.wait:.0f}s "
              f"(last seen: {analysis.get('status', 'not started')})", file=sys.stderr)
        return 4
    if analysis.get("status") == "failed":
        raise Failed(f"analysis failed: {analysis.get('error') or 'no reason given'}")
    record = api.call("GET", f"/files/{sha256}")
    _print(args, record, f"{sha256}  {path.name}\n{_verdict_line(record)}")
    return 3 if _meets(record.get("verdict"), args.fail_on) else 0


# --- watch: a collector -------------------------------------------------------

_SETTLE_SECONDS = 5.0      # a file still being written is left for the next pass
_HELD_BATCH = 500


def _sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1 << 20), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _candidates(folder: Path, recursive: bool, state: dict, skip: Path) -> list[Path]:
    """Files new or changed since they were last handled, and settled."""
    walk = folder.rglob("*") if recursive else folder.glob("*")
    now = time.time()
    out = []
    for path in walk:
        try:
            if path.is_symlink() or not path.is_file() or path == skip:
                continue
            if path.name.startswith("."):
                continue
            st = path.stat()
        except OSError:
            continue
        if now - st.st_mtime < _SETTLE_SECONDS or st.st_size == 0:
            continue
        seen = state.get(str(path))
        if seen and seen[0] == st.st_size and seen[1] == st.st_mtime:
            continue
        out.append(path)
    return sorted(out)


_MESSAGE_SUFFIXES = (".eml", ".msg")
_HEADER = re.compile(rb"^[!-9;-~]{1,76}:[ \t]")
_ADDRESSED = (b"subject", b"message-id", b"received", b"date", b"to")


def is_message(path: Path, everything: bool = False) -> bool:
    """A mail message, to be read as one — by name, or by its first lines
    being headers: a gateway's quarantine often stores messages under an id
    with no extension. A file starting with one header line is not enough;
    it takes a From and one of the headers every message carries."""
    if everything or path.suffix.lower() in _MESSAGE_SUFFIXES:
        return True
    try:
        with path.open("rb") as handle:
            head = handle.read(8192)
    except OSError:
        return False
    names = set()
    for line in head.splitlines():
        if not line.strip():
            break
        if line[:1] in (b" ", b"\t"):
            continue                      # a folded header's continuation
        if not _HEADER.match(line):
            return False
        names.add(line.split(b":", 1)[0].strip().lower())
    return b"from" in names and any(n in names for n in _ADDRESSED)


def _load_state(path: Path) -> dict:
    try:
        return json.loads(path.read_text())
    except (OSError, ValueError):
        return {}


def _save_state(path: Path, state: dict) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_suffix(".tmp")
    tmp.write_text(json.dumps(state))
    tmp.replace(path)


def watch_pass(api: Client, args, folder: Path, state: dict, state_path: Path) -> dict:
    """One look at the folder: hash what is new, ask what is already held, send
    the rest. Returns the counts for the check-in."""
    found = _candidates(folder, args.recursive, state, state_path)
    hashes: dict[Path, str] = {}
    for path in found:
        try:
            hashes[path] = _sha256(path)
        except OSError:
            continue
    held: set[str] = set()
    distinct = sorted(set(hashes.values()))
    for i in range(0, len(distinct), _HELD_BATCH):
        held |= set(api.call("POST", "/files/held",
                             json_body={"hashes": distinct[i:i + _HELD_BATCH]})["held"])
    counts = {"sent": 0, "held": 0, "error": None}
    for path, sha in hashes.items():
        st = path.stat()
        if sha in held:
            counts["held"] += 1
            state[str(path)] = [st.st_size, st.st_mtime, sha, "held"]
            continue
        message = is_message(path, args.mail)
        if message:
            body, kind = _multipart(path, {"collector": args.name})
        else:
            body, kind = _multipart(path, {
                "scan_type": "deep" if args.deep else "quick",
                "collector": args.name})
        try:
            api.call("POST", "/email/messages" if message else "/files/upload",
                     body=body, content_type=kind)
        except Failed as failure:
            if failure.transient:
                # Not recorded, so the next pass sends it. Marked refused, a
                # file met by a deploy or a network blip was never sent again
                # until it changed — lost, with the platform none the wiser.
                # The rest wait too: the platform is not answering.
                counts["error"] = f"not sent, will retry: {failure}"
                print(f"{sha}  {path.name}  not sent, will retry: {failure}",
                      file=sys.stderr)
                break
            if message and failure.status == 409:
                # The same Message-ID was analysed already, in other bytes:
                # held, as far as sending again is concerned.
                counts["held"] += 1
                state[str(path)] = [st.st_size, st.st_mtime, sha, "held"]
                continue
            # Recorded and not retried until the file changes: a file the
            # platform refuses (too large, over quota) would otherwise be sent
            # on every pass.
            counts["error"] = f"{path.name}: {failure}"
            state[str(path)] = [st.st_size, st.st_mtime, sha, f"refused: {failure}"]
            print(f"{sha}  {path.name}  refused: {failure}", file=sys.stderr)
            continue
        held.add(sha)
        counts["sent"] += 1
        state[str(path)] = [st.st_size, st.st_mtime, sha, "sent"]
        if not args.json:
            print(f"{sha}  {path.name}  sent{' as mail' if message else ''}")
    _save_state(state_path, state)
    return counts


def _older(version: str, than: str | None) -> bool:
    def parts(v: str) -> tuple[int, ...]:
        return tuple(int(p) for p in re.findall(r"\d+", v))
    return bool(than) and parts(version) < parts(str(than))


def cmd_watch(api: Client, args) -> int:
    folder = Path(args.folder)
    if not folder.is_dir():
        raise Failed(f"no such folder: {folder}")
    args.name = args.name or f"{socket.gethostname()}:{folder.resolve().name}"
    slug = hashlib.sha256(args.name.encode()).hexdigest()[:12]
    state_path = (Path(args.state) if args.state
                  else Path.home() / ".threatera" / f"watch-{slug}.json")
    # A folder means "keep it in here", which is how the help reads: given
    # one, 1.6 crashed with IsADirectoryError after its first pass.
    if state_path.is_dir():
        state_path = state_path / f"watch-{slug}.json"
    state = _load_state(state_path)
    totals = {"sent": 0, "held": 0}
    # What the platform said at the last check-in: paused from the page, and
    # the version it serves. The first pass assumes running; if it was paused
    # meanwhile, the platform holds the sends with "try again later".
    paused, told_update = False, False
    while True:
        error = None
        counts: dict = {"held": 0}
        if not paused:
            try:
                counts = watch_pass(api, args, folder, state, state_path)
                error = counts["error"]
                totals["sent"] += counts["sent"]
                totals["held"] += counts["held"]
            except Failed as failure:
                error = str(failure)
                print(f"threatera: {failure}", file=sys.stderr)
        if error and "collector_paused" in error:
            error, paused = None, True
        try:
            answer = api.call("POST", "/collectors/heartbeat", json_body={
                "name": args.name, "kind": "mail" if args.mail else "folder",
                "host": socket.gethostname(),
                "watching": str(folder.resolve())[-500:], "version": __version__,
                "interval": int(args.interval), "held": counts["held"],
                "error": error[:500] if error else None}) or {}
            was, paused = paused, bool(answer.get("paused"))
            if paused != was:
                print("threatera: paused from the platform; sending nothing until "
                      "resumed" if paused else "threatera: resumed", file=sys.stderr)
            if not told_update and _older(__version__, answer.get("latest_version")):
                told_update = True
                where = "/guide/collector/" if FROZEN else "/guide/threatera.py"
                print(f"threatera: version {answer['latest_version']} is available "
                      f"(this is {__version__}): {where}", file=sys.stderr)
        except Failed as failure:
            # A collector the platform will not hear from is a failure, not a
            # pass: the Collectors page would mark it silent.
            error = error or f"could not check in: {failure}"
            print(f"threatera: could not check in: {failure}", file=sys.stderr)
        if args.once:
            if args.json:
                print(json.dumps(totals))
            else:
                print(f"{totals['sent']} sent, {totals['held']} already held"
                      + (" (paused from the platform)" if paused else ""))
            return 1 if error else 0
        try:
            time.sleep(args.interval)
        except KeyboardInterrupt:
            return 0


# --- service: a collector that survives a reboot -------------------------------
#
# A watcher started in a terminal stops with the terminal and does not come
# back after a reboot — and a collector that stopped looks exactly like one
# with nothing to send. The definitions below start it at boot, restart it when
# it exits, and read the key from a file rather than a command line, where any
# account on the machine could read it from the process list.

_SLUG = re.compile(r"[^A-Za-z0-9._-]+")


def service_slug(name: str) -> str:
    """The collector's name as it can appear in a file or unit name."""
    return _SLUG.sub("-", name).strip("-.") or "collector"


def _platform(choice: str | None) -> str:
    if choice:
        return choice
    if sys.platform.startswith("win"):
        return "windows"
    return "launchd" if sys.platform == "darwin" else "systemd"


def service_argv(args, *, key_file: str, state: str) -> list[str]:
    """The program and arguments the service runs. Global options first: the
    parser reads them before the command.

    ``-I`` because the service runs with more authority than whoever can write
    beside the script: Python puts a script's own folder first on its import
    path, so a ``socket.py`` dropped next to it would run as the service's
    account — SYSTEM, on Windows, where a folder made under ProgramData lets
    every user create files in it unless told otherwise. Isolated mode leaves
    that folder, and every PYTHON* variable, out."""
    if FROZEN:
        # The build carries its own Python and imports only from inside its
        # own folder, which the setup closes like the script's.
        if args.python:
            raise Failed("--python is for the script; this is the standalone "
                         "build, which carries its own")
        head = [str(Path(sys.executable).resolve())]
    else:
        head = [args.python or sys.executable, "-I", str(Path(__file__).resolve())]
    argv = [*head, "--url", args.url, "--key-file", key_file,
            "watch", str(Path(args.folder).resolve()), "--name", args.name,
            "--interval", f"{args.interval:g}", "--state", state]
    for flag in ("recursive", "deep", "mail"):
        if getattr(args, flag):
            argv.append(f"--{flag}")
    return argv


def _systemd_word(word: str) -> str:
    """One ExecStart word: % and $ are systemd's own, so doubled; quoted when
    it holds a space or a quote."""
    word = word.replace("%", "%%").replace("$", "$$")
    if re.search(r'[\s"\'\\]', word):
        word = '"' + word.replace("\\", "\\\\").replace('"', '\\"') + '"'
    return word


def _systemd(args, slug: str, key_file: str) -> tuple[str, str, list[str]]:
    unit = f"threatera-collector-{slug}"
    state_dir = f"/var/lib/{unit}"
    # The key reaches the service as a systemd credential: readable by the
    # service's own account, whatever that is, and by nobody else.
    argv = service_argv(args, key_file="\0KEY\0", state=f"{state_dir}/state.json")
    exec_start = " ".join(_systemd_word(w) for w in argv).replace(
        "\0KEY\0", "${CREDENTIALS_DIRECTORY}/key")
    who = (f"User={args.user}" if args.user else
           # A throwaway account made for the service: it can read only what
           # everybody may read. A folder that is not readable by others needs
           # --user, an account that can read it.
           "DynamicUser=yes")
    text = "\n".join([
        f"# Threatera collector {args.name!r} — threatera.py {__version__} service",
        "[Unit]",
        f"Description=Threatera collector {args.name}",
        "Wants=network-online.target",
        "After=network-online.target",
        "",
        "[Service]",
        f"ExecStart={exec_start}",
        f"LoadCredential=key:{key_file}",
        who,
        f"StateDirectory={unit}",
        "Restart=always",
        "RestartSec=30",
        # It reads a folder and writes its state; nothing else.
        "NoNewPrivileges=yes",
        "ProtectSystem=strict",
        "ProtectHome=read-only",
        "PrivateTmp=yes",
        "",
        "[Install]",
        "WantedBy=multi-user.target",
        "",
    ])
    path = f"/etc/systemd/system/{unit}.service"
    return text, path, [
        "sudo systemctl daemon-reload",
        f"sudo systemctl enable --now {unit}",
        f"journalctl -u {unit} -f      # what it is doing",
    ]


def _xml(value: str) -> str:
    return (value.replace("&", "&amp;").replace("<", "&lt;")
            .replace(">", "&gt;").replace('"', "&quot;"))


def _launchd(args, slug: str, key_file: str) -> tuple[str, str, list[str]]:
    label = f"eu.threatera.collector.{slug}"
    home = "/Library/Application Support/Threatera"
    argv = service_argv(args, key_file=key_file, state=f"{home}/{slug}.json")
    log = f"/Library/Logs/threatera-collector-{slug}.log"
    user = (f"  <key>UserName</key><string>{_xml(args.user)}</string>\n"
            if args.user else "")
    text = (
        '<?xml version="1.0" encoding="UTF-8"?>\n'
        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
        '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
        '<plist version="1.0">\n<dict>\n'
        f"  <key>Label</key><string>{label}</string>\n"
        "  <key>ProgramArguments</key>\n  <array>\n"
        + "".join(f"    <string>{_xml(w)}</string>\n" for w in argv)
        + "  </array>\n"
        "  <key>RunAtLoad</key><true/>\n"
        "  <key>KeepAlive</key><true/>\n"
        "  <key>ThrottleInterval</key><integer>30</integer>\n"
        f"  <key>StandardOutPath</key><string>{_xml(log)}</string>\n"
        f"  <key>StandardErrorPath</key><string>{_xml(log)}</string>\n"
        + user + "</dict>\n</plist>\n")
    path = f"/Library/LaunchDaemons/{label}.plist"
    return text, path, [
        f"sudo launchctl bootstrap system '{path}'",
        f"tail -f '{log}'      # what it is doing",
    ]


# Who may touch the collector's folder on Windows: SYSTEM, which runs it, and
# Administrators — by well-known SID, because the group's name is translated
# ("Administratoren") and icacls takes the local name. A folder made under
# ProgramData otherwise inherits "Users may create files", and the task runs
# what is in it as SYSTEM.
WINDOWS_ACL = ('/inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" '
               '/grant:r "*S-1-5-32-544:(OI)(CI)F"')


def _windows(args, slug: str, key_file: str) -> tuple[str, str, list[str]]:
    # ntpath, not os.path: the task names Windows paths wherever it is written.
    home = ntpath.join(os.environ.get("ProgramData", r"C:\ProgramData"), "Threatera")
    argv = service_argv(args, key_file=key_file,
                        state=ntpath.join(home, f"{slug}.json"))
    name = f"Threatera collector {slug}"
    # Task Scheduler stops a task after 72 hours unless told otherwise
    # (ExecutionTimeLimit), and gives up after the first failure: neither suits
    # something meant to run for months.
    text = (
        '<?xml version="1.0" encoding="UTF-16"?>\n'
        '<Task version="1.2" '
        'xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">\n'
        f"  <RegistrationInfo><Description>{_xml(name)}</Description>"
        "</RegistrationInfo>\n"
        "  <Triggers><BootTrigger><Enabled>true</Enabled></BootTrigger></Triggers>\n"
        '  <Principals><Principal id="Author"><UserId>S-1-5-18</UserId>'
        "<RunLevel>LeastPrivilege</RunLevel></Principal></Principals>\n"
        "  <Settings>\n"
        "    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>\n"
        "    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>\n"
        "    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>\n"
        "    <StartWhenAvailable>true</StartWhenAvailable>\n"
        "    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>\n"
        "    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count>"
        "</RestartOnFailure>\n"
        "    <Enabled>true</Enabled>\n"
        "  </Settings>\n"
        '  <Actions Context="Author"><Exec>\n'
        f"    <Command>{_xml(argv[0])}</Command>\n"
        f"    <Arguments>{_xml(subprocess.list2cmdline(argv[1:]))}</Arguments>\n"
        "  </Exec></Actions>\n"
        "</Task>\n")
    path = ntpath.join(home, f"{slug}.task.xml")
    return text, path, [
        "# in an administrator prompt; the first line keeps everyone but SYSTEM",
        "# and Administrators out of the folder whose contents run as SYSTEM:",
        f'icacls "{home}" {WINDOWS_ACL}',
        f'schtasks /Create /TN "{name}" /XML "{path}"',
        f'schtasks /Run /TN "{name}"',
    ]


_GENERATORS = {"systemd": _systemd, "launchd": _launchd, "windows": _windows}


def cmd_service(_api, args) -> int:
    folder = Path(args.folder)
    if not folder.is_dir():
        raise Failed(f"no such folder: {folder}")
    if not args.key_file:
        raise Failed("--key-file is required: the service reads its key from a "
                     "file, never from its command line (see save-key)")
    platform = _platform(args.platform)
    if platform == "windows" and args.user:
        raise Failed("--user is for systemd and launchd; the Windows task runs "
                     "as SYSTEM")
    args.name = args.name or f"{socket.gethostname()}:{folder.resolve().name}"
    slug = service_slug(args.name)
    key_file = str(Path(args.key_file).resolve())
    text, path, then = _GENERATORS[platform](args, slug, key_file)
    if not args.install:
        sys.stdout.write(text)
        print(f"\n# save as {path}, then:", file=sys.stderr)
        for line in then:
            print(f"#   {line}", file=sys.stderr)
        return 0
    target = Path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    # The task XML says UTF-16, which is what schtasks reads reliably.
    target.write_text(text, encoding="utf-16" if platform == "windows" else "utf-8")
    print(f"wrote {target}")
    print("now run:")
    for line in then:
        print(f"  {line}")
    return 0


def cmd_save_key(_api, args) -> int:
    """Put a key in a file readable by this account only, asked for without
    echo — never on a command line, never in shell history."""
    import getpass

    key = (getpass.getpass("API key: ") if sys.stdin.isatty()
           else sys.stdin.readline()).strip()
    if not key:
        raise Failed("no key given")
    path = Path(args.path)
    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as handle:
        handle.write(key + "\n")
    os.chmod(path, 0o600)
    print(f"saved to {path}")
    if sys.platform.startswith("win"):
        # A file under ProgramData inherits "Users may read"; take that away.
        print(f'restrict it: icacls "{path}" /inheritance:r '
              '/grant:r "*S-1-5-18:F" /grant:r "*S-1-5-32-544:F"')
    return 0


def _read_key_file(path: str) -> str:
    file = Path(path)
    try:
        key = file.read_text().strip()
    except OSError as error:
        raise Failed(f"cannot read the key file {path}: {error.strerror}") from None
    if os.name == "posix" and file.stat().st_mode & 0o077:
        print(f"threatera: {path} is readable by other accounts; "
              f"chmod 600 it", file=sys.stderr)
    return key


def cmd_file(api: Client, args) -> int:
    record = api.call("GET", f"/files/{args.sha256.lower()}")
    name = record.get("filename") or "(no name)"
    _print(args, record, f"{record.get('hash', args.sha256)}  {name}\n"
           f"{_verdict_line(record)}")
    return 3 if _meets(record.get("verdict"), args.fail_on) else 0


def cmd_ioc(api: Client, args) -> int:
    value = quote(args.value, safe="")
    record = api.call("GET", f"/iocs/{value}")
    try:
        reputation = api.call("GET", f"/iocs/{value}/reputation")
    except Failed:
        reputation = {}
    feeds = [f.get("name") or f.get("feed")
             for f in (record.get("enrichment") or {}).get("feeds") or []]
    lines = [
        f"{record.get('value', args.value)}  ({record.get('type', '?')}, "
        f"{record.get('counter', 0)} sighting"
        f"{'' if record.get('counter', 0) == 1 else 's'})",
        f"analyst: {record.get('analyst_verdict') or 'nobody has decided'}",
        f"feeds: {', '.join(feeds) if feeds else 'none list it'}",
    ]
    if reputation:
        lines.append(f"reputation: {reputation.get('score')} "
                     f"({reputation.get('band')}, {reputation.get('confidence')} "
                     f"confidence)")
    _print(args, {"indicator": record, "reputation": reputation}, "\n".join(lines))
    return 0


def cmd_blocklist(api: Client, args) -> int:
    params = {"format": args.format, "type": args.type}
    if args.format == "json":
        data = api.call("GET", f"/cases/{args.case}/blocklist", params=params)
        print(json.dumps(data, indent=2))
        held = len(data.get("withheld") or [])
        if held:
            print(f"{held} attached artefact(s) left off — see `withheld`",
                  file=sys.stderr)
        return 0
    data = api.call("GET", f"/cases/{args.case}/blocklist", params=params, raw=True)
    sys.stdout.write(data.decode("utf-8"))
    return 0


# --- federate: early warnings without uploading anything ---------------------
#
# The client half of app/services/federation_crypto.py, copied because this file
# is one file of standard-library Python: every value is blinded HERE, so the
# platform sees a group element, never the value. tests/test_federation.py runs
# this copy against the platform's on the same inputs — change both or neither.

_FED_P = int(
    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74"
    "020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F1437"
    "4FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3DC2007CB8A163BF05"
    "98DA48361C55D39A69163FA8FD24CF5F83655D23DCA3AD961C62F356208552BB"
    "9ED529077096966D670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9DE2BCBF695581718"
    "3995497CEA956AE515D2261898FA051015728E5A8AACAA68FFFFFFFFFFFFFFFF", 16)
_FED_G = 4
_FED_BITS = 320
_FED_BYTES = 256
_FED_FIELD = 2**255 - 19
_FED_THRESHOLD = 3
_FED_DST = b"threatera-federation-v1"
_FED_HEX64 = re.compile(r"[0-9a-fA-F]{64}")
_FED_LABEL = re.compile(r"[a-z0-9-]{1,63}")
_FED_BATCH = 500


def fed_normalise(raw: str) -> bytes | None:
    """One line of a list to the protocol's canonical bytes, or None: a
    SHA-256, an IP address, or a domain, guessed from its shape."""
    value = raw.strip()
    if not value or value.startswith("#"):
        return None
    if _FED_HEX64.fullmatch(value):
        return f"sha256:{value.lower()}".encode()
    try:
        return f"ip:{ipaddress.ip_address(value).compressed}".encode()
    except ValueError:
        pass
    value = value.lower().rstrip(".")
    labels = value.split(".")
    if len(labels) >= 2 and all(_FED_LABEL.fullmatch(lb) for lb in labels):
        return f"domain:{value}".encode()
    return None


def _fed_jacobi(a: int, n: int) -> int:
    a %= n
    result = 1
    while a:
        while a % 2 == 0:
            a //= 2
            if n % 8 in (3, 5):
                result = -result
        a, n = n, a
        if a % 4 == 3 and n % 4 == 3:
            result = -result
        a %= n
    return result if n == 1 else 0


def _fed_element(text: str) -> int:
    element = int(text, 16)
    if not (1 < element < _FED_P - 1 and _fed_jacobi(element, _FED_P) == 1):
        raise Failed("the blinder answered with an element outside the group")
    return element


def _fed_hash_to_group(value: bytes) -> int:
    wide = b"".join(hashlib.sha256(_FED_DST + b"|h1|" + bytes([i]) + value).digest()
                    for i in range(9))
    return pow(int.from_bytes(wide, "big") % _FED_P, 2, _FED_P)


def fed_blind(value: bytes, r: int | None = None) -> tuple[int, int]:
    r = r if r is not None else secrets.randbits(_FED_BITS) | (1 << (_FED_BITS - 1))
    return r, _fed_hash_to_group(value) * pow(_FED_G, r, _FED_P) % _FED_P


def fed_unblind(value: bytes, r: int, evaluated: int, key_public: int) -> bytes:
    unblinded = evaluated * pow(pow(key_public, r, _FED_P), -1, _FED_P) % _FED_P
    return hashlib.sha256(_FED_DST + b"|h2|" + len(value).to_bytes(2, "big") + value
                          + unblinded.to_bytes(_FED_BYTES, "big")).digest()


def _fed_field(prf_out: bytes, label: bytes) -> int:
    wide = b"".join(hmac.new(prf_out, _FED_DST + label + bytes([i]), hashlib.sha256)
                    .digest() for i in range(2))
    return int.from_bytes(wide, "big") % _FED_FIELD


def fed_contribution(value: bytes, prf_out: bytes, point: int | None = None) -> dict:
    point = point if point is not None else secrets.randbelow(_FED_FIELD - 1) + 1
    coeffs = [_fed_field(prf_out, b"|a|" + bytes([i])) for i in range(_FED_THRESHOLD)]
    share = sum(c * pow(point, i, _FED_FIELD) for i, c in enumerate(coeffs)) % _FED_FIELD
    root = coeffs[0].to_bytes(32, "big")
    enc = hmac.new(root, _FED_DST + b"|enc", hashlib.sha256).digest()
    mac = hmac.new(root, _FED_DST + b"|mac", hashlib.sha256).digest()
    stream = b"".join(hmac.new(enc, i.to_bytes(4, "big"), hashlib.sha256).digest()
                      for i in range((len(value) + 31) // 32))
    body = bytes(a ^ b for a, b in zip(value, stream))
    return {"token": hmac.new(prf_out, _FED_DST + b"|token", hashlib.sha256).hexdigest(),
            "point": str(point), "share": str(share),
            "sealed": (body + hmac.new(mac, body, hashlib.sha256).digest()[:16]).hex()}


def cmd_federate(api: Client, args) -> int:
    source = sys.stdin if args.path == "-" else open(args.path, encoding="utf-8")
    with source:
        lines = source.readlines()
    values = list(dict.fromkeys(v for v in map(fed_normalise, lines) if v))
    skipped = sum(1 for line in lines if line.strip() and not line.startswith("#")) - len(values)
    totals = {"values": len(values), "accepted": 0, "ready": 0}
    for i in range(0, len(values), _FED_BATCH):
        batch = values[i:i + _FED_BATCH]
        blinded = [fed_blind(v) for v in batch]
        answer = api.call("POST", "/federation/blind", json_body={
            "elements": [b.to_bytes(_FED_BYTES, "big").hex() for _, b in blinded]})
        key_public = _fed_element(answer["public_key"])
        items = [fed_contribution(v, fed_unblind(v, r, _fed_element(e), key_public))
                 for v, (r, _), e in zip(batch, blinded, answer["elements"])]
        result = api.call("POST", "/federation/contributions", json_body={"items": items})
        totals["accepted"] += result["accepted"]
        totals["ready"] += result["ready"]
    _print(args, totals, f"{totals['accepted']} of {totals['values']} contributed"
           f"{f', {skipped} line(s) not a domain, IP or SHA-256' if skipped > 0 else ''}; "
           f"{totals['ready']} already held by three or more organisations "
           "(threatera warnings)")
    return 0


def cmd_warnings(api: Client, args) -> int:
    found = api.call("GET", "/federation/warnings")["warnings"]
    lines = [f"{w['band']:>12}  {w['kind']:<6}  {w['value']}" for w in found]
    _print(args, found, "\n".join(lines) if lines
           else "No early warnings: nothing you contributed is held by three "
                "organisations yet.")
    return 0


def cmd_inbox(api: Client, args) -> int:
    claim = "mine" if args.mine else "unclaimed" if args.unclaimed else None
    data = api.call("GET", "/inbox", params={
        "kind": args.kind, "claim": claim, "limit": args.limit,
    })
    lines = [f"{data.get('total', 0)} waiting"]
    for item in data.get("results") or []:
        who = f"  [{item['claimed_by']}]" if item.get("claimed_by") else ""
        lines.append(f"{item['severity']:<8} {item['kind']:<5} {item['title']}{who}")
    _print(args, data, "\n".join(lines))
    return 0


# --- the command line -----------------------------------------------------------


def parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="threatera", description="The Threatera API from a terminal.")
    p.add_argument("--url", default=os.environ.get("THREATERA_URL", DEFAULT_URL),
                   help="the instance (env THREATERA_URL)")
    p.add_argument("--key", default=os.environ.get("THREATERA_KEY"),
                   help="an API key (env THREATERA_KEY); never printed")
    p.add_argument("--key-file", metavar="PATH",
                   help="read the API key from this file (see save-key)")
    p.add_argument("--org", default=os.environ.get("THREATERA_ORG"),
                   help="organisation to act in, for a key that may name one "
                        "(env THREATERA_ORG)")
    p.add_argument("--json", action="store_true",
                   help="print what the API answered")
    p.add_argument("--version", action="version",
                   version=f"{__version__} (standalone)" if FROZEN else __version__)
    sub = p.add_subparsers(dest="command", required=True)

    up = sub.add_parser("upload", help="upload a file")
    up.add_argument("path")
    up.add_argument("--deep", action="store_true",
                    help="also analyse it and run it in the sandbox")
    up.add_argument("--tag", action="append", help="tag it (repeatable)")
    up.add_argument("--wait", type=float, metavar="SECONDS",
                    help="wait up to this long for the analysis and print the verdict")
    up.add_argument("--fail-on", choices=("suspicious", "malicious"),
                    help="exit 3 when the verdict is this or worse (with --wait)")
    up.set_defaults(run=cmd_upload)

    f = sub.add_parser("file", help="a file's verdicts, by SHA-256")
    f.add_argument("sha256")
    f.add_argument("--fail-on", choices=("suspicious", "malicious"))
    f.set_defaults(run=cmd_file)

    i = sub.add_parser("ioc", help="an indicator: what was decided, who lists it")
    i.add_argument("value")
    i.set_defaults(run=cmd_ioc)

    b = sub.add_parser("blocklist", help="a case's block list, to stdout")
    b.add_argument("case", type=int)
    # No default format: `txt` with --type, `csv` without. A default of txt
    # made the bare `threatera blocklist 14` a usage error every time, because
    # a plain list holds one kind of value and nothing had said which.
    b.add_argument("--format", default=None,
                   choices=("txt", "csv", "defender", "json"),
                   help="txt when --type is given, csv otherwise")
    b.add_argument("--type", choices=("sha256", "sha1", "md5", "domain", "ip"),
                   help="required for txt: a plain list holds one kind of value")
    b.set_defaults(run=cmd_blocklist)

    n = sub.add_parser("inbox", help="what is waiting for a person")
    who = n.add_mutually_exclusive_group()
    who.add_argument("--mine", action="store_true")
    who.add_argument("--unclaimed", action="store_true")
    n.add_argument("--kind", choices=("alert", "email", "file"))
    n.add_argument("--limit", type=int, default=50)
    n.set_defaults(run=cmd_inbox)

    w = sub.add_parser("watch", help="send every new file in a folder, and keep watching")
    w.add_argument("folder")
    w.add_argument("--name", help="what the Collectors page calls it "
                                  "(default: host:folder)")
    w.add_argument("--interval", type=float, default=60.0, metavar="SECONDS",
                   help="how often to look, and to check in (default 60)")
    w.add_argument("--recursive", action="store_true", help="include subfolders")
    w.add_argument("--deep", action="store_true",
                   help="also analyse each file and run it in the sandbox")
    w.add_argument("--mail", action="store_true",
                   help="send every file as a mail message (a mail gateway's "
                        "quarantine); without it, only files that are messages")
    w.add_argument("--once", action="store_true",
                   help="look once, send, check in and stop")
    w.add_argument("--state", help="where to remember what was handled: a "
                                   "file, or a folder to keep it in (default: "
                                   "~/.threatera/watch-<name>.json)")
    w.set_defaults(run=cmd_watch)

    s = sub.add_parser("service", help="keep a collector running: a systemd "
                                       "unit, launchd daemon or Windows task")
    s.add_argument("folder")
    s.add_argument("--name", help="the collector's name, as its key was named")
    s.add_argument("--interval", type=float, default=60.0, metavar="SECONDS")
    s.add_argument("--recursive", action="store_true")
    s.add_argument("--deep", action="store_true")
    s.add_argument("--mail", action="store_true")
    s.add_argument("--platform", choices=("systemd", "launchd", "windows"),
                   help="default: this machine's")
    s.add_argument("--user", help="run as this account (systemd, launchd); "
                                  "default: a throwaway one (systemd) or root")
    s.add_argument("--python", help="the Python to run it with "
                                    "(default: this one)")
    s.add_argument("--install", action="store_true",
                   help="write it where it belongs instead of printing it")
    s.set_defaults(run=cmd_service)

    fe = sub.add_parser("federate", help="contribute values to early warnings, "
                                         "blinded on this machine")
    fe.add_argument("path", help="one domain, IP address or SHA-256 a line; - for stdin")
    fe.set_defaults(run=cmd_federate)
    wa = sub.add_parser("warnings", help="values you contributed that three "
                                         "organisations now hold")
    wa.set_defaults(run=cmd_warnings)

    k = sub.add_parser("save-key", help="store an API key in a file only this "
                                        "account can read, asked for without echo")
    k.add_argument("path")
    k.set_defaults(run=cmd_save_key)
    return p


def main(argv: list[str] | None = None) -> int:
    # Line by line, so a service's log shows what it did when it did it: the
    # service runs isolated (-I), which ignores PYTHONUNBUFFERED.
    for stream in (sys.stdout, sys.stderr):
        reconfigure = getattr(stream, "reconfigure", None)
        if reconfigure is not None:
            reconfigure(line_buffering=True)
    p = parser()
    args = p.parse_args(argv)
    offline = args.command in ("service", "save-key")
    try:
        if args.key_file and not offline:
            args.key = _read_key_file(args.key_file)
    except Failed as failure:
        print(f"threatera: {failure}", file=sys.stderr)
        return 1
    if not args.key and not offline:
        p.error("no API key: set THREATERA_KEY, or pass --key or --key-file")
    if args.command == "service" and args.interval < 5:
        p.error("--interval must be at least 5 seconds")
    if args.command == "watch" and args.interval < 5:
        p.error("--interval must be at least 5 seconds")
    if args.command == "upload" and args.fail_on and not args.wait:
        p.error("--fail-on needs --wait: there is no verdict to fail on yet")
    if args.command == "blocklist" and args.format is None:
        args.format = "txt" if args.type else "csv"
    if args.command == "blocklist" and args.format == "txt" and not args.type:
        p.error("--format txt needs --type: a plain list holds one kind of value")
    try:
        return args.run(Client(args.url, args.key, args.org), args)
    except Failed as failure:
        print(f"threatera: {failure}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())
