# psantana5/vuln-scanner architecture

> Architecture diagram of the GitHub repository psantana5/vuln-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psantana5/vuln-scanner
- Repository: https://github.com/psantana5/vuln-scanner

## Overview

##### Project type and purpose
- This is an open-source, command-line vulnerability scanning tool written in Python.
- It leverages the Requests library to probe a user-supplied target URL for various web and network security issues (XSS, SQLi, directory traversal, etc.).

##### File structure
- Top-level:
- README.md – project documentation and usage instructions
- vuln_scanner/ – main package directory
- Inside vuln_scanner/:
- scanner.py – the only source file; implements the CLI menu, dispatches scanning routines, collects and displays results
- No submodules or multiple services—this is a single-binary tool.

##### README for additional insights
- Describes features (types of vulnerability scans).
- Outlines the user flow: run scanner.py → pick a category → pick a vulnerability → enter target URL → view results.
- Dependencies: Python + requests.

##### Main components
a. User (Operator) – the person invoking the scanner
b. CLI Interface (scanner.py menu) – handles user input, selection logic
c. Scanner Engine – core logic that maps menu selections to scan routines
d. Vulnerability Modules – discrete functions for XSS, SQLi, Directory Traversal, etc.
e. HTTP Client (Requests library) – issues HTTP requests to the target
f. Target Web Application – the external system under test
g. Reporting / Output Formatter – collects scan results, formats console output

##### Relationships and interactions
- User → (runs) → CLI Interface
- CLI Interface → (invokes) → Scanner Engine
- Scanner Engine → (calls) → Vulnerability Module (e.g., run_xss_scan)
- Vulnerability Module → (uses) → HTTP Client → (sends request) → Target Web Application
- Target Web Application → (returns response) → HTTP Client → Vulnerability Module
- Vulnerability Module → (reports findings) → Scanner Engine
- Scanner Engine → (forwards) → Reporting Module → (displays) → User

##### Architectural patterns and design principles
- Single-process, modular design: each vulnerability category is a module/function
- Clear separation of concerns:
- CLI/UI layer
- Core scanning logic
- Network interaction layer (requests)
- Reporting/output
- Dependency on external service is unidirectional (scanner → target).

##### Relevant technologies and libraries
- Python 3.x runtime
- requests library for HTTP interactions
- Standard library modules for CLI I/O and basic parsing

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User (Operator)"]:::actor
    README["Project Documentation (README.md)"]:::external
    CLI["CLI Interface"]:::internal
    Engine["Scanner Engine"]:::internal
    subgraph "Vulnerability Modules"
        XSS["XSS Scan Function"]:::internal
        SQLi["SQLi Scan Function"]:::internal
        Dir["Directory Traversal Scan Function"]:::internal
    end
    HTTP["HTTP Client (requests)"]:::library
    Target["Target Web Application"]:::external
    Reporting["Reporting / Output Formatter"]:::internal

    User -->|"run scanner"| CLI
    README -->|"consult instructions"| User
    CLI -->|"invoke scan"| Engine
    Engine -->|"call scan"| XSS
    Engine -->|"call scan"| SQLi
    Engine -->|"call scan"| Dir
    XSS -->|"HTTP request"| HTTP
    SQLi -->|"HTTP request"| HTTP
    Dir -->|"HTTP request"| HTTP
    HTTP -->|"HTTP response"| XSS
    HTTP -->|"HTTP response"| SQLi
    HTTP -->|"HTTP response"| Dir
    XSS -->|"report findings"| Engine
    SQLi -->|"report findings"| Engine
    Dir -->|"report findings"| Engine
    Engine -->|"forward results"| Reporting
    Reporting -->|"display results"| User

    click README "https://github.com/psantana5/vuln-scanner/blob/main/README.md"
    click CLI "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click Engine "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click XSS "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click SQLi "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click Dir "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click HTTP "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"
    click Reporting "https://github.com/psantana5/vuln-scanner/blob/main/vuln_scanner/scanner.py"

    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef library fill:#ffb,stroke:#333,stroke-width:1px
```
