Canonical Findings Schema

Integrate and consume VScanX's standardized, strongly-typed JSON data contract designed for operational reliability.

Mental Model

A common frustration with security tooling is inconsistent output structures. Many scanners write text reports, customized HTML summaries, or noisy XML grids that developers must write heavy, custom parsers to consume inside pipelines.

VScanX completely eliminates this variance by requiring **every single finding** to adhere strictly to a rigid, standardized, and strongly-typed data schema (defined inside core/schemas.py).

Whether a vulnerability originates from an EVM smart contract sweep, a cloud SSRF validation, or a prompt injection jailbreak, the JSON payload follows the exact same logical structure.

The JSON Findings Schema Contract

The following is a realistic output artifact produced by the Verification Engine upon successfully confirming a critical SSRF vulnerability:

{
  "finding_id": "CAN-2026-F981",
  "trace_id": "tr_00912BCX",
  "signature": "Open Redirect Vulnerability",
  "module": "modules.web.open_redirect_prober",
  "severity": "CRITICAL",
  "confidence": 1.0,
  "verification": {
    "status": "VERIFIED",
    "verified_at": "2026-05-27T14:02:18Z",
    "proof": {
      "request_method": "GET",
      "exploit_payload": "/admin?next=http%3A%2F%2F169.254.169.254%2Flatest%2Fmeta-data%2F",
      "response_evidence": {
        "status_code": 200,
        "header_key": "Server",
        "content_match": "ami-id"
      }
    }
  },
  "reproducibility_metadata": {
    "reproduction_mode": "docker_sandbox",
    "sandbox_image": "vscanx/val-web:latest",
    "replay_linkage_id": "run_291A_web"
  }
}

Schema Field Reference

JSON Key	Type	Description
finding_id	String	Standardized canonical identifier unique to the vulnerability class.
severity	Enum	Vulnerability severity classification: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
confidence	Float	Confidence scoring metric mapping verification precision, varying from 0.0 to 1.0 (VERIFIED).
verification.status	Enum	Confirmation level: `UNVERIFIED`, `PENDING`, or `VERIFIED`.
verification.proof	Object	Dynamic details capturing the exact request, exploit payload, and response content match evidence.
reproducibility_metadata	Object	Orchestration specs storing sandbox image requirements and the replay snapshot linkage id.

Automated CI/CD Build Failures

Because VScanX findings are perfectly structured and reproducible, you can parse the JSON output cleanly to fail integration builds.

The following Python script illustrates how a deployment pipeline parses a VScanX report and exits with status 1 only if a highly reproducible, critical vulnerability is actively verified:

# scripts/pipeline_gate.py
import sys
import json

def parse_report(report_path):
    try:
        with open(report_path, 'r') as file:
            data = json.load(file)
            
        findings = data.get('findings', [])
        for item in findings:
            severity = item.get('severity')
            status = item.get('verification', {}).get('status')
            confidence = item.get('confidence', 0.0)
            
            # Block deploy only if vulnerability is critical and fully verified
            if severity == 'CRITICAL' and status == 'VERIFIED' and confidence == 1.0:
                print(f'[CI/CD GATE] Critical Reproducible Anomaly Flagged: {item["signature"]}')
                sys.exit(1)
                
        print('[CI/CD GATE] Zero verified critical regressions found. Approval granted.')
        sys.exit(0)
    except Exception as err:
        print(f'[CI/CD GATE] Error parsing VScanX report: {err}')
        sys.exit(1)

if __name__ == '__main__':
    parse_report(sys.argv[1])