crypttrace 0.6.0__tar.gz → 0.8.0__tar.gz

{crypttrace-0.6.0/src/crypttrace.egg-info → crypttrace-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.6.0
+Version: 0.8.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -131,7 +131,11 @@ crypttrace serve            # then open http://127.0.0.1:8000
 Paste an address, pick a chain and direction, and get an interactive fund-flow
 graph: nodes coloured by what they are, arrows showing where value went, click a
 node for its full profile, click a transfer line to open it on the block
-explorer. A side panel shows the profile, first-funder chain and off-ramp check.
+explorer. A side panel shows the profile, first-funder chain, off-ramp check
+and whether USDT/USDC at the address is frozen. Tabs add the assessment, the
+timeline, the list of who sent funds here, and address poisoning (look-alikes
+planted in the wallet's history, and payments lured by this address). **Case
+file** downloads the same one-page HTML report `crypttrace report` writes.
 Everything runs on your machine — nothing is uploaded anywhere.
 
 This exists so non-technical victims can use the tool at all: a form and a
@@ -225,7 +229,7 @@ crypttrace crosschain 0xADDRESS --window 48
 crypttrace watch add 0xADDRESS --note "my stolen ETH"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
-# Full investigation report to disk (Markdown + JSON)
+# Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
 crypttrace report 0xADDRESS --depth 3
 
 # Refresh label lists (OFAC sanctions, …)
@@ -460,10 +464,24 @@ are ignored, and every address is checked before it is stored.
 
 ### Reports
 
-`report` runs the full analysis and writes to `~/crypttrace-reports/` (override
-with `--out`): a readable Markdown report (assessment, summary, key findings,
-counterparties, the full fund-flow trace, methodology note) plus a `.json` with
-the raw structured data.
+`report` runs the full analysis and writes a **case file** to
+`~/crypttrace-reports/` (override with `--out`); `investigate` saves the same
+file with the victim's next steps in it. The case file is one HTML page, made
+for whoever receives it — an exchange's compliance team, the police, a lawyer:
+
+- the conclusion in plain words, and what to do now: stablecoins still at the
+  address and who can freeze them, the exchanges the money reached, address
+  poisoning;
+- the fund-flow graph, each address linking to a block explorer;
+- every transfer along the trace with its transaction hashes — the first thing
+  an exchange asks for;
+- where each label comes from, how the tool checked its own arithmetic, and
+  what the method cannot tell you.
+
+It has no scripts and loads nothing from the internet, so it opens in any
+browser or mail client, prints (or saves as PDF) cleanly, and opening it tells
+no one. The raw data is embedded for analysts and written next to it as JSON,
+with its SHA-256 printed on the page; a Markdown version is written too.
 
 ### Self-verification
 
@@ -561,9 +579,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- `report --html`: one self-contained file with the interactive graph, to
-  send to an exchange or attach to a police report
-- `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets

{crypttrace-0.6.0 → crypttrace-0.8.0}/README.md

@@ -97,7 +97,11 @@ crypttrace serve            # then open http://127.0.0.1:8000
 Paste an address, pick a chain and direction, and get an interactive fund-flow
 graph: nodes coloured by what they are, arrows showing where value went, click a
 node for its full profile, click a transfer line to open it on the block
-explorer. A side panel shows the profile, first-funder chain and off-ramp check.
+explorer. A side panel shows the profile, first-funder chain, off-ramp check
+and whether USDT/USDC at the address is frozen. Tabs add the assessment, the
+timeline, the list of who sent funds here, and address poisoning (look-alikes
+planted in the wallet's history, and payments lured by this address). **Case
+file** downloads the same one-page HTML report `crypttrace report` writes.
 Everything runs on your machine — nothing is uploaded anywhere.
 
 This exists so non-technical victims can use the tool at all: a form and a
@@ -191,7 +195,7 @@ crypttrace crosschain 0xADDRESS --window 48
 crypttrace watch add 0xADDRESS --note "my stolen ETH"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
-# Full investigation report to disk (Markdown + JSON)
+# Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
 crypttrace report 0xADDRESS --depth 3
 
 # Refresh label lists (OFAC sanctions, …)
@@ -426,10 +430,24 @@ are ignored, and every address is checked before it is stored.
 
 ### Reports
 
-`report` runs the full analysis and writes to `~/crypttrace-reports/` (override
-with `--out`): a readable Markdown report (assessment, summary, key findings,
-counterparties, the full fund-flow trace, methodology note) plus a `.json` with
-the raw structured data.
+`report` runs the full analysis and writes a **case file** to
+`~/crypttrace-reports/` (override with `--out`); `investigate` saves the same
+file with the victim's next steps in it. The case file is one HTML page, made
+for whoever receives it — an exchange's compliance team, the police, a lawyer:
+
+- the conclusion in plain words, and what to do now: stablecoins still at the
+  address and who can freeze them, the exchanges the money reached, address
+  poisoning;
+- the fund-flow graph, each address linking to a block explorer;
+- every transfer along the trace with its transaction hashes — the first thing
+  an exchange asks for;
+- where each label comes from, how the tool checked its own arithmetic, and
+  what the method cannot tell you.
+
+It has no scripts and loads nothing from the internet, so it opens in any
+browser or mail client, prints (or saves as PDF) cleanly, and opening it tells
+no one. The raw data is embedded for analysts and written next to it as JSON,
+with its SHA-256 printed on the page; a Markdown version is written too.
 
 ### Self-verification
 
@@ -527,9 +545,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- `report --html`: one self-contained file with the interactive graph, to
-  send to an exchange or attach to a police report
-- `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/__init__.py

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

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/assess.py

@@ -240,7 +240,7 @@ def assess(address: str, chain: str = "eth", asset: Optional[dict] = None,
         e = frozen[0]
         signals.append(Signal(
             name="frozen by issuer",
-            observed=f"{e['frozen_amount']:,.2f} {e['token']} at this address is frozen by {e['issuer']}",
+            observed=freeze.describe_frozen(e),
             implication="the issuer blocked it — usually at the request of law enforcement "
                         "or under sanctions",
             confidence="high", weight=40, evidence={"freezes": frozen}))

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/chains.py

@@ -30,6 +30,14 @@ EXPLORER = {
     "sol": "https://solscan.io/account/{}",
 }
 
+TX_EXPLORER = {
+    "eth": "https://etherscan.io/tx/{}", "bsc": "https://bscscan.com/tx/{}",
+    "polygon": "https://polygonscan.com/tx/{}", "arbitrum": "https://arbiscan.io/tx/{}",
+    "optimism": "https://optimistic.etherscan.io/tx/{}", "base": "https://basescan.org/tx/{}",
+    "btc": "https://mempool.space/tx/{}", "tron": "https://tronscan.org/#/transaction/{}",
+    "sol": "https://solscan.io/tx/{}",
+}
+
 _UPSTREAM_ERRORS = (etherscan.EtherscanError, bitcoin.BitcoinError,
                     tron.TronError, solana.SolanaError)
 
@@ -59,6 +67,10 @@ def explorer_url(address: str, chain: str) -> str:
     return EXPLORER.get(chain, EXPLORER["eth"]).format(address)
 
 
+def tx_url(tx_hash: str, chain: str) -> str:
+    return TX_EXPLORER.get(chain, TX_EXPLORER["eth"]).format(tx_hash)
+
+
 def check(chain: str) -> None:
     if chain not in ALL_CHAINS:
         raise ChainError(f"unsupported chain '{chain}'. Options: {ALL_CHAINS}")

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/cli.py

@@ -224,7 +224,7 @@ def report(
         help="Folder to save the report in",
     ),
 ):
-    """Run a full investigation and save a Markdown + JSON report to disk."""
+    """Run a full investigation and save it as an HTML case file (plus Markdown and JSON)."""
     try:
         asset_desc = assets.resolve_asset(asset, chain)
     except ValueError as e:
@@ -232,12 +232,14 @@ def report(
         raise typer.Exit(1)
     try:
         with console.status("Gathering on-chain data and tracing funds…"):
-            md_path = report_mod.generate(address, chain, depth, branching, out, asset_desc)
-    except etherscan.EtherscanError as e:
+            paths = report_mod.generate(address, chain, depth, branching, out, asset_desc)
+    except (chains_mod.ChainError, etherscan.EtherscanError) as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
-    console.print(f"[green]✓ Report saved:[/green] {md_path}")
-    console.print(f"[dim]  Raw data (JSON) saved alongside it in the same folder.[/dim]")
+    console.print(f"[green]✓ Case file saved:[/green] {paths['html']}")
+    console.print("[dim]  One self-contained page: open it in a browser, print it to PDF, or "
+                  "send it as it is.[/dim]")
+    console.print("[dim]  Markdown and raw JSON are saved next to it.[/dim]")
 
 
 @app.command()
@@ -279,14 +281,15 @@ def freeze(
         if e.get("error"):
             console.print(f"{head}: [yellow]could not be read[/yellow] — {e['error']}")
         elif e["frozen"]:
-            console.print(f"{head}: [bold green]FROZEN[/bold green] — {e['frozen_amount']:,.2f} "
-                          f"{e['token']} cannot move" + (f"; {e['movable']:,.2f} still can"
-                                                          if e["movable"] else ""))
-        elif e["balance"]:
+            console.print(f"{head}: [bold green]FROZEN[/bold green] — {freeze_mod.describe_frozen(e)}"
+                          + (f"; {e['movable']:,.2f} still can move" if e["actionable"] else ""))
+        elif e["actionable"]:
             console.print(f"{head}: [bold red]{e['balance']:,.2f} {e['token']} NOT frozen[/bold red]"
                           " — it can still be moved")
             console.print(f"    {e['how']}")
             console.print(f"    [dim]{e['url']}[/dim]")
+        elif e["balance"]:
+            console.print(f"{head}: only dust ({e['balance']:.6f}) — nothing to freeze")
         else:
             console.print(f"{head}: none at this address")
     if labels.type_of(address) == "exchange":

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/freeze.py

@@ -48,6 +48,7 @@ ISSUERS = {
 }
 
 SUPPORTED = ("eth", "tron", "sol")
+MIN_ACTIONABLE = 1.0          # USDT/USDC below this is dust
 
 
 class FreezeError(RuntimeError):
@@ -117,8 +118,18 @@ def _one(address: str, chain: str, symbol: str, contract: str) -> Dict:
         balance = sum(a["amount"] for a in accts)
         frozen_amount = sum(a["amount"] for a in accts if a["state"] == "frozen")
         frozen = any(a["state"] == "frozen" for a in accts)
+    movable = balance - frozen_amount
     return {"token": symbol, "balance": balance, "frozen": frozen,
-            "frozen_amount": frozen_amount, "movable": balance - frozen_amount}
+            "frozen_amount": frozen_amount, "movable": movable,
+            # leftover dust is not worth a freeze request, or a victim's panic
+            "actionable": movable >= MIN_ACTIONABLE}
+
+
+def describe_frozen(e: Dict) -> str:
+    """'4,021.97 USDT here is frozen by Tether', or the blacklisting alone when empty."""
+    if (e.get("frozen_amount") or 0) >= MIN_ACTIONABLE:
+        return f"{e['frozen_amount']:,.2f} {e['token']} here is frozen by {e['issuer']}"
+    return f"This address is blacklisted by {e['issuer']} (no {e['token']} left on it)"
 
 
 def check(address: str, chain: str) -> List[Dict]:
@@ -144,7 +155,7 @@ def check(address: str, chain: str) -> List[Dict]:
             entry.update(_one(address, chain, symbol, tok["contract"]))
         except (FreezeError, KeyError, TypeError, ValueError) as e:
             entry.update({"balance": None, "frozen": None, "frozen_amount": None,
-                          "movable": None, "error": str(e)})
+                          "movable": None, "actionable": None, "error": str(e)})
         out.append(entry)
     return out
 

{crypttrace-0.6.0 → crypttrace-0.8.0}/src/crypttrace/investigate.py

@@ -32,7 +32,7 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
     """Run every check and return a structured result (no printing)."""
     result = {
         "address": address, "chain": chain,
-        "asset": asset["symbol"] if asset else chains.symbol(chain),
+        "asset": asset["symbol"] if asset else chains.symbol(chain), "depth": depth,
         "generated": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
         "errors": [],
     }
@@ -154,13 +154,13 @@ def build_guidance(r: dict) -> dict:
     for e in r.get("freeze") or []:
         if e.get("frozen"):
             steps.insert(0, {
-                "title": f"{e['frozen_amount']:,.2f} {e['token']} here is already frozen by {e['issuer']}",
+                "title": freeze_mod.describe_frozen(e),
                 "body": ("It cannot be moved. Frozen funds can be returned to victims, but only "
                          f"through a legal process: tell the police and {e['issuer']} that you "
                          "are a victim of this address, and include this report."),
                 "urgent": True,
             })
-        elif e.get("movable"):
+        elif e.get("actionable"):
             steps.insert(0, {
                 "title": f"Ask for a freeze: {e['movable']:,.2f} {e['token']} is still here",
                 "body": (f"{e['how']} It can be moved at any moment, so this is the most "
@@ -226,11 +226,13 @@ def guidance_markdown(r: dict) -> str:
 
 
 def save_case(r: dict, out_dir: Path, asset: Optional[dict] = None) -> Path:
-    """Write the full report plus the guidance the victim can act on."""
-    md_path = report_mod.generate(r["address"], r["chain"], 3, 3, out_dir, asset)
+    """Write the case file (HTML, plus Markdown and JSON) with the victim's next steps;
+    returns the HTML one — the file to send."""
+    paths = report_mod.generate(r["address"], r["chain"], r.get("depth", 3), 3, out_dir, asset,
+                                guidance=r.get("guidance"))
     try:
-        with open(md_path, "a", encoding="utf-8") as fh:
+        with open(paths["md"], "a", encoding="utf-8") as fh:
             fh.write(guidance_markdown(r))
     except OSError:
         pass
-    return md_path
+    return paths["html"]