Metadata-Version: 2.4
Name: ipspoof
Version: 2.0.0
Summary: HTTP header/IP allowlist bypass discovery tool for authorized security testing
Author-email: Your Name <you@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourname/ipspoof
Project-URL: Repository, https://github.com/yourname/ipspoof
Project-URL: Issues, https://github.com/yourname/ipspoof/issues
Project-URL: Changelog, https://github.com/yourname/ipspoof/blob/main/CHANGELOG.md
Keywords: security,pentest,bugbounty,ip-spoof,header-bypass,xff,x-forwarded-for,allowlist
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: urllib3>=1.26
Provides-Extra: tor
Requires-Dist: requests[socks]>=2.28; extra == "tor"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# ipspoof

> HTTP header/IP allowlist bypass discovery tool for authorized security testing.

[![PyPI](https://img.shields.io/badge/pypi-v2.0.0-blue)](https://pypi.org/project/ipspoof/)
[![Python](https://img.shields.io/badge/python-3.8+-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()

`ipspoof` helps pentesters and bug bounty hunters quickly identify which HTTP header a web application trusts for client-IP-based access control, and which IP range bypasses the allowlist. Common in labs, CTFs, and real-world engagements where you see messages like:

```
Your IP is not allowed to use this webservice. Only 10.10.10.x is allowed
<img width="1210" height="477" alt="resim" src="https://github.com/user-attachments/assets/b3868ae3-1499-401d-bb17-a171ddc822b3" />

```
![ipspoof demo](docs/images/1.jpeg)

---

## Features

- **Header discovery** — tests 100+ client-IP headers (`X-Forwarded-For`, `X-Real-IP`, `Forwarded`, `Client-IP`, `CF-Connecting-IP`, etc.) with a curated set of trusted IP values.
- **IP fuzzing** — once a working header is found, brute-forces the allowed IP range (e.g. `10.10.10.1-254`).
- **Smart anomaly detection** — catches bypasses by status change, size change, body hash, or body regex.
- **XFF chain variations** — `1.2.3.4, <ip>`, `<ip>, 1.2.3.4`, `for=<ip>`.
- **POST/PUT/PATCH support** — works against login forms and API endpoints.
- **Proxy rotation** — round-robin through a proxy list.
- **Tor support** — route through SOCKS5 with automatic identity rotation.
- **Rate limiting** — avoid bans during brute-force.
- **JSON output** — machine-readable results for reporting.
- **Interactive mode** — guided prompts for quick runs.
![ipspoof Feature](docs/images/2.jpeg)
---

## Installation

### pipx (recommended)

```bash
pipx install ipspoof
```

### pip

```bash
pip install ipspoof
```

### From source

```bash
git clone https://github.com/Exript/ipspoof.git
cd ipspoof
pipx install .
```

For Tor support:

```bash
pipx install "ipspoof[tor]"
```

---

## Usage

### Basic

```bash
ipspoof -u http://target/login.php --follow
```

Output:

![ipspoof Output](docs/images/3.jpeg)


### Full pipeline (header discovery + IP fuzz)

```bash
ipspoof -u http://target/login.php \
  --phase2 --ip-pattern "10.10.10.{n}" --ip-range 1-254 \
  --follow
```

### POST login attempt

```bash
ipspoof -u http://target/login.php \
  -X POST -d "username=admin&password=admin" \
  --body-regex "dashboard|welcome" \
  --follow
```

### Tor + periodic identity rotation

```bash
ipspoof -u http://target/ --tor --tor-new-every 10
```

### Proxy list + rate limit

```bash
ipspoof -u http://target/ --proxy-file proxies.txt --rate 30
```

### Interactive

```bash
ipspoof -i
```
Output:

![ipspoof Output](docs/images/4.jpeg)

---

## Options

| Flag | Description |
|------|-------------|
| `-u, --url` | Target URL |
| `-i, --interactive` | Interactive mode |
| `-t, --threads` | Concurrent threads (default 30) |
| `--timeout` | Request timeout (default 8s) |
| `--follow` | Follow redirects |
| `-c, --cookie` | Cookie string |
| `-X, --method` | HTTP method (default GET) |
| `-d, --data` | Form data (for POST) |
| `--json` | JSON body (for POST) |
| `-H, --header` | Extra static header (repeatable) |
| `--proxy` | Single proxy |
| `--proxy-file` | Proxy list file |
| `--tor` | Route through Tor SOCKS5 |
| `--tor-new-every N` | Rotate Tor identity every N requests |
| `--rate N` | Max requests per second |
| `--body-regex` | Only treat body regex match as HIT |
| `--body-hash` | Treat hash change as HIT |
| `--size-tol` | Size tolerance (default 0.05) |
| `--chain` | Try XFF chain variations |
| `--ip` | IPs for Phase 1 (repeatable) |
| `--phase2` | Run IP fuzz phase |
| `--ip-pattern` | IP pattern (default `10.10.10.{n}`) |
| `--ip-range` | IP range (default `1-254`) |
| `-o, --output` | Save results as JSON |

---

## Tor setup (optional)

For `--tor-new-every`, add to `/etc/tor/torrc`:

```
ControlPort 9051
CookieAuthentication 0
```

Then:

```bash
sudo systemctl restart tor
```

Without this, `--tor` still works but `--tor-new-every` will only print a warning.

---

## How it works

1. **Baseline** — sends a request with no spoof headers. Records status, size, and body hash of the "deny" response.
2. **Phase 1** — for each (header, trusted IP) pair, sends a request and compares the response against baseline. Any response with a different status, size, hash, or regex match is flagged as a HIT.
3. **Phase 2** — takes the working header(s) from Phase 1 and brute-forces the IP range you specify.

The tool never sends anything malicious — it only adds HTTP headers to ordinary requests.

---

## Legal

This tool is for **authorized security testing only**. Use it against:

- Systems you own
- Systems you have explicit written permission to test
- CTF/lab environments designed for testing

Unauthorized use against third-party systems is illegal in most jurisdictions. The author takes no responsibility for misuse.

---

## Contributing

PRs welcome. Please open an issue first for major changes.

```bash
git clone https://github.com/Exript/ipspoof.git
cd ipspoof
pip install -e ".[dev]"
```

---

## License

MIT — see [LICENSE](LICENSE).
