GhostScan v3.0 — From Scattered Scripts to an Elite Open-Source Pentest Framework

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

GhostScan v3.0 is an elite, modular penetration testing framework for Kali Linux that brings together 53 security tools under a single, intelligent CLI — with correlation-aware scoring, WAF bypass profiles, adaptive workflows, and professional report generation.

The philosophy behind GhostScan is simple but powerful: signal over noise. Most security scanners dump 300+ raw findings and leave the tester to figure out what matters. GhostScan gives you 10 findings you can act on today, each ranked by a scoring formula that accounts for real-world impact, exploitability confidence, and business context:

score = (impact × 0.6) + (confidence × 0.4)

What makes it different from a typical scanner wrapper:

• Correlation engine — automatically detects compound risks. A login panel + SQL injection isn't two MEDIUM findings. It's one CRITICAL: SQLi on Auth Endpoint = Auth Bypass + Full DB Dump, scored at 9.8.
• Context multipliers — payment paths, exposed databases, and authenticated endpoints automatically elevate severity based on business impact.
• WAF bypass profiles — auto-detects CloudFlare, Akamai, AWS WAF, F5, Imperva, ModSecurity, Wordfence, and Sucuri, then applies the right sqlmap tamper chain and timing delays.
• Plugin system — drop a .py file into plugins/ and it loads automatically on the next scan. Plugins run sandboxed with timeout kill-switches so a broken plugin never stops the chain.
• Adaptive workflow engine — after each scan, GhostScan generates exact next commands based on what was actually found, not a static checklist.
• Scan profiles — stealth (passive only, 2s rate, no probing), standard (balanced), and aggressive (all modules, 50 threads, large wordlists, full injection suite).
• Report generation — PDF, HTML, Markdown, and JSON out of the box.
• CI/CD from day one — GitHub Actions runs syntax checks and unit tests across Python 3.10, 3.11, and 3.12 on every push.

⚠️ For authorized security testing only. Always obtain written permission before testing any system.

GitHub repository: https://github.com/rodrigofurlaneti/scanghost

Demo

Example scan output (correlation engine):

✓ Login panel at /wp-login.php (HTTP 200)
✓ SQL injection in ?search= (boolean-based)
✓ Content-Security-Policy missing
= 🔴 CRITICAL [9.8] SQLi on Auth Endpoint = Auth Bypass + DB Dump
  Attack: admin'-- → bypass auth → dump wp_users → crack hashes

✓ Redis on port 6379 (open to internet)
✓ No authentication (default config)
= 🔴 CRITICAL [9.6] Database Exposed Externally
  Attack: redis-cli → CONFIG SET → cron RCE

Full scan, PDF report:

ghostscan -t your-authorized-target.com --all --report pdf

Stealth recon only:

ghostscan -t target.com --mode stealth --recon

WAF bypass + browser DOM XSS:

ghostscan -t target.com --web --waf-bypass --browser --screenshots

The Comeback Story

This project started from a frustrating reality: penetration testing workflows are fragmented. You run nmap, then manually feed results into nikto, then into sqlmap, then into gobuster — each tool in its own terminal window, each output in its own format, and you're left manually correlating 300 raw findings to figure out what actually matters.

I started GhostScan as a personal tool to fix that for myself. The first version was a single Python script that called tools sequentially and printed output to the terminal. It worked, but barely — one missing tool would crash the whole run, there was no scoring, no scope enforcement, and the "report" was a text dump.

It sat unfinished for months. The core idea was solid, but it needed a lot more work before I'd share it with anyone. The Finish-Up-A-Thon was the push I needed.

Before — what the project looked like when I picked it back up:

• A single Python script that called tools sequentially
• No scoring or severity weighting — everything was "found" or "not found"
• No scope enforcement — it could happily scan out-of-scope hosts
• No WAF awareness — most active scans got blocked immediately
• Reports were raw terminal output dumped to a text file
• No plugin system, no extensibility
• No CI, no tests

What I finished to get to v3:

1. Hard scope enforcement — ScopeEnforcer blocks out-of-scope requests and SSRF-prone IPs (169.254.x.x, 10.x.x.x by default) before any tool even runs. This was the most important safety addition.

2. Safe parallel executor — SafeExecutor runs tools concurrently with per-tool timeouts, retry logic, and failure isolation. One broken tool (e.g. a segfaulting nuclei template) never stops the scan.

3. Intelligence & correlation engine — IntelligenceEngine cross-references all findings from all modules to detect compound attack paths. This was the hardest module to finish. The raw data comes in from recon, web, and vuln modules in different shapes; the engine normalises it, deduplicates it, applies context multipliers, ranks attack surface targets, and surfaces correlations.

4. WAF bypass engine — WafBypass maps detected WAF vendors to specific sqlmap tamper scripts, encoding techniques, and rate delays. Previously the framework just got blocked and returned zero findings against WAF-protected targets.

5. Adaptive workflow engine — WorkflowEngine generates contextual next steps. If SQLi was found, it tells you exactly which sqlmap flags to run. If Redis is open, it gives you the specific redis-cli commands. Not generic advice — exact commands.

6. Headless browser module — HeadlessBrowser (Playwright) scans for DOM XSS, hidden endpoints, and client-side secrets. Catches things that static HTTP requests miss entirely.

7. Plugin system — completely new. plugins/base.py defines the GhostScanPlugin base class with sandboxed loading, per-plugin timeouts, confidence thresholds, and finding caps. Three built-in plugins ship with the framework: admin_finder.py, xss_custom.py, and sensitive_files.py.

8. Report generation — ReportingModule now produces proper PDF reports (via ReportLab), dark-theme HTML, structured JSON, and Markdown — all from the same normalised finding schema.

9. Web frontend + API — the framework was wrapped in an API layer and a web interface to make it accessible beyond the command line. The deployment config (staticwebapp.config.json) includes hardened security headers out of the box — it would be embarrassing for a security tool to ship without CSP, HSTS, and X-Frame-Options.

10. CI/CD — GitHub Actions runs syntax checks and integration tests across Python 3.10/3.11/3.12 on every push. The test suite validates scope enforcement (SSRF protection), WAF bypass profiles, and the intelligence correlation engine.

The transformation from "one guy's unfinished script" to a tested, documented, CI-backed open-source framework took months of evenings and weekends. The Finish-Up-A-Thon was the deadline I needed to actually ship it.

My Experience with GitHub Copilot

GitHub Copilot was deeply involved in every phase of this project — not as a code generator I blindly accepted, but as a fast, context-aware collaborator that dramatically reduced the time between "I know what this should do" and "this actually works."

Where Copilot helped the most:

Building the intelligence engine. The correlation logic is the most complex part of GhostScan. Given a Redis port open on the internet, a login panel, a missing CSP header, and a JS secret — how do you automatically detect which combinations create compound CRITICAL risks? I described the desired behaviour in a comment and Copilot drafted the scoring matrix and multiplier logic. It wasn't perfect on the first attempt, but it gave me a structure I could reason about and refine, instead of staring at a blank file.

The WAF bypass profiles. Mapping 8 different WAF vendors to their known sqlmap tamper chains, encoding specifics, and appropriate timing delays is tedious research work. Copilot accelerated this significantly — I'd write the CloudFlare profile, and Copilot would suggest accurate completions for Akamai, F5, and Imperva based on the pattern it saw. I still validated every tamper chain against actual test environments, but the scaffolding was generated in minutes.

Writing the plugin sandbox. Building a plugin loader that isolates crashes, enforces timeouts, caps findings, and suppresses low-confidence results requires a lot of boilerplate threading and error-handling code. Copilot handled most of that correctly on the first pass, which meant I could focus on the plugin API design rather than concurrent.futures plumbing.

The reporting module. Generating PDF reports with ReportLab is notoriously verbose. Copilot wrote most of the table formatting, colour mapping, and page layout code from a short description and the finding schema. I estimated that would have taken me two full evenings to write from scratch; with Copilot it took a few hours.

Test cases. The CI integration tests — scope enforcement, WAF bypass validation, intelligence engine assertions — were mostly Copilot-generated from the function signatures and docstrings. It understood what the functions were supposed to do and wrote meaningful assertions.

What Copilot didn't replace: architectural decisions, security correctness, and tool integration logic. Every suggestion got reviewed, and anything touching security behaviour (scope enforcement, SSRF protection, WAF detection) was written and tested manually.

The honest summary: without Copilot, GhostScan v3 would still be unfinished. With it, I shipped a tested, documented, CI-backed framework. That's the difference.