@vulcn/plugin-report 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -65,18 +65,137 @@ declare function generateJson(session: Session, result: RunResult, generatedAt:
 
 declare function generateYaml(session: Session, result: RunResult, generatedAt: string, engineVersion: string): string;
 
+/**
+ * SARIF Report Generator for Vulcn
+ *
+ * Produces 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
+ */
+
+/**
+ * SARIF v2.1.0 Log — top-level structure
+ */
+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 Vulcn scan results.
+ *
+ * Usage:
+ *   const sarif = generateSarif(session, result, generatedAt, "0.4.0");
+ *   await writeFile("vulcn-report.sarif", JSON.stringify(sarif, null, 2));
+ *
+ * The output can be uploaded to:
+ *   - GitHub Code Scanning: `gh api /repos/{owner}/{repo}/code-scanning/sarifs`
+ *   - GitHub Actions: `github/codeql-action/upload-sarif@v3`
+ *   - Azure DevOps: SARIF SAST Scans Tab extension
+ *
+ * @param session  - The session that was executed
+ * @param result   - The run result with findings
+ * @param generatedAt - ISO timestamp
+ * @param engineVersion - Vulcn engine version
+ */
+declare function generateSarif(session: Session, result: RunResult, generatedAt: string, engineVersion: string): SarifLog;
+
 /**
  * @vulcn/plugin-report
  * Report Generation Plugin for Vulcn
  *
- * Generates security reports in HTML, JSON, and YAML formats
+ * Generates security reports in HTML, JSON, YAML, and SARIF 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
+ * - SARIF v2.1.0 for GitHub Code Scanning and IDE integration
  *
  * 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 +210,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 +231,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 +247,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 HtmlReportData, type JsonReport, type ReportConfig, type SarifLog, configSchema, plugin as default, generateHtml, generateJson, generateSarif, generateYaml };

package/dist/index.d.ts

@@ -65,18 +65,137 @@ declare function generateJson(session: Session, result: RunResult, generatedAt:
 
 declare function generateYaml(session: Session, result: RunResult, generatedAt: string, engineVersion: string): string;
 
+/**
+ * SARIF Report Generator for Vulcn
+ *
+ * Produces 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
+ */
+
+/**
+ * SARIF v2.1.0 Log — top-level structure
+ */
+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 Vulcn scan results.
+ *
+ * Usage:
+ *   const sarif = generateSarif(session, result, generatedAt, "0.4.0");
+ *   await writeFile("vulcn-report.sarif", JSON.stringify(sarif, null, 2));
+ *
+ * The output can be uploaded to:
+ *   - GitHub Code Scanning: `gh api /repos/{owner}/{repo}/code-scanning/sarifs`
+ *   - GitHub Actions: `github/codeql-action/upload-sarif@v3`
+ *   - Azure DevOps: SARIF SAST Scans Tab extension
+ *
+ * @param session  - The session that was executed
+ * @param result   - The run result with findings
+ * @param generatedAt - ISO timestamp
+ * @param engineVersion - Vulcn engine version
+ */
+declare function generateSarif(session: Session, result: RunResult, generatedAt: string, engineVersion: string): SarifLog;
+
 /**
  * @vulcn/plugin-report
  * Report Generation Plugin for Vulcn
  *
- * Generates security reports in HTML, JSON, and YAML formats
+ * Generates security reports in HTML, JSON, YAML, and SARIF 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
+ * - SARIF v2.1.0 for GitHub Code Scanning and IDE integration
  *
  * 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 +210,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 +231,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 +247,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 HtmlReportData, type JsonReport, type ReportConfig, type SarifLog, configSchema, plugin as default, generateHtml, generateJson, generateSarif, generateYaml };

package/dist/index.js

@@ -928,6 +928,248 @@ function generateYaml(session, result, generatedAt, engineVersion) {
   return header + stringify(report, { indent: 2 });
 }
 
+// src/sarif.ts
+var CWE_MAP = {
+  xss: {
+    id: 79,
+    name: "Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')"
+  },
+  sqli: {
+    id: 89,
+    name: "Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')"
+  },
+  ssrf: { id: 918, name: "Server-Side Request Forgery (SSRF)" },
+  xxe: {
+    id: 611,
+    name: "Improper Restriction of XML External Entity Reference"
+  },
+  "command-injection": {
+    id: 78,
+    name: "Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')"
+  },
+  "path-traversal": {
+    id: 22,
+    name: "Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')"
+  },
+  "open-redirect": {
+    id: 601,
+    name: "URL Redirection to Untrusted Site ('Open Redirect')"
+  },
+  reflection: {
+    id: 200,
+    name: "Exposure of Sensitive Information to an Unauthorized Actor"
+  },
+  "security-misconfiguration": {
+    id: 16,
+    name: "Configuration"
+  },
+  "information-disclosure": {
+    id: 200,
+    name: "Exposure of Sensitive Information to an Unauthorized Actor"
+  },
+  custom: { id: 20, name: "Improper Input Validation" }
+};
+function toSarifLevel(severity) {
+  switch (severity) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+    case "info":
+      return "note";
+    default:
+      return "warning";
+  }
+}
+function toSecuritySeverity(severity) {
+  switch (severity) {
+    case "critical":
+      return "9.0";
+    case "high":
+      return "7.0";
+    case "medium":
+      return "4.0";
+    case "low":
+      return "2.0";
+    case "info":
+      return "0.0";
+    default:
+      return "4.0";
+  }
+}
+function toPrecision(severity) {
+  switch (severity) {
+    case "critical":
+      return "very-high";
+    case "high":
+      return "high";
+    case "medium":
+      return "medium";
+    case "low":
+    case "info":
+      return "low";
+    default:
+      return "medium";
+  }
+}
+function toRuleId(type) {
+  return `VULCN-${type.toUpperCase().replace(/[^A-Z0-9]+/g, "-")}`;
+}
+function buildRules(findings) {
+  const seenTypes = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    if (!seenTypes.has(f.type)) {
+      seenTypes.set(f.type, f);
+    }
+  }
+  return Array.from(seenTypes.entries()).map(([type, sampleFinding]) => {
+    const cwe = CWE_MAP[type] || CWE_MAP.custom;
+    const ruleId = toRuleId(type);
+    return {
+      id: ruleId,
+      name: type,
+      shortDescription: {
+        text: `${cwe.name} (CWE-${cwe.id})`
+      },
+      fullDescription: {
+        text: `Vulcn detected a potential ${type} vulnerability. ${cwe.name}. See CWE-${cwe.id} for details.`
+      },
+      helpUri: `https://cwe.mitre.org/data/definitions/${cwe.id}.html`,
+      help: {
+        text: `## ${cwe.name}
+
+CWE-${cwe.id}: ${cwe.name}
+
+This rule detects ${type} vulnerabilities by injecting security payloads into form inputs and analyzing the application's response for signs of exploitation.
+
+### Remediation
+
+See https://cwe.mitre.org/data/definitions/${cwe.id}.html for detailed remediation guidance.`,
+        markdown: `## ${cwe.name}
+
+**CWE-${cwe.id}**: ${cwe.name}
+
+This rule detects \`${type}\` vulnerabilities by injecting security payloads into form inputs and analyzing the application's response for signs of exploitation.
+
+### Remediation
+
+See [CWE-${cwe.id}](https://cwe.mitre.org/data/definitions/${cwe.id}.html) for detailed remediation guidance.`
+      },
+      properties: {
+        tags: ["security", `CWE-${cwe.id}`, `external/cwe/cwe-${cwe.id}`],
+        precision: toPrecision(sampleFinding.severity),
+        "security-severity": toSecuritySeverity(sampleFinding.severity)
+      },
+      defaultConfiguration: {
+        level: toSarifLevel(sampleFinding.severity)
+      }
+    };
+  });
+}
+function toSarifResult(finding, rules) {
+  const ruleId = toRuleId(finding.type);
+  const ruleIndex = rules.findIndex((r) => r.id === ruleId);
+  let messageText = `${finding.title}
+
+${finding.description}`;
+  if (finding.evidence) {
+    messageText += `
+
+Evidence: ${finding.evidence}`;
+  }
+  messageText += `
+
+Payload: ${finding.payload}`;
+  const uri = finding.url || "unknown";
+  const fingerprint = `${finding.type}:${finding.stepId}:${finding.payload.slice(0, 50)}`;
+  return {
+    ruleId,
+    ruleIndex: Math.max(ruleIndex, 0),
+    level: toSarifLevel(finding.severity),
+    message: { text: messageText },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri
+          },
+          region: {
+            startLine: 1
+          }
+        },
+        logicalLocations: [
+          {
+            name: finding.stepId,
+            kind: "test-step"
+          }
+        ]
+      }
+    ],
+    fingerprints: {
+      vulcnFindingV1: fingerprint
+    },
+    partialFingerprints: {
+      vulcnType: finding.type,
+      vulcnStepId: finding.stepId
+    },
+    properties: {
+      severity: finding.severity,
+      payload: finding.payload,
+      stepId: finding.stepId,
+      ...finding.evidence ? { evidence: finding.evidence } : {},
+      ...finding.metadata || {}
+    }
+  };
+}
+function generateSarif(session, result, generatedAt, engineVersion) {
+  const rules = buildRules(result.findings);
+  const results = result.findings.map((f) => toSarifResult(f, rules));
+  const uniqueUrls = [
+    ...new Set(result.findings.map((f) => f.url).filter(Boolean))
+  ];
+  const artifacts = uniqueUrls.map((url) => ({
+    location: { uri: url }
+  }));
+  const startDate = new Date(generatedAt);
+  const endDate = new Date(startDate.getTime() + result.duration);
+  const sarifLog = {
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "Vulcn",
+            version: engineVersion,
+            semanticVersion: engineVersion,
+            informationUri: "https://vulcn.dev",
+            rules
+          }
+        },
+        results,
+        invocations: [
+          {
+            executionSuccessful: result.errors.length === 0,
+            startTimeUtc: generatedAt,
+            endTimeUtc: endDate.toISOString(),
+            properties: {
+              sessionName: session.name,
+              stepsExecuted: result.stepsExecuted,
+              payloadsTested: result.payloadsTested,
+              durationMs: result.duration,
+              ...result.errors.length > 0 ? { errors: result.errors } : {}
+            }
+          }
+        ],
+        ...artifacts.length > 0 ? { artifacts } : {}
+      }
+    ]
+  };
+  return sarifLog;
+}
+
 // src/index.ts
 var configSchema = z.object({
   /**
@@ -935,10 +1177,11 @@ var configSchema = z.object({
    * - "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.enum(["html", "json", "yaml", "all"]).default("html"),
+  format: z.enum(["html", "json", "yaml", "sarif", "all"]).default("html"),
   /**
    * Output directory for report files
    * @default "."
@@ -956,14 +1199,14 @@ var configSchema = z.object({
   open: z.boolean().default(false)
 });
 function getFormats(format) {
-  if (format === "all") return ["html", "json", "yaml"];
+  if (format === "all") return ["html", "json", "yaml", "sarif"];
   return [format];
 }
 var plugin = {
   name: "@vulcn/plugin-report",
   version: "0.1.0",
   apiVersion: 1,
-  description: "Report generation plugin \u2014 generates beautiful HTML, JSON, and YAML security reports",
+  description: "Report generation plugin \u2014 generates HTML, JSON, YAML, and SARIF security reports",
   configSchema,
   hooks: {
     onInit: async (ctx) => {
@@ -1031,6 +1274,23 @@ var plugin = {
               ctx.logger.info(`\u{1F4C4} YAML report: ${yamlPath}`);
               break;
             }
+            case "sarif": {
+              const sarifReport = generateSarif(
+                ctx.session,
+                result,
+                generatedAt,
+                engineVersion
+              );
+              const sarifPath = `${basePath}.sarif`;
+              await writeFile(
+                sarifPath,
+                JSON.stringify(sarifReport, null, 2),
+                "utf-8"
+              );
+              writtenFiles.push(sarifPath);
+              ctx.logger.info(`\u{1F4C4} SARIF report: ${sarifPath}`);
+              break;
+            }
           }
         } catch (err) {
           ctx.logger.error(
@@ -1057,6 +1317,7 @@ export {
   index_default as default,
   generateHtml,
   generateJson,
+  generateSarif,
   generateYaml
 };
 //# sourceMappingURL=index.js.map