@vulcn/plugin-report 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,142 @@
 import { z } from 'zod';
-import { Session, RunResult, Finding, VulcnPlugin } from '@vulcn/engine';
+import { PayloadCategory, Session, RunResult, VulcnPlugin } from '@vulcn/engine';
+
+/**
+ * Vulcn Report Model
+ *
+ * The canonical data model from which all output formats (HTML, JSON,
+ * YAML, SARIF) are derived. This is the single source of truth for
+ * CWE mappings, severity scores, fingerprinting, risk computation,
+ * and passive analysis categorisation.
+ *
+ *   RunResult + Session
+ *          ↓
+ *     buildReport()
+ *          ↓
+ *     VulcnReport (canonical)
+ *          ↓
+ *   ┌──────┴──────────┬──────────┬──────────┐
+ *   HTML            JSON       YAML       SARIF
+ *
+ * Every output format is a projection of this model.
+ */
+
+interface CweEntry {
+    id: number;
+    name: string;
+}
+type Severity = "critical" | "high" | "medium" | "low" | "info";
+interface PassiveCheckDefinition {
+    id: string;
+    label: string;
+    icon: string;
+    color: string;
+    remedy: string;
+    checks: string[];
+}
+interface EnrichedFinding {
+    /** Original raw finding fields */
+    type: PayloadCategory;
+    severity: Severity;
+    title: string;
+    description: string;
+    stepId: string;
+    payload: string;
+    url: string;
+    evidence?: string;
+    metadata?: Record<string, unknown>;
+    /** Enriched fields — computed by buildReport() */
+    ruleId: string;
+    cwe: CweEntry;
+    securitySeverity: string;
+    fingerprint: string;
+    /** Detection classification */
+    detectionMethod: "active" | "passive";
+    /** Passive category (only set when detectionMethod === "passive") */
+    passiveCategory?: string;
+}
+interface ReportRule {
+    /** e.g. "VULCN-XSS" */
+    id: string;
+    /** Raw type name e.g. "xss" */
+    type: string;
+    /** CWE info */
+    cwe: CweEntry;
+    /** Severity of the first finding with this rule */
+    severity: Severity;
+    securitySeverity: string;
+    /** Description for help text */
+    description: string;
+}
+interface PassiveCategorySummary {
+    definition: PassiveCheckDefinition;
+    /** Findings in this category */
+    findings: EnrichedFinding[];
+    /** Issue count */
+    issueCount: number;
+    /** Number of checks that passed */
+    passedChecks: number;
+    /** Total checks for this category */
+    totalChecks: number;
+    /** PASS | WARN | FAIL */
+    status: "pass" | "warn" | "fail";
+}
+interface PassiveAnalysis {
+    totalIssues: number;
+    categories: PassiveCategorySummary[];
+}
+interface RiskAssessment {
+    score: number;
+    percent: number;
+    label: "Critical" | "High" | "Medium" | "Low" | "Clear";
+}
+type SeverityCounts = Record<Severity, number>;
+interface VulcnReport {
+    /** Report format version */
+    reportVersion: "2.0";
+    /** Engine version that generated the scan */
+    engineVersion: string;
+    /** ISO timestamp when this report was generated */
+    generatedAt: string;
+    /** Session metadata */
+    session: {
+        name: string;
+        driver: string;
+        driverConfig: Record<string, unknown>;
+        stepsCount: number;
+        metadata?: Record<string, unknown>;
+    };
+    /** Execution statistics */
+    stats: {
+        stepsExecuted: number;
+        payloadsTested: number;
+        durationMs: number;
+        errors: string[];
+    };
+    /** Summary / overview data */
+    summary: {
+        totalFindings: number;
+        severityCounts: SeverityCounts;
+        risk: RiskAssessment;
+        vulnerabilityTypes: string[];
+        affectedUrls: string[];
+    };
+    /** Rule registry — one rule per unique finding type */
+    rules: ReportRule[];
+    /** All findings — enriched with CWE, fingerprints, classification */
+    findings: EnrichedFinding[];
+    /** Active findings (subset) */
+    activeFindings: EnrichedFinding[];
+    /** Passive analysis summary */
+    passiveAnalysis: PassiveAnalysis;
+}
+/**
+ * Build a VulcnReport from raw scan output.
+ *
+ * This is the single transformation point. All output formats
+ * (HTML, JSON, YAML, SARIF) operate on the returned model.
+ */
+declare function buildReport(session: Session, result: RunResult, generatedAt: string, engineVersion: string): VulcnReport;
 
 /**
  * HTML Report Generator for Vulcn
@@ -12,33 +149,25 @@ import { Session, RunResult, Finding, VulcnPlugin } from '@vulcn/engine';
  * - Responsive design
  */
 
-interface HtmlReportData {
-    session: Session;
-    result: RunResult;
-    generatedAt: string;
-    engineVersion: string;
-}
-declare function generateHtml(data: HtmlReportData): string;
+declare function generateHtml(report: VulcnReport): string;
 
 /**
  * JSON Report Generator for Vulcn
  *
- * Produces a structured, machine-readable JSON report.
+ * Projects the canonical VulcnReport into a clean JSON structure
+ * suitable for CI/CD pipelines and programmatic consumption.
  */
 
+/**
+ * The JSON output shape — a clean projection of VulcnReport.
+ */
 interface JsonReport {
     vulcn: {
         version: string;
         reportVersion: string;
         generatedAt: string;
     };
-    session: {
-        name: string;
-        driver: string;
-        driverConfig: Record<string, unknown>;
-        stepsCount: number;
-        metadata?: Record<string, unknown>;
-    };
+    session: VulcnReport["session"];
     execution: {
         stepsExecuted: number;
         payloadsTested: number;
@@ -49,34 +178,152 @@ interface JsonReport {
     summary: {
         totalFindings: number;
         riskScore: number;
-        severityCounts: Record<string, number>;
+        riskLabel: string;
+        severityCounts: VulcnReport["summary"]["severityCounts"];
         vulnerabilityTypes: string[];
         affectedUrls: string[];
     };
-    findings: Finding[];
+    findings: VulcnReport["findings"];
+    passiveAnalysis: {
+        totalIssues: number;
+        categories: Array<{
+            id: string;
+            label: string;
+            status: string;
+            issueCount: number;
+            passedChecks: number;
+            totalChecks: number;
+            remedy: string;
+        }>;
+    };
+    rules: VulcnReport["rules"];
 }
-declare function generateJson(session: Session, result: RunResult, generatedAt: string, engineVersion: string): JsonReport;
+declare function generateJson(report: VulcnReport): JsonReport;
 
 /**
  * YAML Report Generator for Vulcn
  *
- * Produces a human-readable YAML report.
+ * Produces a human-readable YAML report from the canonical VulcnReport.
  */
 
-declare function generateYaml(session: Session, result: RunResult, generatedAt: string, engineVersion: string): string;
+declare function generateYaml(report: VulcnReport): string;
+
+/**
+ * SARIF Report Generator for Vulcn
+ *
+ * Projects the canonical VulcnReport into SARIF v2.1.0 (Static Analysis
+ * Results Interchange Format) compatible with GitHub Code Scanning,
+ * Azure DevOps, and other SARIF-consuming tools.
+ *
+ * @see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ * @see https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning
+ */
+
+interface SarifLog {
+    $schema: string;
+    version: "2.1.0";
+    runs: SarifRun[];
+}
+interface SarifRun {
+    tool: SarifTool;
+    results: SarifResult[];
+    invocations: SarifInvocation[];
+    artifacts?: SarifArtifact[];
+}
+interface SarifTool {
+    driver: SarifToolComponent;
+}
+interface SarifToolComponent {
+    name: string;
+    version: string;
+    informationUri: string;
+    semanticVersion: string;
+    rules: SarifRule[];
+}
+interface SarifRule {
+    id: string;
+    name: string;
+    shortDescription: {
+        text: string;
+    };
+    fullDescription: {
+        text: string;
+    };
+    helpUri: string;
+    help: {
+        text: string;
+        markdown: string;
+    };
+    properties: {
+        tags: string[];
+        precision: "very-high" | "high" | "medium" | "low";
+        "security-severity": string;
+    };
+    defaultConfiguration: {
+        level: SarifLevel;
+    };
+}
+type SarifLevel = "error" | "warning" | "note" | "none";
+interface SarifResult {
+    ruleId: string;
+    ruleIndex: number;
+    level: SarifLevel;
+    message: {
+        text: string;
+    };
+    locations: SarifLocation[];
+    fingerprints: Record<string, string>;
+    partialFingerprints: Record<string, string>;
+    properties: Record<string, unknown>;
+}
+interface SarifLocation {
+    physicalLocation: {
+        artifactLocation: {
+            uri: string;
+            uriBaseId?: string;
+        };
+        region?: {
+            startLine: number;
+            startColumn?: number;
+        };
+    };
+    logicalLocations?: Array<{
+        name: string;
+        kind: string;
+    }>;
+}
+interface SarifInvocation {
+    executionSuccessful: boolean;
+    startTimeUtc?: string;
+    endTimeUtc?: string;
+    properties?: Record<string, unknown>;
+}
+interface SarifArtifact {
+    location: {
+        uri: string;
+    };
+    length?: number;
+}
+/**
+ * Generate a SARIF v2.1.0 log from a VulcnReport.
+ *
+ * Usage:
+ *   const report = buildReport(session, result, generatedAt, "0.5.0");
+ *   const sarif = generateSarif(report);
+ *   await writeFile("vulcn-report.sarif", JSON.stringify(sarif, null, 2));
+ */
+declare function generateSarif(report: VulcnReport): SarifLog;
 
 /**
  * @vulcn/plugin-report
  * Report Generation Plugin for Vulcn
  *
- * Generates security reports in HTML, JSON, and YAML formats
- * after a run completes. Features:
- * - Modern dark-themed HTML report with Vulcn branding
- * - Machine-readable JSON for CI/CD integration
- * - Human-readable YAML for documentation
+ * Generates security reports in HTML, JSON, YAML, and SARIF formats
+ * after a run completes. All formats are projections of the canonical
+ * VulcnReport model, built once via buildReport().
  *
  * Configuration:
- *   format:     "html" | "json" | "yaml" | "all"  (default: "html")
+ *   format:     "html" | "json" | "yaml" | "sarif" | "all"  (default: "html")
  *   outputDir:  directory for reports               (default: ".")
  *   filename:   base filename (no extension)        (default: "vulcn-report")
  *   open:       auto-open HTML in browser           (default: false)
@@ -91,10 +338,11 @@ declare const configSchema: z.ZodObject<{
      * - "html":  Beautiful dark-themed HTML report
      * - "json":  Machine-readable structured JSON
      * - "yaml":  Human-readable YAML
-     * - "all":   Generate all three formats
+     * - "sarif": SARIF v2.1.0 for GitHub Code Scanning
+     * - "all":   Generate all formats
      * @default "html"
      */
-    format: z.ZodDefault<z.ZodEnum<["html", "json", "yaml", "all"]>>;
+    format: z.ZodDefault<z.ZodEnum<["html", "json", "yaml", "sarif", "all"]>>;
     /**
      * Output directory for report files
      * @default "."
@@ -111,12 +359,12 @@ declare const configSchema: z.ZodObject<{
      */
     open: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    format: "html" | "json" | "yaml" | "all";
+    format: "html" | "json" | "yaml" | "sarif" | "all";
     outputDir: string;
     filename: string;
     open: boolean;
 }, {
-    format?: "html" | "json" | "yaml" | "all" | undefined;
+    format?: "html" | "json" | "yaml" | "sarif" | "all" | undefined;
     outputDir?: string | undefined;
     filename?: string | undefined;
     open?: boolean | undefined;
@@ -127,4 +375,4 @@ type ReportConfig = z.infer<typeof configSchema>;
  */
 declare const plugin: VulcnPlugin;
 
-export { type HtmlReportData, type JsonReport, type ReportConfig, configSchema, plugin as default, generateHtml, generateJson, generateYaml };
+export { type CweEntry, type EnrichedFinding, type JsonReport, type PassiveAnalysis, type PassiveCategorySummary, type PassiveCheckDefinition, type ReportConfig, type ReportRule, type RiskAssessment, type SarifLog, type SeverityCounts, type VulcnReport, buildReport, configSchema, plugin as default, generateHtml, generateJson, generateSarif, generateYaml };