# kasem545/vulnsearch architecture

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

- Interactive diagram: https://gitdiagram.com/kasem545/vulnsearch
- Repository: https://github.com/kasem545/vulnsearch

## Overview

##### Project type and purpose
- This is an open‑source, command‑line vulnerability enumeration tool written as two shell scripts (`vulnsearch.sh` and `vulnsearch‑cve.sh`).
- Purpose: Given a domain or IP, it uses DNS resolution and the Shodan API to discover running services, extract CVE identifiers via JSON parsing (`jq`), and then fetch proof‑of‑concept references for each CVE.

##### File structure
- Top level:
- LICENSE – open‑source license
- README.md – usage instructions and project description
- img/ – example screenshots of output
- vulnsearch.sh – primary script that:
a. reads domain from stdin
b. resolves DNS to IP
c. queries Shodan
d. parses JSON for ports, CPEs, CVEs
- vulnsearch‑cve.sh – secondary script that, given a CVE, pulls POC references from multiple online trackers
- No complex directories (no frontend/backend split); it’s a linear CLI pipeline.
- Configuration: requires `jq` and an environment variable (Shodan API key, implied).

##### README for additional insights
- Dependencies: `jq` (JSON parser), Shodan API
- Usage examples show data flow: domain → script → shodan/search → JSON output → CVE list → PoC URLs
- Screenshots (`img/*.png`) demonstrate two modes: all‑in‑one scan and CVE‑to‑POC lookup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment
    Env["Environment: Linux Shell, SHODAN_API_KEY, jq"]:::environment

    %% User Input and Output
    User["User (CLI)"]:::external
    STDOUT["STDOUT (Results)"]:::external

    %% External Services
    DNSService["DNS Server"]:::external
    ShodanService["Shodan API Endpoint"]:::external
    CVETrackers["CVE Reference Trackers"]:::external

    %% Local Modules
    subgraph "Shell Scripts Module" 
        ScanScript["vulnsearch.sh"]:::local
        DNSResolver["DNS Resolver (dig/host)"]:::local
        ShodanClient["Shodan API Client (curl)"]:::local
        JSONParser["JSON Parser (jq)"]:::transform
    end

    CVEScript["vulnsearch-cve.sh"]:::local

    %% Flow
    User -->|"invoke vulnsearch.sh with domain"| ScanScript
    ScanScript -->|"calls"| DNSResolver
    DNSResolver -->|"queries"| DNSService
    DNSService -->|"response: IP"| DNSResolver
    DNSResolver -->|"returns IP"| ScanScript

    ScanScript -->|"HTTPS request"| ShodanClient
    ShodanClient -->|"query"| ShodanService
    ShodanService -->|"response: JSON"| ShodanClient
    ShodanClient -->|"pipes JSON"| JSONParser
    JSONParser -->|"extract CVE list"| ScanScript

    ScanScript -->|"for each CVE"| CVEScript
    CVEScript -->|"fetch POC"| CVETrackers
    CVETrackers -->|"POC URLs"| CVEScript
    CVEScript -->|"returns POC URLs"| ScanScript

    ScanScript -->|"aggregate and print"| STDOUT
    STDOUT -->|"output to"| User

    %% Click Events
    click ScanScript "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch.sh"
    click CVEScript "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch-cve.sh"
    click DNSResolver "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch.sh"
    click ShodanClient "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch.sh"
    click JSONParser "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch.sh"
    click CVEScript "https://github.com/kasem545/vulnsearch/blob/main/vulnsearch-cve.sh"
    click CVETrackers "https://github.com/kasem545/vulnsearch/tree/main/img/"
    click README.md "https://github.com/kasem545/vulnsearch/blob/main/README.md"
    click LICENSE "https://github.com/kasem545/vulnsearch/tree/main/LICENSE"

    %% Styles
    classDef local fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef external fill:#F7D6AE,stroke:#333,stroke-width:1px
    classDef transform fill:#D3F7AE,stroke:#333,stroke-width:1px
    classDef environment fill:#E0E0E0,stroke:#333,stroke-width:1px
```
