Discover a commonly overlooked vulnerability class in seconds during pentests and bug bounties
Introduction: A Vulnerability Class You Don’t See Coming
Nearly every modern web application runs behind a reverse proxy, load balancer, or CDN. These layers pass client information to the application using various HTTP headers:
X-Forwarded-ForX-Real-IPForwardedCF-Connecting-IPX-Originating-IPClient-IP…and 100+ variations
These headers are user-controllable. If the application trusts them to make decisions — such as “this user is from the internal network,” “this request comes from the admin IP,” or “this traffic originates from an allowed country” — then access controls can be bypassed by adding a single HTTP header.
This vulnerability class is:
Widespread — present in tens of thousands of applications
Critical — can grant access to admin panels, internal APIs, or payment endpoints
Hard to find — manual testing takes hours
Hard to report — which header, which IP block, which endpoint… all scattered
ipspoof was built to find this vulnerability class automatically and quickly.
What Is This Vulnerability Class?
Consider a simple scenario. An application’s /admin endpoint is only accessible from the internal network (10.0.0.0/8). The application checks the client like this:
client_ip = request.headers.get("X-Forwarded-For")
if client_ip and client_ip.startswith("10."):
return admin_panel()
else:
return "Access denied"The application assumes X-Forwarded-For comes from a trusted source. But in reality, any user can add this header:
curl -H "X-Forwarded-For: 10.0.0.1" https://target/adminBy adding a single header, you just accessed the admin panel.
This vulnerability appears in several forms:
1. IP Allowlist Bypass — access is restricted to a specific IP block, you’re outside it, and you spoof the header to get in.
2. Admin Panel Access — panel only open from localhost; X-Forwarded-For: 127.0.0.1 gets you in.
3. Internal API Access — internal API only callable from the internal network; spoof the header and call it from outside.
4. Rate Limit Bypass — rate limiting is per IP; send a different IP each request to bypass it.
5. Geo-Restriction Bypass — content is locked to specific countries; spoof the header to access it.
6. Cache Poisoning — the cache mechanism keys on the header; poison it with fake headers.
The common thread: the application trusts a client-controllable header.
What Does ipspoof Do?
ipspoof automatically discovers this vulnerability class using a two-phase pipeline.
Phase 1 — Header Discovery:
It sends different client-IP headers to the application. It detects which header the application reads, which one it trusts, and which value changes its behavior. It works with 100+ headers and a curated “trusted IP” list.
Phase 2 — IP Fuzzing:
After finding which header works, it locks that header and fuzzes the IP range you specify (e.g., 10.0.0.1-254). This tells you exactly which IP block bypasses the allowlist.
The result: which header and which IP combination bypasses access controls — within seconds.
The tool never sends anything malicious. It only adds headers to ordinary HTTP requests.
Why Not Just Do It Manually?
Those who try manual testing hit this wall:
Coverage: 100+ headers × 254 IPs = 30,000 requests
Speed: Hours with Burp Community, days through a corporate proxy
Uncertainty: “Which header should I try?” is unanswered from the start
Scatter: Findings scattered across tabs, notes, browser history
False negatives: Trying 5 headers and reporting “it’s not there”
ipspoof compresses this process:
Down to level of seconds (Phase 1)
Tests every header automatically
Verifies what it finds (Phase 2)
Saves results as JSON
In short: it replaces manual testing — and it’s not just faster, it’s more reliable and more comprehensive.
Installation
The cleanest path is pipx:
pipx install ipspoof
Alternatively:
pip install ipspoofWith Tor support:
pipx install "ipspoof[tor]"Dependencies are lightweight: requests and urllib3. Installation takes 10 seconds.
Usage
Basic
ipspoof -u https://target.com/endpoint --followOutput:
[*] Phase 1: Header discovery (105 headers x 11 IPs)
[+] HIT: X-Forwarded-For: 10.0.0.1 -> status=200 size=1770
[+] HIT: X-Real-IP: 10.0.0.1 -> status=200 size=1770
[*] Phase 1 complete in 39.0s. 4 anomalies.Interpretation: In ~39 seconds you learned that two headers can be spoofed and that internal IPs are accepted.
Full Pipeline
ipspoof -u https://target.com/endpoint \
--phase2 --ip-pattern "10.0.0.n" --ip-range 1-254 \
--followLocks onto the headers found in Phase 1 and fuzzes 10.0.0.1-254. Lists which IPs are accepted.
POST Requests
ipspoof -u https://target.com/api/admin \
-X POST -d "action=delete" \
--header "Authorization: Bearer xyz" \
--body-regex "success"For login forms, REST APIs, and GraphQL endpoints.
WAF/IPS-Protected Targets
ipspoof -u https://target.com/ --rate 30 \
--proxy-file proxies.txt \
--tor --tor-new-every 10Max 30 req/s, round-robin proxy rotation, Tor identity rotation every 10 requests.
Interactive Mode
ipspoof -i
Highlighted Features
Comprehensive Header Discovery:
100+ client-IP headers. X-Forwarded-For, X-Real-IP, Forwarded, Client-IP, CF-Connecting-IP, X-Originating-IP, Via, Proxy-Client-IP, and derivatives.
Four Detection Modes:
Status, size, body hash, and body regex. Even same-size different-content responses are caught.
XFF Chain Variations:
With --chain:
1.2.3.4, 10.0.0.110.0.0.1, 1.2.3.4for=10.0.0.1
Bypasses are caught even when the app reads only the first value.
POST/PUT/PATCH/JSON Support:
Full support for login forms, REST APIs, and GraphQL.
Proxy and Tor:--proxy-file for round-robin rotation, --tor for SOCKS5, --tor-new-every for periodic identity renewal.
Rate Limiting:--rate N for max req/s. Reduces WAF/IPS ban risk.
JSON Output:-o results.json saves findings in a machine-readable format. For reporting and re-running.
Interactive Mode:
Step-by-step prompts. Ideal for beginners.
Real-World Use Cases
1. During a Bug Bounty
The program scope includes a SaaS application. In the API docs you spot an endpoint marked “internal.” You try:
ipspoof -u https://api.target.com/internal/users --followPhase 1 runs. You see that X-Forwarded-For: 10.0.0.1 returns 200. You found a critical access control vulnerability.
2. During a Pentest Engagement
The client says, “our admin panel is only open from the internal network.” You test:
ipspoof -u https://admin.client.com/ -iIn interactive mode, you enter the URL, say yes to --follow. Phase 1 shows X-Real-IP: 127.0.0.1 works. A reportable finding for the client.
3. Testing Your Own Application
Before going live, you check:
ipspoof -u https://staging.myproduct.com/admin --phase2You only allow 10.0.0.0/8, but Phase 1 shows X-Forwarded-For can be spoofed. You fix it before shipping.
How It Works (Technical)
1. Baseline Capture:
Sends a request without spoof headers. Records the status, size, and body hash of the “default” response. This is the reference point.
2. Header Discovery (Phase 1):
Sends parallel requests for each (header, trusted IP) pair. Compares responses against baseline. Different status, size, hash, or regex match = HIT.
3. IP Fuzz (Phase 2):
Locks onto Phase 1’s working headers and fuzzes the IP range. Lists which IPs bypass the allowlist.
4. Output:
Prints live HITs to the console, saves findings as JSON.
Comparison with Other Tools
ipspoof's edge: specialized for a specific vulnerability class, two-phase, smart detection, with production features like proxy/Tor/rate-limit.
Legal Notice
This tool is for authorized security testing only. Use it against:
Systems you own
Systems you have written permission to test
CTF/lab environments
Unauthorized use against third-party systems is illegal in most jurisdictions. The author cannot be held responsible for misuse. If you’re doing bug bounties, always respect the program’s scope and rules.