py-scan

A modular security scanning toolkit. Applying concepts learned in SEC542: Web App Penetration Testing and Ethical Hacking.

• requests + BeautifulSoup (basic discovery)
• Typer CLI with organized modes/ directory
• Async DAST (Playwright + asyncio) with basic test suite

Project Structure

py-scan/
├── main.py          # CLI entry point
├── modes/           # Scanning modules
│   ├── scanner.py      # Web discovery
│   ├── web_check.py    # Security headers
│   ├── forensics.py    # EXIF & PII analysis
│   ├── dns_recon.py    # DNS reconnaissance
│   ├── port_scanner.py # TCP port scanning
│   ├── brute.py        # SSH Brute force
│   ├── network.py      # Packet crafting (scapy)
│   └── engine.py       # Async DAST engine (playwright)
└── tests/           # Test suite

Usage

1. Create virtual environment:
   • python3 -m venv .venv
2. Initialize virtual environment:
   • source .venv/bin/activate
3. Install packages:
   • pip install .

Web Security

4. Scan for links/forms:
   • python3 main.py scan https://www.scrapethissite.com/pages/forms/
5. Check security headers/files:
   • python3 main.py test-web https://www.scrapethissite.com/pages/forms/

Networking & DNS

6. Resolve DNS records:
   • python3 main.py dns google.com
7. Scan common TCP ports:
   • python3 main.py scan-ports 127.0.0.1

Packet Crafting (requires root)

May need to re-run the setup commands with sudo for this to work.

8. Ping target with ICMP:
   • sudo python3 main.py ping 8.8.8.8
9. TCP SYN scan (raw sockets):
   • sudo python3 main.py syn-scan 192.168.1.1
10. Craft custom packet:
    • sudo python3 main.py craft "IP(dst='8.8.8.8')/ICMP()"
    • sudo python3 main.py craft "IP(dst='1.1.1.1')/TCP(dport=80)"

Brute Force (requires targets)

Security Warning: Only use on systems you own or have explicit permission to test

11. SSH brute force:

    • python3 main.py brute-ssh 192.168.1.10 data/users.txt data/pass.txt --delay 1 --stop-on-success

12. SMB brute force:

    • python3 main.py brute-smb 192.168.1.10 data/users.txt data/pass.txt --delay 0.5

13. Generate wordlist:

    • python3 main.py wordlist "admin,root,user" output.txt --patterns "123,\!,2024"

14. Quick service reconnaissance:

    • python3 main.py quick-check-services 192.168.1.10

DAST (Dynamic Application Security Testing)

Uses Playwright for browser automation - scans JavaScript-heavy applications

15. Run DAST scan (async crawling with XSS detection):
    • python3 main.py dast https://example.com
    • python3 main.py dast https://example.com --depth 3 --workers 5 --headless false
    • python3 main.py dast https://example.com --max-pages 100 --output-dir ./scan-results

Generates HTML report with findings. Report includes:

• XSS vulnerabilities (reflected, DOM-based, stored)
• Full page HTML capture for evidence
• Screenshots of vulnerable pages
• Severity classifications (Critical, High, Medium, Low)

Forensics

15. Extract EXIF data:
    • python3 main.py forensics exif assets/test-img-1.jpg
    • python3 main.py forensics exif assets/test-img-2.jpg
16. Scan for PII:
    • python3 main.py forensics pii assets/test-txt-1.txt
    • python3 main.py forensics pii assets/test-txt-2.txt
17. Extract strings from binary:
    • python3 main.py forensics strings assets/test-img-1.jpg | head
    • python3 main.py forensics strings assets/test-img-2.jpg | head

Development

1. Install development dependencies:
   • pip install -e ".[dev]"
2. Run quality checks (linting, types, tests):
   • ``./scripts/check.sh`
3. Auto-format code:
   • ``./scripts/format.sh`
4. Run specific test modules:
   • pytest tests/test_dns.py or
   • pytest tests/test_ports.py ...

Note: All code should pass ./scripts/check.sh before being committed.

Roadmap

• Pre-commit hooks for ruff, mypy, and pytest
• Enhanced DAST patterns for additional vulnerability classes
• Functional directory reorganization (web/, network/, forensics/, exploit/)