# Penetration Testing

Active security assessment against a live target. Unlike code-only analysis, this involves running tools against actual systems — reconnaissance, scanning, exploitation attempts, and evidence collection.

**When to use:** The user has a target (domain, IP, web app URL) and wants an offensive assessment, not just source code review. This is the "attacker's perspective" workflow.

## Prerequisites

- For **localhost/dev targets**: no authorization needed — it's the user's own machine.
- For **remote/production targets**: explicit written authorization from the target owner.
- Clear rules of engagement for remote targets (scope, testing window).
- Do NOT probe remote systems without confirmation.

## Default Flow (Path + Dev)

When the user provides a codebase path without a remote URL:

1. Run SAST via `steering/full-scan.md` on the source code
2. Detect how to start the dev server:
   - Look for `package.json` → `npm run dev` / `npm start`
   - Look for `docker-compose.yml` → `docker compose up -d`
   - Look for `Makefile` → `make run`
   - Look for `manage.py` → `python manage.py runserver`
   - Ask the user if unclear
3. Start the dev server, wait for it to be ready
4. Run DAST against `localhost:<port>` (phases 2-4 below)
5. Correlate: match DAST findings to source code locations from SAST
6. Stop the dev server

## Extended Flow (Path + Production URL)

When the user also provides a production URL:

1. Complete the default flow above (SAST + DAST localhost)
2. Show gate: "This will send active probes to [URL]. Authorized? [y/n]"
3. On confirmation: run DAST against production URL
4. Compare: findings present in dev but absent in prod (mitigated by infra?) and vice versa
5. Final report correlates all three layers

## Phase 1: Reconnaissance

Gather information without touching the target directly, then move to active probing.

### Passive (no direct contact with target)

```bash
python3 scripts/pentest.py recon-passive --target <domain>
```

The script runs:
- WHOIS lookup (registrar, nameservers, creation date)
- DNS enumeration (A, AAAA, MX, NS, TXT, CNAME records)
- Subdomain discovery via certificate transparency logs
- Technology fingerprinting from public sources

### Active (direct contact — requires authorization)

```bash
python3 scripts/pentest.py recon-active --target <ip_or_domain> --ports <range>
```

The script wraps:
- Host discovery (ping sweep or TCP probe)
- Port scanning (top 1000 or full 65535 based on `--ports`)
- Service version detection on open ports
- OS fingerprinting

Record all discovered hosts, ports, and services. This becomes the attack surface map.

## Phase 2: Enumeration

Dig deeper into discovered services.

### Web targets

```bash
python3 scripts/pentest.py enumerate-web --url <base_url>
```

Covers:
- Directory and file brute-forcing (common paths, backup files, admin panels)
- Subdomain enumeration (DNS brute, certificate transparency)
- Technology stack detection (frameworks, CMS, WAF identification)
- robots.txt, sitemap.xml, .well-known paths
- HTTP method testing on discovered endpoints
- Authentication mechanism identification

### Infrastructure targets

- Banner grabbing on non-HTTP services
- SMB share enumeration
- SNMP community string testing
- Default credential checks on known services

## Phase 3: Vulnerability Identification

Map discovered services to known vulnerabilities and potential attack vectors.

### Automated scanning

```bash
python3 scripts/pentest.py vuln-scan --target <url_or_ip> --type <web|infra>
```

For web targets, check OWASP Top 10:
1. **Injection** — SQLi, command injection, LDAP injection, template injection
2. **Broken Auth** — default creds, weak passwords, session fixation
3. **Sensitive Data Exposure** — cleartext transmission, backup files, source disclosure
4. **XXE** — XML entity injection in upload/API endpoints
5. **Broken Access Control** — IDOR, privilege escalation, path traversal
6. **Misconfig** — default pages, directory listing, verbose errors, CORS
7. **XSS** — reflected, stored, DOM-based
8. **Insecure Deserialization** — object injection in serialized data
9. **Known CVEs** — version-matched CVE checks against detected software
10. **SSRF** — server-side request forgery in URL parameters

### Manual testing

After automated scans, test for logic flaws that scanners miss:
- Business logic bypasses (price manipulation, workflow skipping)
- Race conditions in state-changing operations
- Chained vulnerabilities (low-severity issues combining into high-impact)

## Phase 4: Exploitation (Proof of Concept)

For each identified vulnerability, attempt controlled exploitation to confirm impact.

**Rules:**
- Minimal impact — demonstrate the bug, don't destroy data
- Document every step — screenshot, request/response, timestamp
- Stop if unexpected damage occurs
- Stay within authorized scope

Record results:

```bash
python3 scripts/scan_db.py add-finding \
  --scan-id <id> \
  --title "SQL Injection in /api/search" \
  --severity critical \
  --category injection \
  --file "api/routes/search.js" \
  --line 42 \
  --description "Unsanitized user input in search parameter passed directly to SQL query" \
  --evidence "Request: GET /api/search?q=1' OR 1=1-- Response: 200 OK with all database records"
```

## Phase 5: Post-Exploitation (if in scope)

When rules of engagement allow:
- Lateral movement mapping (what else can you reach from compromised position)
- Privilege escalation attempts
- Data access assessment (what sensitive data is reachable)
- Persistence mechanism identification (not deployment — just identifying)

## Phase 6: Reporting

```bash
python3 scripts/finalize.py --scan-dir .security
```

The pentest report adds to the standard report format:

| Section | Content |
|---------|---------|
| Executive Summary | Business impact in non-technical language |
| Scope | Authorized targets, testing window, methodology |
| Attack Narrative | Chronological story of the assessment |
| Findings | Sorted by severity with full reproduction steps |
| Evidence | Screenshots, request/response dumps, tool output |
| Remediation | Prioritized fix recommendations with effort estimates |
| Positive Observations | What's working well (defenders need wins too) |

## Severity Rating

Follow `references/severity-policy.md`, but with CVSS alignment for pentest context:

| Severity | CVSS Range | Pentest Context |
|----------|-----------|-----------------|
| Critical | 9.0–10.0 | RCE, full auth bypass, mass data exfil, supply chain |
| High | 7.0–8.9 | SQLi with data access, stored XSS + session theft, priv esc |
| Medium | 4.0–6.9 | Reflected XSS, info disclosure, missing security controls |
| Low | 0.1–3.9 | Missing headers, version disclosure, theoretical issues |
| Info | — | Best practices, hardening suggestions, architecture notes |

## Tools Reference

The `scripts/pentest.py` script wraps system tools when available and falls back to Python alternatives.

### Tool Matrix

| Function | System Tool | Python Alternative (pip) | Stdlib Fallback |
|----------|------------|--------------------------|-----------------|
| Port scanning | `nmap` | `python-nmap` or `python3-nmap` | `socket` connect scan |
| DNS enumeration | `dig`, `host` | `dnspython` | `socket.getaddrinfo` |
| WHOIS lookup | `whois` | `python-whois` | crt.sh HTTPS query |
| Subdomain enum | `subfinder`, `amass` | `bbot` | crt.sh CT log query |
| Dir brute-force | `gobuster`, `feroxbuster` | `dirsearch` | `urllib` common-path check |
| Tech detection | `whatweb`, `wappalyzer` | `builtwith`, `webtech` | HTTP header analysis |
| Web vuln scan | `nikto` | `wapiti3` | Manual checks |
| Template scan | `nuclei` | `wapiti3` (module-based) | Header/config checks |
| SQL injection | `sqlmap` | `sqlmap` (is Python) | Parameter probing |
| XSS detection | — | `wapiti3`, `xsser` | Reflected input check |
| OSINT recon | `theHarvester` | `theHarvester` (is Python) | Search API queries |
| HTTP proxy | `burpsuite`, `mitmproxy` | `mitmproxy` (is Python) | — |

### Installation

```bash
# Minimal (covers most use cases)
pip install dnspython python-whois requests

# Full pentest stack
pip install dnspython python-whois python3-nmap wapiti3 dirsearch bbot webtech mitmproxy
```

### Priority Order

The script tries tools in this order:
1. **System binary** (fastest, most features) — e.g., `nmap` on PATH
2. **Python pip package** (portable, no root needed) — e.g., `python3-nmap`
3. **Stdlib fallback** (always works, limited) — e.g., `socket` scan

If nothing external is available, the stdlib fallback still produces useful results — just slower and less comprehensive.