socks5-killswitch
Blocks all requests if your SOCKS5 proxy fails — no silent fallback.
SOCKS5 proxy session for Python built on requests.Session.
If the proxy drops — all requests are instantly killed. No silent fallback to your real IP.
The Problem
Standard requests + SOCKS5 proxy setup has a fatal flaw: if the proxy goes down, requests silently fall back to your real IP. You're exposed and don't even know it.
The Solution
Request ──► Proxy OK? ──► Yes ──► Send through proxy
│
No
│
KILL SWITCH ON
│
┌─────────┴─────────┐
│ All requests │
│ blocked forever │
│ ProxyError raised │
└───────────────────┘
Install
pip install socks5-killswitch
Quick Start
from socks5_killswitch import create_session, ProxyError
# Create a protected session — real IP is detected and verified automatically
session = create_session(
host="proxy.example.com",
port=1080,
username="your-socks5-user",
password="your-socks5-pass",
)
# All requests go through the proxy — just like normal requests.Session
resp = session.get("https://example.com")
# Periodic leak check — verifies visible IP != real IP
session.check_ip()
# If proxy ever fails:
# ❌ ProxyError raised
# ❌ ALL further requests blocked
# ❌ No fallback to direct connection
# ✅ Your real IP is not exposed through this session
How It Works
| Event | What happens |
|---|---|
create_session() |
Detects real IP via ipify.org, connects through proxy, verifies proxy IP is different |
| Successful request | Passes through proxy as normal |
| Any request failure | Kill switch activates — _killed = True, ProxyError raised |
| Subsequent requests | Instantly raise ProxyError — zero network calls |
check_ip() |
Preflight TCP check → verifies visible IP != real IP (works even after kill switch!) |
API
create_session(host, port, username, password, **kwargs)
Factory that returns a verified SafeSession.
| Parameter | Type | Default | Description |
|---|---|---|---|
host |
str |
— | SOCKS5 proxy host |
port |
int |
— | SOCKS5 proxy port |
username |
str |
— | SOCKS5 username |
password |
str |
— | SOCKS5 password |
timeout |
int |
15 |
Default request timeout (seconds) |
ip_check_url |
str |
https://api.ipify.org |
IP detection service URL |
preflight |
bool |
True |
TCP-check proxy reachability before IP verification |
SafeSession
Extends requests.Session with kill switch protection.
session.get(url) # proxied request, kills on failure
session.post(url, data=b"…") # binary data works (AMF2, protobuf, etc.)
session.check_ip() # returns proxy IP or raises ProxyError
repr(session) # <SafeSession proxy=socks5://user:***@host:1080 killed=False>
ProxyError
Raised when proxy fails or IP leak is detected. Original exception is chained via __cause__.
Security Model
What the kill switch covers
- Proxy failure → instant block — if any request through the proxy raises an exception, the session is permanently locked. No fallback to a direct connection, ever.
- IP verification on startup —
create_session()detects your real IP, connects through the proxy, and confirms the proxy IP is different before returning the session. - On-demand leak detection —
check_ip()verifies your visible IP hasn't changed. Call it periodically in long-running sessions.
What is outside the scope
This is application-level protection for a single requests.Session. It does not cover:
- DNS queries — uses
socks5://by default (local DNS resolution). Your ISP can see which domains you visit. See #1. - Requests outside
SafeSession— a plainrequests.get()elsewhere in your code goes direct. - Non-HTTP traffic — WebSocket, UDP, raw sockets are not routed through the proxy.
- OS-level enforcement — other processes and applications are not affected.
For maximum protection, combine this library with a VPN or firewall rules that block non-proxied outbound traffic.
Design Decisions
socks5://notsocks5h://— DNS is resolved locally (required for PIA and similar providers)- Pure library — no
.env, no config files, no side effects. All parameters passed explicitly check_ip()bypasses kill switch — intentional; leak detection must work even in degraded state- Preflight TCP check —
check_ip()verifies proxy is TCP-reachable before hitting ipify, preventing real IP leak to external services - Password masked in
repr()—socks5://user:***@host:1080, safe for logging
License
Metadata
Release files for socks5-killswitch 0.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| socks5_killswitch-0.0.4.tar.gz | 11.2 kB | With provenance | Details for socks5_killswitch-0.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| socks5_killswitch-0.0.4-py3-none-any.whl | Python 3 | none | any | Details for socks5_killswitch-0.0.4-py3-none-any.whl |
Total release size: 18.3 kB
Release files / socks5_killswitch-0.0.4.tar.gz
| Download URL | socks5_killswitch-0.0.4.tar.gz |
|---|---|
| Size | 11.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2bd798b5345f7ed0b9e0f921d248729a7ca6729b08afd327fa9ce76c2eacd0f9
|
|
BLAKE2b-256 checksum How to use checksums |
94615a95576b1afc47918ffba49948e144c18c16fcbf4d472ae6dcc6e0da36bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 6, 2026.
Transparency logRelease files / socks5_killswitch-0.0.4-py3-none-any.whl
| Download URL | socks5_killswitch-0.0.4-py3-none-any.whl |
|---|---|
| Size | 7.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e2c8968db6cd661e331ef95264487573a43278a3534387e1fb17986fd40019f2
|
|
BLAKE2b-256 checksum How to use checksums |
4c645a758c4b315cc5c6331739141a3e40b3f5533e43bd64c68e300947544550
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 6, 2026.
Transparency logSecurity for socks5-killswitch 0.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for socks5_killswitch-0.0.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.