All scanning tools and PoC execution run inside a **BlackArch Linux** Docker container — nothing is installed on the host.

---

## उपकरण

श्रेणी के अनुसार व्यवस्थित 86 उपकरण। प्रत्येक उपकरण समर्थित लक्ष्य प्रकार घोषित करता है; ऑर्केस्ट्रेटर असंगत युग्मों को स्वचालित रूप से छोड़ देता है।

### नेटवर्क और पोर्ट स्कैनिंग
| उपकरण | नोट |
|------|-------|
| `nmap` | सेवा/संस्करण पहचान के साथ पूर्ण पोर्ट स्कैन |
| `rustscan` | तेज़ पोर्ट स्कैनर, nmap को फीड करता है |
| `masscan` | उच्च गति TCP/UDP स्कैनर |
| `naabu` | सेवा पहचान के साथ पोर्ट स्कैनर |
| `netdiscover` | ARP-आधारित होस्ट खोज |

### वेब एप्लिकेशन
| उपकरण | नोट |
|------|-------|
| `nuclei` | टेम्पलेट-आधारित भेद्यता स्कैनर |
| `nikto` | वेब सर्वर गलत कॉन्फ़िगरेशन स्कैनर |
| `wapiti` | ब्लैक-बॉक्स वेब भेद्यता स्कैनर |
| `ffuf` | तेज़ वेब फ़ज़र (निर्देशिकाएँ, पैरामीटर, हेडर) |
| `feroxbuster` | पुनरावृत्ति के साथ सामग्री खोज |
| `gobuster` | URI/DNS/vhost ब्रूट-फोर्सर |
| `wfuzz` | वेब एप्लिकेशन फ़ज़र |
| `dalfox` | पैरामीटर विश्लेषण के साथ XSS स्कैनर |
| `xsstrike` | उन्नत XSS पहचान इंजन |
| `commix` | कमांड इंजेक्शन शोषक |
| `sqlmap` | स्वचालित SQL इंजेक्शन और अधिग्रहण |
| `nosqlmap` | NoSQL इंजेक्शन स्कैनर |
| `httpx` | HTTP प्रोबिंग और फ़िंगरप्रिंटिंग |
| `whatweb` | वेब प्रौद्योगिकी फ़िंगरप्रिंटर |
| `wafw00f` | WAF पहचान और फ़िंगरप्रिंटिंग |
| `wpscan` | WordPress भेद्यता स्कैनर |
| `acunetix` | वेब भेद्यता स्कैनर (API-आधारित) |
| `arachni` | वेब एप्लिकेशन सुरक्षा स्कैनर |
| `zap` | OWASP ZAP DAST स्कैनर |
| `wapiti` | ब्लैक-बॉक्स भेद्यता स्कैनर |
| `drheader` | HTTP सुरक्षा हेडर विश्लेषक |
| `humble` | HTTP हेडर सुरक्षा जाँचक |
| `hakrawler` | URL और एंडपॉइंट के लिए तेज़ वेब क्रॉलर |
| `katana` | अगली पीढ़ी का वेब क्रॉलिंग फ्रेमवर्क |
| `gau` | ज्ञात URL संग्राहक (AlienVault, WaybackMachine) |
| `jsluice` | JavaScript रहस्य और URL निकालने वाला |
| `corscanner` | CORS गलत कॉन्फ़िगरेशन स्कैनर |
| `crlfuzz` | CRLF इंजेक्शन स्कैनर |
| `smuggler` | HTTP अनुरोध तस्करी डिटेक्टर |
| `linkfinder` | JavaScript/HTML स्रोत में एंडपॉइंट खोज |
| `cariddi` | रहस्य और एंडपॉइंट पहचान के साथ वेब क्रॉलर |

### API और GraphQL
| उपकरण | नोट |
|------|-------|
| `kiterunner` | kite फ़ाइलों के साथ API रूट खोज |
| `graphql_cop` | GraphQL सुरक्षा ऑडिटर |
| `restler` | स्टेटफुल REST API फ़ज़र |
| `apifuzzer` | OpenAPI/Swagger-आधारित फ़ज़र |
| `cherrybomb` | OpenAPI स्पेक सुरक्षा लिंटर |
| `arjun` | HTTP पैरामीटर खोज |
| `paramspider` | wayback/स्रोतों से पैरामीटर खनन |

### DNS और टोही
| उपकरण | नोट |
|------|-------|
| `amass` | सबडोमेन गणना (निष्क्रिय + सक्रिय) |
| `subfinder` | तेज़ निष्क्रिय सबडोमेन गणना |
| `dnsx` | DNS रिज़ॉल्वर और प्रोब टूलकिट |
| `dnsrecon` | DNS गणना और ज़ोन ट्रांसफर |
| `fierce` | DNS टोही और होस्ट खोज |
| `theharvester` | OSINT: ईमेल, नाम, होस्ट, सबडोमेन |
| `puredns` | वाइल्डकार्ड फ़िल्टरिंग के साथ तेज़ सबडोमेन ब्रूट-फोर्सर |
| `alterx` | सबडोमेन क्रमपरिवर्तन इंजन |
| `waybackurls` | Wayback Machine से ऐतिहासिक URL संग्रह |
| `httprobe` | लाइव HTTP/HTTPS होस्ट प्रोबर |

### TLS / SSL
| उपकरण | नोट |
|------|-------|
| `testssl` | TLS कॉन्फ़िगरेशन और साइफर सूट ऑडिट |
| `sslyze` | TLS स्कैनर (साइफर सूट, Heartbleed, ROBOT) |
| `sslscan` | SSL/TLS सेवा स्कैनर |
| `tlsx` | तेज़ TLS प्रोबिंग |
| `tls_attacker` | TLS प्रोटोकॉल आक्रमण उपकरण |
| `ssh_audit` | SSH कॉन्फ़िगरेशन और एल्गोरिदम ऑडिटर |

### SMB और नेटवर्क सेवाएँ
| उपकरण | नोट |
|------|-------|
| `smbmap` | SMB शेयर गणना और अनुमतियाँ |
| `enum4linux` | SMB/NetBIOS गणना |
| `crackmapexec` | Active Directory और SMB मूल्यांकन |
| `openvas` | OpenVAS भेद्यता स्कैनर |

### SAST और कोड विश्लेषण
| उपकरण | नोट |
|------|-------|
| `bandit` | Python SAST — सामान्य सुरक्षा एंटी-पैटर्न |
| `semgrep` | सामुदायिक नियमों के साथ बहु-भाषा SAST |
| `gosec` | Go सुरक्षा जाँचक |
| `bearer` | गोपनीयता और सुरक्षा नियमों के साथ डेटा-फ्लो SAST |
| `horusec` | बहु-भाषा SAST इंजन |
| `brakeman` | Ruby on Rails SAST स्कैनर |
| `flawfinder` | सामान्य त्रुटियों के लिए C/C++ स्थैतिक विश्लेषण |
| `dependency_check` | OWASP निर्भरता भेद्यता स्कैनर |
| `pip_audit` | Python पैकेज भेद्यता जाँचक |

### सॉफ़्टवेयर संरचना विश्लेषण (SCA)
| उपकरण | नोट |
|------|-------|
| `osv-scanner` | ओपन सोर्स भेद्यता डेटाबेस स्कैनर |
| `npm-audit` | Node.js पैकेज भेद्यता ऑडिट |
| `govulncheck` | Go मॉड्यूल भेद्यता जाँचक |

### रहस्य पहचान
| उपकरण | नोट |
|------|-------|
| `gitleaks` | Git इतिहास रहस्य स्कैनर |
| `trufflehog` | गहन एंट्रॉपी-आधारित रहस्य खोजक |
| `secretfinder` | JS फ़ाइलों और एंडपॉइंट में रहस्य |
| `detect-secrets` | बेसलाइन-आधारित रहस्य स्कैनर |
| `noseyparker` | पैटर्न नियमों के साथ उच्च गति रहस्य स्कैनर |

### IaC और कॉन्फ़िगरेशन
| उपकरण | नोट |
|------|-------|
| `checkov` | Terraform/K8s/Dockerfile IaC स्कैनर |
| `tfsec` | Terraform स्थैतिक विश्लेषण |
| `terrascan` | मल्टी-क्लाउड IaC सुरक्षा स्कैनर |
| `hadolint` | Dockerfile सर्वोत्तम-अभ्यास लिंटर |

### क्लाउड इन्फ्रास्ट्रक्चर
| उपकरण | नोट |
|------|-------|
| `prowler` | AWS/GCP/Azure सुरक्षा स्थिति मूल्यांकन |
| `kube-bench` | CIS Kubernetes बेंचमार्क जाँचक |

### कंटेनर और सप्लाई चेन
| उपकरण | नोट |
|------|-------|
| `trivy` | कंटेनर इमेज + फाइलसिस्टम भेद्यता स्कैनर |
| `grype` | कंटेनर और पैकेज भेद्यता मैचर |

---

## लक्ष्य प्रकार गेटिंग

ऑर्केस्ट्रेटर प्रत्येक लक्ष्य को एक या अधिक प्रकारों में वर्गीकृत करता है और केवल उन्हीं उपकरणों को चलाता है जो उस प्रकार के लिए समर्थन घोषित करते हैं। यह शोर को समाप्त करता है, जैसे वेब URL के विरुद्ध चलने वाले SMB उपकरण।

| प्रकार | उदाहरण | मेल खाने वाले उपकरण |
|------|---------|-----------------|
| `HOST` | `example.com` | DNS, SSL, वेब, SMB उपकरण |
| `IP` | `10.0.0.1` | नेटवर्क, पोर्ट, SMB उपकरण |
| `CIDR` | `10.0.0.0/24` | नेटवर्क स्कैनर |
| `URL` | `https://app.example.com` | वेब, API, SSL उपकरण |
| `PATH` | `/src/myapp` | SAST, SCA, रहस्य, IaC उपकरण |
| `REPO` | `https://github.com/org/repo` | रहस्य, SAST, SCA उपकरण |
| `IMAGE` | `myapp:latest` | कंटेनर स्कैनर |
| `CLOUD` | `aws:profile=prod`, `arn:aws:…` | क्लाउड स्थिति उपकरण (prowler, kube-bench, terrascan) |

वर्गीकरण स्वचालित है — बस लक्ष्य स्ट्रिंग पास करें; स्कैनर प्रकार का पता लगा लेता है।

मान्यता प्राप्त क्लाउड लक्ष्य प्रारूप:
- AWS ARN: `arn:aws:iam::123456789012:root`
- नामित प्रोफ़ाइल शॉर्टहैंड: `aws:profile=production`
- GCP प्रोजेक्ट: `projects/my-project-id`
- Azure सब्सक्रिप्शन UUID: `00000000-0000-0000-0000-000000000000`

---

## स्कैन मोड

| मोड | विवरण |
|------|-------------|
| `paranoid` | अधिकतम गोपनीयता — निष्क्रिय प्रोबिंग, न्यूनतम फुटप्रिंट |
| `passive` | कोई सक्रिय आक्रमण नहीं — केवल गणना और बैनर ग्रैबिंग **(डिफ़ॉल्ट)** |
| `active` | मानक भेद्यता जाँच सक्षम |
| `aggressive` | पूर्ण स्कैन: सभी टेम्पलेट, ब्रूट-फोर्स, तेज़ टाइमिंग |

---

## प्रमाणित स्कैनिंग

क्रेडेंशियल सभी प्रासंगिक वेब उपकरणों (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx) को अग्रेषित किए जाते हैं।

### वैश्विक क्रेडेंशियल

हर लक्ष्य पर लागू, जब तक कि प्रति-लक्ष्य ओवरराइड मौजूद न हो।

**कॉन्फ़िग के माध्यम से:**```toml
[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

[scan.auth.cookies]
session = "abc123"

[scan.auth.headers]
X-API-Key = "my-api-key"

**CLI के माध्यम से** (केवल वैश्विक):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

**Resolution:** `per-target config > global config`

---

## LLM विश्लेषण

जब कोई API कुंजी मौजूद होती है, LLM परत स्वचालित रूप से सक्रिय हो जाती है। यह स्कैन परिणामों पर चार पास करता है:

| पास | नाम | यह क्या करता है |
|------|------|-------------|
| 1 | **ट्रायेज** | प्रत्येक खोज के लिए CWE, विश्वास स्तर, फ़ॉल्स-पॉज़िटिव फ़्लैग, शोषण-क्षमता सारांश निर्दिष्ट करता है, और एक PoC डिज़ाइन करता है |
| 2 | **PoC निर्माण** | स्व-निहित Python/Bash स्क्रिप्ट लिखता है जो कंटेनर में पहले से मौजूद टूल्स का उपयोग करके खोज की पुष्टि करते हैं |
| 3 | **शमन** | ठोस अल्पकालिक शमन उपाय और स्थायी सुधार उत्पन्न करता है, वैकल्पिक रूप से PoC साक्ष्य के आधार पर |
| 4 | **क्लस्टरिंग** | खोजों को मूल कारण के आधार पर समूहित करता है, साझा सुधार लिखता है, और एक कार्यकारी सारांश तैयार करता है |

### प्रोवाइडर कॉन्फ़िगरेशन

LLM क्लाइंट OpenAI-API-संगत है — यह OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter, और किसी भी अन्य संगत एंडपॉइंट के साथ काम करता है।```toml
[llm]
enabled   = "auto"          # "auto" | true | false  (auto = on when api_key present)
api_key   = ""              # or set OPENAI_API_KEY env var
base_url  = ""              # leave empty for OpenAI; set for Ollama/vLLM/etc.
model     = "gpt-4o"        # REQUIRED when LLM is active — no default

# Sampling parameters (all OpenAI-compatible)
temperature = 0.2
top_p       = 0.95
max_tokens  = 4096
# top_k and other non-standard params go in extra_body:
# [llm.extra_body]
# top_k = 40

**vLLM उदाहरण:**```toml
[llm]
base_url = "http://localhost:8000/v1"
api_key  = "token-abc123"
model    = "meta-llama/Meta-Llama-3-8B-Instruct"

**फीचर प्राथमिकता:** `tool override > category override > global`

### कस्टम प्रॉम्प्ट्स

सभी LLM प्रॉम्प्ट्स ओवरराइड करने योग्य हैं:```toml
[llm.prompts]
enrich_system    = "You are a senior penetration tester..."
mitigation_user  = "Write remediation steps for: {title}..."
# Available placeholders: {title} {severity} {description} {cwe}
#   {exploitability} {tool} {target} {cves} {raw_output}

---

## PoC निर्माण और निष्पादन

### निर्माण (हमेशा होस्ट-सुरक्षित)

LLM प्रत्येक निष्कर्ष के लिए स्व-निहित Python और/या Bash स्क्रिप्ट लिखता है। स्क्रिप्ट BlackArch इमेज में पहले से मौजूद टूल्स (`curl`, `sqlmap`, `nuclei`, `dalfox`, आदि) का उपयोग करती हैं और `<report>_assets/poc/` में लिखी जाती हैं। निर्माण कभी भी कोड निष्पादित नहीं करता — यह केवल फ़ाइलें लिखता है।```toml
[llm.poc]
languages        = ["python", "bash"]
only_severities  = ["critical", "high", "medium"]
max_pocs         = 20
allow_git_clone  = false   # permit cloning official exploit PoCs from GitHub

---

## प्लगइन सिस्टम

एक `.py` फ़ाइल डालें जो एक या अधिक `AbstractTool` उपवर्गों को परिभाषित करती है, `./plugins/` (या `~/.vuln-scanner/plugins/`) में — और वे स्टार्टअप पर स्वतः खोज ली जाती हैं — कोई कोड परिवर्तन आवश्यक नहीं है।

**खोज क्रम** (नाम टकराव पर बाद की प्रविष्टियाँ ओवरराइड करती हैं):
1. `./plugins/` (CWD के सापेक्ष)
2. `~/.vuln-scanner/plugins/`
3. `[plugins] dirs` या `--plugin-dir` के माध्यम से कॉन्फ़िगर किए गए अतिरिक्त निर्देशिकाएँ

**उदाहरण प्लगइन** (`plugins/my_scanner.py`):```python
from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, ScanStatus, TargetType
from vuln_scanner.tools.models import Finding, ScanInput, ScanResult

class MyScannerTool(AbstractTool):
    name: str = "my-scanner"
    category: str = "web"
    # Only runs against URL targets — skipped automatically for IPs, paths, etc.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["my-scanner", "--target", target, "--json"]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        ...

**CLI:**```bash
vuln-scanner --plugin-dir /opt/company-scanners --targets https://app.example.com

कॉन्फ़िग-स्तर पर कोई प्रति-लक्ष्य प्लगिन फ़िल्टर नहीं है — वह तर्क प्लगिन में ही होता है।

---

## रिपोर्ट प्रारूप

तीन प्रारूप समानांतर रूप से जनरेट होते हैं। कोई भी संयोजन चुनें:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| चरण | क्रिया |
|------|--------|
| 1 | पूर्वापेक्षाएँ जाँचता है |
| 2 | `.env` लोड करता है (यदि अनुपस्थित हो तो `.env.example` से कॉपी करता है) |
| 3 | DefectDojo स्टैक प्रारंभ करता है |
| 4 | DefectDojo API के तैयार होने की प्रतीक्षा करता है |
| 5 | व्यवस्थापक क्रेडेंशियल्स के माध्यम से API टोकन प्राप्त करता है |
| 6 | असुरक्षित लक्ष्य कंटेनर प्रारंभ करता है |
| 7 | प्रत्येक लक्ष्य के सुलभ होने की प्रतीक्षा करता है |
| 8 | स्कैनर Docker इमेज बनाता है |
| 9 | स्कैनर चलाता है, रिपोर्ट तैयार करता है, DefectDojo पर पुश करता है |
| 10 | URL और टियरडाउन निर्देशों के साथ सारांश प्रिंट करता है |

**LLM विश्लेषण के साथ:**```bash
# Copy the example env and add your key
cp .env.example .env
# Edit .env: set OPENAI_API_KEY and VS_LLM_MODEL
./poc.sh

**विघटन:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

---

## scanner.sh — Docker Wrapper

`scanner.sh` स्कैनर चलाने के लिए अनुशंसित दैनिक इंटरफ़ेस है। यह `docker compose run` को रैप करता है, ताकि आपको compose कमांड को मैन्युअल रूप से टाइप करने की आवश्यकता न पड़े — बस टारगेट और फ़्लैग सीधे पास करें।```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### यह स्वचालित रूप से क्या करता है

- `.env` लोड करता है (यदि अनुपस्थित हो तो `.env.example` से कॉपी करता है)
- यदि कोई कॉन्फ़िग मौजूद नहीं है तो `config.example.toml` → `config.toml` कॉपी करता है
- `vuln_scanner_network` Docker नेटवर्क बनाता है यदि मौजूद नहीं है
- एक कस्टम `--config` फ़ाइल को कंटेनर में `/app/config.toml` पर माउंट करता है
- जब `--build` पास किया जाता है तो इमेज को पुनर्निर्मित करता है

---

## कॉन्फ़िगरेशन

एनोटेटेड टेम्पलेट कॉपी करें:```bash
cp config.example.toml config.toml

**कॉन्फ़िग मर्ज प्राथमिकता:** `CLI > env vars > config.toml > defaults`

---

## पर्यावरणीय चर

### मुख्य

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | रिक्त स्थान से अलग की गई लक्ष्य सूची |
| `VS_MODE` | `--mode` | स्कैन मोड |
| `VS_TIMEOUT` | `--timeout` | प्रति-टूल टाइमआउट (सेकंड) |
| `VS_RATE_LIMIT` | `--rate-limit` | दर सीमा (req/s) |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | समानांतर टूल स्लॉट |
| `VS_INCLUDE_TOOLS` | `--include-tools` | नाम से टूल्स को व्हाइटलिस्ट करें |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | नाम से टूल्स को ब्लैकलिस्ट करें |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | श्रेणियों को व्हाइटलिस्ट करें |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | श्रेणियों को ब्लैकलिस्ट करें |
| `VS_OUTPUT_DIR` | `--output-dir` | रिपोर्ट आउटपुट निर्देशिका |

### रिपोर्ट

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | रिपोर्ट प्रारूप: `markdown html json` |

### LLM

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | एपीआई कुंजी (मानक पर्यावरणीय चर, फ़ॉलबैक के रूप में प्रयुक्त) |
| `OPENAI_BASE_URL` | — | बेस URL फ़ॉलबैक (गैर-OpenAI एंडपॉइंट के लिए) |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | मॉडल नाम (सक्रिय होने पर आवश्यक) |
| `VS_LLM_TEMPERATURE` | — | सैंपलिंग तापमान |
| `VS_LLM_MAX_TOKENS` | — | अधिकतम आउटपुट टोकन |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | वैश्विक सुविधा टॉगल, उदा. `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | PoC निष्पादन सक्षम करें (केवल कंटेनर) |

### प्रमाणित स्कैनिंग

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | बेयरर टोकन (`Authorization: Bearer …`) |
| `VS_AUTH_USERNAME` | `--auth-user` | HTTP बेसिक उपयोगकर्ता नाम |
| `VS_AUTH_PASSWORD` | `--auth-pass` | HTTP बेसिक पासवर्ड |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | फ़ॉर्म-आधारित लॉगिन URL |

कुकीज़ और अतिरिक्त हेडर कॉन्फ़िग फ़ाइल या `--auth-cookie` / `--auth-header` CLI फ़्लैग के माध्यम से सेट किए जाने चाहिए।

### प्लगइन्स

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | प्लगइन स्वतः-खोज सक्षम/अक्षम करें |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | अतिरिक्त प्लगइन निर्देशिकाएँ (रिक्त स्थान से अलग) |

### DefectDojo

| चर | CLI फ़्लैग | विवरण |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | DefectDojo बेस URL |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | एपीआई टोकन |
| `VS_DEFECTDOJO_PRODUCT` | — | उत्पाद नाम |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | एंगेजमेंट नाम |

---

## प्रोजेक्ट संरचना```
vuln_scanner/
├── config/
│   ├── models.py        # AppConfig, AppLLMConfig, PluginsConfig (pydantic)
│   └── loader.py        # 3-layer merge: TOML + env (VS_*) + CLI
│
├── tools/
│   ├── enums.py         # Severity, Confidence, ScanStatus, ScanMode, TargetType
│   ├── models.py        # Finding, ScanInput, ScanResult, AuthConfig (pydantic)
│   ├── target.py        # classify_target() — maps target string to TargetType set
│   ├── abstract.py      # AbstractTool ABC + subprocess execution helpers
│   ├── __init__.py      # TOOL_REGISTRY (86 tools)
│   └── <tool>.py        # One file per tool (86 total)
│
├── llm/
│   ├── models.py        # LLMConfig, LLMFeatures, PocConfig (pydantic)
│   ├── features.py      # resolve_features() — tool > category > global merge
│   ├── client.py        # LLMClient — thin openai SDK wrapper
│   ├── analyzer.py      # LLMAnalyzer — 4-pass analysis pipeline
│   └── prompts.py       # Default prompt templates (all overridable)
│
├── poc/
│   ├── models.py        # Poc, PocVerdict
│   ├── generator.py     # PocGenerator — writes scripts, never executes (host-safe)
│   └── runner.py        # PocRunner — executes scripts (VS_IN_CONTAINER guard)
│
├── reports/
│   ├── base.py          # AbstractReporter
│   ├── markdown.py      # Professional structured Markdown report
│   ├── html.py          # Self-contained HTML with light/dark theme
│   └── json_reporter.py # Full Assessment JSON dump
│
├── defectdojo/
│   └── client.py        # DefectDojoClient — push findings via REST API
│
├── plugins.py           # Plugin auto-discovery (./plugins/, ~/.vuln-scanner/plugins/)
├── model.py             # Assessment, Cluster, AssessmentStats
└── orchestrator.py      # ScanOrchestrator — type-gated, async concurrent execution

plugins/                 # Drop .py plugin files here (auto-discovered at startup)
main.py                  # Entry point
config.example.toml      # Fully documented configuration template
.env.example             # Environment variable reference
Dockerfile               # BlackArch-based image; bakes VS_IN_CONTAINER=1
docker-compose.yaml                # DefectDojo stack
docker-compose.scanner.yaml        # Scanner service
docker-compose.target.yaml        # Vulnerable test targets (Juice Shop, WebGoat)
scanner.sh                        # Convenience wrapper — runs the scanner via docker compose
poc.sh                            # End-to-end quick-start script (DefectDojo + targets + scanner)

from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, TargetType
from vuln_scanner.tools.models import Finding, ScanInput

class MyTool(AbstractTool):
    name: str = "mytool"
    category: str = "web"
    # Declare which target types this tool supports.
    # The orchestrator skips mismatched (tool, target) pairs automatically.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL, TargetType.HOST})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["mytool", "--target", target]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        findings = []
        for line in raw.splitlines():
            if "VULN" in line:
                findings.append(Finding(
                    title="Example finding",
                    severity=Severity.HIGH,
                    description=line,
                    tool=self.name,
                    target=target,
                ))
        return findings
```
2. इसे `vuln_scanner/tools/__init__.py` में पंजीकृत करें:```python
from vuln_scanner.tools.mytool import MyTool

TOOL_REGISTRY: dict[str, type[AbstractTool]] = {
    ...
    "mytool": MyTool,
}
```
3. बाइनरी को `Dockerfile` में जोड़ें:```dockerfile
RUN pacman -Sy --noconfirm mytool
```
**सुझाव:**
- stdout के बजाय किसी फ़ाइल में लिखने वाले टूल के लिए, `build_command()` में `OUTPUT_FILE_SENTINEL` का उपयोग करें और `run()` को ओवरराइड करके `self._run_with_tempfile()` को कॉल करें।
- `applicable_targets = frozenset(TargetType)` (डिफ़ॉल्ट) वाले टूल सभी टारगेट प्रकारों पर चलते हैं — इसका उपयोग केवल वास्तव में सार्वभौमिक टूलों के लिए करें।
- बाइनरी नहीं मिली → `ScanStatus.SKIPPED` (रिपोर्ट से छिपा हुआ)। टूल त्रुटि → `ScanStatus.FAILED` (परिशिष्ट A में दिखाया गया)।

---

## विकास```bash
# Install with dev dependencies
uv sync

# Run tests (host-safe only — no real tool execution)
uv run pytest tests/ -v

# Lint
uv run ruff check .
uv run ruff format .
```
**Test categories:**
- `tests/test_config.py` — कॉन्फ़िग मर्ज और सत्यापन
- `tests/test_target_typing.py` — `classify_target()` और `applies_to()`
- `tests/test_orchestrator_gating.py` — मॉक टूल्स के साथ टाइप-गेटिंग
- `tests/test_llm.py` — LLM सुविधाएँ, मॉक क्लाइंट, PoC रनर कंटेनर गार्ड
- `tests/test_reports.py` — सभी तीन रिपोर्टर (Markdown, HTML, JSON)
- `tests/test_nmap.py` — nmap आउटपुट पार्सर

**Safety rule:** होस्ट पर वास्तविक स्कैनिंग टूल कभी न चलाएँ। सभी टूल निष्पादन Docker कंटेनर के अंदर पृथक टार्गेट कंटेनरों के विरुद्ध होता है। `PocRunner` इसे लागू करता है — यह किसी भी PoC स्क्रिप्ट को निष्पादित करने से पहले `VS_IN_CONTAINER=1` की जाँच करता है, और Docker इमेज इस वेरिएबल को बेक करती है।

---

## DefectDojo एकीकरण

जब `api_key` और `product_name` कॉन्फ़िगर किए जाते हैं, तो निष्कर्ष स्वचालित रूप से पुश किए जाते हैं।

**अपनी API कुंजी प्राप्त करें:**
1. DefectDojo को http://localhost:8080 पर खोलें
2. लॉग इन करें (डिफ़ॉल्ट: `admin` / `admin`)
3. **Profile → API v2 Key** पर जाएँ

**मैन्युअल पुश:**```bash
VS_DEFECTDOJO_API_KEY=your-key \
VS_DEFECTDOJO_PRODUCT="My App" \
uv run vuln-scanner --targets 192.168.1.1
```