crypttrace 0.32.0__tar.gz → 0.33.0__tar.gz

{crypttrace-0.32.0/src/crypttrace.egg-info → crypttrace-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.32.0
+Version: 0.33.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -329,6 +329,26 @@ entities — that's the OSINT handoff point. `--direction out` (default) answers
 money come from", which is how you vet a suspicious address or find a victim's
 source of funds.
 
+### Cases — an investigation kept as a file
+
+An investigation rarely fits one address. `case` keeps the addresses (any
+chain, each with a role: victim, suspect, intermediary, exchange, mixer, bridge
+or other), a log of notes, and the last snapshot of each address. `refresh`
+reads them all again and says what changed: a balance that went down, new
+activity since the last look.
+
+```bash
+crypttrace case new ronin --note "Ronin bridge exploit, March 2022"
+crypttrace case add ronin 0x098b…2f96 --chain eth --role suspect --note "exploiter"
+crypttrace case note ronin "asked Binance for KYC on the first-gas withdrawal"
+crypttrace case refresh ronin        # what moved since the last refresh
+crypttrace case show ronin           # addresses, current labels, last snapshot, the log
+```
+
+A case is one JSON file in `~/.crypttrace/cases/`. Every `case` command also
+takes a path to a `.json` file, so handing a case to a colleague is sending the
+file.
+
 ### Watch & alerts — catching the cash-out
 
 The only window to freeze stolen funds is the moment they reach an exchange
@@ -727,6 +747,7 @@ src/crypttrace/
   offramp.py       # exchange-deposit detection
   bridges.py       # cross-chain matching
   watch.py         # watchlist + alerts
+  case.py          # investigations as files: addresses, roles, notes, snapshots
   report.py        # Markdown + JSON reports
   export.py        # traced graph as GraphML (Gephi) and edge-list CSV (Maltego)
   prices.py        # USD valuation

{crypttrace-0.32.0 → crypttrace-0.33.0}/README.md

@@ -295,6 +295,26 @@ entities — that's the OSINT handoff point. `--direction out` (default) answers
 money come from", which is how you vet a suspicious address or find a victim's
 source of funds.
 
+### Cases — an investigation kept as a file
+
+An investigation rarely fits one address. `case` keeps the addresses (any
+chain, each with a role: victim, suspect, intermediary, exchange, mixer, bridge
+or other), a log of notes, and the last snapshot of each address. `refresh`
+reads them all again and says what changed: a balance that went down, new
+activity since the last look.
+
+```bash
+crypttrace case new ronin --note "Ronin bridge exploit, March 2022"
+crypttrace case add ronin 0x098b…2f96 --chain eth --role suspect --note "exploiter"
+crypttrace case note ronin "asked Binance for KYC on the first-gas withdrawal"
+crypttrace case refresh ronin        # what moved since the last refresh
+crypttrace case show ronin           # addresses, current labels, last snapshot, the log
+```
+
+A case is one JSON file in `~/.crypttrace/cases/`. Every `case` command also
+takes a path to a `.json` file, so handing a case to a colleague is sending the
+file.
+
 ### Watch & alerts — catching the cash-out
 
 The only window to freeze stolen funds is the moment they reach an exchange
@@ -693,6 +713,7 @@ src/crypttrace/
   offramp.py       # exchange-deposit detection
   bridges.py       # cross-chain matching
   watch.py         # watchlist + alerts
+  case.py          # investigations as files: addresses, roles, notes, snapshots
   report.py        # Markdown + JSON reports
   export.py        # traced graph as GraphML (Gephi) and edge-list CSV (Maltego)
   prices.py        # USD valuation

{crypttrace-0.32.0 → crypttrace-0.33.0}/src/crypttrace/__init__.py

@@ -1,2 +1,2 @@
 """crypttrace — OSINT crypto investigation CLI."""
-__version__ = "0.32.0"
+__version__ = "0.33.0"

crypttrace-0.33.0/src/crypttrace/case.py

@@ -0,0 +1,187 @@
+"""An investigation kept as a file: its addresses, their roles, notes, and what
+changed since you last looked.
+
+A case is one JSON file — by default ~/.crypttrace/cases/NAME.json, or any path
+— so handing a case to a colleague is sending them the file. It holds:
+
+  - addresses across chains, each with a role (victim, suspect, exchange, …)
+    and a note;
+  - a log of timestamped notes;
+  - for each address, the last snapshot taken by `refresh`: native balance
+    and the time of the latest transfer (tokens included where the chain has
+    them). The next `refresh` compares against it, which is how a case tells
+    you the money moved again.
+"""
+import datetime as dt
+import json
+import re
+import time
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from crypttrace import addresses, chains, config
+
+CASES_DIR = config.DATA_DIR / "cases"
+ROLES = ("victim", "suspect", "intermediary", "exchange", "mixer", "bridge", "other")
+FORMAT = 1
+_ALL_TOKENS = {"contract": None, "symbol": "*"}
+
+
+class CaseError(ValueError):
+    pass
+
+
+def path_for(name_or_path: str) -> Path:
+    """A case named in the cases folder, or a .json file anywhere."""
+    p = Path(name_or_path)
+    if p.suffix.lower() == ".json" or p.parent != Path("."):
+        return p
+    if not re.fullmatch(r"[\w.-]{1,64}", name_or_path):
+        raise CaseError("a case name is letters, digits, '.', '-' or '_' (up to 64)")
+    return CASES_DIR / f"{name_or_path}.json"
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def new(name: str, note: str = "") -> Path:
+    p = path_for(name)
+    if p.exists():
+        raise CaseError(f"case already exists: {p}")
+    case = {"crypttrace_case": FORMAT, "name": p.stem, "created": _now(), "updated": _now(),
+            "addresses": [], "notes": []}
+    if note:
+        case["notes"].append({"at": _now(), "text": note})
+    save(case, p)
+    return p
+
+
+def load(name: str) -> dict:
+    p = path_for(name)
+    try:
+        case = json.loads(p.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise CaseError(f"no such case: {p}")
+    except ValueError as e:
+        raise CaseError(f"{p} is not a readable case file: {e}")
+    if not isinstance(case, dict) or "crypttrace_case" not in case:
+        raise CaseError(f"{p} is not a crypttrace case file")
+    case["_path"] = str(p)
+    return case
+
+
+def save(case: dict, p: Optional[Path] = None) -> Path:
+    p = Path(p or case["_path"])
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data = {k: v for k, v in case.items() if not k.startswith("_")}
+    data["updated"] = _now()
+    tmp = p.with_suffix(p.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+    tmp.replace(p)                       # a half-written case never replaces a good one
+    return p
+
+
+def all_cases() -> List[dict]:
+    out = []
+    for p in sorted(CASES_DIR.glob("*.json")):
+        try:
+            c = load(str(p))
+        except CaseError:
+            continue
+        out.append({"name": c.get("name", p.stem), "path": str(p), "addresses": len(c.get("addresses", [])),
+                    "notes": len(c.get("notes", [])), "updated": c.get("updated")})
+    return out
+
+
+def add(name: str, address: str, chain: str, role: str = "other", note: str = "") -> dict:
+    chains.check(chain)
+    if role not in ROLES:
+        raise CaseError(f"role must be one of: {', '.join(ROLES)}")
+    ok, why = addresses.validate(address, chain)
+    if not ok:
+        raise CaseError(f"not a valid {chain} address: {why}")
+    case = load(name)
+    key = chains.norm_addr(address, chain)
+    for a in case["addresses"]:
+        if a["chain"] == chain and a["address"] == key:
+            a["role"] = role                # adding it again updates it
+            if note:
+                a["note"] = note
+            save(case)
+            return a
+    entry = {"address": key, "chain": chain, "role": role, "note": note, "added": _now(), "snapshot": None}
+    case["addresses"].append(entry)
+    save(case)
+    return entry
+
+
+def remove(name: str, address: str, chain: Optional[str] = None) -> bool:
+    case = load(name)
+    before = len(case["addresses"])
+    case["addresses"] = [a for a in case["addresses"]
+                         if not (a["address"] == chains.norm_addr(address, a["chain"])
+                                 and (chain is None or a["chain"] == chain))]
+    if len(case["addresses"]) == before:
+        return False
+    save(case)
+    return True
+
+
+def note(name: str, text: str) -> dict:
+    case = load(name)
+    entry = {"at": _now(), "text": text}
+    case["notes"].append(entry)
+    save(case)
+    return entry
+
+
+def snapshot(address: str, chain: str) -> dict:
+    """Native balance and the time of the latest transfer, read fresh."""
+    snap = {"at": _now(), "balance": None, "last_seen": None, "error": None}
+    try:
+        snap["balance"] = chains.balance(address, chain)
+        rows = list(chains.transfers(address, chain, 50, fresh=True))
+        if not chains.is_utxo(chain):
+            try:
+                rows += chains.transfers(address, chain, 50, asset=_ALL_TOKENS, fresh=True)
+            except chains.ChainError:
+                pass
+        stamps = [int(r.get("timestamp") or 0) for r in rows if r.get("timestamp")]
+        snap["last_seen"] = max(stamps) if stamps else None
+    except chains.ChainError as e:
+        snap["error"] = str(e)
+    return snap
+
+
+def changes(prev: Optional[dict], cur: dict) -> List[str]:
+    """What is different from the last snapshot, in words."""
+    if cur.get("error"):
+        return [f"could not be read: {cur['error']}"]
+    if not prev or prev.get("error"):
+        return ["first snapshot"]
+    out = []
+    a, b = prev.get("balance"), cur.get("balance")
+    if a is not None and b is not None and abs(b - a) > max(1e-9, abs(a) * 1e-9):
+        out.append(f"balance {a:,.8f} -> {b:,.8f} ({b - a:+,.8f})")
+    if (cur.get("last_seen") or 0) > (prev.get("last_seen") or 0):
+        when = dt.datetime.fromtimestamp(cur["last_seen"], dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+        out.append(f"new activity, latest {when}")
+    return out
+
+
+def refresh(name: str, take: Callable[[str, str], dict] = snapshot) -> List[dict]:
+    """Snapshot every address; report what changed since the last refresh."""
+    case = load(name)
+    report = []
+    for a in case["addresses"]:
+        cur = take(a["address"], a["chain"])
+        diff = changes(a.get("snapshot"), cur)
+        report.append({**{k: a[k] for k in ("address", "chain", "role")}, "changes": diff,
+                       "moved": any(not d.startswith(("first", "could not")) for d in diff),
+                       "balance": cur.get("balance"), "previous": a.get("snapshot")})
+        if not cur.get("error"):
+            a["snapshot"] = cur
+    case.setdefault("refreshes", []).append(_now())
+    save(case)
+    return report

{crypttrace-0.32.0 → crypttrace-0.33.0}/src/crypttrace/cli.py

@@ -1034,5 +1034,124 @@ def watch_run(
         console.print("\n[dim]Stopped.[/dim]")
 
 
+# ---------------------------------------------------------------- cases
+case_app = typer.Typer(help="Keep an investigation as a file: addresses, roles, notes, what changed.")
+app.add_typer(case_app, name="case")
+CASE_ARG = typer.Argument(..., help="Case name (kept in ~/.crypttrace/cases) or a path to a .json case file")
+
+
+def _case_call(fn, *a, **kw):
+    from crypttrace import case as case_mod
+    try:
+        return fn(*a, **kw)
+    except (case_mod.CaseError, chains_mod.ChainError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@case_app.command("new")
+def case_new(name: str = CASE_ARG,
+             note: str = typer.Option("", "--note", "-n", help="What the case is about")):
+    """Start a case."""
+    from crypttrace import case as case_mod
+    p = _case_call(case_mod.new, name, note)
+    console.print(f"[green]✓ Case created[/green] {p}\n[dim]Add addresses with "
+                  f"`crypttrace case add {name} ADDRESS --chain … --role suspect`[/dim]")
+
+
+@case_app.command("list")
+def case_list():
+    """Cases in ~/.crypttrace/cases."""
+    from crypttrace import case as case_mod
+    cases = case_mod.all_cases()
+    if not cases:
+        console.print("[dim]No cases yet. Start one with `crypttrace case new NAME`.[/dim]")
+        return
+    t = render.Table(header_style="bold")
+    for c in ("Case", "Addresses", "Notes", "Updated (UTC)"):
+        t.add_column(c)
+    for c in cases:
+        t.add_row(c["name"], str(c["addresses"]), str(c["notes"]), render._ts(str(c["updated"] or 0)))
+    console.print(t)
+
+
+@case_app.command("add")
+def case_add(name: str = CASE_ARG,
+             address: str = typer.Argument(..., help="Address to add"),
+             chain: str = CHAIN_OPT,
+             role: str = typer.Option("other", "--role", "-r",
+                                      help="victim, suspect, intermediary, exchange, mixer, bridge or other"),
+             note: str = typer.Option("", "--note", "-n", help="Why it is in the case")):
+    """Add an address to a case (adding it again updates its role and note)."""
+    from crypttrace import case as case_mod
+    a = _case_call(case_mod.add, name, address, chain, role, note)
+    console.print(f"[green]✓[/green] {a['address']} ({a['chain']}) as {a['role']}"
+                  + (f" — {a['note']}" if a.get("note") else ""))
+
+
+@case_app.command("remove")
+def case_remove(name: str = CASE_ARG, address: str = typer.Argument(..., help="Address to drop"),
+                chain: Optional[str] = typer.Option(None, "--chain", "-c", help="Only on this chain")):
+    """Drop an address from a case."""
+    from crypttrace import case as case_mod
+    if _case_call(case_mod.remove, name, address, chain):
+        console.print(f"[green]✓ Removed[/green] {address}")
+    else:
+        console.print("[dim]That address is not in the case.[/dim]")
+
+
+@case_app.command("note")
+def case_note(name: str = CASE_ARG, text: str = typer.Argument(..., help="The note")):
+    """Add a timestamped note to the case log."""
+    from crypttrace import case as case_mod
+    _case_call(case_mod.note, name, text)
+    console.print("[green]✓ Noted[/green]")
+
+
+@case_app.command("show")
+def case_show(name: str = CASE_ARG):
+    """The case: its addresses with current labels, the last snapshot, the log."""
+    from crypttrace import case as case_mod
+    c = _case_call(case_mod.load, name)
+    console.print(f"[bold]{c['name']}[/bold]  [dim]{c['_path']}[/dim]")
+    if c["addresses"]:
+        t = render.Table(header_style="bold")
+        for col in ("Role", "Chain", "Address", "Label", "Note", "Last snapshot"):
+            t.add_column(col)
+        for a in c["addresses"]:
+            s = a.get("snapshot") or {}
+            snap = "—" if not s else (
+                (f"{s['balance']:,.8f}" if s.get("balance") is not None else "?") + " "
+                f"{chains_mod.symbol(a['chain'])} · seen "
+                + (render._ts(str(s['last_seen'])) if s.get("last_seen") else "never")
+                + f" · taken {render._ts(str(s['at']))}")
+            t.add_row(a["role"], a["chain"], a["address"], labels.label_of(a["address"]) or "",
+                      a.get("note") or "", snap)
+        console.print(t)
+    else:
+        console.print("[dim]No addresses yet.[/dim]")
+    for n in c.get("notes", []):
+        console.print(f"  [dim]{render._ts(str(n['at']))}[/dim]  {n['text']}")
+
+
+@case_app.command("refresh")
+def case_refresh(name: str = CASE_ARG):
+    """Read every address again and say what changed since the last refresh."""
+    from crypttrace import case as case_mod
+    rep = _case_call(case_mod.refresh, name)
+    if not rep:
+        console.print("[dim]The case has no addresses.[/dim]")
+        return
+    moved = [r for r in rep if r["moved"]]
+    for r in rep:
+        mark = "[bold yellow]●[/bold yellow]" if r["moved"] else "[dim]·[/dim]"
+        console.print(f"{mark} {r['role']:<12} {r['chain']:<8} {r['address']}")
+        for d in r["changes"]:
+            console.print(f"      {d}")
+    console.print(f"\n[bold]{len(moved)}[/bold] of {len(rep)} address(es) changed since the last refresh."
+                  if any(r["previous"] for r in rep) else "\nFirst snapshot taken; the next refresh "
+                  "will say what changed.")
+
+
 if __name__ == "__main__":
     app()

{crypttrace-0.32.0 → crypttrace-0.33.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.32.0
+Version: 0.33.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -329,6 +329,26 @@ entities — that's the OSINT handoff point. `--direction out` (default) answers
 money come from", which is how you vet a suspicious address or find a victim's
 source of funds.
 
+### Cases — an investigation kept as a file
+
+An investigation rarely fits one address. `case` keeps the addresses (any
+chain, each with a role: victim, suspect, intermediary, exchange, mixer, bridge
+or other), a log of notes, and the last snapshot of each address. `refresh`
+reads them all again and says what changed: a balance that went down, new
+activity since the last look.
+
+```bash
+crypttrace case new ronin --note "Ronin bridge exploit, March 2022"
+crypttrace case add ronin 0x098b…2f96 --chain eth --role suspect --note "exploiter"
+crypttrace case note ronin "asked Binance for KYC on the first-gas withdrawal"
+crypttrace case refresh ronin        # what moved since the last refresh
+crypttrace case show ronin           # addresses, current labels, last snapshot, the log
+```
+
+A case is one JSON file in `~/.crypttrace/cases/`. Every `case` command also
+takes a path to a `.json` file, so handing a case to a colleague is sending the
+file.
+
 ### Watch & alerts — catching the cash-out
 
 The only window to freeze stolen funds is the moment they reach an exchange
@@ -727,6 +747,7 @@ src/crypttrace/
   offramp.py       # exchange-deposit detection
   bridges.py       # cross-chain matching
   watch.py         # watchlist + alerts
+  case.py          # investigations as files: addresses, roles, notes, snapshots
   report.py        # Markdown + JSON reports
   export.py        # traced graph as GraphML (Gephi) and edge-list CSV (Maltego)
   prices.py        # USD valuation

{crypttrace-0.32.0 → crypttrace-0.33.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/crypttrace/analysis.py
 src/crypttrace/assess.py
 src/crypttrace/assets.py
 src/crypttrace/bridges.py
+src/crypttrace/case.py
 src/crypttrace/chains.py
 src/crypttrace/cli.py
 src/crypttrace/config.py