TORQUE SCANNER - README

USER OPERATION GUIDE

Torque Scanner is a cross‑platform network reconnaissance and audit tool
designed to perform repeated HTTP requests with randomized user agent
rotation, timing jitter, and optional Tor routing. It provides real‑time
feedback through a web‑based control panel which automatically launches
in your default browser.

1. Launching the Application

Run the binary appropriate for your system:

    ./torque-scanner      (Linux / macOS)
    torque-scanner.exe    (Windows)

On launch, Torque Scanner starts a small local web server and attempts
to open your browser automatically. If it does not open, the terminal
will display the URL:

    http://127.0.0.1:xxxxx/

Copy this into your browser manually.

2. The Control Panel Interface

Once opened, you will see the main interface containing:

-   Target URL – The website or endpoint to be scanned.
-   Request Count – Total number of HTTP GET requests to send.
-   Concurrency – Number of workers (threads).
-   Jitter Settings – Random timing delays between requests.
-   Retry & Backoff Settings – Controls how failed requests are
    repeated.
-   Tor Settings:
    -   Use Tor – Routes traffic through a SOCKS5 Tor proxy at
        127.0.0.1:9050.
    -   Tor NEWNYM – Requests a new Tor identity between requests
        (requires the Tor control port at 127.0.0.1:9051).
-   Real‑time Output Panel – Displays live request logs via SSE.

3. Starting a Scan

Enter your target URL (e.g., http://example.com).
Set your preferred options and click:

    INITIATE ATTACK PROBE

You will see each request logged in real time, including:

-   Worker ID
-   HTTP status codes
-   User‑Agent string selected
-   Tor routing notes
-   Retry attempts and backoff delays

4. Stopping a Scan

Press:

    CEASE ATTACK PROBE

Workers will complete any in‑progress request and halt gracefully.

5. Tor Status Indicator

At the top of the UI, Torque Scanner displays:

-   SOCKS5 availability (port 9050)
-   Control port availability (port 9051)

These indicators update every 3 seconds.

6. Log Files

All scans are logged into:

    ./logs/tor_scanner_YYYYMMDD_HHMMSS.log

These logs can be used for security audits, debugging, and evidence
collection.

------------------------------------------------------------------------

TECHNICAL OVERVIEW & INTERNAL ARCHITECTURE

1. Overview

Torque Scanner is a concurrency‑driven network interrogation tool
designed to evaluate:

-   Endpoint rate limiting
-   User‑agent filtering behavior
-   Load balancing characteristics
-   Tor behavior (through different identities)
-   Error handling and response reliability
-   Infrastructure resiliency under controlled request bursts

It is not a stress‑testing tool. Its purpose is security auditing and
behavioral analysis, not overwhelming a service.

2. Architecture Summary

The software is built as a single Go program embedding both:

-   An HTTP server (UI backend)
-   A complete web interface (HTML, CSS, JavaScript)

Major components include:

A. Web UI Server

-   Serves the embedded HTML GUI.
-   Provides:
    -   /start – Begins a scan.
    -   /stop – Halts a scan.
    -   /events – SSE endpoint for live logs.

B. Worker Engine

-   A configurable number of goroutines pull jobs from a channel.
-   Each job represents a single HTTP GET request.
-   Workers:
    -   Randomize a user agent
    -   Sleep for jitter delay
    -   Attempt request with retry & exponential backoff
    -   Broadcast results via SSE

C. User Agent Management

-   Loads user-agents.txt if found.
-   Otherwise uses a compact built‑in list.
-   Random selection per request.

D. Tor Integration

Torque Scanner can direct all traffic through:

    socks5://127.0.0.1:9050

Workers may optionally trigger a NEWNYM request on the control port,
forcing a new Tor exit node identity.

E. Real‑Time Logs (SSE)

All activity is broadcast through Server‑Sent Events:

-   Low latency
-   Auto‑reconnecting
-   Live streaming to all connected browsers.

F. Logging Subsystem

Every request is logged to file with:

-   Timestamp
-   Target
-   Worker ID
-   Status code
-   User agent
-   Retry attempts
-   Tor usage notes

3. Why Torque Scanner Is Useful

Torque Scanner is valuable for:

✔ Web Security Testing
✔ Tor privacy analysis
✔ Endpoint reliability testing
✔ Infrastructure diagnostics
✔ Educational & research purposes

4. Cross‑Platform Support

Torque Scanner can be compiled for:

-   Linux (x86_64, ARM, ARM64)
-   Windows
-   macOS
-   Raspberry Pi (ARM)

5. Ethical Usage

Torque Scanner is intended for:

-   Your own systems
-   Systems you have permission to test
-   Security auditing and research

Do not use it on systems where you lack authorization.

------------------------------------------------------------------------

END OF DOCUMENT