VXDF: Validated EXploitable Data Flow

VXDF Dashboard

VXDF (Validated eXploitable Data Flow) is a next-generation security validation platform for verifying, validating, and reporting on security findings from any scanner.

• Core Architecture
• Key Components
• Validation Workflow
• Data Model
• Project Structure
• Installation
• Running the Application
• Dynamic Configuration
• Documentation
• License

VXDF follows a modular microservices architecture with clear separation between:

1. Validation Engine - Core vulnerability verification logic
2. API Layer - RESTful interface for frontend integration
3. Data Processing - SARIF/DAST/CycloneDX parsing pipeline to transform inputs into the canonical VXDF Pydantic models
4. Evidence Collection - Automated exploit validation system
5. Reporting - Serialization of the VXDFModel Pydantic object to the standard VXDF format for export

• Validation Engine: Core business logic for vulnerability verification
• Flask API: REST endpoints for frontend integration
• SQLAlchemy ORM: Database management with SQLite
• Parser System: Modular input processors (SARIF, DAST, CycloneDX) that normalize findings to the VXDF Pydantic models
• Validator Plugins: Vulnerability-specific validation logic
• Docker Integration: Isolated validation environments

• React/TypeScript: Modern UI with Vite build system
• Dynamic Dashboard: Real-time validation statistics
• Data Flow Visualization: Interactive vulnerability tracing
• Evidence Viewer: Validation proof inspection
• Report Generator: Export of findings in the standard VXDF format (JSON)

1. Input Ingestion

   • Accepts SARIF, DAST JSON, CycloneDX SBOMs
   • Normalizes findings to the common VXDF data model (defined by Pydantic models in api/models/vxdf.py)

2. Vulnerability Processing

   • Filters by severity/vulnerability type
   • Enriches with CWE/CVSS data

3. Automated Validation

   • Docker-based isolated testing
   • Evidence collection (HTTP requests, stack traces)
   • Exploitability confirmation

4. Reporting

   • Generates VXDF-standard reports by serializing the populated VXDFModel Pydantic object
   • Maintains audit trail of validation attempts

The canonical data model for VXDF is defined using Pydantic in Python, located in api/models/vxdf.py. This provides a structured and validated way to represent security findings according to the VXDF specification.

The root model is VXDFModel, which encapsulates the entire VXDF document. Key nested models include:

• VulnerabilityDetailsModel: Describes a single vulnerability, including its ID, title, description, severity, affected components, exploit flows, and evidence.
• EvidenceModel: Details a piece of evidence, specifying its type (e.g., HTTP request, code snippet, screenshot) and the associated structured data.
• LocationModel: Specifies a precise location relevant to a vulnerability (e.g., source code location, web endpoint).
• SeverityModel: Captures severity information, including qualitative levels and quantitative scores like CVSS.
• ExploitFlowModel: Describes a sequence of steps an attacker might take.

These Pydantic models are the source of truth for the VXDF data structure and are used to generate the normative JSON schema.

For the complete normative JSON schema, refer to docs/normative-schema.json. The detailed specification document can be found in [docs/Validated Exploitable Data Flow (VXDF) Format.md](docs/Validated Exploitable Data Flow (VXDF) Format.md).

(Previously, this section showed an illustrative TypeScript interface, which is now superseded by the Pydantic models and the normative JSON schema.)

• api/requirements.txt - Backend Python dependencies
• api/models/vxdf.py - Canonical Pydantic models for the VXDF schema.
• docs/normative-schema.json - The normative JSON schema generated from Pydantic models.
• frontend/vite.config.ts - Frontend configuration, including API proxy settings
• config/config.json - Application configuration
• data/vxdf_validate.db - SQLite database (created on first run)

• Backend API: http://localhost:6789
• Frontend UI: http://localhost:3000
• Log files: logs/backend.log and logs/frontend.log

• Python 3.9+
• Node.js 16+ and npm
• Git

The easiest way to start the application is to use the single script:

The backend will be available at http://localhost:6789 and the frontend at http://localhost:3000.

You can also start the services separately if needed:

If you prefer to set up the application manually:

1. Create a virtual environment:

2. Install dependencies:

3. Initialize the database (if it doesn't exist):

4. Start the API server:

1. Navigate to the frontend directory:

2. Install dependencies:

3. Start the development server:

• Sidebar navigation: Driven by frontend/src/config/sidebarConfig.ts (or API in future)
• Dashboard data: All stats, charts, and tables are fetched from the backend API
• Branding: Logo and product name are configurable
• Alerts/Notifications: (Planned) Will be fetched from API

• Startup Guide
• API Documentation
• VXDF Format

1. Import Order: Always import models in the correct order to avoid circular imports:

   • First import database modules
   • Then import model classes

2. Database Connection: Ensure the database file (data/vxdf_validate.db) is accessible and correctly initialized.

3. API Port: The API runs on port 6789 by default. Make sure this port is available.

4. Frontend Proxy: The frontend uses a proxy to communicate with the API. Check frontend/vite.config.ts if you change the API port.

If you encounter issues:

1. Reset the database:

2. Check logs:

3. Verify API is accessible:

4. Clear temporary files:

5. Fix port conflicts:

A Makefile is provided for easy startup and health checks:

• make dev — Start both backend and frontend in dev mode.
• make check — Run health checks to ensure both servers are up and API endpoints respond.

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Mihir Shah [email protected]

Please read CONTRIBUTING.md and INSTALLATION.md for details on our code of conduct and the process for submitting pull requests.