AI Vulnerability Explainer

Nmap tells you what is exposed. AI Vulnerability Explainer tells you what it means, why it matters, and how to fix it.

Comment

💡 Inspiration

Port scanners like Nmap are foundational tools for security engineers, sysadmins, and defenders. However, raw Nmap output is cryptic. A scan report showing 6200/tcp open vsftpd 2.3.4 or 80/tcp open Apache httpd 2.4.49 doesn't explain the operational risk, the underlying vulnerability, or the exact defensive steps needed to fix it.

Generic AI chatbots often hallucinate fake CVE numbers or manufacture false security findings. We set out to build an evidence-backed platform that combines authoritative CVE intelligence (NVD & CISA KEV) with Google Gemini AI to transform raw scan data into clear, prioritized defensive intelligence without AI hallucinations.

🛡️ What It Does

AI Vulnerability Explainer ingests authorized Nmap scan results across multiple formats (direct text, PNG/JPG screenshots via OCR, PDF reports, TXT, DOC, DOCX files) and converts raw service exposure into evidence-backed vulnerability assessments.

Key Capabilities:

  • Multi-Format Scan Ingestion: Upload past Nmap outputs, PDF audit reports, Word documents, or screenshot images (with automatic text extraction via Tesseract OCR).
  • Authoritative CVE Matching: Matches detected software products and versions against NVD & CISA KEV records (CVE-2011-2523, CVE-2021-41773, CVE-2017-7494). Never fabricates CVE IDs.
  • Strict Fact vs. AI Separation: Every statement is explicitly labeled as ✓ VERIFIED FACT (authoritative CVEs, CVSS ratings, raw Nmap lines), ✦ AI ASSESSMENT (plain explanation, technical mechanism, business impact, remediation), or ? UNKNOWN.
  • Three-State Applicability: Categorizes findings into CONFIRMED (version range matches), POTENTIAL (generic version match), or UNKNOWN.
  • Interactive Raw Evidence Viewer & Data Provenance: Inspect raw extracted scan lines and view data provenance sources (Nmap, NVD, CISA KEV, Vendor Advisory, Gemini).
  • Deterministic Risk Engine: Aggregates CVSS v3 ratings, CISA KEV status, and service exposure into a deterministic risk rating (CRITICAL, HIGH, MEDIUM, LOW).
  • 1-Click Multi-Format Export: Download professional security assessment reports in PDF, DOCX, or structured JSON.
  • 1-Click Demo Lab Mode: Pre-loaded vulnerable lab target (192.168.56.101) for instant evaluation.

⚙️ How We Built It

  • Frontend: Built with React 18, Vite, and TailwindCSS 4 featuring a sleek dark-mode glassmorphism cybersecurity dashboard, interactive attack surface topology table, and multi-pill severity filters.
  • Backend API: Node.js and Express.js REST API controllers.
  • AI Reasoning Layer: Powered by Google Gemini API (@google/genai, model: gemini-2.0-flash). Scan outputs are encapsulated inside strict prompt isolation boundaries (<UNTRUSTED_SCAN_INPUT>) to resist prompt-injection attacks embedded within scan text.
  • File Processing & OCR: tesseract.js for image OCR, pdf-parse for PDF text extraction, and mammoth for DOCX files.
  • Report Generation: pdfkit for PDF compilation and docx for Word document generation.

⚡ Challenges We Ran Into

  1. Preventing AI Hallucinations: Standard LLMs often guess non-existent CVE numbers. We solved this by creating a hybrid pipeline: deterministic NVD/CISA KEV lookup verifies the vulnerability first, and Gemini only explains and contextualizes verified facts.
  2. Prompt Injection Safety: Malicious scan files could contain prompt injection payloads (e.g. Ignore previous instructions...). We enforced strict XML/JSON data wrappers and system-level prompt directives instructing Gemini to treat input strictly as untrusted raw evidence.
  3. Multi-Format Ingestion Consistency: Extracting clean Nmap text from noisy OCR screenshots required regex normalization to preserve port, protocol, and version alignment.

🏆 Accomplishments That We're Proud Of

  • Implemented a complete 10-phase cybersecurity architecture that feels like a professional security analysis product rather than a simple chatbot.
  • Successfully achieved clear 3-tier information labeling (✓ VERIFIED FACT, ✦ AI ASSESSMENT, ? UNKNOWN) throughout the dashboard and generated reports.
  • Created a 100% offline-resilient fallback mode so the application works seamlessly even when an API key is unavailable.
  • Passing a comprehensive automated test suite covering Nmap parsing, CVE matching, risk aggregation, and PDF/DOCX generation.

📚 What We Learned

  • How to design reliable guardrails combining deterministic database intelligence with generative AI reasoning.
  • Best practices in prompt isolation for parsing untrusted user-supplied file contents.
  • How to structure multi-format report builders (PDF/DOCX/JSON) that maintain strict data provenance and security boundaries.

🔮 What's Next for AI Vulnerability Explainer

  • Active Network Scanning Workflow: Add optional authorized live Nmap scan execution for local laboratory environments.
  • Integration with Security Tools: Export findings directly to SIEM solutions (Splunk, Elastic) and ticketing systems (Jira, GitHub Issues).
  • CISA KEV Live Synchronization: Periodic automatic syncing with CISA Known Exploited Vulnerabilities catalog.

Built With

Share this project:

Updates