{"id":30201556,"url":"https://github.com/miladhzzzz/nuclei-api","last_synced_at":"2025-08-13T10:51:01.345Z","repository":{"id":307278108,"uuid":"922879540","full_name":"miladhzzzz/nuclei-api","owner":"miladhzzzz","description":"MCP Server / API Wrapper For Nuclei Scanner","archived":false,"fork":false,"pushed_at":"2025-07-30T10:23:28.000Z","size":269,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-30T12:52:02.984Z","etag":null,"topics":["automation","bugbounty","cybersecurity","mcp-server","platform","python","reconnaissance"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/miladhzzzz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-27T08:54:33.000Z","updated_at":"2025-07-12T16:09:36.000Z","dependencies_parsed_at":"2025-07-30T12:52:05.629Z","dependency_job_id":"995a1461-eaab-4b4c-b878-8bbe208161bb","html_url":"https://github.com/miladhzzzz/nuclei-api","commit_stats":null,"previous_names":["miladhzzzz/nuclei-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/miladhzzzz/nuclei-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladhzzzz%2Fnuclei-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladhzzzz%2Fnuclei-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladhzzzz%2Fnuclei-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladhzzzz%2Fnuclei-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miladhzzzz","download_url":"https://codeload.github.com/miladhzzzz/nuclei-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladhzzzz%2Fnuclei-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270228430,"owners_count":24548818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","bugbounty","cybersecurity","mcp-server","platform","python","reconnaissance"],"created_at":"2025-08-13T10:50:31.434Z","updated_at":"2025-08-13T10:51:01.344Z","avatar_url":"https://github.com/miladhzzzz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nuclei API: Automated Vulnerability Template Generation \u0026 Scanning Platform\n\n## Overview\n\n**Nuclei API** is an advanced, AI-augmented platform for automated vulnerability scanning and template management, built around [Nuclei](https://nuclei.projectdiscovery.io/). It provides a REST API for running scans, managing templates, and orchestrating a pipeline that fetches new vulnerabilities, generates detection templates using an LLM, validates them, and refines them as needed. The system leverages FastAPI, Celery, Redis, Docker, and Ollama (LLM) to deliver scalable, intelligent, and automated security scanning.\n\n---\n\n## Key Features\n\n- **Automated CVE Template Generation:**  \n  Fetches recent vulnerabilities (CVEs) from public sources and uses an LLM to generate Nuclei YAML templates for each.\n- **Template Validation \u0026 Refinement:**  \n  Validates generated templates by running them against known vulnerable hosts. If validation fails, templates are refined using the LLM and retried.\n- **Flexible Scanning API:**  \n  Exposes endpoints to run Nuclei scans on targets (IP/domain), with support for custom templates, AI-generated templates, and standard templates.\n- **Asynchronous Pipeline:**  \n  Uses Celery for distributed, asynchronous task orchestration (fetching, generating, validating, refining).\n- **Metrics \u0026 Caching:**  \n  Uses Redis for caching vulnerability data and tracking pipeline metrics.\n- **Containerized Scanning:**  \n  Runs Nuclei scans in Docker containers for isolation and resource control.\n- **Custom Template Support:**  \n  Upload and use your own Nuclei templates.\n- **Real-Time Log Streaming:**  \n  Stream scan logs directly from running Docker containers.\n- **Extensible \u0026 Modular:**  \n  Modular controllers for Docker, Nuclei, Fingerprinting, and Templates.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n    subgraph User\n        A1[API Client / UI]\n    end\n    subgraph API\n        B1[FastAPI App]\n        B2[NucleiRoutes]\n        B3[PipelineRoutes]\n    end\n    subgraph Celery\n        C1[fetch_vulnerabilities]\n        C2[process_vulnerabilities]\n        C3[generate_nuclei_template]\n        C4[store_templates]\n        C5[validate_template]\n        C6[refine_nuclei_template]\n    end\n    subgraph Services\n        D1[Ollama LLM]\n        D2[Redis]\n        D3[Docker Engine]\n        D4[Nuclei Scanner]\n    end\n\n    A1--REST--\u003eB1\n    B1--routes--\u003eB2\n    B1--routes--\u003eB3\n    B2--triggers--\u003eCelery\n    B3--triggers--\u003eCelery\n    C1--uses--\u003eD2\n    C2--uses--\u003eD1\n    C3--uses--\u003eD1\n    C4--stores--\u003eFileSystem\n    C5--runs--\u003eD4\n    C5--in--\u003eD3\n    C5--metrics--\u003eD2\n    C6--uses--\u003eD1\n    D4--runs in--\u003eD3\n```\n\n---\n\n## Pipeline Flow\n\n```mermaid\nflowchart TD\n    A[fetch_vulnerabilities] --\u003e B[process_vulnerabilities]\n    B --\u003e C[generate_nuclei_templates (group)]\n    C --\u003e D[store_templates]\n    D --\u003e E[validate_templates_callback (group)]\n    E --\u003e F[validate_template (per template)]\n    F --fail--\u003e G[refine_nuclei_template]\n    G --\u003e H[store_refined_template]\n    H --\u003e F\n    F --success--\u003e I[Done]\n```\n\n---\n\n## Setup Instructions\n\n### Prerequisites\n\n- **Python 3.8+**\n- **Docker \u0026 Docker Compose**\n- **Redis**\n- **Ollama (or compatible LLM API)**\n- *(Optional)* **Node.js \u0026 npm** (if using the UI)\n\n### Clone the Repository\n\n```sh\ngit clone \u003crepository-url\u003e\ncd nuclei-api\n```\n\n### Install Python Dependencies\n\n```sh\npip install -r requirements.txt\n```\n\n### Clone Nuclei Templates\n\n```sh\ngit clone https://github.com/projectdiscovery/nuclei-templates.git\n```\n\n### Start Redis and Ollama\n\nYou can use Docker Compose to start all services (API, Redis, Ollama, etc.):\n\n```sh\ndocker-compose up -d\n```\n\nOr start them individually as needed.\n\n### Run the API\n\n```sh\ncd app/\npython3 main.py\n```\n\nThe API will be available at `http://localhost:8080`.\n\n---\n\n## Usage Examples\n\n### 1. **Trigger the Automated Template Generation Pipeline**\n\n```sh\ncurl -X GET http://localhost:8080/nuclei/template/generate\n```\nThis will fetch new CVEs, generate templates using the LLM, store, and validate them.\n\n### 2. **Run a Scan (API)**\n\n#### Basic Scan\n\n```sh\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"target\": \"https://example.com\", \"templates\": [\"cves/\"] }' \\\n  http://localhost:8080/nuclei/scan\n```\n\n#### Custom Template Scan\n\n```sh\ncurl -X POST \\\n  -F \"target=https://example.com\" \\\n  -F \"template_file=@/path/to/custom-template.yaml\" \\\n  http://localhost:8080/nuclei/scan/custom\n```\n\n#### Fetch Scan Logs\n\n```sh\ncurl http://localhost:8080/nuclei/scan/nuclei_scan_123456/logs\n```\n\n---\n\n## API Endpoints\n\n### Health Check\n\n- **GET /**  \n  Returns `{ \"ping\": \"pong!\" }`\n\n### Run a Scan\n\n- **POST /nuclei/scan**  \n  Request:\n  ```json\n  {\n    \"target\": \"https://example.com\",\n    \"templates\": [\"cves/\"] // Optional\n  }\n  ```\n  Response:  \n  Returns scan result or task ID for async scans.\n\n### Run a Custom Scan\n\n- **POST /nuclei/scan/custom**  \n  Form Data:\n    - `target`: The target domain or IP to scan.\n    - `template_file`: Custom template YAML file (optional).\n    - `templates`: Comma-separated list of templates (optional).\n\n### Get Scan Logs\n\n- **GET /nuclei/scan/{container_id}/logs**  \n  Streams logs from the running scan container.\n\n### Upload a Custom Template\n\n- **POST /nuclei/template/upload**  \n  Upload and validate a custom Nuclei template.\n\n### Trigger Template Generation Pipeline\n\n- **GET /nuclei/template/generate**  \n  Starts the full CVE-to-template pipeline.\n\n---\n\n## Metrics \u0026 Monitoring\n\n- **Redis** is used for caching vulnerability data and tracking pipeline metrics (templates generated, validated, refinements, failures, etc.).\n- **Sentry** integration is available for error monitoring (configure via environment).\n\n---\n\n## Extending \u0026 Customizing\n\n- **Add new vulnerability sources** by editing the `fetch_vulnerabilities` task.\n- **Change LLM model or endpoint** via configuration.\n- **Integrate with your own UI** or use the provided API directly.\n\n---\n\n## Contributing\n\nContributions are welcome! Please open issues or pull requests for bug fixes, new features, or improvements.\n\n---\n\n## License\n\n[MIT](LICENSE) or as specified in the repository.\n\n---\n\n## Contact\n\nFor more details or support, please contact the development team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiladhzzzz%2Fnuclei-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiladhzzzz%2Fnuclei-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiladhzzzz%2Fnuclei-api/lists"}