# dghostninja/vulnera architecture

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

- Interactive diagram: https://gitdiagram.com/dghostninja/vulnera
- Repository: https://github.com/dghostninja/vulnera

## Overview

##### Project Type & Purpose
- Vulnera is an automated DAST scanner built in Python, designed to be integrated into CI/CD pipelines (e.g., GitHub Actions) or run manually via Docker or direct execution.
- The system scans web applications using an external scanning tool (Wapiti) and reports findings via Telegram alerts.
- Key focuses: integration in continuous deployment pipelines, Docker support for containerized environments, multi-target scanning, and report notifications.

##### Analyzing the File Structure
- Top-Level Files/Folders:
- .github/workflows/main.yml: Contains GitHub Actions configuration that automates scanning on every push and scheduled runs.
- Dockerfile: Defines container setup to run the scanner.
- scan.py: Main Python script responsible for running the vulnerability scan.
- requirements.txt: Lists Python dependencies.
- targets.txt: Used to provide multiple URLs when scanning.
- assets: Contains images (e.g., banner) used in the documentation.
- The layout is simple, supporting a single-purpose utility with diverse deployment methods.

##### Key Components of the System
a. Scanner Core (scan.py):
- Responsible for orchestrating the vulnerability scanning using Wapiti (an external dependency).
- Reads a single target or multiple targets from targets.txt.
- Processes scanning results and triggers notifications.
b. External Security Scanner (Wapiti):
- An established open-source web vulnerability scanner integrated by the Python script.
c. CI/CD Integration (GitHub Actions):
- Located in the .github/workflows directory.
- Automates dependency caching, installation, scanning execution and report dispatch.
d. Docker Environment:
- Containerizes the application, ensuring compatibility across deployment environments.
- The Dockerfile defines how the application, along with Wapiti and Python dependencies, is bundled.
e. Telegram Notification Module:
- Integrated within scan.py, sends real-time vulnerability reports using configured Telegram credentials.
f. User Provided Targets:
- The use of targets.txt indicates support for scanning multiple URLs.

##### Relationships & Interactions
- The scanner (scan.py) acts as the central orchestrator:
- It triggers Wapiti to perform security scans.
- Depending on configuration, it reads targets either from its command line or from targets.txt.
- After scanning, it formats and sends reports to Telegram.
- The CI/CD pipeline (GitHub Actions workflow) automates:
- Environment setup (dependency installation, caching of Wapiti).
- Running scan.py as part of the security testing on pushes or on a schedule.
- Docker provides a consistent runtime where the above processes (scanning + reporting) run encapsulated.

##### Final Guidance
- “Scanner Core (scan.py)”
- Linked to “Targets Input (targets.txt/CLI)”
- Linked to “Wapiti Scanner”
- Linked to “Telegram Reporting”
- “CI/CD Pipeline (GitHub Actions)” which triggers the scanner and manages environment set-up.
- “Docker Container” that encapsulates the application for consistent deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Vulnera["Vulnera DAST Scanner"]:::main
    Vulnera -->|"triggers"| CI["CI/CD Pipeline (GitHub Actions)"]:::ci
    CI -->|"builds"| DC["Docker Container"]:::docker
    DC -->|"supports"| ME["Manual Execution (CLI)"]:::manual
    ME -->|"invokes"| SC["Scanner Core (scan.py)"]:::core
    TI["Targets Input (CLI/targets.txt)"]:::input
    DEPS["Deps (requirements.txt)"]:::deps
    TI -->|"provides targets"| SC
    DEPS -->|"supplies dependencies"| SC
    SC -->|"runs scan with"| WS["Wapiti Scanner (External)"]:::external
    SC -->|"reports via"| TR["Telegram Reporting (Telegram API)"]:::external

    click CI "https://github.com/dghostninja/vulnera/blob/main/.github/workflows/main.yml"
    click DC "https://github.com/dghostninja/vulnera/tree/main/Dockerfile"
    click SC "https://github.com/dghostninja/vulnera/blob/main/scan.py"
    click TI "https://github.com/dghostninja/vulnera/blob/main/targets.txt"
    click DEPS "https://github.com/dghostninja/vulnera/blob/main/requirements.txt"
    click WS "https://github.com/dghostninja/vulnera/blob/main/scan.py"
    click TR "https://github.com/dghostninja/vulnera/blob/main/scan.py"

    classDef main fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef ci fill:#C1E1C1,stroke:#000,stroke-width:2px;
    classDef docker fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef manual fill:#FFFFCC,stroke:#000,stroke-width:2px;
    classDef core fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef input fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef deps fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:2px;
```
