Metadata-Version: 2.4
Name: humanoidprobe
Version: 1.0.8
Summary: HumanoidProbe is a command-line XSS WAF intelligence tool that probes how a WAF responds to payload variations — telling you what gets blocked, what passes through, and what gets reflected back.
Author-email: CyberSafeLabs <hello.cybersafe@gmail.com>
Project-URL: Homepage, https://github.com/hellocybersafe/humanoidprobe
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests

# HumanoidProbe
**by CyberSafeLabs**

> *Analyse WAF behaviour. Think like an attacker.*

HumanoidProbe is a command-line XSS WAF intelligence tool that probes how a WAF responds to payload variations — telling you what gets blocked, what passes through, and what gets reflected back.

Built from real bug bounty research. Not theory.

---

## What it does

- Fires categorised XSS payload variations at a target URL and parameter
- Detects WAF blocks via status codes, response body analysis, and response length changes
- Identifies reflected payloads — the highest value findings
- Summarises WAF behaviour and what it appears to be filtering
- Gives you actionable intelligence to craft smarter bypass payloads

---

## Installation

**1. Make sure Python 3 is installed**
```bash
python3 --version
```
If not:
```bash
sudo apt update && sudo apt install python3 python3-pip -y
```

**2. Install the dependency**
```bash
pip3 install requests
```

---

## Usage

```bash
python3 humanoidprobe.py -u <URL> -p <parameter>
```

**Example:**
```bash
python3 humanoidprobe.py -u https://example.com/search -p q
```

**With options:**
```bash
python3 humanoidprobe.py -u https://example.com/search -p q --delay 1 --timeout 15
```

---

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `-u` / `--url` | Target URL | Required |
| `-p` / `--parameter` | GET parameter to test | Required |
| `--payloads` | Custom payload file path | payloads/xss.txt |
| `--delay` | Seconds between requests | 0.5 |
| `--timeout` | Request timeout in seconds | 10 |

---

## Output verdicts

| Verdict | Meaning |
|---------|---------|
| `REFLECTED` | Payload passed AND appeared in the response — investigate in browser immediately |
| `PASSED` | WAF did not block — worth exploring further |
| `BLOCKED` | WAF caught this payload |
| `ERROR` | Request failed (timeout, connection error) |

---

## Project structure

```
humanoidprobe/
├── humanoidprobe.py    # Main entry point — what you run
├── payloads/
│   └── xss.txt         # XSS payload list
├── core/
│   ├── requester.py    # Sends HTTP requests
│   ├── detector.py     # Analyses responses (blocked vs passed)
│   └── reporter.py     # Terminal output and summary
└── README.md
```

---

## Roadmap

- [ ] WAF memory — builds a profile of WAF behaviour across sessions
- [ ] Intelligent bypass suggestions — generates mutations based on what passed
- [ ] POST parameter support
- [ ] SQLi payload module
- [ ] Output to file (JSON / txt)
- [ ] Burp Suite integration
- [ ] Full recon and attack surface mapping modules
- [ ] Humanoid Intelligence — AI layer (coming in future versions)

---

## Legal & ethical use

Only use HumanoidProbe against targets you have explicit permission to test.
Unauthorised testing is illegal. This tool is built for legitimate security research and bug bounty programmes only.

---

## About

HumanoidProbe is the first tool from **CyberSafeLabs** — an independent cybersecurity research initiative focused on protecting digital assets through offensive research, vulnerability discovery, and practical security tooling.

The long-term vision: **Humanoid Intelligence** — an AI-powered security research platform built from real hunting experience.

*CyberSafeLabs — protecting digital assets through research*
