Share
## https://sploitus.com/exploit?id=9BFE7385-86D8-5DA3-A472-E0D5C0C7460C
# 🔴 Bugspray
**Multi-vector web application vulnerability scanner**
*SQLi · XSS · SSTI · NoSQLi · SSRF · LFI · CMDi · Path Traversal · Open Redirect*
[](https://www.python.org)
[](LICENSE)
[](tests/)
[](CHANGELOG.md)
[]()
```text
╔══════════════════════════════════════════════════════════════╗
║ ║
║ 🔴 Bugspray — Spray bugs. Find vulns. Repeat. ║
║ ║
║ "Every web app has at least one bug. ║
║ Find it before someone else does." ║
║ ║
╚══════════════════════════════════════════════════════════════╝
```
Built by **[@shahram08](https://github.com/shahram08)** — AI Security Engineer portfolio piece #102.
---
## ⚠️ Legal Notice
**This tool is for AUTHORIZED security testing ONLY.**
- ✅ Only test systems you OWN or have EXPLICIT WRITTEN PERMISSION to test
- ❌ Unauthorized access to computer systems is illegal (CFAA, similar laws worldwide)
- ✅ Always have a signed scope-of-work (SOW) or bug bounty program invitation
- ❌ Do not use to attack systems without authorization, even for "research"
The author is not responsible for misuse. **By using this tool you agree to use it legally and ethically.**
---
## ⚡ What is Bugspray?
A CLI-first **multi-vector web vulnerability scanner** built around three core ideas:
| Pillar | What it does |
|--------|--------------|
| 🕷️ **Crawl-first** | Discovers URLs, forms, and parameters by itself (no manual setup) |
| 🎯 **Multi-vector** | 8+ injection categories in one tool — no need for sqlmap + xsser + ssrfmap separately |
| 🔐 **Auth-aware** | Login to the app first, scan the authenticated surface too |
It is **NOT** a replacement for Burp Suite Pro — it's a focused, scriptable scanner that fits in CI pipelines and learns the AI/ML Security Engineer's red-team workflow.
## ✨ Features
### Vulnerability coverage (8 vectors)
- 💉 **SQL injection** (error / boolean / time / union based; MySQL, PostgreSQL, SQLite, MSSQL)
- 🌐 **Reflected & stored XSS** (HTML, attribute, JS context)
- 🧪 **Server-Side Template Injection** (Jinja2, Twig, Freemarker, Smarty, ERB)
- 🍃 **NoSQL injection** (MongoDB operator injection)
- 🌐 **SSRF** (URL smuggling, redirect chains, internal IPs)
- 📁 **LFI / Path Traversal** (absolute, relative, encoding tricks)
- 💥 **Command Injection** (`;`, `|`, `&&`, backticks, `$()`)
- ↪️ **Open Redirect** (whitelist bypass, parameter pollution)
### Recon & enrichment
- 🔍 Built-in **web crawler** (BFS, same-origin, robots-aware)
- 🎨 **Tech fingerprinting** (CMS, frameworks, server, JS libs)
- 🍪 **Cookie security audit** (HttpOnly, Secure, SameSite)
- 🌐 **CORS misconfig detection**
- 🔐 **Auth-aware scanning** (form login, Basic, Bearer, Cookie)
### Reporting
- 📄 **Markdown** pentest report with severity badges
- 📊 **JSON** for downstream tooling (jq, Slack bots)
- 🎨 **HTML** single-file dashboard with severity heatmap
- 🛠️ **PoC generator** — outputs ready-to-paste curl/HTTPie/requests commands
### Developer experience
- 🐍 Pure Python — no Java, no external binaries
- 🧩 **Modular scanner plugins** — drop a payload file = new scanner
- 📈 **Rate limiting** — adaptive throttling, respects `Retry-After`
- 🚦 **Scope guard** — refuses URLs not in your `--scope` allowlist
- 🧪 **CI-friendly** — JSON output + exit codes for pipelines
---
## 🚀 Quick Start
### Install
```bash
git clone https://github.com/shahram08/bugspray.git
cd bugspray
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 30-second demo (safe — uses intentionally vulnerable test bed)
```bash
# Spin up DVWA (Damn Vulnerable Web App) in Docker
docker run -d -p 80:80 vulnerables/web-dvwa
# Dry-run scan (no exploits, just detection)
bugspray scan --target http://localhost/login.php --safe
# Full scan against a lab
bugspray scan --target http://localhost/login.php \
--auth-form "/login.php:username=admin&password=password" \
--vectors sqli,xss,ssti \
--output report.html
```
### CLI usage
```bash
bugspray scan --target [options]
Required:
--target, -t URL Target web application URL
Discovery:
--crawl / --no-crawl Enable URL/parameter discovery (default: on)
--depth INT Max crawl depth (default: 3)
--scope Comma-separated URL patterns to include
Authentication:
--auth-form /path:u=USER&p=PASS
--auth-basic USER:PASS
--auth-bearer TOKEN
--auth-cookie "session=xyz"
Scanners:
--vectors a,b,c Comma-separated: sqli,xss,ssti,nosqli,ssrf,lfi,cmdi,traversal,redirect
--exclude-vectors ... Skip specific vectors
--level 1-5 Detection aggression (default: 3)
Output:
--output, -o FILE Output file (.md, .html, .json — chosen by extension)
--format Explicit format: json|markdown|html
--poc Include reproduction PoC snippets
Safety:
--safe Read-only / non-destructive detection only
--confirm REQUIRED for active exploitation
--rate N Requests per second (default: 5)
--timeout N Per-request timeout seconds (default: 10)
```
### Library use
```python
from bugspray.core.scanner import Scanner
from bugspray.core.session import Session
from bugspray.scanners import sqli, xss, ssti
scanner = Scanner(
target="https://target.example.com",
session=Session(),
vectors=[sqli, xss, ssti],
level=3,
)
result = scanner.run()
print(result.summary())
for finding in result.findings:
print(f"[{finding.severity.upper()}] {finding.title} — {finding.url}")
```
---
## 📸 Sample Output
```text
🔴 Bugspray v0.1.0
[*] Crawling https://target.example.com (depth=3) ...
Discovered 47 URLs, 23 forms, 91 input points
[*] Authenticating as admin@target.example.com ...
✓ Authenticated, 18 additional URLs in scope
[*] Running scanners: sqli, xss, ssti, nosqli, ssrf, lfi, cmdi
[CRITICAL] SQL injection (UNION-based) — https://target/api/users?id=
POST /api/users id=1' UNION SELECT username,password FROM users--
[CRITICAL] Server-Side Template Injection (Jinja2) — https://target/search?q=
GET /search?q={{7*7}} → response contains "49"
[ HIGH ] Reflected XSS — https://target/profile?name=
GET /profile?name=alert(1)
[ MEDIUM ] Missing CSP header — https://target/
→ consider adding Content-Security-Policy
[ LOW ] Cookie missing HttpOnly flag — session=xyz
[*] Scan complete in 4m 12s. 18 findings, 4 severity buckets.
[*] HTML report: report.html
[*] PoC bundle: report.poc.sh
```
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ CLI (typer) │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Bugspray Core │
│ ┌──────────┬─────────────┬─────────────┬──────────────┐ │
│ │ Crawler │ Session │ RateLimit │ AuthManager │ │
│ └────┬─────┴─────────────┴─────────────┴──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Scanner Pipeline (plugin chain) │ │
│ │ sqli → xss → ssti → nosqli → ssrf → lfi → │ │
│ │ cmdi → traversal → redirect │ │
│ └───────────────────┬──────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Reporter (markdown | json | html | poc) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
Each **scanner plugin** implements:
```python
class Scanner(Protocol):
name: str
description: str
severity_levels: list[str]
async def scan(self, endpoint: Endpoint) -> list[Finding]: ...
```
Drop a new file in `bugspray/scanners/` with the protocol — auto-registered.
---
## 🛠️ Tech Stack
- **Language:** Python 3.10+ (async)
- **HTTP:** httpx (sync + async)
- **HTML parsing:** BeautifulSoup4 + lxml
- **CLI:** Typer + Rich (pretty output)
- **Testing:** pytest + pytest-asyncio
- **Reporting:** Jinja2 templates
- **Build:** setuptools + pyproject.toml (PEP 621)
## 🧪 Testing
```bash
# Run tests
pytest tests/ -v
# Coverage report
pytest tests/ --cov=bugspray --cov-report=term-missing
```
The test suite uses **MockTarget** — a vulnerable target served by the test runner itself, so no external network is required for CI.
## ⚖️ Legal & Ethics
See [SECURITY.md](SECURITY.md) for how to report vulnerabilities found **in this project itself**, and [docs/LEGAL.md](docs/LEGAL.md) for the full usage policy.
## 🤝 Contributing
PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). New scanner plugins are an especially good way to start.
## 📜 License
MIT — see [LICENSE](LICENSE).
## 🙋 Author
Built by **[@shahram08](https://github.com/shahram08)** as portfolio piece **#102** in the AI Security Engineer track.
> *Bugspray — because every web app has at least one bug. Find it before someone else does.*