vulnpilot 0.1.0__py3-none-any.whl

vulnpilot/__init__.py

@@ -0,0 +1,3 @@
+# VulnPilot by PatchVex
+# Mission: Help security teams turn vulnerability scan data into prioritized action.
+__version__ = "0.1.0"

vulnpilot/cli.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+VulnPilot CLI by PatchVex
+Usage:
+    vulnpilot analyze scan.csv
+    vulnpilot analyze scan.csv --all
+    vulnpilot update-feeds
+    vulnpilot --version
+"""
+from __future__ import annotations
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from vulnpilot import __version__
+from vulnpilot.parser import parse_nessus_csv
+from vulnpilot.enrich import enrich, update_feeds
+from vulnpilot.scoring import score_all
+from vulnpilot.reports import render_summary, render_findings, render_top_hosts, render_free_tier_gate
+
+FREE_TIER_LIMIT = 20
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    try:
+        findings = parse_nessus_csv(Path(args.csv))
+    except FileNotFoundError as e:
+        print(f"\n  ERROR: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"\n  ERROR: {e}", file=sys.stderr)
+        return 1
+
+    if not findings:
+        print("\n  No actionable findings in this CSV.")
+        return 0
+
+    enrich(findings,
+           kev_path=Path(args.kev) if args.kev else None,
+           epss_path=Path(args.epss) if args.epss else None)
+
+    scored = score_all(findings)
+    use_colour = sys.stdout.isatty() and not args.no_colour
+    is_paid = args.all or bool(args.license)
+    limit = len(scored) if is_paid else FREE_TIER_LIMIT
+
+    print(render_summary(scored, use_colour=use_colour))
+    print(render_findings(scored, limit=limit, use_colour=use_colour))
+    print(render_top_hosts(scored, top_n=args.top_hosts, use_colour=use_colour))
+
+    if not is_paid and len(scored) > FREE_TIER_LIMIT:
+        print(render_free_tier_gate(len(scored), FREE_TIER_LIMIT, use_colour=use_colour))
+
+    return 0
+
+
+def cmd_update_feeds(args: argparse.Namespace) -> int:
+    try:
+        update_feeds(cache_dir=Path(args.cache) if args.cache else None)
+    except Exception as e:
+        print(f"\n  ERROR: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vulnpilot",
+        description="VulnPilot by PatchVex — Turn vulnerability scan data into prioritized action.",
+    )
+    parser.add_argument("--version", action="version", version=f"VulnPilot {__version__}")
+    parser.add_argument("--no-colour", "--no-color", action="store_true", dest="no_colour")
+
+    sub = parser.add_subparsers(dest="command")
+
+    analyze = sub.add_parser("analyze", help="Analyze a Nessus CSV export")
+    analyze.add_argument("csv", help="Path to Nessus CSV file")
+    analyze.add_argument("--kev", help="Path to local KEV JSON")
+    analyze.add_argument("--epss", help="Path to local EPSS CSV")
+    analyze.add_argument("--top-hosts", type=int, default=10, metavar="N")
+    analyze.add_argument("--all", action="store_true", help="Show all findings [Pro]")
+    analyze.add_argument("--license", metavar="KEY", help="License key [Pro]")
+
+    feeds = sub.add_parser("update-feeds", help="Download latest KEV and EPSS feeds")
+    feeds.add_argument("--cache", help="Cache directory")
+
+    return parser
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+    parser = build_parser()
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+    if args.command == "analyze":
+        sys.exit(cmd_analyze(args))
+    elif args.command == "update-feeds":
+        sys.exit(cmd_update_feeds(args))
+
+
+if __name__ == "__main__":
+    main()

vulnpilot/enrich/__init__.py

@@ -0,0 +1,3 @@
+from .enricher import enrich
+from .feeds import load_kev, load_epss, update_feeds
+__all__ = ["enrich", "load_kev", "load_epss", "update_feeds"]

vulnpilot/enrich/enricher.py

@@ -0,0 +1,33 @@
+"""
+vulnpilot/enrich/enricher.py
+Applies KEV and EPSS data to parsed findings.
+"""
+from __future__ import annotations
+import logging
+from pathlib import Path
+from typing import List, Optional
+from vulnpilot.parser.nessus import Finding
+from .feeds import load_kev, load_epss
+
+logger = logging.getLogger(__name__)
+
+
+def enrich(findings: List[Finding], kev_path: Optional[Path] = None, epss_path: Optional[Path] = None) -> List[Finding]:
+    kev_set = load_kev(kev_path)
+    epss_map = load_epss(epss_path)
+    kev_hits = epss_hits = 0
+
+    for f in findings:
+        for cve in f.cve_list:
+            if cve in kev_set:
+                f.kev_match = True
+                kev_hits += 1
+            if cve in epss_map:
+                score, percentile = epss_map[cve]
+                if f.epss_score is None or score > f.epss_score:
+                    f.epss_score = score
+                    f.epss_percentile = percentile
+                    epss_hits += 1
+
+    logger.info("Enrichment: %d KEV matches, %d EPSS scores", kev_hits, epss_hits)
+    return findings

vulnpilot/enrich/feeds.py

@@ -0,0 +1,72 @@
+"""
+vulnpilot/enrich/feeds.py
+Loads CISA KEV and FIRST EPSS data from local cache.
+Customer vulnerability data never leaves their machine.
+"""
+from __future__ import annotations
+import csv
+import gzip
+import json
+import logging
+import urllib.request
+from pathlib import Path
+from typing import Dict, Optional, Set, Tuple
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CACHE = Path.home() / ".vulnpilot" / "feeds"
+KEV_URL  = "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json"
+EPSS_URL = "https://epss.cyentia.com/epss_scores-current.csv.gz"
+
+
+def load_kev(kev_path: Optional[Path] = None) -> Set[str]:
+    path = kev_path or DEFAULT_CACHE / "known_exploited_vulnerabilities.json"
+    if not path.exists():
+        logger.warning("KEV file not found at %s — run 'vulnpilot update-feeds' first.", path)
+        return set()
+    with open(path, encoding="utf-8") as fh:
+        data = json.load(fh)
+    cve_set = {v["cveID"].upper() for v in data.get("vulnerabilities", [])}
+    logger.info("Loaded %d KEV entries", len(cve_set))
+    return cve_set
+
+
+def load_epss(epss_path: Optional[Path] = None) -> Dict[str, Tuple[float, float]]:
+    path = epss_path or DEFAULT_CACHE / "epss_scores-current.csv.gz"
+    if not path.exists():
+        uncompressed = path.with_suffix("")
+        if uncompressed.exists():
+            path = uncompressed
+        else:
+            logger.warning("EPSS file not found at %s — run 'vulnpilot update-feeds' first.", path)
+            return {}
+
+    epss: Dict[str, Tuple[float, float]] = {}
+    opener = gzip.open if path.suffix == ".gz" else open
+
+    with opener(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            if line.startswith("#"):
+                continue
+            break
+        reader = csv.DictReader(fh, fieldnames=["cve", "epss", "percentile"])
+        next(reader, None)
+        for row in reader:
+            cve = row["cve"].strip().upper()
+            try:
+                epss[cve] = (float(row["epss"].strip()), float(row["percentile"].strip()))
+            except (ValueError, KeyError):
+                continue
+
+    logger.info("Loaded %d EPSS scores", len(epss))
+    return epss
+
+
+def update_feeds(cache_dir: Optional[Path] = None) -> None:
+    cache = cache_dir or DEFAULT_CACHE
+    cache.mkdir(parents=True, exist_ok=True)
+    print("Downloading CISA KEV feed...")
+    urllib.request.urlretrieve(KEV_URL, cache / "known_exploited_vulnerabilities.json")
+    print("Downloading FIRST EPSS feed...")
+    urllib.request.urlretrieve(EPSS_URL, cache / "epss_scores-current.csv.gz")
+    print("Feeds updated successfully.")

vulnpilot/parser/__init__.py

@@ -0,0 +1,2 @@
+from .nessus import parse_nessus_csv, Finding
+__all__ = ["parse_nessus_csv", "Finding"]

vulnpilot/parser/nessus.py

@@ -0,0 +1,139 @@
+"""
+vulnpilot/parser/nessus.py
+Parses Nessus CSV exports into normalized Finding objects.
+"""
+from __future__ import annotations
+import csv
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+NESSUS_COLUMNS = {
+    "plugin id":             "plugin_id",
+    "cve":                   "cve",
+    "cvss v3.0 base score":  "cvss_v3",
+    "cvss v2.0 base score":  "cvss_v2",
+    "risk":                  "risk",
+    "host":                  "host",
+    "protocol":              "protocol",
+    "port":                  "port",
+    "name":                  "name",
+    "synopsis":              "synopsis",
+    "description":           "description",
+    "solution":              "solution",
+    "see also":              "references",
+    "plugin output":         "plugin_output",
+}
+
+RISK_ORDER = {"critical": 4, "high": 3, "medium": 2, "low": 1, "none": 0, "": 0}
+
+
+@dataclass
+class Finding:
+    plugin_id: str
+    cve: str
+    cvss_v3: Optional[float]
+    cvss_v2: Optional[float]
+    risk: str
+    host: str
+    port: str
+    protocol: str
+    name: str
+    synopsis: str
+    description: str
+    solution: str
+    references: str
+    plugin_output: str
+    epss_score: Optional[float] = None
+    epss_percentile: Optional[float] = None
+    kev_match: bool = False
+    priority_score: Optional[float] = None
+    priority_label: Optional[str] = None
+
+    @property
+    def cve_list(self) -> List[str]:
+        if not self.cve:
+            return []
+        return [c.strip().upper() for c in self.cve.split(",") if c.strip().startswith("CVE-")]
+
+    @property
+    def cvss(self) -> float:
+        return self.cvss_v3 or self.cvss_v2 or 0.0
+
+    @property
+    def risk_value(self) -> int:
+        return RISK_ORDER.get(self.risk.lower(), 0)
+
+
+def _safe_float(value: str) -> Optional[float]:
+    try:
+        return float(value.strip()) if value.strip() else None
+    except ValueError:
+        return None
+
+
+def parse_nessus_csv(path: Path) -> List[Finding]:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"CSV not found: {path}")
+
+    with open(path, newline="", encoding="utf-8-sig") as fh:
+        raw = fh.read()
+
+    lines = raw.splitlines()
+    header_idx = None
+    for i, line in enumerate(lines):
+        lower = line.lower()
+        if "plugin id" in lower and "risk" in lower and "host" in lower:
+            header_idx = i
+            break
+
+    if header_idx is None:
+        raise ValueError(
+            "This does not look like a Nessus CSV export. "
+            "Expected columns: Plugin ID, Risk, Host, CVE."
+        )
+
+    body = "\n".join(lines[header_idx:])
+    reader = csv.DictReader(body.splitlines())
+
+    col_map = {}
+    for raw_col in (reader.fieldnames or []):
+        normalized = NESSUS_COLUMNS.get(raw_col.strip().lower())
+        if normalized:
+            col_map[raw_col] = normalized
+
+    findings: List[Finding] = []
+    skipped = 0
+
+    for row in reader:
+        mapped = {v: row.get(k, "").strip() for k, v in col_map.items()}
+        if mapped.get("risk", "").lower() in ("none", ""):
+            skipped += 1
+            continue
+        host = mapped.get("host", "")
+        if not host:
+            skipped += 1
+            continue
+        findings.append(Finding(
+            plugin_id=mapped.get("plugin_id", ""),
+            cve=mapped.get("cve", ""),
+            cvss_v3=_safe_float(mapped.get("cvss_v3", "")),
+            cvss_v2=_safe_float(mapped.get("cvss_v2", "")),
+            risk=mapped.get("risk", ""),
+            host=host,
+            port=mapped.get("port", ""),
+            protocol=mapped.get("protocol", ""),
+            name=mapped.get("name", ""),
+            synopsis=mapped.get("synopsis", ""),
+            description=mapped.get("description", ""),
+            solution=mapped.get("solution", ""),
+            references=mapped.get("references", ""),
+            plugin_output=mapped.get("plugin_output", ""),
+        ))
+
+    logger.info("Parsed %d findings (%d informational skipped)", len(findings), skipped)
+    return findings

vulnpilot/reports/__init__.py

@@ -0,0 +1,2 @@
+from .terminal import render_summary, render_findings, render_top_hosts, render_free_tier_gate
+__all__ = ["render_summary", "render_findings", "render_top_hosts", "render_free_tier_gate"]

vulnpilot/reports/terminal.py

@@ -0,0 +1,88 @@
+"""
+vulnpilot/reports/terminal.py
+Renders prioritized findings to terminal output.
+"""
+from __future__ import annotations
+from collections import Counter, defaultdict
+from typing import List
+from vulnpilot.parser.nessus import Finding
+
+RESET="\033[0m";BOLD="\033[1m";RED="\033[91m";ORANGE="\033[33m"
+YELLOW="\033[93m";CYAN="\033[96m";GREY="\033[90m";WHITE="\033[97m"
+
+def _c(text, colour, use_colour):
+    return f"{colour}{text}{RESET}" if use_colour else text
+
+def _label_colour(label, use_colour):
+    colours = {"CRITICAL NOW": RED, "HIGH": ORANGE, "MEDIUM": YELLOW, "LOW": CYAN}
+    return _c(label, colours.get(label, WHITE), use_colour)
+
+def render_summary(findings: List[Finding], use_colour: bool = True) -> str:
+    total = len(findings)
+    risk_counts = Counter(f.risk.upper() for f in findings)
+    kev_count = sum(1 for f in findings if f.kev_match)
+    high_epss = sum(1 for f in findings if (f.epss_score or 0) >= 0.9)
+    unique_hosts = len({f.host for f in findings})
+    lines = [
+        "", _c("━"*60, BOLD, use_colour),
+        _c("  VulnPilot by PatchVex — Vulnerability Prioritization", BOLD, use_colour),
+        _c("━"*60, BOLD, use_colour), "",
+        f"  Total findings        : {_c(str(total), BOLD, use_colour)}",
+        f"  Unique hosts          : {unique_hosts}", "",
+        f"  {_c('Critical', RED, use_colour)}              : {risk_counts.get('CRITICAL', 0)}",
+        f"  {_c('High', ORANGE, use_colour)}                 : {risk_counts.get('HIGH', 0)}",
+        f"  {_c('Medium', YELLOW, use_colour)}               : {risk_counts.get('MEDIUM', 0)}",
+        f"  {_c('Low', CYAN, use_colour)}                  : {risk_counts.get('LOW', 0)}", "",
+        f"  {_c('KEV matches', RED, use_colour)} (exploited now) : {_c(str(kev_count), BOLD, use_colour)}",
+        f"  {_c('EPSS >= 90%', ORANGE, use_colour)} (high risk)    : {high_epss}",
+        "", _c("━"*60, BOLD, use_colour),
+    ]
+    return "\n".join(lines)
+
+def render_findings(findings: List[Finding], limit: int = 20, use_colour: bool = True) -> str:
+    shown = findings[:limit]
+    lines = ["", _c(f"  TOP {limit} PRIORITIZED FINDINGS", BOLD, use_colour),
+             _c("  (KEV + EPSS + CVSS composite score)", GREY, use_colour), ""]
+    header = f"  {'#':<5}{'Score':<7}{'Priority':<14}{'Host':<22}{'CVE':<20}{'Finding':<36}"
+    lines.append(_c(header, BOLD, use_colour))
+    lines.append(_c("  " + "─"*100, GREY, use_colour))
+    for i, f in enumerate(shown, start=1):
+        cve_display = f.cve_list[0] if f.cve_list else "N/A"
+        name_display = f.name[:34] + ".." if len(f.name) > 36 else f.name
+        host_display = f.host[:20] + ".." if len(f.host) > 22 else f.host
+        kev_flag = _c(" ★KEV", RED, use_colour) if f.kev_match else ""
+        row = (f"  {i:<5}{f.priority_score:<7.1f}"
+               f"{(f.priority_label or ''):<14}{host_display:<22}"
+               f"{cve_display:<20}{name_display}{kev_flag}")
+        lines.append(row)
+    lines += ["", _c("  ★ KEV = CISA Known Exploited — patch these first, no debate.", RED, use_colour), ""]
+    return "\n".join(lines)
+
+def render_top_hosts(findings: List[Finding], top_n: int = 10, use_colour: bool = True) -> str:
+    host_scores: dict = defaultdict(float)
+    host_kev: dict = defaultdict(int)
+    host_critical: dict = defaultdict(int)
+    for f in findings:
+        host_scores[f.host] += f.priority_score or 0
+        if f.kev_match: host_kev[f.host] += 1
+        if f.risk.lower() == "critical": host_critical[f.host] += 1
+    ranked = sorted(host_scores.items(), key=lambda x: x[1], reverse=True)[:top_n]
+    lines = ["", _c(f"  TOP {top_n} HOSTS BY AGGREGATE RISK", BOLD, use_colour), ""]
+    for i, (host, score) in enumerate(ranked, start=1):
+        kev_tag = _c(f" [{host_kev[host]} KEV]", RED, use_colour) if host_kev[host] else ""
+        crit_tag = f" [{host_critical[host]} critical]" if host_critical[host] else ""
+        lines.append(f"  {i:>2}. {host:<32} score={score:.1f}{kev_tag}{crit_tag}")
+    lines.append("")
+    return "\n".join(lines)
+
+def render_free_tier_gate(total: int, shown: int, use_colour: bool = True) -> str:
+    lines = [
+        "", _c("─"*60, GREY, use_colour),
+        _c(f"  FREE TIER: showing top {shown} of {total} findings", YELLOW, use_colour),
+        _c(f"  {total - shown} findings hidden.", YELLOW, use_colour), "",
+        "  Upgrade to VulnPilot Professional to unlock all findings,",
+        "  PDF reports, Jira integration, and scheduled scans.", "",
+        _c("  https://patchvex.com/pricing", CYAN, use_colour),
+        _c("─"*60, GREY, use_colour), "",
+    ]
+    return "\n".join(lines)

vulnpilot/scoring/__init__.py

@@ -0,0 +1,2 @@
+from .engine import score_all, score_finding, ScoringConfig, DEFAULT_CONFIG
+__all__ = ["score_all", "score_finding", "ScoringConfig", "DEFAULT_CONFIG"]

vulnpilot/scoring/engine.py

@@ -0,0 +1,60 @@
+"""
+vulnpilot/scoring/engine.py
+Composite risk scoring engine.
+Score = KEV(40) + EPSS(35) + CVSS(15) + Severity(10)
+KEV hard floor: any KEV finding scores at least 75.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass
+from typing import List
+from vulnpilot.parser.nessus import Finding
+
+logger = logging.getLogger(__name__)
+
+SEVERITY_SCORE = {"critical": 1.0, "high": 0.75, "medium": 0.4, "low": 0.1, "none": 0.0, "": 0.0}
+
+
+@dataclass
+class ScoringConfig:
+    kev_weight: float = 40.0
+    epss_weight: float = 35.0
+    cvss_weight: float = 15.0
+    severity_weight: float = 10.0
+
+
+DEFAULT_CONFIG = ScoringConfig()
+
+
+def _normalize_cvss(cvss: float) -> float:
+    return min(max(cvss, 0.0), 10.0) / 10.0
+
+
+def score_finding(finding: Finding, config: ScoringConfig = DEFAULT_CONFIG) -> float:
+    raw = (
+        (config.kev_weight if finding.kev_match else 0.0) +
+        config.epss_weight * (finding.epss_score or 0.0) +
+        config.cvss_weight * _normalize_cvss(finding.cvss) +
+        config.severity_weight * SEVERITY_SCORE.get(finding.risk.lower(), 0.0)
+    )
+    if finding.kev_match:
+        raw = max(raw, 75.0)
+    return min(round(raw, 2), 100.0)
+
+
+def _priority_label(score: float, kev: bool) -> str:
+    if kev or score >= 75:
+        return "CRITICAL NOW"
+    if score >= 50:
+        return "HIGH"
+    if score >= 25:
+        return "MEDIUM"
+    return "LOW"
+
+
+def score_all(findings: List[Finding], config: ScoringConfig = DEFAULT_CONFIG, limit: int = 0) -> List[Finding]:
+    for f in findings:
+        f.priority_score = score_finding(f, config)
+        f.priority_label = _priority_label(f.priority_score, f.kev_match)
+    findings.sort(key=lambda f: f.priority_score, reverse=True)
+    return findings[:limit] if limit > 0 else findings

vulnpilot-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PatchVex
+
+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.

vulnpilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.1
+Name: vulnpilot
+Version: 0.1.0
+Summary: Turn vulnerability scan data into prioritized action. Runs locally. Your data never leaves your machine.
+Project-URL: Homepage, https://patchvex.com
+Project-URL: Repository, https://github.com/PatchVex/vulnpilot
+Project-URL: Bug Tracker, https://github.com/PatchVex/vulnpilot/issues
+Keywords: security,vulnerability,nessus,cve,kev,epss,devsecops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# VulnPilot
+
+**Prioritize vulnerabilities using real-world exploit intelligence — not just severity scores.**
+
+Runs locally. Your data never leaves your machine.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![Status: Developer Preview](https://img.shields.io/badge/status-developer%20preview-orange.svg)]()
+[![Version: 0.1.0](https://img.shields.io/badge/version-0.1.0-blue.svg)]()
+
+---
+
+## Quick Start
+
+```bash
+pip install vulnpilot
+vulnpilot update-feeds
+vulnpilot analyze scan.csv
+```
+
+VulnPilot downloads the latest public threat intelligence, analyzes your Nessus scan locally, and shows what should be remediated first. No API keys required.
+
+---
+
+## Features
+
+- Local-first vulnerability prioritization — scan data never leaves your machine
+- CISA KEV enrichment — flags findings confirmed exploited in the wild
+- FIRST EPSS enrichment — exploitation probability scoring
+- Composite risk scoring — KEV + EPSS + CVSS combined
+- Top vulnerable hosts ranked by aggregate risk
+- Zero cloud upload, zero telemetry, zero account required
+- GitHub Actions daily feed automation
+- Open source Community Edition — MIT licensed
+
+---
+
+## The problem
+
+Security teams often spend hours manually triaging scan results. Your Nessus export contains thousands of findings. CVSS says hundreds are Critical. The real question — which ones are actively being exploited right now?
+
+VulnPilot automates this process in seconds on typical scan files.
+
+---
+
+## Why VulnPilot?
+
+| Instead of | VulnPilot |
+|---|---|
+| Sorting by CVSS score alone | Uses KEV + EPSS + CVSS composite scoring |
+| Manual triage taking hours | Automated prioritization in seconds |
+| Uploading scans to cloud services | Local-first — data never leaves your machine |
+| Enterprise-only platforms | Developer Preview — free and open source |
+
+---
+
+## Why local-first?
+
+Many organizations prohibit uploading vulnerability scan data to third-party cloud services. VulnPilot performs all analysis locally on your machine.
+
+No customer vulnerability data is transmitted outside your environment.
+
+---
+
+## Architecture
+
+```
+          Public Threat Intelligence
+      +-------------------------------+
+      |  CISA KEV      FIRST EPSS     |
+      +---------------+---------------+
+                      |
+              vulnpilot update-feeds
+                      |
+          ~/.vulnpilot/feeds/ (local cache)
+                      |
+              vulnpilot analyze
+                      |
+      Nessus CSV (Local Machine Only)
+                      |
+         Composite Risk Engine
+                      |
+         Prioritized Findings
+```
+
+Only public threat intelligence feeds are downloaded. No API keys required. Your scan data never leaves your machine.
+
+---
+
+## Install
+
+```bash
+pip install vulnpilot
+```
+
+Tested on Python 3.10, 3.11, and 3.12.
+
+---
+
+## Usage
+
+```bash
+# Download latest KEV and EPSS feeds
+vulnpilot update-feeds
+
+# Analyze a Nessus CSV export
+vulnpilot analyze scan.csv
+
+# Show top N hosts by aggregate risk
+vulnpilot analyze scan.csv --top-hosts 5
+
+# Use local feed files
+vulnpilot analyze scan.csv --kev ./kev.json --epss ./epss.csv.gz
+
+# Disable colour output (for CI pipelines)
+vulnpilot analyze scan.csv --no-colour
+```
+
+---
+
+## Example output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  VulnPilot by PatchVex — Vulnerability Prioritization
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Total findings        : 5,482
+  Unique hosts          : 47
+  Critical              : 142
+  KEV matches           : 19
+  EPSS >= 90%           : 31
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  #    Score   Priority      Host              CVE                Finding
+  ───────────────────────────────────────────────────────────────────────
+  1    100.0   CRITICAL NOW  192.168.1.10      CVE-2021-44228     Log4Shell ★KEV
+  2    100.0   CRITICAL NOW  192.168.1.25      CVE-2023-34362     MOVEit SQL Injection ★KEV
+  3    99.8    CRITICAL NOW  192.168.1.15      CVE-2020-1472      Zerologon ★KEV
+  4    99.7    CRITICAL NOW  192.168.1.11      CVE-2021-26084     Confluence RCE ★KEV
+  5    11.5    LOW           192.168.1.10      N/A                SSH Weak Ciphers
+
+  ★ KEV = CISA Known Exploited Vulnerability — highest remediation priority
+        based on active exploitation in the wild.
+
+  TOP 10 HOSTS BY AGGREGATE RISK
+   1. 192.168.1.10    score=122.0 [1 KEV] [1 critical]
+   2. 192.168.1.25    score=100.0 [1 KEV] [1 critical]
+   3. 192.168.1.15    score=99.8  [1 KEV] [1 critical]
+```
+
+---
+
+## How scoring works
+
+The scoring algorithm is deterministic, transparent, and fully documented.
+
+VulnPilot uses a composite risk score that combines four signals:
+
+| Signal | Weight | Source |
+|---|---|---|
+| CISA KEV match | 40% | Known exploited in the wild |
+| FIRST EPSS score | 35% | Exploitation probability |
+| CVSS base score | 15% | Severity context |
+| Scanner risk rating | 10% | Nessus severity label |
+
+The composite score is intentionally opinionated. Known exploited vulnerabilities receive the greatest weight because active exploitation is a stronger predictor of remediation priority than severity alone. EPSS estimates exploitation likelihood in the next 30 days, while CVSS and scanner severity provide additional context for findings without EPSS data.
+
+Any finding confirmed in the CISA KEV catalog scores a minimum of 75 regardless of other factors. The weighting model is intentionally transparent and may evolve based on community feedback and real-world usage.
+
+> **Note**
+>
+> VulnPilot provides prioritization guidance to assist remediation workflows.
+> Final remediation decisions should always consider asset criticality, business context,
+> exploit mitigations, and organizational risk tolerance.
+
+---
+
+## Privacy by design
+
+- Scan data processed entirely on your local machine
+- No account required
+- No cloud upload, ever
+- No telemetry or analytics
+- No API keys required
+- Works air-gapped after initial feed download
+- Open source — inspect every line of code
+
+---
+
+## Feed updates
+
+VulnPilot pulls two public datasets:
+
+- **CISA KEV** — Known Exploited Vulnerabilities catalog (maintained by CISA)
+- **FIRST EPSS** — Exploit Prediction Scoring System (updated daily by FIRST.org)
+
+Feeds are cached at `~/.vulnpilot/feeds/` on your machine. No API keys required.
+
+```bash
+vulnpilot update-feeds
+```
+
+The GitHub repository also runs an automated daily feed sync via GitHub Actions, publishing optimized feed files for the CLI to consume.
+
+---
+
+## Supported scanners
+
+| Scanner | Status |
+|---|---|
+| Nessus (.csv export) | ✅ Supported |
+| Qualys | Planned |
+| Rapid7 | Planned |
+| OpenVAS | Planned |
+| Microsoft Defender | Planned |
+| AWS Inspector | Planned |
+
+---
+
+## Roadmap
+
+**Current — v0.1.0 (Developer Preview)**
+- [x] Nessus CSV parser
+- [x] CISA KEV enrichment
+- [x] FIRST EPSS enrichment
+- [x] Composite risk scoring
+- [x] Prioritized terminal output
+- [x] Top hosts by aggregate risk
+- [x] Free tier — top 20 findings
+- [x] GitHub Actions daily feed automation
+
+**v0.2.0**
+- [ ] HTML report export
+- [ ] PDF report export
+
+**v0.3.0**
+- [ ] Jira integration
+- [ ] Slack notifications
+- [ ] Scheduled scans
+
+**v0.4.0**
+- [ ] Qualys CSV support
+- [ ] REST API
+
+**v1.0.0**
+- [ ] Rapid7 and OpenVAS support
+- [ ] Self-hosted Docker edition
+- [ ] Team features
+
+Future development priorities will be driven by community feedback and real-world usage.
+
+---
+
+## Requirements
+
+- Python 3.10, 3.11, or 3.12
+- pip
+- Internet connection for feed updates (air-gapped use supported after initial download)
+- Nessus .csv export file
+
+---
+
+## Contributing
+
+Issues, bug reports, and pull requests are welcome.
+
+- **Bug reports and feature requests:** [github.com/PatchVex/vulnpilot/issues](https://github.com/PatchVex/vulnpilot/issues)
+- **Security disclosures:** security@patchvex.com
+
+Good first issues are labelled `good first issue` in the issue tracker. Please search existing issues before opening a new one.
+
+---
+
+## Acknowledgements
+
+VulnPilot uses publicly available threat intelligence published by:
+
+- [CISA Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
+- [FIRST Exploit Prediction Scoring System (EPSS)](https://www.first.org/epss/)
+
+Thank you to both organizations for maintaining these community resources.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+Free to use, modify, and distribute. Commercial use permitted.
+
+---
+
+## About PatchVex
+
+VulnPilot is built and maintained by [PatchVex](https://patchvex.com).
+
+PatchVex builds privacy-first workflow tools for security and DevSecOps teams. Our products help engineers spend less time managing vulnerability data and more time fixing the issues that matter.
+
+- Website: [patchvex.com](https://patchvex.com)
+- Email: hello@patchvex.com
+- GitHub: [github.com/PatchVex](https://github.com/PatchVex)

vulnpilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+vulnpilot/__init__.py,sha256=pfuSXvGCERnVj-EYz3ZNd0VuRjnJ8kFK5pXlXwpqG8s,131
+vulnpilot/cli.py,sha256=P7XnBzJiNehX-jwzmVjaKyIcyqfwx61Aw9SBcZ0fD4o,3499
+vulnpilot/enrich/__init__.py,sha256=S37CGy1-A-vPiJnTRESGxTrfDOu5E75bRI8ZGP0FaIs,144
+vulnpilot/enrich/enricher.py,sha256=iM0yCQrY16P2f8XvvkPjEPnJGAHBPA3YjsqFzhZDW6c,1063
+vulnpilot/enrich/feeds.py,sha256=tJ0ctJqd6sln_yCFBSGCWXx6BDbQkNjdkh5xAb1kGI4,2634
+vulnpilot/parser/__init__.py,sha256=rVfaYC2pXjejQyge5rKQ0qFnjqxb9wyxsYrm1TB8ME8,88
+vulnpilot/parser/nessus.py,sha256=Grb8i6ycjXVc06U6jAazWsrbxDD6hip6MjcRvu_-uJA,4123
+vulnpilot/reports/__init__.py,sha256=5el470lZD9H7o4Inbb_Kx0BI35y72Pqqo8p07scAFRA,188
+vulnpilot/reports/terminal.py,sha256=m7E4pJeyd36is--U2tY4assuT5eAlBhx2-YLIWg4GOY,4643
+vulnpilot/scoring/__init__.py,sha256=Ss9K9exGRYqDolkxTffvO3nLFzgtZi7CU2kwjwy5zyw,152
+vulnpilot/scoring/engine.py,sha256=vvU43x48cXZYzmUA1ahHaZRcNFi2Eze2RiDJC8DQSoU,1797
+vulnpilot-0.1.0.dist-info/LICENSE,sha256=RK6YHCN0U9EnI1NRO6mY1HANMOw0xFmgx46cem-yy0w,1065
+vulnpilot-0.1.0.dist-info/METADATA,sha256=minRidZNleYG1JaIp2EGBqWEEnPFyrWCKUsrMFkDDIc,10534
+vulnpilot-0.1.0.dist-info/WHEEL,sha256=Wyh-_nZ0DJYolHNn1_hMa4lM7uDedD_RGVwbmTjyItk,91
+vulnpilot-0.1.0.dist-info/entry_points.txt,sha256=Kn41I6BzrmRvtjcmn09hEI1EUMn14zLTAkwDxeBu7IM,49
+vulnpilot-0.1.0.dist-info/top_level.txt,sha256=B0edhMLTMuc7VDzyPUkcjGgisM-tPbZQ5ZWp3yj8aN8,10
+vulnpilot-0.1.0.dist-info/RECORD,,

vulnpilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (71.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vulnpilot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vulnpilot = vulnpilot.cli:main

vulnpilot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vulnpilot