Vulnerability-Bench

Vulnerability-Bench is an intelligent vulnerability intelligence platform designed to eliminate the signal-to-noise problem in vulnerability management. It ingests security advisories from authoritative sources (NVD, GHSA), normalizes the data, and prepares it for AI-driven enrichment and proactive alerting.

🚀 Overview

Security teams are overwhelmed by the volume of CVEs published annually. Vulnerability-Bench solves this by building an automated pipeline that filters, enriches, and routes only the vulnerabilities that matter to your organization.

Key Capabilities

Multi-Source Ingestion: Automated adapters for NVD (API 2.0) and GHSA (GraphQL).
Role-Based Access Control: Secure dashboard and APIs with Spring Security (ADMIN, ANALYST, VIEWER roles).
AI-Powered Intelligence: Automated generation of vulnerability summaries and remediation advice using LLMs (OpenAI).
Web Dashboard: A modern, glassmorphic UI for triaging and managing vulnerabilities with dynamic filtering, responsive layout alignment, and client-side markdown rendering for CVE details and AI summaries.
Proactive Alerting: Real-time Slack notifications when vulnerabilities match user-defined watchlists.
MCP Integration: Native Model Context Protocol (MCP) support, allowing AI agents to query and analyze vulnerability data.
Intelligent Deduplication: Record merging to maintain a single canonical record for each CVE.

📚 Domain Knowledge

For a deeper understanding of the concepts and workflows implemented in this platform, please refer to our comprehensive learning guides:

Vulnerability Fundamentals: Definitions, lifecycles, and core concepts.
Scoring Systems (CVSS & EPSS): How we measure severity vs. likelihood to calculate risk.
Data Sources & Identifiers: Details on CVE, CWE, NVD, and GHSA.
Workflows by Persona: How different roles (Admin, Analyst, Viewer) use the platform.

🔧 Setup Guides

Step-by-step instructions for configuring key integrations and features:

Admin Dashboard Ingest Trigger: Use the admin UI to manually trigger an ingestion cycle.
OAuth2 Setup Guide: Enable GitHub and Google social login for the dashboard.
Slack Integration Setup: Configure real-time vulnerability alerts in Slack.
Auto-Remediation (GitHub) Setup: Enable the dashboard "Generate Auto-Patch PR" workflow for dependency management.

🛠 Tech Stack

Core: Java 23+, Spring Boot 3.4.3, Spring AI
Batch Processing: Spring Batch 5
Web UI: Thymeleaf, HTMX, Vanilla CSS (Modern Glassmorphism), marked.js (Markdown rendering)
Database: PostgreSQL 18 (JSONB support for raw data)
Cache/Dedup: Redis 7
Migrations: Flyway
API Documentation: SpringDoc OpenAPI 3.1 (Swagger UI)
Infrastructure: Docker & Docker Compose

🏗 System Architecture

flowchart TD
    subgraph External["External Sources"]
        NVD["NVD API 2.0"]
        GHSA["GHSA GraphQL"]
        OpenAI["OpenAI API"]
    end

    subgraph Core["vulnerability-bench Core"]
        direction TB
        IE["Ingest Engine \n (Spring Batch)"]
        DD["Dedup & \n Normalize"]
        AI["AI Enrichment \n (Spring AI)"]
        PG[("PostgreSQL")]
        REDIS[("Redis")]
        
        IE --> DD
        DD --> PG
        DD --> REDIS
        PG --> AI
        AI --> PG
    end

    subgraph Interface["Interface Layer"]
        REST["REST API"]
        DASH["Web Dashboard \n (HTMX)"]
        MCP["MCP Server"]
    end

    External --> IE
    OpenAI <--> AI
    PG --> REST
    PG --> DASH
    PG --> MCP

🚦 Getting Started

Prerequisites

1. Clone the Repository

git clone https://github.com/prasadgaikwad/vulnerability-bench.git
cd vulnerability-bench

2. Start Infrastructure

Launch the database and cache using Docker Compose:

docker-compose up -d

Note

Database Port: The PostgreSQL instance is exposed on port 5433 to avoid conflicts with other local Postgres installations.

Database Initialization

The application uses Flyway for database schema management.

Schema Creation: The database schema (tables, indexes, etc.) is automatically created when you run the application for the first time.
Initial Data: On first startup, the database will be empty. You must trigger an ingestion cycle (see Core Endpoints) or wait for the first scheduled run (every 15 minutes) to see data.

Tip

Troubleshooting Authentication Errors: If you see FATAL: password authentication failed for user "vulnbench", it's likely due to a stale Docker volume from a previous setup. You can reset it by running:

docker-compose down -v
docker-compose up -d

3. API Keys Setup

OpenAI API Key (Required for AI Features)

To enable AI summaries and remediation advice:

Obtain a key from platform.openai.com.
Set the environment variable: export OPENAI_API_KEY=your_key_here

NVD API Key (Optional but Recommended)

While the NVD API can be used without a key, it is heavily throttled (1 request every 6 seconds). With a key, you can perform up to 50 requests in a 30-second window.

Request a key at nvd.nist.gov/developers/request-an-api-key.
Set the environment variable: export NVD_API_KEY=your_key_here

GitHub Token (Required)

A GitHub Personal Access Token (PAT) is required to access the GHSA via their GraphQL API.

Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic).
Generate a new token with at least public_repo (for public advisories) or read:packages scope.
Set the environment variable: export GITHUB_TOKEN=your_token_here

Slack Integration (Optional)

To receive vulnerability alerts in Slack, follow the detailed setup instructions in docs/setup/slack-setup.md.

4. Run the Application

./gradlew bootRun

Access the Dashboard at: http://localhost:8080/dashboard

🔐 User Authentication & Roles

Vulnerability-Bench is secured with Spring Security. It supports form-based local authentication and OAuth2 login (GitHub and Google).

Default Local Credentials

Username	Password	Role
`admin`	`admin`	`ROLE_ADMIN`

OAuth2 Setup

To enable OAuth2 login, configure the following environment variables:

GitHub: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
Google: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

Users logging in via OAuth2 for the first time will be automatically provisioned with the ROLE_USER role.

For a complete step-by-step walkthrough — including creating OAuth Apps, configuring redirect URIs, and troubleshooting common errors — see the OAuth2 Setup Guide.

Auto-Remediation PRs

The dashboard can generate a remediation branch and open a GitHub pull request for supported manifests (pom.xml and package.json).

To enable the workflow, set these environment variables:

VULNBENCH_AUTO_REMEDIATION_ENABLED=true
GITHUB_REMEDIATION_OWNER and GITHUB_REMEDIATION_REPO
GITHUB_REMEDIATION_TOKEN with repo scope access
Optional overrides: GITHUB_REMEDIATION_BASE_BRANCH, GITHUB_REMEDIATION_MANIFEST_PATH

If the integration is disabled or incomplete, the dashboard still shows a preview message instead of creating a PR.

For comprehensive configuration details, database migration information, and troubleshooting, see the Auto-Remediation Setup Guide.

Access Control Levels

ADMIN: Can access the dashboard, trigger ingestion, and manage other users via the /users page.
ANALYST: Can access the dashboard and vulnerability details to perform triage.
VIEWER: Can view vulnerability data but cannot trigger modifications or AI enrichments.

📖 API Documentation

Once the application is running, you can access the interactive API documentation at:

Swagger UI: http://localhost:8080/swagger-ui.html
OpenAPI Spec: http://localhost:8080/api-docs

Core Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/vulnerabilities`	Paginated list of all CVEs
`GET`	`/api/v1/vulnerabilities/{cveId}`	Detailed view of a specific CVE
`POST`	`/api/v1/admin/ingest/trigger`	Manually trigger an ingestion cycle
`GET`	`/api/v1/admin/ingest/status`	Monitor the state of background ingest jobs
`POST`	`/api/v1/admin/ingest/slack/test`	Send a test message to Slack (`?channel=ID`)

Sample Request & Response

Request: List Vulnerabilities

GET http://localhost:8080/api/v1/vulnerabilities?severity=CRITICAL&size=1

Response:

{
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "cveId": "CVE-2024-12345",
      "title": "Remote Code Execution in Example-Package",
      "severity": "CRITICAL",
      "cvssV3Score": 9.8,
      "epssScore": 0.045,
      "epssPercentile": 0.852,
      "epssTrend": "INCREASING",
      "riskScore": 83.5,
      "inCisaKev": true,
      "state": "PUBLISHED",
      "publishedAt": "2024-03-20T10:00:00Z"
    }
  ],
  "pageable": { ... },
  "totalElements": 1250,
  "totalPages": 1250,
  "size": 1,
  "number": 0
}

🗺 Roadmap

Slice 1: Foundation: Core ingestion, dedup, and REST API.
Slice 2: Slack Alerts: Proactive notifications for watched packages.
Slice 3: AI Enrichment: LLM-generated summaries and remediation advice.
Slice 4: Dashboard: Web UI for triage and management (Thymeleaf + HTMX).
Slice 5: MCP Server: Enable agentic AI to query vulnerability data.
Intelligence: EPSS Integration & AI Exploitability Analysis.
Slice 6: Export & Reporting: PDF/CSV/JSON exports for security compliance.
Auto-Remediation PRs: Generate GitHub branches and pull requests for supported manifests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

2026-06-08 — UI/UX Polish and Markdown Support (Issues #62, #63)

Implemented client-side markdown rendering using marked.js and custom CSS styling for CVE descriptions and AI-generated summaries (Issue #63).
Resolved CVE details page centering, alignment, and responsiveness bugs across desktop, tablet, and mobile layouts (Issue #62, #67).
Polished the dashboard table, search bar interface, and pagination, including moving data export features directly to the table header (Issue #64, #66).
Enhanced analytics page graphs, typography hierarchy, and global CSS theme consistency.
Optimized the SBOM Upload layout with interactive drag-and-drop feedback and custom states (Issue #68).
Redesigned the authentication and login pages, improving input layouts and styling social login action buttons (Issue #71).
Applied SEO best practices across the application including descriptive titles, meta headers, and unique elements IDs (Issue #70).

2026-05-25 — Admin Dashboard Ingest Trigger (Issue #54)

Added an admin-only Trigger Ingestion action to the dashboard with confirmation modal, progress indicator, and toast feedback.
The trigger action posts to /api/v1/admin/ingest/trigger, respects CSRF protection, and is hidden from non-admin users.
Added dashboard UI tests for role-based button visibility and strengthened the admin ingest controller test to verify the backend service is invoked.
Documented the workflow in Admin Dashboard Ingest Trigger.

2026-05-25 — Dynamic Risk Score Engine (Issue #38)

Implemented Dynamic Risk Score Engine: Introduced a weighted risk scoring formula (40% CVSS + 40% EPSS + 20% CISA KEV) to intelligently prioritize vulnerabilities by real-world impact.
Automatic Calculation: Risk scores are automatically calculated during vulnerability ingestion and recalculated when vulnerability data is updated.
Smart Prioritization: Search and list endpoints now default to sorting by risk score (descending) to surface high-priority vulnerabilities first.
API Enhancements: Added riskScore field to VulnerabilityResponse and VulnerabilityDetailResponse DTOs.
Comprehensive Testing: Added 36 unit tests covering formula validation, boundary conditions, null handling, and real-world scenarios. See RiskScoreCalculatorTest.java.
Documentation: Created Dynamic Risk Score Engine Guide with implementation details, usage examples, and future enhancement ideas.

2026-05-24 — Documentation Reorganization

Reorganized setup guides into a dedicated docs/setup/ folder for better discoverability and maintainability.
Moved oauth2-setup.md and slack-setup.md to docs/setup/ alongside the new auto-remediation guide.
Added comprehensive Auto-Remediation Setup Guide with configuration options, examples, security best practices, and troubleshooting.
Updated README with new "Setup Guides" section to highlight deployment and configuration documentation.

2026-05-21 — Tests

Implemented additional API security and endpoint tests (issue #45): expanded vulnerability search tests and CSRF coverage for enrichment endpoints. See tests under src/test/java/dev/prasadgaikwad/vulnbench/api.
Added a test to verify the vulnerabilities list endpoint caps requested page sizes to 100 to avoid excessive query load.

2026-05-23 — Auto-Remediation PRs

Added the dashboard auto-remediation flow for supported GitHub repositories. The new endpoint compiles safe dependency upgrades for pom.xml and package.json, opens a branch, and creates a pull request when repository credentials are configured.
Documented the required remediation environment variables and updated the vulnerability detail page with a Generate Auto-Patch PR action.

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
docs		docs
gradle/wrapper		gradle/wrapper
screenshots		screenshots
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle		build.gradle
docker-compose.yml		docker-compose.yml
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

Vulnerability-Bench

🚀 Overview

Key Capabilities

📚 Domain Knowledge

🔧 Setup Guides

🛠 Tech Stack

🏗 System Architecture

🚦 Getting Started

Prerequisites

1. Clone the Repository

2. Start Infrastructure

Database Initialization

3. API Keys Setup

OpenAI API Key (Required for AI Features)

NVD API Key (Optional but Recommended)

GitHub Token (Required)

Slack Integration (Optional)

4. Run the Application

🔐 User Authentication & Roles

Default Local Credentials

OAuth2 Setup

Auto-Remediation PRs

Access Control Levels

📖 API Documentation

Core Endpoints

Sample Request & Response

Request: List Vulnerabilities

Response:

🗺 Roadmap

📄 License

Changelog

2026-06-08 — UI/UX Polish and Markdown Support (Issues #62, #63)

2026-05-25 — Admin Dashboard Ingest Trigger (Issue #54)

2026-05-25 — Dynamic Risk Score Engine (Issue #38)

2026-05-24 — Documentation Reorganization

2026-05-21 — Tests

2026-05-23 — Auto-Remediation PRs

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages