Skip to content
Back to search

tor-egress

MCP server + skill: ogni richiesta HTTP(S) esce su Tor (SOCKS5h) con fingerprint TLS da browser reale. Per agenti che non devono far vedere l'IP reale ai target.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gidixi--tor-egress/badge.svg)](/listings/gidixi--tor-egress)

HTML

<a href="/listings/gidixi--tor-egress"><img src="/api/listings/gidixi--tor-egress/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 194 lines · 1 finding marked
  1. # tor-egress
  2. MCP server (stdio) + skill per **instradare ogni richiesta HTTP(S) su Tor**, con
  3. fingerprint TLS/HTTP2 da browser reale. Autonomo e senza path cablati: si copia in
  4. qualsiasi progetto, su qualsiasi macchina.
  5. Il problema che risolve: un agente che usa `curl`, `wget` o `requests` in modo
  6. diretto mette l'IP della macchina negli access log del target, in chiaro. Qui l'IP
  7. che il target vede è quello di un exit node Tor, e la richiesta ha la firma di
  8. Chrome/Firefox, non di un tool di scan.
  9. ```
  10. agent ──tool MCP──▶ server.py ──socks5h──▶ Tor (127.0.0.1:9050) ──▶ target
  11. │
  12. └─ guard: tunnel giù ⇒ la richiesta NON parte
  13. ```
  14. ## Cosa c'è dentro
  15. ```
  16. tor-egress/
  17. ├── extension.js estensione pi: registra l'MCP server (nessuna dipendenza npm)
  18. ├── package.json manifest pi (extension + skills) e scripts di test
  19. ├── server/
  20. │ ├── server.py MCP server stdio (FastMCP): 6 tool
  21. │ └── torhttp.py nucleo: tunnel, sessione, passo minimo, retry, NEWNYM
  22. ├── skills/tor-egress/ SKILL.md: istruzioni d'uso per l'agente
  23. ├── bin/
  24. │ ├── torcurl.py CLI equivalente ai tool (fallback senza MCP)
  25. │ └── acurl curl forzato su Tor (si ferma se il tunnel è giù)
  26. ├── install.sh installer da URL raw (curl | bash)
  27. ├── setup-tor.sh installa/configura Tor + ControlPort + dipendenze Python
  28. ├── selftest.py handshake MCP + richieste reali via Tor
  29. └── requirements.txt mcp, curl_cffi
  30. ```
  31. ## Tool esposti
  32. | Tool | A cosa serve |
  33. |---|---|
  34. | `tor_status(check_direct=false)` | tunnel SOCKS, ControlPort, exit node corrente, leak check |
  35. | `tor_exit_ip()` | solo l'IP con cui ci vede il mondo |
  36. | `tor_newnym(verify=true, wait=4)` | nuovo circuito / nuovo exit node (retry se Tor riusa lo stesso) |
  37. | `http_request(url, method, ...)` | una richiesta anonima: headers, params, data, json_body, cookies, impersonate, timeout, save_path, verify_tls, max_body_chars |
  38. | `http_batch(calls, delay, stop_on_error, max_body_chars)` | N richieste in sequenza con passo; stesso schema di `http_request` per ogni elemento |
  39. | `tor_selftest()` | verifica end-to-end senza toccare target (usa checkip.amazonaws.com) |
  40. `http_request` ritorna un dizionario serializzabile:
  41. ```json
  42. {"ok": true, "status": 200, "via": "tor", "final_url": "...", "headers": {...},
  43. "body": "...", "json": {...}, "bytes": 1234, "elapsed_ms": 812.3,
  44. "truncated": false, "saved_to": null}
  45. ```
  46. I corpi oltre `max_body_chars` vengono troncati nella risposta e salvati interi in un
  47. file temporaneo (`full_body_file`); `save_path` scrive il corpo completo dove dici tu.
  48. Nei client che prefissano i tool con il nome del server, i nomi diventano
  49. `mcp__tor_egress__http_request`, `mcp__tor_egress__tor_status`, …
  50. (i trattini diventano underscore).
  51. ## Installazione
  52. ### In un colpo (script dall'URL raw)
  53. ```bash
  54. curl -fsSL https://raw.githubusercontent.com/gidixi/tor-egress/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 68 on GitHub
  55. ```
  56. Lo script scarica il pacchetto in `~/.local/share/tor-egress`, verifica/installa
  57. `mcp` e `curl_cffi`, controlla il tunnel Tor e propone la registrazione in pi.
  58. ```bash
  59. # con Tor configurato al volo (chiede sudo) e test finale:
  60. curl -fsSL .../install.sh | bash -s -- --with-tor --check
  61. # in una cartella diversa, senza toccare pi:
  62. curl -fsSL .../install.sh | bash -s -- --dir ~/opt/tor-egress --no-pi
  63. # aggiornare / disinstallare:
  64. curl -fsSL .../install.sh | bash # aggiorna il checkout esistente
  65. bash ~/.local/share/tor-egress/install.sh --uninstall
  66. ```
  67. Opzioni: `--dir PATH`, `--ref REF`, `--with-tor`, `--no-deps`, `--pi`, `--no-pi`,
  68. `--check`, `--uninstall`, `--help` (variabili: `TOR_EGRESS_DIR`, `TOR_EGRESS_REF`,
  69. `TOR_EGRESS_REPO`, `TOR_SOCKS`).
  70. ### 0. Prerequisiti (una volta per macchina)
  71. ```bash
  72. sudo bash setup-tor.sh # tor + SocksPort 9050 + ControlPort 9051 + mcp + curl_cffi
  73. python3 selftest.py # deve finire con "ESITO: OK"
  74. ```
  75. `setup-tor.sh` è idempotente: non ricrea la password del ControlPort se
  76. `~/.tor_ctrl_pass` esiste e fa un backup di `/etc/tor/torrc`.
  77. ### 1. Con pi (skill + MCP in un colpo)
  78. ```bash
  79. pi install /percorso/di/tor-egress # oppure: pi install -l ./tor-egress
  80. pi mcp list # deve mostrare tor-egress con 6 tool
  81. ```
  82. L'estensione registra il server a ogni avvio, quindi non serve toccare
  83. `~/.pi/agent/mcp.json`. Se preferisci la configurazione statica (o un altro client),
  84. usa lo snippet qui sotto.
  85. ### 2. Con qualsiasi client MCP (Claude Code/Desktop, Cursor, Codex, …)
  86. ```json
  87. {
  88. "mcpServers": {
  89. "tor-egress": {
  90. "command": "python3",
  91. "args": ["/percorso/di/tor-egress/server/server.py"],
  92. "env": {
  93. "TOR_SOCKS_ENDPOINT": "127.0.0.1:9050",
  94. "TOR_CONTROL_ENDPOINT": "127.0.0.1:9051",
  95. "TOR_CTRL_PASSFILE": "~/.tor_ctrl_pass"
  96. }
  97. }
  98. }
  99. }
  100. ```
  101. Con pi da riga di comando:
  102. ```bash
  103. pi mcp add tor-egress -- python3 /percorso/di/tor-egress/server/server.py
  104. ```
  105. ### 3. La skill, per agenti che non usano MCP
  106. Copia `skills/tor-egress/` nella cartella skill dell'agente
  107. (`.agents/skills/`, `.claude/skills/`, `~/.pi/agent/skills/`, …). La skill spiega
  108. quali tool usare e quali regole rispettare; senza MCP punti a `bin/torcurl.py`.
  109. ## Configurazione (variabili d'ambiente del server MCP)
  110. | Variabile | Default | Effetto |
  111. |---|---|---|
  112. | `TOR_SOCKS_ENDPOINT` | `127.0.0.1:9050` | dove ascolta il SOCKS di Tor |
  113. | `TOR_CONTROL_ENDPOINT` | `127.0.0.1:9051` | ControlPort per NEWNYM |
  114. | `TOR_CTRL_PASSFILE` | `~/.tor_ctrl_pass` | password del ControlPort (600) |
  115. | `TOR_MIN_INTERVAL` | `1.2` | secondi minimi fra richieste consecutive |
  116. | `TOR_MAX_BODY_CHARS` | `20000` | troncamento di default dei corpi |
  117. | `TOR_ALLOW_DIRECT` | `0` | `1` abilita `allow_direct=true` (uscita senza Tor) |
  118. | `TOR_MCP_PYTHON` | `python3` | interprete usato dall'estensione pi |
  119. ## Perché è sicuro per default
  120. - **Guard sul tunnel**: prima di ogni richiesta controlla il SOCKS; se è giù solleva
  121. `TunnelDown` e non parte nulla. Nessun fallback silenzioso all'IP reale.
  122. - **`socks5h` obbligatorio**: il DNS lo risolve l'exit node, quindi nessuna query DNS
  123. locale che riveli i domini visitati.
  124. - **Uscita diretta impossibile per sbaglio**: `allow_direct=true` viene rifiutato con
  125. `DirectRefused` finché non imposti `TOR_ALLOW_DIRECT=1` nel server. È una decisione
  126. esplicita, non un default.
  127. - **Un solo client condiviso**: passo minimo e sessioni vivono in un processo con lock,
  128. così un batch non può trasformarsi in una raffica.
  129. - **Nessun disco per default**: cookie e header di sessione non vengono persistiti;
  130. i corpi troncati finiscono in file temporanei che il chiamante può cancellare.
  131. ## Limiti noti
  132. - Tor non rende anonimi i *contenuti*: se ti autentichi con un account reale, il
  133. target sa chi sei. L'anonimato è di rete, non di identità applicativa.
  134. - Il rate limiting moltiplica gli exit node: un 429 può dipendere dall'exit node
  135. condiviso con altri. `tor_newnym()` lo risolve spesso.
  136. - Tor è lento (0,5–3 s per richiesta): per enumerazioni grandi conviene `http_batch`
  137. con `delay` realistico invece di centinaia di chiamate MCP.
  138. - Non è un tool di port scan: SOCKS5 TCP connect scan via Tor è lento e rumoroso.
  139. ## Test
  140. ```bash
  141. python3 selftest.py # completo (rete: solo checkip.amazonaws.com)
  142. python3 selftest.py --offline # solo import/config/registrazione tool
  143. python3 server/torhttp.py # stato in JSON
  144. python3 bin/torcurl.py --newnym
  145. ```
  146. ## Portarlo su un'altra macchina
  147. 1. copia la cartella (nessun path assoluto cablato dentro: tutto è relativo);
  148. 2. `sudo bash setup-tor.sh`;
  149. 3. `python3 selftest.py`;
  150. 4. `pi install ./tor-egress` oppure lo snippet `mcpServers`.
  151. Se hai già Tor configurato, salta il punto 2 e imposta `TOR_SOCKS_ENDPOINT` /
  152. `TOR_CONTROL_ENDPOINT` di conseguenza.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.