# scf13/ghostscan architecture

> Architecture diagram of the GitHub repository scf13/ghostscan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scf13/ghostscan
- Repository: https://github.com/scf13/ghostscan

## Overview

GhostScan is a modular penetration-testing framework. Its main workflow accepts a target, enforces scope, performs reconnaissance and web analysis, checks for vulnerabilities, then correlates and scores findings for reports and adaptive next steps. Optional plugins add checks; browser analysis and WAF evasion extend web scanning, while integrated Kali tools support discovery and testing. The graph follows README capabilities and sampled call sites; several module internals and the reporting wiring were not sampled, so uncertain links are omitted.

Main entry points: [`ghostscan.py`](https://github.com/scf13/ghostscan/blob/main/ghostscan.py) (CLI and scan orchestration), [`plugins/base.py`](https://github.com/scf13/ghostscan/blob/main/plugins/base.py) (Plugin sandbox), [`modules/web_analysis.py`](https://github.com/scf13/ghostscan/blob/main/modules/web_analysis.py) (Web analysis), [`modules/tool_integration.py`](https://github.com/scf13/ghostscan/blob/main/modules/tool_integration.py) (Security tool adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Scan control"]
  node_entry["CLI and scan orchestration<br/>[ghostscan.py]"]
  node_scope["Scope enforcement<br/>[scope.py]"]
  node_executor["Parallel execution<br/>[executor.py]"]
end

subgraph group_discovery["Discovery"]
  node_recon["Reconnaissance<br/>[recon.py]"]
  node_tools["Security tool adapters"]
  node_web["Web analysis<br/>[web_analysis.py]"]
  node_wordlists["Wordlist selection<br/>[wordlists.py]"]
end

subgraph group_testing["Analysis and testing"]
  node_vuln["Vulnerability checks<br/>[vuln_detection.py]"]
  node_browser["Browser scanning<br/>[browser.py]"]
  node_waf["WAF evasion<br/>[waf_bypass.py]"]
end

subgraph group_assessment["Assessment and guidance"]
  node_intelligence["Scoring and correlation<br/>[intelligence.py]"]
  node_normaliser["Finding normalisation<br/>[normaliser.py]"]
  node_reporting["Report generation<br/>[reporting.py]"]
  node_workflow["Adaptive next steps<br/>[workflow.py]"]
end

subgraph group_extensions["Extensions"]
  node_pluginloader["Plugin sandbox<br/>[base.py]"]
  node_adminplugin["Admin finder<br/>[admin_finder.py]"]
  node_sensitiveplugin["Sensitive file checks<br/>[sensitive_files.py]"]
  node_xssplugin["Custom XSS checks<br/>[xss_custom.py]"]
end

node_operator(("Tester"))
node_target(("Target"))

node_operator -->|"configures scan"| node_entry
node_entry -->|"checks target"| node_scope
node_scope -->|"permits access"| node_target
node_entry -->|"starts recon"| node_recon
node_entry -->|"starts web scan"| node_web
node_entry -->|"starts checks"| node_vuln
node_entry -->|"loads plugins"| node_pluginloader
node_entry -->|"analyses results"| node_intelligence
node_entry -->|"requests report"| node_reporting
node_entry -->|"requests guidance"| node_workflow
node_entry -->|"dispatches tasks"| node_executor
node_recon -->|"runs tools"| node_tools
node_web -->|"runs tools"| node_tools
node_web -->|"selects lists"| node_wordlists
node_web -.->|"applies evasion"| node_waf
node_web -.->|"uses browser"| node_browser
node_vuln -->|"runs tools"| node_tools
node_pluginloader -->|"runs plugin"| node_adminplugin
node_pluginloader -->|"runs plugin"| node_sensitiveplugin
node_pluginloader -->|"runs plugin"| node_xssplugin
node_adminplugin -->|"returns findings"| node_pluginloader
node_sensitiveplugin -->|"returns findings"| node_pluginloader
node_xssplugin -->|"returns findings"| node_pluginloader
node_intelligence -->|"normalises findings"| node_normaliser
node_reporting -->|"presents results"| node_operator
node_workflow -->|"suggests actions"| node_operator

click node_entry "https://github.com/scf13/ghostscan/blob/main/ghostscan.py"
click node_scope "https://github.com/scf13/ghostscan/blob/main/modules/scope.py"
click node_executor "https://github.com/scf13/ghostscan/blob/main/modules/executor.py"
click node_recon "https://github.com/scf13/ghostscan/blob/main/modules/recon.py"
click node_tools "https://github.com/scf13/ghostscan/blob/main/modules/tool_integration.py"
click node_web "https://github.com/scf13/ghostscan/blob/main/modules/web_analysis.py"
click node_wordlists "https://github.com/scf13/ghostscan/blob/main/modules/wordlists.py"
click node_vuln "https://github.com/scf13/ghostscan/blob/main/modules/vuln_detection.py"
click node_browser "https://github.com/scf13/ghostscan/blob/main/modules/browser.py"
click node_waf "https://github.com/scf13/ghostscan/blob/main/modules/waf_bypass.py"
click node_pluginloader "https://github.com/scf13/ghostscan/blob/main/plugins/base.py"
click node_adminplugin "https://github.com/scf13/ghostscan/blob/main/plugins/admin_finder.py"
click node_sensitiveplugin "https://github.com/scf13/ghostscan/blob/main/plugins/sensitive_files.py"
click node_xssplugin "https://github.com/scf13/ghostscan/blob/main/plugins/xss_custom.py"
click node_intelligence "https://github.com/scf13/ghostscan/blob/main/modules/intelligence.py"
click node_normaliser "https://github.com/scf13/ghostscan/blob/main/modules/normaliser.py"
click node_reporting "https://github.com/scf13/ghostscan/blob/main/modules/reporting.py"
click node_workflow "https://github.com/scf13/ghostscan/blob/main/modules/workflow.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_scope,node_executor toneBlue
class node_recon,node_tools,node_web,node_wordlists toneAmber
class node_vuln,node_browser,node_waf toneMint
class node_intelligence,node_normaliser,node_reporting,node_workflow toneRose
class node_pluginloader,node_adminplugin,node_sensitiveplugin,node_xssplugin,node_operator,node_target toneIndigo
```

## Components

### Scan control

- [CLI and scan orchestration](https://github.com/scf13/ghostscan/blob/main/ghostscan.py): `ghostscan.py`
- [Scope enforcement](https://github.com/scf13/ghostscan/blob/main/modules/scope.py): `modules/scope.py`
- [Parallel execution](https://github.com/scf13/ghostscan/blob/main/modules/executor.py): `modules/executor.py`

### Discovery

- [Reconnaissance](https://github.com/scf13/ghostscan/blob/main/modules/recon.py): `modules/recon.py`
- [Security tool adapters](https://github.com/scf13/ghostscan/blob/main/modules/tool_integration.py): `modules/tool_integration.py`
- [Web analysis](https://github.com/scf13/ghostscan/blob/main/modules/web_analysis.py): `modules/web_analysis.py`
- [Wordlist selection](https://github.com/scf13/ghostscan/blob/main/modules/wordlists.py): `modules/wordlists.py`

### Analysis and testing

- [Vulnerability checks](https://github.com/scf13/ghostscan/blob/main/modules/vuln_detection.py): `modules/vuln_detection.py`
- [Browser scanning](https://github.com/scf13/ghostscan/blob/main/modules/browser.py): `modules/browser.py`
- [WAF evasion](https://github.com/scf13/ghostscan/blob/main/modules/waf_bypass.py): `modules/waf_bypass.py`

### Assessment and guidance

- [Scoring and correlation](https://github.com/scf13/ghostscan/blob/main/modules/intelligence.py): `modules/intelligence.py`
- [Finding normalisation](https://github.com/scf13/ghostscan/blob/main/modules/normaliser.py): `modules/normaliser.py`
- [Report generation](https://github.com/scf13/ghostscan/blob/main/modules/reporting.py): `modules/reporting.py`
- [Adaptive next steps](https://github.com/scf13/ghostscan/blob/main/modules/workflow.py): `modules/workflow.py`

### Extensions

- [Plugin sandbox](https://github.com/scf13/ghostscan/blob/main/plugins/base.py): `plugins/base.py`
- [Admin finder](https://github.com/scf13/ghostscan/blob/main/plugins/admin_finder.py): `plugins/admin_finder.py`
- [Sensitive file checks](https://github.com/scf13/ghostscan/blob/main/plugins/sensitive_files.py): `plugins/sensitive_files.py`
- [Custom XSS checks](https://github.com/scf13/ghostscan/blob/main/plugins/xss_custom.py): `plugins/xss_custom.py`

### Other components

- **Tester**
- **Target**

## Connections

- Tester → CLI and scan orchestration: configures scan
- CLI and scan orchestration → Scope enforcement: checks target
- Scope enforcement → Target: permits access
- CLI and scan orchestration → Reconnaissance: starts recon
- CLI and scan orchestration → Web analysis: starts web scan
- CLI and scan orchestration → Vulnerability checks: starts checks
- CLI and scan orchestration → Plugin sandbox: loads plugins
- CLI and scan orchestration → Scoring and correlation: analyses results
- CLI and scan orchestration → Report generation: requests report
- CLI and scan orchestration → Adaptive next steps: requests guidance
- CLI and scan orchestration → Parallel execution: dispatches tasks
- Reconnaissance → Security tool adapters: runs tools
- Web analysis → Security tool adapters: runs tools
- Web analysis → Wordlist selection: selects lists
- Web analysis → WAF evasion: applies evasion
- Web analysis → Browser scanning: uses browser
- Vulnerability checks → Security tool adapters: runs tools
- Plugin sandbox → Admin finder: runs plugin
- Plugin sandbox → Sensitive file checks: runs plugin
- Plugin sandbox → Custom XSS checks: runs plugin
- Admin finder → Plugin sandbox: returns findings
- Sensitive file checks → Plugin sandbox: returns findings
- Custom XSS checks → Plugin sandbox: returns findings
- Scoring and correlation → Finding normalisation: normalises findings
- Report generation → Tester: presents results
- Adaptive next steps → Tester: suggests actions