# kushvaibhav/pynuclei architecture

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

- Interactive diagram: https://gitdiagram.com/kushvaibhav/pynuclei
- Repository: https://github.com/kushvaibhav/pynuclei

## Overview

##### Project type and purpose
- PyNuclei is an open-source Python library and CLI wrapper around the Nuclei vulnerability scanner (a Golang binary). It exposes a simple Python API and command-line tool to run Nuclei scans, manage templates, generate image-based PoCs, and return results as Python dictionaries.

##### File structure
- Top-level artifacts
- bin/nuclei – CLI entrypoint script
- Dockerfile & docker-compose.yml – containerize the library + Nuclei binary
- .github/workflows/python-publish.yml – build/test/publish to PyPI
- tests/ – unit tests for core functionality
- pyproject.toml, setup.py, requirements.txt – packaging and dependencies
- PyNuclei/
- PyNuclei.py – main Nuclei wrapper class
- poc.py – PoC image generation module
- static/ – configuration and image templates for PoC

##### README for additional insights
- Core features: scanning hosts with selected templates, random user-agents, rate limiting, PoC image generation (terminal, request/response, code-execution), template enumeration, update functionality.
- Usage revolves around instantiating Nuclei(path) and calling scan(), returnTemplatesDetails(), or updateNuclei().

##### Components and relationships
a. Main components
- User/Developer (CLI or Python import)
- CLI entrypoint (bin/nuclei)
- Python runtime & PyNuclei package
– Nuclei wrapper class
– PoC generator (poc.py)
– Static config/templates
- Nuclei binary (external Golang executable)
- Network/Target Hosts
- Docker container (optional deploy)
- CI/CD (GitHub Actions → PyPI)
b. Data flows / interactions
1. User invokes CLI or imports library
2. PyNuclei library initializes Nuclei class → loads config, template list
3. scan() call
– Spawns Nuclei binary process
– Passes flags (templates, rateLimit, userAgent, etc.)
– Nuclei binary scans target hosts over network → returns raw JSON results
4. PoC generator processes results → produces images (PNG)
5. Library returns Python dict + file paths for PoCs
6. updateNuclei() optionally downloads latest Nuclei binary & templates
7. Tests exercise library functions in tests/
8. Dockerfile bundles Python app + Nuclei binary for containerized usage
9. GitHub Actions runs tests, builds package, pushes to PyPI
c. Architectural patterns & principles
- Wrapper/Adapter around a CLI binary
- Separation of concerns: scanning vs. PoC generation
- Config-driven templates and rate limiting
- Containerization for reproducible environments
- CI/CD pipeline for package publishing
d. Key technologies & libraries
- Python 3.x
- Subprocess (to invoke Nuclei binary)
- Pillow or similar (for image PoC generation)
- Docker, docker-compose
- GitHub Actions
- PyPI packaging tools (setuptools, pyproject.toml)

##### Detail without overcomplicating
- Every module (Nuclei.py vs. poc.py vs. static).
- Process boundaries (local vs. external binary vs. network).
- Packaging and deployment layers (Docker, CI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Developer"]:::external
    CLI["CLI Entrypoint"]:::cli
    User -->|"invokes CLI"| CLI

    subgraph "PyNuclei Library"
        direction TB
        Wrapper["PyNuclei Wrapper Class"]:::core
        PoC["PoC Generator Module"]:::module
        Config["Static Config & Templates"]:::config
        Wrapper -->|"loads config & templates"| Config
        Wrapper -->|"calls PoC generator"| PoC
    end

    Binary["Nuclei Binary"]:::binary
    Network["Target Hosts"]:::network

    CLI -->|"calls init & scan()"| Wrapper
    Wrapper -->|"spawn process: scan request"| Binary
    Binary -->|"scans over network"| Network
    Network -->|"returns raw JSON results"| Binary
    Binary -->|"JSON results"| Wrapper
    Wrapper -->|"process results"| PoC
    PoC -->|"PNG PoC files"| User
    Wrapper -->|"returns Python dict + file paths"| User

    subgraph "Docker Container" 
        style DockerContainer stroke-dasharray: 5 5
        direction TB
        DockerfileNode["Dockerfile"]:::container
        DockerCompose["docker-compose.yml"]:::container
        DockerfileNode -->|"builds image including PyNuclei"| Wrapper
        DockerfileNode -->|"includes Nuclei Binary"| Binary
    end

    subgraph "CI/CD Pipeline"
        direction TB
        CICD["GitHub Actions"]:::cicd
        PyPI["PyPI"]:::external
        TestSuite["Test Suite"]:::tests
        Packaging1["pyproject.toml"]:::packaging
        Packaging2["setup.py"]:::packaging
        Packaging3["requirements.txt"]:::packaging
        Readme["README.md"]:::doc
        License["LICENSE"]:::doc

        Packaging1 --> CICD
        Packaging2 --> CICD
        Packaging3 --> CICD
        TestSuite --> CICD
        CICD -->|"runs tests & build"| PyPI
    end

    click CLI "https://github.com/kushvaibhav/pynuclei/tree/master/bin/nuclei"
    click Wrapper "https://github.com/kushvaibhav/pynuclei/blob/master/PyNuclei/PyNuclei.py"
    click PoC "https://github.com/kushvaibhav/pynuclei/blob/master/PyNuclei/poc.py"
    click Config "https://github.com/kushvaibhav/pynuclei/tree/master/PyNuclei/static/"
    click DockerfileNode "https://github.com/kushvaibhav/pynuclei/tree/master/Dockerfile"
    click DockerCompose "https://github.com/kushvaibhav/pynuclei/blob/master/docker-compose.yml"
    click CICD "https://github.com/kushvaibhav/pynuclei/blob/master/.github/workflows/python-publish.yml"
    click TestSuite "https://github.com/kushvaibhav/pynuclei/tree/master/tests/"
    click Packaging1 "https://github.com/kushvaibhav/pynuclei/blob/master/pyproject.toml"
    click Packaging2 "https://github.com/kushvaibhav/pynuclei/blob/master/setup.py"
    click Packaging3 "https://github.com/kushvaibhav/pynuclei/blob/master/requirements.txt"
    click Readme "https://github.com/kushvaibhav/pynuclei/blob/master/README.md"
    click License "https://github.com/kushvaibhav/pynuclei/tree/master/LICENSE"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef module fill:#ffb,stroke:#333,stroke-width:1px
    classDef config fill:#fbf,stroke:#333,stroke-width:1px
    classDef binary fill:#fbb,stroke:#333,stroke-width:1px
    classDef network fill:#ccf,stroke:#333,stroke-width:1px
    classDef container fill:#eef,stroke:#333,stroke-width:1px
    classDef cicd fill:#cff,stroke:#333,stroke-width:1px
    classDef tests fill:#fcf,stroke:#333,stroke-width:1px
    classDef packaging fill:#ffc,stroke:#333,stroke-width:1px
    classDef doc fill:#ddd,stroke:#333,stroke-width:1px
```
