Skip to content
KitploitKITPLOIT
ToolsExploitsBlog
Log in
Submit
ToolsExploitsBlog
Submit

Hacking, PenTest, and Cybersecurity Tools for Your Security Arsenal!

Kitploit is a directory of hacking, cybersecurity, and pentesting tools. Discover the latest project updates to find vulnerabilities, analyze systems, automate testing, and strengthen your security.

FeedsContactPrivacy© 2026 Kitploit

Tool Directory

Categories

View all categories
Loading categories
Tools/GitHubGitHub/khalidelborai/xtor
Scripting & AutomationNetwork SecurityPrivacyUtilities & FrameworksCrawler
GitHubkhalidelborai/xtor

xtor

Python library for programmatic Tor instance management with SOCKS5 proxy, identity rotation, stream isolation, hidden services, circuit control, and async HTTP clients.

View Repository
11589 months agoNot yet reviewed
Website
Share

xtor

Python library for managing Tor instances programmatically.

PyPI version Python 3.10+ License: GPL-3.0-or-later CI

Features

  • Launch new Tor processes or connect to existing ones
  • Pre-configured httpx clients (sync + async) with SOCKS5 proxy
  • Identity rotation with optional wait-for-new-IP
  • Stream isolation for traffic separation
  • Circuit and stream management
  • Exit node info (country, bandwidth, flags)
  • Ephemeral hidden services (.onion)
  • Event listeners (circuit, stream, bandwidth events)
  • TorPool for managing multiple instances with round-robin and random selection
  • Named instances with CLI management
  • Custom exception hierarchy for precise error handling

Installation

Prerequisites

Linux (Debian/Ubuntu):

sudo apt-get install tor obfs4proxy

Windows:

Download the Tor Expert Bundle from torproject.org.

Python Package

pip install xtor
# or
uv add xtor

Quick Start

from xtor import Tor

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    print(f"Connected through IP: {tor.ip}")
    resp = tor.client.get("https://api.ipify.org")
    print(resp.text)

Usage

Start a New Tor Process

from xtor import Tor
from xtor.exceptions import TorNotFoundError, PortInUseError

try:
    with Tor.start(port=9052, control_port=9053, host="127.0.0.1", password="mypass") as tor:
        print(tor.ip)
        resp = tor.client.get("https://api.ipify.org")
        print(resp.text)
except TorNotFoundError:
    print("Tor not found on PATH")
except PortInUseError as e:
    print(f"Port in use: {e}")

Note: Tor.startTor() is available as an alias for Tor.start() for backwards compatibility.

Connect to an Existing Instance

with Tor(password="mypass", port=9050, control_port=9051) as tor:
    print(tor.ip)

New Identity

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    print(tor.ip)
    tor.new_identity(wait=True, timeout=30)
    print(tor.ip)  # New IP

Async Client

import asyncio
from xtor import Tor

async def main():
    with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
        async with tor.async_client as client:
            resp = await client.get("https://api.ipify.org")
            print(resp.text)

asyncio.run(main())

Stream Isolation

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    # Each key gets its own circuit
    client_a = tor.isolated_client("session-a")
    client_b = tor.isolated_client("session-b")
    # Requests through client_a and client_b use different circuits

Circuit Management

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    circuits = tor.get_circuits()
    for c in circuits:
        print(f"Circuit {c.id}: {c.status}, path: {c.path}")

    # Close a specific circuit
    tor.close_circuit(circuits[0].id)

Exit Node Info

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    info = tor.exit_node
    if info:
        print(f"Exit: {info.nickname} ({info.country})")
        print(f"Flags: {info.flags}")

Hidden Services

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    service = tor.create_hidden_service({80: 8080})
    print(f"Service: {service.onion_address}")

    # Remove when done
    tor.remove_hidden_service(service)

Event Listeners

with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
    def on_bandwidth(event):
        print(f"Read: {event.read}, Written: {event.written}")

    tor.add_event_listener("BW", on_bandwidth)
    # ... do work ...
    tor.remove_event_listener(on_bandwidth)

TorPool

from xtor import TorPool

with TorPool(size=3, base_port=9100, password="secret") as pool:
    # Round-robin
    tor = pool.next()
    print(tor.client.get("https://api.ipify.org").text)

    # Rotate all identities
    pool.rotate_all()

    # Random selection
    tor = pool.random()

Named Instances (Python)

from xtor import Tor

# Start named instance
tor = Tor.start(port=9052, control_port=9053, host="127.0.0.1", name="my-tor")

# Later, reconnect by name
tor = Tor.from_name("my-tor")
with tor:
    print(tor.ip)

CLI Reference

The xtor CLI manages named Tor instances as background processes.

# Start a named instance
xtor start my-tor --port 9052 --control-port 9053

# List instances
xtor list

# Connection details
xtor connect my-tor

# Stop instance
xtor stop my-tor

# Remove instance and data
xtor remove my-tor

Custom Exceptions

XtorError (base)
├── TorNotFoundError
├── PortInUseError
├── IdentityChangeTimeout
├── ConnectionError
└── AuthenticationError

Catch-all pattern:

from xtor.exceptions import XtorError

try:
    with Tor.start(port=9052, control_port=9053, host="127.0.0.1") as tor:
        ...
except XtorError as e:
    print(f"xtor error: {e}")

License

GPL-3.0-or-later

Download Tool

Most Popular

View all →

Discover the most used tools by our community.

  • 1

    OsintHunter

    letox4/osinthunter

    🎯 The ultimate OSINT toolkit: investigation graph, confidence scoring, alias families, map, timeline and reports. 49 modules, 400+ sites, no API keys required.

    732
  • 2

    ghostlock-app

    yukonga/ghostlock-app

    GhostLock One-Tap Execution App (CVE-2026-43499)

    506
  • 3

    ARTEX

    baarai/artex

    LLM multi-agent autonomous penetration testing platform with planner/worker agents, asset and exploration graphs, MITM traffic recording, and vulnerability retesting.

    405
  • 4

    redforge

    cybersecurity91/redforge

    Browser-side red team toolkit with 102 offline tools for recon, payload generation, credential attacks, crypto, encoding and engagement reporting.

    342
  • 5

    CyberStrikeAI

    ed1s0nz/cyberstrikeai

    The system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.

    261
  • 6

    antifox

    antifox-ai/antifox

    AI multi-agent autonomous penetration testing platform that runs recon, attack-surface discovery, exploitation validation and evidence-backed report delivery.

    259

Explore all tools

Browse our collection of tools

View all tools →