SNI-Spoofing

Network-level SNI manipulation research tool for authorized security testing

Explore TLS ClientHello construction, packet interception, TCP sequencing, and relay lifecycle management in a controlled environment.

Warning

Authorized use only. This project is intended for security research, laboratory environments, protocol analysis, and networks you own or are explicitly authorized to test. Do not use it to circumvent access controls, organizational restrictions, or network policies without permission.

📖 Overview

SNI-Spoofing is a Windows-focused Python networking project that experiments with manipulating the early stages of TLS traffic at the packet level.

The implementation combines:

Python asyncio for connection and relay lifecycle management
WinDivert via pydivert for packet interception and injection
Custom TLS ClientHello construction for protocol experimentation
IPv4 / IPv6-aware networking helpers
Config-driven runtime behavior
Bounded retries and graceful shutdown
Thread-safe state management between asynchronous and packet-processing components

The repository is primarily useful as a practical study of how application-layer TLS metadata interacts with lower-level TCP packet behavior.

🧭 Table of Contents

Overview
Core Capabilities
Architecture
Packet and Connection Flow
Repository Structure
Requirements
Installation
Configuration
Running the Project
Operational Notes
Troubleshooting
Security Considerations
Development
Contributing
License
Maintainer

✨ Core Capabilities

Capability	Description
TLS ClientHello construction	Builds controlled TLS handshake payloads containing SNI and related extensions.
SNI selection	Supports a configurable pool of SNI values for protocol experiments.
TCP packet processing	Uses WinDivert to observe and manipulate selected packets at the Windows network layer.
IPv4 / IPv6 support	Network configuration and validation account for both address families.
TLS 1.2 / 1.3 fields	Supports the TLS versions represented by the current configuration and packet-building logic.
Async relay	Uses asyncio to relay traffic in both directions and coordinate connection teardown.
Bounded retries	Connection attempts use configurable retry limits and delays.
Input validation	Addresses, ports, TLS values, and selected TLS field lengths are validated before use.
Graceful shutdown	Active sockets and relay tasks are cleaned up when the process exits.
Structured configuration	Runtime values live in config.json instead of being scattered through the source.

🏗️ Architecture

At a high level, the project has four cooperating layers:

┌─────────────────┐
│     Client      │
└────────┬────────┘
         │
         ▼
┌──────────────────────────────┐
│       SNI Proxy / Relay      │
│                              │
│  ┌────────────────────────┐  │
│  │      asyncio relay     │  │
│  └───────────┬────────────┘  │
│              │               │
│  ┌───────────▼────────────┐  │
│  │  Connection lifecycle  │  │
│  └───────────┬────────────┘  │
└──────────────┼───────────────┘
               │
               ▼
┌──────────────────────────────┐
│   WinDivert / pydivert       │
│   Packet interception layer  │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│        Target endpoint       │
└──────────────────────────────┘

Design goals

Keep application networking separate from packet construction.
Make configuration explicit and reviewable.
Bound retries and cleanup work.
Protect shared packet-processing state from concurrent mutation.
Make failures observable through logging.

🔬 Packet and Connection Flow

The implementation is designed around a controlled packet-processing lifecycle:

A client connection reaches the configured local listener.
The application establishes the corresponding outbound connection.
The packet-processing layer observes the relevant TCP handshake.
The handshake module constructs the experimental TLS payload.
Packet-processing state is coordinated with the asynchronous relay.
Once packet-level processing is complete, the normal bidirectional relay handles application data.
When either direction terminates, the relay cancels the remaining task and releases resources.

Research note: TCP sequencing, retransmission behavior, TLS framing, and middlebox behavior can vary between operating systems, network paths, and server implementations. Results from a laboratory environment should not be treated as universally reproducible.

📁 Repository Structure

SNI-SPOOFING/
├── .github/
│   └── ...                    # GitHub project configuration
├── utils/
│   ├── Network.py             # Network helpers
│   └── Packet.py              # Packet/TLS construction and validation
├── SNI.py                     # Main application
├── Fake_Handshake.py          # Handshake implementation
├── Injector.py                # Packet injection lifecycle
├── Log_Monitoring.py          # Logging / monitoring
├── config.json                # Runtime configuration
├── requirements.txt           # Python dependencies
├── SECURITY.md                # Security reporting policy
├── CONTRIBUTING.md            # Contribution guidelines
├── CODE_OF_CONDUCT.md         # Community standards
├── LICENSE                    # MIT License
└── README.md                  # Project documentation

📦 Requirements

Requirement	Current project expectation
Operating system	Windows 10 / 11
Python	3.8–3.12
Dependency	pydivert >= 3.1.0
Privileges	Administrator privileges may be required by WinDivert
Network access	Use only an authorized test environment

The dependency list is intentionally small:

pydivert>=3.1.0

Note

WinDivert is a Windows kernel-level packet interception component. Python version compatibility and driver availability should be verified in your test environment before debugging application-level behavior.

🛠️ Installation

1. Clone the repository

git clone https://github.com/ItsWanheda/SNI-SPOOFING.git
cd SNI-SPOOFING

2. Create a virtual environment

Using Python 3.12 is a practical baseline for the current project:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. Review the configuration

Before running the application, inspect:

config.json

Use an endpoint and network interface that belong to your authorized test environment.

⚙️ Configuration

The repository currently ships with the following configuration shape:

{
  "LISTEN_HOST": "127.0.0.1",
  "LISTEN_PORT": 1080,
  "CONNECT_IP": "1.2.3.4",
  "CONNECT_PORT": 443,
  "SNI_LIST": [
    "www.google.com",
    "www.youtube.com",
    "www.cloudflare.com",
    "www.github.com"
  ],
  "TLS_VERSION": "1.3",
  "MAX_RETRIES": 3,
  "RETRY_DELAY": 2,
  "LOG_LEVEL": "INFO",
  "HEALTH_CHECK_PORT": 8080
}

Configuration reference

Key	Type	Purpose
LISTEN_HOST	string	Local address used by the listener.
LISTEN_PORT	integer	Local TCP listening port.
CONNECT_IP	string	Authorized target endpoint address.
CONNECT_PORT	integer	Target TCP port.
SNI_LIST	array	SNI values used by the handshake experiment.
TLS_VERSION	string	TLS version represented in the generated handshake.
MAX_RETRIES	integer	Maximum connection retry count.
RETRY_DELAY	number	Delay between retry attempts, in seconds.
LOG_LEVEL	string	Application logging verbosity.
HEALTH_CHECK_PORT	integer	Port reserved for health/monitoring functionality.

Configuration guidance

Keep LISTEN_HOST bound to localhost unless your authorized lab specifically requires another interface.
Replace placeholder target values before testing.
Keep retry limits bounded.
Use a small, controlled SNI list while developing.
Never place credentials, API keys, or private secrets in config.json.

▶️ Running the Project

Start the application from an elevated PowerShell session when required by the local WinDivert installation:

.\.venv\Scripts\Activate.ps1
python SNI.py

For a first test, use a controlled endpoint and observe the application logs before introducing additional variables.

Stop the application

Use:

Ctrl+C

The application is designed to clean up active sockets, relay tasks, and packet-processing state during shutdown.

🧪 Operational Notes

This project touches several layers of the networking stack at once. When testing changes, isolate variables.

Application layer

Confirm:

Python environment is active.
Dependencies import successfully.
Configuration parses correctly.
The listener can bind to its configured port.

Network layer

Confirm:

The target address is reachable from the authorized test machine.
The configured port is available.
Windows Firewall rules are understood.
WinDivert is installed and accessible.

Packet layer

Use packet-capture and logging tools in your lab to understand:

TCP handshake state
packet ordering
retransmissions
TLS record boundaries
ClientHello contents
connection teardown

Avoid changing several layers simultaneously; otherwise it becomes difficult to determine which change caused a result.

🔧 Troubleshooting

pydivert import error

Verify that the virtual environment is active:

.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Then verify the import:

python -c "import pydivert; print(pydivert.__version__)"

WinDivert handle cannot be opened

Check the following:

Run with the privileges required by your WinDivert installation.
Confirm that the installed Python version is supported.
Reinstall the dependency if the installation is incomplete.
Check Windows Event Viewer and application logs.
Verify that endpoint security software is not blocking the driver.

Do not disable security controls blindly. On managed devices, follow the organization's security process.

Address already in use

Identify the process using the configured port:

netstat -ano | findstr :1080

Change LISTEN_PORT to an available port or stop the conflicting process if authorized.

Configuration validation fails

Check:

IP address syntax
TCP port range
TLS version
SNI list contents
retry values
JSON syntax

A minimal JSON validation check is:

python -m json.tool config.json

Connections fail unexpectedly

Work through the layers in order:

Configuration
    ↓
Python dependencies
    ↓
Listener
    ↓
Outbound TCP connection
    ↓
WinDivert availability
    ↓
Packet processing
    ↓
TLS handshake
    ↓
Application relay

Collect logs at the first failing layer rather than assuming the failure is caused by TLS.

🛡️ Security Considerations

Because this project operates close to the network stack, treat it as security-sensitive software.

Use an isolated test environment

Recommended environments include:

a dedicated Windows test machine
a virtual machine
a private lab network
systems you own or have explicit authorization to test

Avoid accidental exposure

Prefer 127.0.0.1 for local experiments.
Avoid binding to all interfaces unless required.
Do not expose the service directly to the public internet.
Monitor listening ports before and after testing.

Protect the host

WinDivert operates at a low level in the Windows networking stack. Keep Windows, Python, dependencies, and endpoint protection software maintained.

Responsible research

The techniques represented by this project can affect network controls and traffic interpretation. Use them to understand protocols and validate systems you are authorized to assess—not to defeat controls on networks you do not own.

For security disclosures, see SECURITY.md.

🧑‍💻 Development

Recommended workflow

Read the existing implementation
        ↓
Create a focused change
        ↓
Test in an isolated environment
        ↓
Inspect logs and packet behavior
        ↓
Run regression checks
        ↓
Document the behavior
        ↓
Commit with a clear message

🤝 Contributing

Contributions are welcome when they improve reliability, documentation, testing, maintainability, or authorized security research capabilities.

Fork the repository.
Create a focused feature branch.
Make a small, testable change.
Update documentation when behavior changes.
Run the relevant checks locally.
Use a clear Conventional Commit message.
Open a pull request with a concise explanation.

See CONTRIBUTING.md for repository-specific guidance.

📄 License

This project is released under the MIT License.

See LICENSE for the complete license text.

👤 Maintainer

ItsWanheda

GitHub: @ItsWanheda
Repository: SNI-SPOOFING

⚠️ Disclaimer

This software is provided for educational, research, and authorized security-testing purposes.

The maintainer does not authorize the use of this project to:

bypass access controls without permission
interfere with networks or systems belonging to others
evade organizational security policies
disrupt services or communications
access restricted resources without authorization

You are responsible for understanding and complying with the laws, regulations, contracts, and network policies that apply to your environment.

_{Built for protocol research, network engineering, and authorized security testing.}

Name		Name	Last commit message	Last commit date
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
utils		utils
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Fake_Handshake.py		Fake_Handshake.py
Injector.py		Injector.py
LICENSE		LICENSE
Log_Monitoring.py		Log_Monitoring.py
README.md		README.md
SECURITY.md		SECURITY.md
SNI.py		SNI.py
config.json		config.json
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation