# knakul853/nuclei architecture

> Architecture diagram of the GitHub repository knakul853/nuclei, 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/knakul853/nuclei
- Repository: https://github.com/knakul853/nuclei

## Overview

##### Main Components
- CLI Entry Points – Represented in the “cmd” directory (for example, cmd/nuclei, cmd/docgen, cmd/functional-test, etc.). These modules serve as the user interface and application’s starting point.
- Core Engine and Runner – Refer to the modules in “pkg/core” and “internal/runner” that coordinate scan execution, scheduling, concurrency (via workpools), and error handling.
- Template/Catalog Loader – The nuclei engine loads scanning templates defined in YAML (see “pkg/catalog” and “pkg/templates”), making these components a key “configuration” and “rules” provider.
- Fuzzing Module – Found in “pkg/fuzz” (as well as some integration tests and associated helper libraries) which support dynamic input modifications and on-the-fly payload generation.
- Input Handling – “pkg/input” and its sub-packages (formats, providers, types) are responsible for ingesting target data (e.g., URLs, lists of hosts, files).
- Authentication and External Integrations – “pkg/authprovider,” “pkg/external,” and various reporting modules in “pkg/reporting” help integrate with external systems (e.g. ProjectDiscovery cloud, Jira, GitLab, etc.) and handle authentication for some targets.
- Reporting/Output – Managed by “pkg/output” and “pkg/reporting,” which format and send scan results in various formats (JSON, Markdown, SARIF).
- Testing & CI/CD Modules – Several directories (integration_tests, .github/workflows, Makefile, Dockerfiles, helm charts) indicate robust testing, continuous integration, and deployment orchestration.
- Additional Helpers and Libraries – The “lib,” “internal,” “pkg/utils,” and “pkg/operators” directories provide utility functions, DSL evaluators, and matching/extraction logic.

##### Relationships and Data Flow
- The Engine (core runner) takes these inputs and uses the Template Loader to retrieve YAML templates from the catalog (which might be local files or fetched from remote sources).
- Once the templates are loaded, the core engine coordinates with the Protocol Handlers by dispatching scan jobs – these use specific protocol modules (HTTP, DNS, etc.) to perform network requests, exploit simulation, or fuzzing.
- Depending on results from the protocol execution, extracted data and scan results are processed by reporting modules. These components transform the results into output formats (JSON, Markdown, etc.) and offer integration with external services.
- Optionally, there is additional support from fuzzing and DSL engine components in “pkg/fuzz” and “pkg/operators” that modify or direct scanning payloads dynamically.
- Lastly, error handling, logging, and health-check functionality (internal/runner, internal/server) ensure that the scan runtime is observable and robust.

##### Architectural Patterns/Design Principles
- Modular Design – The directory structure clearly divides responsibilities (e.g., core scanning, protocol-specific modules, input/output, fuzzing).
- Extensibility via Plugins/Templates – The YAML-based template system allows users or contributors to add or modify scan logic without touching the engine code.
- Clear Separation between User Interface (CLI) and Scanning Logic – The entry points (cmd)nuclei and runner are separate from business logic in pkg/core and pkg/protocols.
- Testing and CI/CD – As seen in the .github/workflows and integration_tests directories, continuous validation is built in.

##### Relevant Technologies, Frameworks, and Tools
- Go (Language level): The entire system is built in Go with modules that suggest extensive unit, integration, and fuzz testing.
- YAML Templates: These drive the scanning rules and detection scenarios.
- Docker & Helm: Presence in the file tree indicates containerization and deployment support.
- External Integration Points: Reporting to ProjectDiscovery cloud, integrations with Jira, Splunk, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input Layer
    subgraph "User Input Layer"
        cli["CLI Entry Points (cmd/nuclei, docgen, functional-test)"]:::cli
        input["Input Handling (pkg/input)"]:::cli
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        engine["Core Engine & Runner (pkg/core, internal/runner)"]:::core
        template["Template & Catalog Loader (pkg/catalog, pkg/templates)"]:::template
        protocol["Protocol Handlers (pkg/protocols: HTTP, DNS, SSL, headless, file, network)"]:::protocol
        fuzz["Fuzzing Module (pkg/fuzz)"]:::fuzz
    end

    %% Output & Integration Layer
    subgraph "Output & Integration Layer"
        reporting["Reporting & Output (pkg/output, pkg/reporting)"]:::reporting
        auth["Authentication & External Integrations (pkg/authprovider, pkg/external, pkg/reporting)"]:::auth
    end

    %% Support & Infrastructure
    subgraph "Support & Infrastructure"
        utils["Helpers & Utilities (lib, internal, pkg/utils, pkg/operators)"]:::utilities
        testing["Testing & CI/CD (integration_tests, .github/workflows)"]:::testing
    end

    %% Data Flow
    cli -->|"supplies"| input
    input -->|"passes targets"| engine
    engine -->|"queries"| template
    engine -->|"dispatches tasks"| protocol
    engine -->|"triggers"| fuzz
    template -->|"retrieves rules"| protocol
    protocol -->|"returns results"| reporting
    auth ---|"integrates with"| reporting

    %% Support Connections
    utils ---|"supports"| engine
    utils ---|"supports"| template
    utils ---|"supports"| protocol

    %% Styling
    classDef cli fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef core fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef template fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef protocol fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef fuzz fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef reporting fill:#f5c6cb,stroke:#333,stroke-width:2px;
    classDef auth fill:#ffe5b4,stroke:#333,stroke-width:2px;
    classDef utilities fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef testing fill:#d4d4d4,stroke:#333,stroke-width:2px;

    %% Click Events
    click cli "https://github.com/knakul853/nuclei/tree/dev/cmd/nuclei"
    click engine "https://github.com/knakul853/nuclei/tree/dev/pkg/core"
    click engine "https://github.com/knakul853/nuclei/tree/dev/internal/runner"
    click template "https://github.com/knakul853/nuclei/tree/dev/pkg/catalog"
    click template "https://github.com/knakul853/nuclei/tree/dev/pkg/templates"
    click protocol "https://github.com/knakul853/nuclei/tree/dev/pkg/protocols"
    click fuzz "https://github.com/knakul853/nuclei/tree/dev/pkg/fuzz"
    click input "https://github.com/knakul853/nuclei/tree/dev/pkg/input"
    click auth "https://github.com/knakul853/nuclei/tree/dev/pkg/authprovider"
    click auth "https://github.com/knakul853/nuclei/tree/dev/pkg/external"
    click auth "https://github.com/knakul853/nuclei/tree/dev/pkg/reporting"
    click reporting "https://github.com/knakul853/nuclei/tree/dev/pkg/output"
    click reporting "https://github.com/knakul853/nuclei/tree/dev/pkg/reporting"
    click testing "https://github.com/knakul853/nuclei/tree/dev/.github/workflows"
    click testing "https://github.com/knakul853/nuclei/tree/dev/integration_tests"
    click utils "https://github.com/knakul853/nuclei/tree/dev/lib"
    click utils "https://github.com/knakul853/nuclei/tree/dev/internal"
    click utils "https://github.com/knakul853/nuclei/tree/dev/pkg/utils"
    click utils "https://github.com/knakul853/nuclei/tree/dev/pkg/operators"
```
