cve-finder-cli 1.0.0__tar.gz

cve_finder_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cve_finder_cli-1.0.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: cve-finder-cli
+Version: 1.0.0
+Summary: Fetch CVEs per application from NVD (CVE API 2.0)
+Author-email: "Dr. Fatih Tekin" <fatih.tekin.de@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/DrFatihTekin/cve_finder
+Project-URL: Repository, https://github.com/DrFatihTekin/cve_finder
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# CVE Finder
+
+Fetch CVEs per application from NVD (National Vulnerability Database) API 2.0.
+
+## Installation
+
+```bash
+pip3 install cve-finder-cli
+```
+
+Or install from source (editable):
+
+```bash
+pip install -e .
+```
+
+Or from the directory:
+```bash
+python -m pip install .
+```
+
+## Usage
+
+After installation, use the `cve-finder` command:
+
+```bash
+# Using CPE (exact match)
+cve-finder --cpe "cpe:2.3:a:gitlab:gitlab:16.7:*:*:*:*:*:*:*" --json output.json
+
+# Using keyword search
+cve-finder --app "nginx" --version "1.24.0" --csv nginx.csv
+
+# Filter by severity and date (case-insensitive)
+cve-finder --app "openssl" --severity critical --since 2024-01-01 --max 50
+
+# Multiple severities (repeat flag or comma-separated)
+cve-finder --app "jira" --severity CRITICAL --severity MEDIUM
+cve-finder --app "jira" --severity CRITICAL,MEDIUM
+
+# Print to console (no file output)
+cve-finder --app "tomcat" --version "9.0.0"
+```
+
+### Direct script usage
+
+You can also run the entry script directly:
+
+```bash
+# Best (exact): use a CPE name
+python main.py --cpe "cpe:2.3:a:nginx:nginx:1.24.0:*:*:*:*:*:*:*" --csv nginx_1.24.0.csv
+
+# Keyword search (fuzzier)
+python main.py --app "nginx" --version "1.24.0" --json out.json
+
+# Keyword search, no version
+python main.py --app "openssl" --since 2024-01-01 --max 200 --csv openssl.csv
+```
+
+## Options
+
+- `--cpe` - Exact CPE name for precise matching
+- `--app` - Application name for keyword search
+- `--version` - Optional version (with --app)
+- `--since` - Filter CVEs published since date (YYYY-MM-DD)
+- `--until` - End date for published window
+- `--severity` - Filter by severity (case-insensitive). Repeat flag or use comma-separated list (LOW, MEDIUM, HIGH, CRITICAL)
+- `--max` - Maximum CVEs to fetch (default: 1000)
+- `--page-size` - Results per page (max 200)
+- `--timeout` - HTTP timeout seconds
+- `--json` - Save results to JSON file
+- `--csv` - Save results to CSV file
+- `--format` - Output format to stdout: json or csv
+
+## API Key
+
+Set `NVD_API_KEY` environment variable to reduce rate limiting:
+```bash
+export NVD_API_KEY="your_key_here"
+```
+
+Get your API key at: https://nvd.nist.gov/developers/request-an-api-key

cve_finder_cli-1.0.0/README.md

@@ -0,0 +1,81 @@
+# CVE Finder
+
+Fetch CVEs per application from NVD (National Vulnerability Database) API 2.0.
+
+## Installation
+
+```bash
+pip3 install cve-finder-cli
+```
+
+Or install from source (editable):
+
+```bash
+pip install -e .
+```
+
+Or from the directory:
+```bash
+python -m pip install .
+```
+
+## Usage
+
+After installation, use the `cve-finder` command:
+
+```bash
+# Using CPE (exact match)
+cve-finder --cpe "cpe:2.3:a:gitlab:gitlab:16.7:*:*:*:*:*:*:*" --json output.json
+
+# Using keyword search
+cve-finder --app "nginx" --version "1.24.0" --csv nginx.csv
+
+# Filter by severity and date (case-insensitive)
+cve-finder --app "openssl" --severity critical --since 2024-01-01 --max 50
+
+# Multiple severities (repeat flag or comma-separated)
+cve-finder --app "jira" --severity CRITICAL --severity MEDIUM
+cve-finder --app "jira" --severity CRITICAL,MEDIUM
+
+# Print to console (no file output)
+cve-finder --app "tomcat" --version "9.0.0"
+```
+
+### Direct script usage
+
+You can also run the entry script directly:
+
+```bash
+# Best (exact): use a CPE name
+python main.py --cpe "cpe:2.3:a:nginx:nginx:1.24.0:*:*:*:*:*:*:*" --csv nginx_1.24.0.csv
+
+# Keyword search (fuzzier)
+python main.py --app "nginx" --version "1.24.0" --json out.json
+
+# Keyword search, no version
+python main.py --app "openssl" --since 2024-01-01 --max 200 --csv openssl.csv
+```
+
+## Options
+
+- `--cpe` - Exact CPE name for precise matching
+- `--app` - Application name for keyword search
+- `--version` - Optional version (with --app)
+- `--since` - Filter CVEs published since date (YYYY-MM-DD)
+- `--until` - End date for published window
+- `--severity` - Filter by severity (case-insensitive). Repeat flag or use comma-separated list (LOW, MEDIUM, HIGH, CRITICAL)
+- `--max` - Maximum CVEs to fetch (default: 1000)
+- `--page-size` - Results per page (max 200)
+- `--timeout` - HTTP timeout seconds
+- `--json` - Save results to JSON file
+- `--csv` - Save results to CSV file
+- `--format` - Output format to stdout: json or csv
+
+## API Key
+
+Set `NVD_API_KEY` environment variable to reduce rate limiting:
+```bash
+export NVD_API_KEY="your_key_here"
+```
+
+Get your API key at: https://nvd.nist.gov/developers/request-an-api-key

cve_finder_cli-1.0.0/cve_finder/__init__.py

@@ -0,0 +1 @@
+"""cve_finder package."""

cve_finder_cli-1.0.0/cve_finder/api.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .models import CVEItem
+from .utils import parse_cvss, pick_english_description
+
+
+NVD_ENDPOINT = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+DEFAULT_RESULTS_PER_PAGE = 200  # NVD allows up to 200 per request
+
+
+def request_page(
+    session: requests.Session,
+    params: Dict[str, Any],
+    api_key: Optional[str],
+    timeout: int,
+) -> Dict[str, Any]:
+    headers = {"User-Agent": "cve-per-app-script/1.0"}
+    if api_key:
+        headers["apiKey"] = api_key
+
+    resp = session.get(NVD_ENDPOINT, params=params, headers=headers, timeout=timeout)
+    if resp.status_code == 429:
+        # Rate-limited. Back off and retry once.
+        retry_after = resp.headers.get("Retry-After")
+        sleep_s = int(retry_after) if retry_after and retry_after.isdigit() else 6
+        time.sleep(sleep_s)
+        resp = session.get(NVD_ENDPOINT, params=params, headers=headers, timeout=timeout)
+
+    resp.raise_for_status()
+    return resp.json()
+
+
+def extract_items(nvd_json: Dict[str, Any]) -> List[CVEItem]:
+    out: List[CVEItem] = []
+    vulns = nvd_json.get("vulnerabilities") or []
+    for v in vulns:
+        c = (v.get("cve") or {})
+        cve_id = c.get("id") or ""
+        published = c.get("published")
+        last_modified = c.get("lastModified")
+        desc = pick_english_description(c.get("descriptions") or [])
+
+        metrics = c.get("metrics") or {}
+        v31, v30, v2, sev = parse_cvss(metrics)
+
+        refs = []
+        for r in (c.get("references") or []):
+            url = r.get("url")
+            if url:
+                refs.append(url)
+
+        out.append(
+            CVEItem(
+                cve_id=cve_id,
+                published=published,
+                last_modified=last_modified,
+                description=desc,
+                cvss_v31=v31,
+                cvss_v30=v30,
+                cvss_v2=v2,
+                severity=sev,
+                references=refs,
+            )
+        )
+    return out

cve_finder_cli-1.0.0/cve_finder/cli.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from typing import Any, Dict, List
+
+import requests
+
+from .api import DEFAULT_RESULTS_PER_PAGE, extract_items, request_page
+from .models import CVEItem
+from .output import format_csv, format_grouped, format_json, save_csv, save_json
+from .utils import iso_date_to_nvd_range
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Fetch CVEs per application from NVD.")
+    group = p.add_mutually_exclusive_group(required=True)
+    group.add_argument("--cpe", help="Exact CPE name, e.g. cpe:2.3:a:vendor:product:version:*:*:*:*:*:*:*")
+    group.add_argument("--app", help="Application name keyword, e.g. nginx, openssl, tomcat")
+
+    p.add_argument("--version", help="Optional version (used only with --app keyword search)")
+    p.add_argument("--since", help="Only CVEs published since date (YYYY-MM-DD or ISO8601)")
+    p.add_argument("--until", help="End date for published window (YYYY-MM-DD or ISO8601). Default: now")
+
+    p.add_argument(
+        "--severity",
+        action="append",
+        help="Filter by CVSS v3 severity. Use multiple --severity flags or a comma-separated list (e.g., CRITICAL,MEDIUM).",
+    )
+    p.add_argument("--max", type=int, default=1000, help="Maximum CVEs to fetch (default 1000)")
+    p.add_argument("--page-size", type=int, default=DEFAULT_RESULTS_PER_PAGE, help="Results per page (max 200)")
+    p.add_argument("--timeout", type=int, default=30, help="HTTP timeout seconds")
+
+    out_group = p.add_mutually_exclusive_group(required=False)
+    out_group.add_argument("--json", dest="json_out", help="Write results to JSON file")
+    out_group.add_argument("--csv", dest="csv_out", help="Write results to CSV file")
+
+    p.add_argument("--format", choices=["json", "csv"], help="Output format to stdout (instead of grouped display)")
+    return p
+
+
+def build_params(args: argparse.Namespace) -> Dict[str, Any]:
+    params: Dict[str, Any] = {
+        "startIndex": 0,
+        "resultsPerPage": args.page_size,
+    }
+
+    # Filter by application
+    if args.cpe:
+        params["cpeName"] = args.cpe
+    else:
+        # keywordSearch is broad; include version as additional keyword if provided
+        keyword = args.app.strip()
+        if args.version:
+            keyword = f"{keyword} {args.version.strip()}"
+        params["keywordSearch"] = keyword
+
+    # Optional time window
+    if args.since:
+        start, end = iso_date_to_nvd_range(args.since, args.until)
+        # Use "pubStartDate/pubEndDate" so you're filtering by published dates
+        params["pubStartDate"] = start
+        params["pubEndDate"] = end
+
+    # Optional severity filtering (NVD supports single cvssV3Severity)
+    severities = normalize_severities(args.severity)
+    if len(severities) == 1:
+        params["cvssV3Severity"] = severities[0]
+
+    return params
+
+
+def fetch_cves(args: argparse.Namespace) -> List[CVEItem]:
+    if args.page_size > 200 or args.page_size < 1:
+        raise ValueError("--page-size must be between 1 and 200 for NVD.")
+
+    api_key = os.getenv("NVD_API_KEY")  # optional but recommended
+    params = build_params(args)
+
+    items: List[CVEItem] = []
+    session = requests.Session()
+
+    fetched = 0
+    total_results = None
+
+    while True:
+        page = request_page(session, params, api_key, args.timeout)
+        if total_results is None:
+            total_results = page.get("totalResults", 0)
+
+        page_items = extract_items(page)
+        items.extend(page_items)
+        fetched += len(page_items)
+
+        # Stop conditions
+        if fetched >= args.max:
+            items = items[: args.max]
+            break
+
+        start_index = params["startIndex"]
+        results_per_page = params["resultsPerPage"]
+
+        # If no more results
+        if len(page_items) == 0:
+            break
+
+        # Next page
+        next_index = start_index + results_per_page
+        if total_results is not None and next_index >= total_results:
+            break
+
+        params["startIndex"] = next_index
+
+        # Gentle pacing if no API key (avoid 429)
+        if not api_key:
+            time.sleep(0.8)
+
+    # Local severity filter in case API doesn't enforce it reliably
+    severities = normalize_severities(args.severity)
+    if severities:
+        items = [it for it in items if (it.severity or "").upper() in severities]
+
+    # Sort by published date desc (if available)
+    items.sort(key=lambda it: it.published or "", reverse=True)
+    return items
+
+
+def normalize_severities(raw: List[str] | None) -> List[str]:
+    if not raw:
+        return []
+    allowed = {"LOW", "MEDIUM", "HIGH", "CRITICAL"}
+    values = []
+    for entry in raw:
+        parts = [p.strip().upper() for p in entry.split(",") if p.strip()]
+        values.extend(parts)
+    invalid = [v for v in values if v not in allowed]
+    if invalid:
+        raise ValueError(f"Invalid severity value(s): {', '.join(invalid)}")
+    # Preserve order and uniqueness
+    seen = set()
+    result = []
+    for v in values:
+        if v not in seen:
+            seen.add(v)
+            result.append(v)
+    return result
+
+
+def output_results(items: List[CVEItem], args: argparse.Namespace) -> int:
+    if args.json_out:
+        save_json(items, args.json_out)
+        print(f"Wrote {len(items)} CVEs to JSON: {args.json_out}")
+    elif args.csv_out:
+        save_csv(items, args.csv_out)
+        print(f"Wrote {len(items)} CVEs to CSV: {args.csv_out}")
+    elif args.format == "json":
+        print(format_json(items))
+    elif args.format == "csv":
+        print(format_csv(items))
+    else:
+        print(format_grouped(items))
+
+    return 0
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        items = fetch_cves(args)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 2
+
+    return output_results(items, args)

cve_finder_cli-1.0.0/cve_finder/models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class CVEItem:
+    cve_id: str
+    published: Optional[str]
+    last_modified: Optional[str]
+    description: str
+    cvss_v31: Optional[float]
+    cvss_v30: Optional[float]
+    cvss_v2: Optional[float]
+    severity: Optional[str]
+    references: List[str]

cve_finder_cli-1.0.0/cve_finder/output.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import csv
+import json
+from typing import List
+
+from .models import CVEItem
+
+
+def save_json(items: List[CVEItem], path: str) -> None:
+    data = [item.__dict__ for item in items]
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def save_csv(items: List[CVEItem], path: str) -> None:
+    fieldnames = [
+        "cve_id",
+        "published",
+        "last_modified",
+        "severity",
+        "cvss_v31",
+        "cvss_v30",
+        "cvss_v2",
+        "description",
+        "references",
+    ]
+    with open(path, "w", encoding="utf-8", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=fieldnames)
+        w.writeheader()
+        for item in items:
+            row = item.__dict__.copy()
+            row["references"] = " | ".join(item.references)
+            w.writerow(row)
+
+
+def format_json(items: List[CVEItem]) -> str:
+    data = [item.__dict__ for item in items]
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def format_csv(items: List[CVEItem]) -> str:
+    import io
+
+    fieldnames = [
+        "cve_id",
+        "published",
+        "last_modified",
+        "severity",
+        "cvss_v31",
+        "cvss_v30",
+        "cvss_v2",
+        "description",
+        "references",
+    ]
+    output = io.StringIO()
+    w = csv.DictWriter(output, fieldnames=fieldnames)
+    w.writeheader()
+    for item in items:
+        row = item.__dict__.copy()
+        row["references"] = " | ".join(item.references)
+        w.writerow(row)
+    return output.getvalue()
+
+
+def format_grouped(items: List[CVEItem]) -> str:
+    from collections import defaultdict
+
+    by_severity = defaultdict(list)
+    for it in items:
+        sev = it.severity or "UNKNOWN"
+        by_severity[sev].append(it)
+
+    # Print grouped by severity (CRITICAL -> HIGH -> MEDIUM -> LOW -> UNKNOWN)
+    severity_order = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"]
+    lines = []
+    total_printed = 0
+    header = "CVE_ID | PUBLISHED | SCORE | DESCRIPTION"
+    for sev in severity_order:
+        if sev not in by_severity:
+            continue
+        cves = by_severity[sev]
+        lines.append(f"\n{'='*80}")
+        lines.append(f"{sev} ({len(cves)} CVEs)")
+        lines.append(f"{'='*80}")
+        lines.append(header)
+        for it in cves[:50]:  # Limit per severity group
+            score = it.cvss_v31 or it.cvss_v30 or it.cvss_v2
+            lines.append(f"{it.cve_id} | {it.published} | {score} | {it.description[:100]}")
+            total_printed += 1
+        if len(cves) > 50:
+            lines.append(f"... ({len(cves) - 50} more {sev} CVEs)")
+
+    lines.append(f"\nTotal CVEs fetched: {len(items)}")
+    return "\n".join(lines)

cve_finder_cli-1.0.0/cve_finder/utils.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def iso_date_to_nvd_range(since: str, until: Optional[str]) -> Tuple[str, str]:
+    """
+    Convert YYYY-MM-DD (or full ISO) into NVD required ISO-8601 with timezone.
+    NVD expects e.g. 2024-01-01T00:00:00.000Z
+    """
+
+    def parse_date(d: str) -> datetime:
+        # Accept YYYY-MM-DD or full ISO
+        try:
+            if len(d) == 10:
+                return datetime.strptime(d, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+            # try full ISO
+            dt = datetime.fromisoformat(d.replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt.astimezone(timezone.utc)
+        except Exception as e:
+            raise ValueError(f"Invalid date format '{d}'. Use YYYY-MM-DD or ISO8601.") from e
+
+    start_dt = parse_date(since)
+    end_dt = parse_date(until) if until else datetime.now(timezone.utc)
+
+    # NVD wants milliseconds and Z
+    def fmt(dt: datetime) -> str:
+        return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+    return fmt(start_dt), fmt(end_dt)
+
+
+def pick_english_description(descriptions: List[Dict[str, Any]]) -> str:
+    for d in descriptions or []:
+        if d.get("lang") == "en" and d.get("value"):
+            return d["value"]
+    # fallback: first description if exists
+    if descriptions and descriptions[0].get("value"):
+        return descriptions[0]["value"]
+    return ""
+
+
+def parse_cvss(metrics: Dict[str, Any]) -> Tuple[Optional[float], Optional[float], Optional[float], Optional[str]]:
+    """
+    Extract best available CVSS score and severity from NVD metrics.
+    """
+    v31 = v30 = v2 = None
+    sev = None
+
+    # CVSS v3.1
+    m31 = metrics.get("cvssMetricV31") or []
+    if m31:
+        data = (m31[0].get("cvssData") or {})
+        v31 = data.get("baseScore")
+        sev = data.get("baseSeverity") or sev
+
+    # CVSS v3.0
+    m30 = metrics.get("cvssMetricV30") or []
+    if m30:
+        data = (m30[0].get("cvssData") or {})
+        v30 = data.get("baseScore")
+        sev = data.get("baseSeverity") or sev
+
+    # CVSS v2
+    m2 = metrics.get("cvssMetricV2") or []
+    if m2:
+        data = (m2[0].get("cvssData") or {})
+        v2 = data.get("baseScore")
+        # v2 severity sometimes under "baseSeverity" elsewhere; keep sev if already set
+        sev = sev or m2[0].get("baseSeverity")
+
+    return v31, v30, v2, sev