PII-Scanner3 v3.0

Complete Bug Bounty Reconnaissance Framework — 7-Phase Methodology

█████▄ ██ ██     ▄█████  ▄▄▄▄  ▄▄▄  ▄▄  ▄▄
██▄▄█▀ ██ ██ ▄▄▄ ▀▀▀▄▄▄ ██▀▀▀ ██▀██ ███▄██
██     ██ ██     █████▀ ▀████ ██▀██ ██ ▀██
   ::: PII-Scanner3 v3.0.0 :::

An enterprise-grade reconnaissance framework that follows a professional 7-phase bug bounty methodology — from passive OSINT to subdomain takeover detection — all in a single CLI tool with a rich TUI interface.

---

Quick Start

pip install -e .
pii-scanner3 recon example.com --passive

Full Scan

pii-scanner3 scan example.com --github-token ghp_xxxxx

Interactive Mode

pii-scanner3 interactive

---

The 7 Phases

Phase	Name	What It Does
1	Passive Subdomain Enumeration	OSINT sources (crt.sh, OTX, Riddler, SecurityTrails, VirusTotal, CertSpotter)
2	Active Subdomain Enumeration	DNS bruteforce (120+ wordlist), permutation, vhost enumeration
3	Infrastructure Mapping	ASN lookup, CIDR scanning, PTR resolution
4	WAF Bypass & Origin Discovery	WAF detection (9 vendors), origin IP via favicon/historical DNS/SSL
5	URL & Endpoint Discovery	Wayback Machine, OTX, URLScan, JS analysis, directory fuzzing (85 paths)
6	GitHub Intelligence	Code/repo/issue search, 35 dork queries, 13 secret patterns
7	Subdomain Takeover Detection	15 service fingerprints, CNAME classification

---

Commands

pii-scanner3 {scan,recon,interactive} [options]

Command	Description
scan	Full 7-phase reconnaissance scan
recon	Quick recon (subdomains + URLs + endpoints only)
interactive	TUI-based module picker with result browsing

Key Options

Option	Applies To	Description
--passive	scan, recon	No direct requests to target
--github-token	scan, recon	GitHub API token (Phase 6)
--org	scan, recon	GitHub/GitLab organization
--workers	scan, recon	Concurrency (default: 20)
--headless	scan	Enable Playwright browser
--output	scan, recon	Output directory (default: output/)
--exit-code	scan	CI/CD mode — exit 1 on critical findings

Full documentation: docs/usage.md

---

Architecture

.
├── main.py
├── modules/
│   ├── cli/                       # CLI app, display, interactive mode
│   ├── engine.py                  # 7-phase orchestrator
│   ├── phase1_passive_recon/      # OSINT subdomain sources
│   ├── phase2_active_recon/       # DNS bruteforce, permutation, vhost
│   ├── phase3_infrastructure/     # ASN, CIDR, PTR
│   ├── phase4_waf_bypass/         # Origin IP, WAF detection
│   ├── phase5_discovery/          # URL discovery, JS analysis, fuzzing
│   ├── phase6_github/             # GitHub scanning, dorking, secrets
│   ├── phase7_takeover/           # Subdomain takeover detection
│   ├── crawler/                   # JS crawling & scoping
│   ├── detectors/                 # Secrets, PII, source maps, AST
│   ├── analysis/                  # Taint tracking, GraphQL, correlation
│   ├── report/                    # JSON/TXT/HTML reports
│   └── utils/                     # Config, logging, banner
├── config/
│   ├── .pii-ignore.example
│   └── scope_rules.yaml
├── docs/
│   └── usage.md                   # Full documentation
├── requirements.txt
└── setup.py

---

Installation

pip install -e .                    # Core
pip install -e ".[full]"            # + browser, HTML reports, favicon hashing

Dependencies

Package	Purpose
requests	HTTP client
dnspython	DNS resolution
rich	TUI output, progress bars, tables
beautifulsoup4	HTML parsing (Phase 5)
mmh3	Favicon hashing (Phase 4)
pyOpenSSL	SSL certificate parsing (Phase 4)
playwright	Headless browser (optional)
jinja2	HTML report templates (optional)

---

Output

output/
├── report.json                 # Findings in JSON
├── summary.txt                 # Plain-text summary
├── full_results.json           # Complete scan dump
└── visualizations/
    └── report.html             # Interactive HTML report

---

CI/CD Integration

# GitHub Actions
- name: Run PII-Scanner3
  run: |
    pip install -e .
    pii-scanner3 scan https://example.com --exit-code

Exit codes: 0 = clean, 1 = secrets or takeovers found.

---

Changelog

v3.0.0 (Current)

• Complete 7-phase bug bounty methodology
• Passive/active subdomain enumeration from 12+ OSINT sources
• Infrastructure mapping (ASN, CIDR, PTR)
• WAF bypass & origin IP discovery (9 WAF vendors)
• URL discovery from Wayback/OTX/URLScan
• JavaScript analysis & directory fuzzing
• GitHub intelligence (scanning, dorking, secret patterns)
• Subdomain takeover detection (15 service fingerprints)
• Rich TUI with progress bars and summary panels
• Interactive module selection mode

v2.x

• JS crawling, secret detection, PII validation
• Source map analysis, AST analysis
• GraphQL scanning, correlation engine
• Live credential validation

---

Credits

Created and maintained by Abdul Salam

---

License

MIT