How kushvaibhav/pynuclei works
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).