@vulcn/plugin-report 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +650 -263
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +174 -46
- package/dist/index.d.ts +174 -46
- package/dist/index.js +649 -263
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,142 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { Session, RunResult,
|
|
2
|
+
import { PayloadCategory, Session, RunResult, VulcnPlugin } from '@vulcn/engine';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Vulcn Report Model
|
|
6
|
+
*
|
|
7
|
+
* The canonical data model from which all output formats (HTML, JSON,
|
|
8
|
+
* YAML, SARIF) are derived. This is the single source of truth for
|
|
9
|
+
* CWE mappings, severity scores, fingerprinting, risk computation,
|
|
10
|
+
* and passive analysis categorisation.
|
|
11
|
+
*
|
|
12
|
+
* RunResult + Session
|
|
13
|
+
* ↓
|
|
14
|
+
* buildReport()
|
|
15
|
+
* ↓
|
|
16
|
+
* VulcnReport (canonical)
|
|
17
|
+
* ↓
|
|
18
|
+
* ┌──────┴──────────┬──────────┬──────────┐
|
|
19
|
+
* HTML JSON YAML SARIF
|
|
20
|
+
*
|
|
21
|
+
* Every output format is a projection of this model.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
interface CweEntry {
|
|
25
|
+
id: number;
|
|
26
|
+
name: string;
|
|
27
|
+
}
|
|
28
|
+
type Severity = "critical" | "high" | "medium" | "low" | "info";
|
|
29
|
+
interface PassiveCheckDefinition {
|
|
30
|
+
id: string;
|
|
31
|
+
label: string;
|
|
32
|
+
icon: string;
|
|
33
|
+
color: string;
|
|
34
|
+
remedy: string;
|
|
35
|
+
checks: string[];
|
|
36
|
+
}
|
|
37
|
+
interface EnrichedFinding {
|
|
38
|
+
/** Original raw finding fields */
|
|
39
|
+
type: PayloadCategory;
|
|
40
|
+
severity: Severity;
|
|
41
|
+
title: string;
|
|
42
|
+
description: string;
|
|
43
|
+
stepId: string;
|
|
44
|
+
payload: string;
|
|
45
|
+
url: string;
|
|
46
|
+
evidence?: string;
|
|
47
|
+
metadata?: Record<string, unknown>;
|
|
48
|
+
/** Enriched fields — computed by buildReport() */
|
|
49
|
+
ruleId: string;
|
|
50
|
+
cwe: CweEntry;
|
|
51
|
+
securitySeverity: string;
|
|
52
|
+
fingerprint: string;
|
|
53
|
+
/** Detection classification */
|
|
54
|
+
detectionMethod: "active" | "passive";
|
|
55
|
+
/** Passive category (only set when detectionMethod === "passive") */
|
|
56
|
+
passiveCategory?: string;
|
|
57
|
+
}
|
|
58
|
+
interface ReportRule {
|
|
59
|
+
/** e.g. "VULCN-XSS" */
|
|
60
|
+
id: string;
|
|
61
|
+
/** Raw type name e.g. "xss" */
|
|
62
|
+
type: string;
|
|
63
|
+
/** CWE info */
|
|
64
|
+
cwe: CweEntry;
|
|
65
|
+
/** Severity of the first finding with this rule */
|
|
66
|
+
severity: Severity;
|
|
67
|
+
securitySeverity: string;
|
|
68
|
+
/** Description for help text */
|
|
69
|
+
description: string;
|
|
70
|
+
}
|
|
71
|
+
interface PassiveCategorySummary {
|
|
72
|
+
definition: PassiveCheckDefinition;
|
|
73
|
+
/** Findings in this category */
|
|
74
|
+
findings: EnrichedFinding[];
|
|
75
|
+
/** Issue count */
|
|
76
|
+
issueCount: number;
|
|
77
|
+
/** Number of checks that passed */
|
|
78
|
+
passedChecks: number;
|
|
79
|
+
/** Total checks for this category */
|
|
80
|
+
totalChecks: number;
|
|
81
|
+
/** PASS | WARN | FAIL */
|
|
82
|
+
status: "pass" | "warn" | "fail";
|
|
83
|
+
}
|
|
84
|
+
interface PassiveAnalysis {
|
|
85
|
+
totalIssues: number;
|
|
86
|
+
categories: PassiveCategorySummary[];
|
|
87
|
+
}
|
|
88
|
+
interface RiskAssessment {
|
|
89
|
+
score: number;
|
|
90
|
+
percent: number;
|
|
91
|
+
label: "Critical" | "High" | "Medium" | "Low" | "Clear";
|
|
92
|
+
}
|
|
93
|
+
type SeverityCounts = Record<Severity, number>;
|
|
94
|
+
interface VulcnReport {
|
|
95
|
+
/** Report format version */
|
|
96
|
+
reportVersion: "2.0";
|
|
97
|
+
/** Engine version that generated the scan */
|
|
98
|
+
engineVersion: string;
|
|
99
|
+
/** ISO timestamp when this report was generated */
|
|
100
|
+
generatedAt: string;
|
|
101
|
+
/** Session metadata */
|
|
102
|
+
session: {
|
|
103
|
+
name: string;
|
|
104
|
+
driver: string;
|
|
105
|
+
driverConfig: Record<string, unknown>;
|
|
106
|
+
stepsCount: number;
|
|
107
|
+
metadata?: Record<string, unknown>;
|
|
108
|
+
};
|
|
109
|
+
/** Execution statistics */
|
|
110
|
+
stats: {
|
|
111
|
+
stepsExecuted: number;
|
|
112
|
+
payloadsTested: number;
|
|
113
|
+
durationMs: number;
|
|
114
|
+
errors: string[];
|
|
115
|
+
};
|
|
116
|
+
/** Summary / overview data */
|
|
117
|
+
summary: {
|
|
118
|
+
totalFindings: number;
|
|
119
|
+
severityCounts: SeverityCounts;
|
|
120
|
+
risk: RiskAssessment;
|
|
121
|
+
vulnerabilityTypes: string[];
|
|
122
|
+
affectedUrls: string[];
|
|
123
|
+
};
|
|
124
|
+
/** Rule registry — one rule per unique finding type */
|
|
125
|
+
rules: ReportRule[];
|
|
126
|
+
/** All findings — enriched with CWE, fingerprints, classification */
|
|
127
|
+
findings: EnrichedFinding[];
|
|
128
|
+
/** Active findings (subset) */
|
|
129
|
+
activeFindings: EnrichedFinding[];
|
|
130
|
+
/** Passive analysis summary */
|
|
131
|
+
passiveAnalysis: PassiveAnalysis;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Build a VulcnReport from raw scan output.
|
|
135
|
+
*
|
|
136
|
+
* This is the single transformation point. All output formats
|
|
137
|
+
* (HTML, JSON, YAML, SARIF) operate on the returned model.
|
|
138
|
+
*/
|
|
139
|
+
declare function buildReport(session: Session, result: RunResult, generatedAt: string, engineVersion: string): VulcnReport;
|
|
3
140
|
|
|
4
141
|
/**
|
|
5
142
|
* HTML Report Generator for Vulcn
|
|
@@ -12,33 +149,25 @@ import { Session, RunResult, Finding, VulcnPlugin } from '@vulcn/engine';
|
|
|
12
149
|
* - Responsive design
|
|
13
150
|
*/
|
|
14
151
|
|
|
15
|
-
|
|
16
|
-
session: Session;
|
|
17
|
-
result: RunResult;
|
|
18
|
-
generatedAt: string;
|
|
19
|
-
engineVersion: string;
|
|
20
|
-
}
|
|
21
|
-
declare function generateHtml(data: HtmlReportData): string;
|
|
152
|
+
declare function generateHtml(report: VulcnReport): string;
|
|
22
153
|
|
|
23
154
|
/**
|
|
24
155
|
* JSON Report Generator for Vulcn
|
|
25
156
|
*
|
|
26
|
-
*
|
|
157
|
+
* Projects the canonical VulcnReport into a clean JSON structure
|
|
158
|
+
* suitable for CI/CD pipelines and programmatic consumption.
|
|
27
159
|
*/
|
|
28
160
|
|
|
161
|
+
/**
|
|
162
|
+
* The JSON output shape — a clean projection of VulcnReport.
|
|
163
|
+
*/
|
|
29
164
|
interface JsonReport {
|
|
30
165
|
vulcn: {
|
|
31
166
|
version: string;
|
|
32
167
|
reportVersion: string;
|
|
33
168
|
generatedAt: string;
|
|
34
169
|
};
|
|
35
|
-
session:
|
|
36
|
-
name: string;
|
|
37
|
-
driver: string;
|
|
38
|
-
driverConfig: Record<string, unknown>;
|
|
39
|
-
stepsCount: number;
|
|
40
|
-
metadata?: Record<string, unknown>;
|
|
41
|
-
};
|
|
170
|
+
session: VulcnReport["session"];
|
|
42
171
|
execution: {
|
|
43
172
|
stepsExecuted: number;
|
|
44
173
|
payloadsTested: number;
|
|
@@ -49,36 +178,47 @@ interface JsonReport {
|
|
|
49
178
|
summary: {
|
|
50
179
|
totalFindings: number;
|
|
51
180
|
riskScore: number;
|
|
52
|
-
|
|
181
|
+
riskLabel: string;
|
|
182
|
+
severityCounts: VulcnReport["summary"]["severityCounts"];
|
|
53
183
|
vulnerabilityTypes: string[];
|
|
54
184
|
affectedUrls: string[];
|
|
55
185
|
};
|
|
56
|
-
findings:
|
|
186
|
+
findings: VulcnReport["findings"];
|
|
187
|
+
passiveAnalysis: {
|
|
188
|
+
totalIssues: number;
|
|
189
|
+
categories: Array<{
|
|
190
|
+
id: string;
|
|
191
|
+
label: string;
|
|
192
|
+
status: string;
|
|
193
|
+
issueCount: number;
|
|
194
|
+
passedChecks: number;
|
|
195
|
+
totalChecks: number;
|
|
196
|
+
remedy: string;
|
|
197
|
+
}>;
|
|
198
|
+
};
|
|
199
|
+
rules: VulcnReport["rules"];
|
|
57
200
|
}
|
|
58
|
-
declare function generateJson(
|
|
201
|
+
declare function generateJson(report: VulcnReport): JsonReport;
|
|
59
202
|
|
|
60
203
|
/**
|
|
61
204
|
* YAML Report Generator for Vulcn
|
|
62
205
|
*
|
|
63
|
-
* Produces a human-readable YAML report.
|
|
206
|
+
* Produces a human-readable YAML report from the canonical VulcnReport.
|
|
64
207
|
*/
|
|
65
208
|
|
|
66
|
-
declare function generateYaml(
|
|
209
|
+
declare function generateYaml(report: VulcnReport): string;
|
|
67
210
|
|
|
68
211
|
/**
|
|
69
212
|
* SARIF Report Generator for Vulcn
|
|
70
213
|
*
|
|
71
|
-
*
|
|
72
|
-
* compatible with GitHub Code Scanning,
|
|
73
|
-
* SARIF-consuming tools.
|
|
214
|
+
* Projects the canonical VulcnReport into SARIF v2.1.0 (Static Analysis
|
|
215
|
+
* Results Interchange Format) compatible with GitHub Code Scanning,
|
|
216
|
+
* Azure DevOps, and other SARIF-consuming tools.
|
|
74
217
|
*
|
|
75
218
|
* @see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
|
|
76
219
|
* @see https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning
|
|
77
220
|
*/
|
|
78
221
|
|
|
79
|
-
/**
|
|
80
|
-
* SARIF v2.1.0 Log — top-level structure
|
|
81
|
-
*/
|
|
82
222
|
interface SarifLog {
|
|
83
223
|
$schema: string;
|
|
84
224
|
version: "2.1.0";
|
|
@@ -165,34 +305,22 @@ interface SarifArtifact {
|
|
|
165
305
|
length?: number;
|
|
166
306
|
}
|
|
167
307
|
/**
|
|
168
|
-
* Generate a SARIF v2.1.0 log from
|
|
308
|
+
* Generate a SARIF v2.1.0 log from a VulcnReport.
|
|
169
309
|
*
|
|
170
310
|
* Usage:
|
|
171
|
-
* const
|
|
311
|
+
* const report = buildReport(session, result, generatedAt, "0.5.0");
|
|
312
|
+
* const sarif = generateSarif(report);
|
|
172
313
|
* await writeFile("vulcn-report.sarif", JSON.stringify(sarif, null, 2));
|
|
173
|
-
*
|
|
174
|
-
* The output can be uploaded to:
|
|
175
|
-
* - GitHub Code Scanning: `gh api /repos/{owner}/{repo}/code-scanning/sarifs`
|
|
176
|
-
* - GitHub Actions: `github/codeql-action/upload-sarif@v3`
|
|
177
|
-
* - Azure DevOps: SARIF SAST Scans Tab extension
|
|
178
|
-
*
|
|
179
|
-
* @param session - The session that was executed
|
|
180
|
-
* @param result - The run result with findings
|
|
181
|
-
* @param generatedAt - ISO timestamp
|
|
182
|
-
* @param engineVersion - Vulcn engine version
|
|
183
314
|
*/
|
|
184
|
-
declare function generateSarif(
|
|
315
|
+
declare function generateSarif(report: VulcnReport): SarifLog;
|
|
185
316
|
|
|
186
317
|
/**
|
|
187
318
|
* @vulcn/plugin-report
|
|
188
319
|
* Report Generation Plugin for Vulcn
|
|
189
320
|
*
|
|
190
321
|
* Generates security reports in HTML, JSON, YAML, and SARIF formats
|
|
191
|
-
* after a run completes.
|
|
192
|
-
*
|
|
193
|
-
* - Machine-readable JSON for CI/CD integration
|
|
194
|
-
* - Human-readable YAML for documentation
|
|
195
|
-
* - SARIF v2.1.0 for GitHub Code Scanning and IDE integration
|
|
322
|
+
* after a run completes. All formats are projections of the canonical
|
|
323
|
+
* VulcnReport model, built once via buildReport().
|
|
196
324
|
*
|
|
197
325
|
* Configuration:
|
|
198
326
|
* format: "html" | "json" | "yaml" | "sarif" | "all" (default: "html")
|
|
@@ -247,4 +375,4 @@ type ReportConfig = z.infer<typeof configSchema>;
|
|
|
247
375
|
*/
|
|
248
376
|
declare const plugin: VulcnPlugin;
|
|
249
377
|
|
|
250
|
-
export { type
|
|
378
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,142 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { Session, RunResult,
|
|
2
|
+
import { PayloadCategory, Session, RunResult, VulcnPlugin } from '@vulcn/engine';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Vulcn Report Model
|
|
6
|
+
*
|
|
7
|
+
* The canonical data model from which all output formats (HTML, JSON,
|
|
8
|
+
* YAML, SARIF) are derived. This is the single source of truth for
|
|
9
|
+
* CWE mappings, severity scores, fingerprinting, risk computation,
|
|
10
|
+
* and passive analysis categorisation.
|
|
11
|
+
*
|
|
12
|
+
* RunResult + Session
|
|
13
|
+
* ↓
|
|
14
|
+
* buildReport()
|
|
15
|
+
* ↓
|
|
16
|
+
* VulcnReport (canonical)
|
|
17
|
+
* ↓
|
|
18
|
+
* ┌──────┴──────────┬──────────┬──────────┐
|
|
19
|
+
* HTML JSON YAML SARIF
|
|
20
|
+
*
|
|
21
|
+
* Every output format is a projection of this model.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
interface CweEntry {
|
|
25
|
+
id: number;
|
|
26
|
+
name: string;
|
|
27
|
+
}
|
|
28
|
+
type Severity = "critical" | "high" | "medium" | "low" | "info";
|
|
29
|
+
interface PassiveCheckDefinition {
|
|
30
|
+
id: string;
|
|
31
|
+
label: string;
|
|
32
|
+
icon: string;
|
|
33
|
+
color: string;
|
|
34
|
+
remedy: string;
|
|
35
|
+
checks: string[];
|
|
36
|
+
}
|
|
37
|
+
interface EnrichedFinding {
|
|
38
|
+
/** Original raw finding fields */
|
|
39
|
+
type: PayloadCategory;
|
|
40
|
+
severity: Severity;
|
|
41
|
+
title: string;
|
|
42
|
+
description: string;
|
|
43
|
+
stepId: string;
|
|
44
|
+
payload: string;
|
|
45
|
+
url: string;
|
|
46
|
+
evidence?: string;
|
|
47
|
+
metadata?: Record<string, unknown>;
|
|
48
|
+
/** Enriched fields — computed by buildReport() */
|
|
49
|
+
ruleId: string;
|
|
50
|
+
cwe: CweEntry;
|
|
51
|
+
securitySeverity: string;
|
|
52
|
+
fingerprint: string;
|
|
53
|
+
/** Detection classification */
|
|
54
|
+
detectionMethod: "active" | "passive";
|
|
55
|
+
/** Passive category (only set when detectionMethod === "passive") */
|
|
56
|
+
passiveCategory?: string;
|
|
57
|
+
}
|
|
58
|
+
interface ReportRule {
|
|
59
|
+
/** e.g. "VULCN-XSS" */
|
|
60
|
+
id: string;
|
|
61
|
+
/** Raw type name e.g. "xss" */
|
|
62
|
+
type: string;
|
|
63
|
+
/** CWE info */
|
|
64
|
+
cwe: CweEntry;
|
|
65
|
+
/** Severity of the first finding with this rule */
|
|
66
|
+
severity: Severity;
|
|
67
|
+
securitySeverity: string;
|
|
68
|
+
/** Description for help text */
|
|
69
|
+
description: string;
|
|
70
|
+
}
|
|
71
|
+
interface PassiveCategorySummary {
|
|
72
|
+
definition: PassiveCheckDefinition;
|
|
73
|
+
/** Findings in this category */
|
|
74
|
+
findings: EnrichedFinding[];
|
|
75
|
+
/** Issue count */
|
|
76
|
+
issueCount: number;
|
|
77
|
+
/** Number of checks that passed */
|
|
78
|
+
passedChecks: number;
|
|
79
|
+
/** Total checks for this category */
|
|
80
|
+
totalChecks: number;
|
|
81
|
+
/** PASS | WARN | FAIL */
|
|
82
|
+
status: "pass" | "warn" | "fail";
|
|
83
|
+
}
|
|
84
|
+
interface PassiveAnalysis {
|
|
85
|
+
totalIssues: number;
|
|
86
|
+
categories: PassiveCategorySummary[];
|
|
87
|
+
}
|
|
88
|
+
interface RiskAssessment {
|
|
89
|
+
score: number;
|
|
90
|
+
percent: number;
|
|
91
|
+
label: "Critical" | "High" | "Medium" | "Low" | "Clear";
|
|
92
|
+
}
|
|
93
|
+
type SeverityCounts = Record<Severity, number>;
|
|
94
|
+
interface VulcnReport {
|
|
95
|
+
/** Report format version */
|
|
96
|
+
reportVersion: "2.0";
|
|
97
|
+
/** Engine version that generated the scan */
|
|
98
|
+
engineVersion: string;
|
|
99
|
+
/** ISO timestamp when this report was generated */
|
|
100
|
+
generatedAt: string;
|
|
101
|
+
/** Session metadata */
|
|
102
|
+
session: {
|
|
103
|
+
name: string;
|
|
104
|
+
driver: string;
|
|
105
|
+
driverConfig: Record<string, unknown>;
|
|
106
|
+
stepsCount: number;
|
|
107
|
+
metadata?: Record<string, unknown>;
|
|
108
|
+
};
|
|
109
|
+
/** Execution statistics */
|
|
110
|
+
stats: {
|
|
111
|
+
stepsExecuted: number;
|
|
112
|
+
payloadsTested: number;
|
|
113
|
+
durationMs: number;
|
|
114
|
+
errors: string[];
|
|
115
|
+
};
|
|
116
|
+
/** Summary / overview data */
|
|
117
|
+
summary: {
|
|
118
|
+
totalFindings: number;
|
|
119
|
+
severityCounts: SeverityCounts;
|
|
120
|
+
risk: RiskAssessment;
|
|
121
|
+
vulnerabilityTypes: string[];
|
|
122
|
+
affectedUrls: string[];
|
|
123
|
+
};
|
|
124
|
+
/** Rule registry — one rule per unique finding type */
|
|
125
|
+
rules: ReportRule[];
|
|
126
|
+
/** All findings — enriched with CWE, fingerprints, classification */
|
|
127
|
+
findings: EnrichedFinding[];
|
|
128
|
+
/** Active findings (subset) */
|
|
129
|
+
activeFindings: EnrichedFinding[];
|
|
130
|
+
/** Passive analysis summary */
|
|
131
|
+
passiveAnalysis: PassiveAnalysis;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Build a VulcnReport from raw scan output.
|
|
135
|
+
*
|
|
136
|
+
* This is the single transformation point. All output formats
|
|
137
|
+
* (HTML, JSON, YAML, SARIF) operate on the returned model.
|
|
138
|
+
*/
|
|
139
|
+
declare function buildReport(session: Session, result: RunResult, generatedAt: string, engineVersion: string): VulcnReport;
|
|
3
140
|
|
|
4
141
|
/**
|
|
5
142
|
* HTML Report Generator for Vulcn
|
|
@@ -12,33 +149,25 @@ import { Session, RunResult, Finding, VulcnPlugin } from '@vulcn/engine';
|
|
|
12
149
|
* - Responsive design
|
|
13
150
|
*/
|
|
14
151
|
|
|
15
|
-
|
|
16
|
-
session: Session;
|
|
17
|
-
result: RunResult;
|
|
18
|
-
generatedAt: string;
|
|
19
|
-
engineVersion: string;
|
|
20
|
-
}
|
|
21
|
-
declare function generateHtml(data: HtmlReportData): string;
|
|
152
|
+
declare function generateHtml(report: VulcnReport): string;
|
|
22
153
|
|
|
23
154
|
/**
|
|
24
155
|
* JSON Report Generator for Vulcn
|
|
25
156
|
*
|
|
26
|
-
*
|
|
157
|
+
* Projects the canonical VulcnReport into a clean JSON structure
|
|
158
|
+
* suitable for CI/CD pipelines and programmatic consumption.
|
|
27
159
|
*/
|
|
28
160
|
|
|
161
|
+
/**
|
|
162
|
+
* The JSON output shape — a clean projection of VulcnReport.
|
|
163
|
+
*/
|
|
29
164
|
interface JsonReport {
|
|
30
165
|
vulcn: {
|
|
31
166
|
version: string;
|
|
32
167
|
reportVersion: string;
|
|
33
168
|
generatedAt: string;
|
|
34
169
|
};
|
|
35
|
-
session:
|
|
36
|
-
name: string;
|
|
37
|
-
driver: string;
|
|
38
|
-
driverConfig: Record<string, unknown>;
|
|
39
|
-
stepsCount: number;
|
|
40
|
-
metadata?: Record<string, unknown>;
|
|
41
|
-
};
|
|
170
|
+
session: VulcnReport["session"];
|
|
42
171
|
execution: {
|
|
43
172
|
stepsExecuted: number;
|
|
44
173
|
payloadsTested: number;
|
|
@@ -49,36 +178,47 @@ interface JsonReport {
|
|
|
49
178
|
summary: {
|
|
50
179
|
totalFindings: number;
|
|
51
180
|
riskScore: number;
|
|
52
|
-
|
|
181
|
+
riskLabel: string;
|
|
182
|
+
severityCounts: VulcnReport["summary"]["severityCounts"];
|
|
53
183
|
vulnerabilityTypes: string[];
|
|
54
184
|
affectedUrls: string[];
|
|
55
185
|
};
|
|
56
|
-
findings:
|
|
186
|
+
findings: VulcnReport["findings"];
|
|
187
|
+
passiveAnalysis: {
|
|
188
|
+
totalIssues: number;
|
|
189
|
+
categories: Array<{
|
|
190
|
+
id: string;
|
|
191
|
+
label: string;
|
|
192
|
+
status: string;
|
|
193
|
+
issueCount: number;
|
|
194
|
+
passedChecks: number;
|
|
195
|
+
totalChecks: number;
|
|
196
|
+
remedy: string;
|
|
197
|
+
}>;
|
|
198
|
+
};
|
|
199
|
+
rules: VulcnReport["rules"];
|
|
57
200
|
}
|
|
58
|
-
declare function generateJson(
|
|
201
|
+
declare function generateJson(report: VulcnReport): JsonReport;
|
|
59
202
|
|
|
60
203
|
/**
|
|
61
204
|
* YAML Report Generator for Vulcn
|
|
62
205
|
*
|
|
63
|
-
* Produces a human-readable YAML report.
|
|
206
|
+
* Produces a human-readable YAML report from the canonical VulcnReport.
|
|
64
207
|
*/
|
|
65
208
|
|
|
66
|
-
declare function generateYaml(
|
|
209
|
+
declare function generateYaml(report: VulcnReport): string;
|
|
67
210
|
|
|
68
211
|
/**
|
|
69
212
|
* SARIF Report Generator for Vulcn
|
|
70
213
|
*
|
|
71
|
-
*
|
|
72
|
-
* compatible with GitHub Code Scanning,
|
|
73
|
-
* SARIF-consuming tools.
|
|
214
|
+
* Projects the canonical VulcnReport into SARIF v2.1.0 (Static Analysis
|
|
215
|
+
* Results Interchange Format) compatible with GitHub Code Scanning,
|
|
216
|
+
* Azure DevOps, and other SARIF-consuming tools.
|
|
74
217
|
*
|
|
75
218
|
* @see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
|
|
76
219
|
* @see https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning
|
|
77
220
|
*/
|
|
78
221
|
|
|
79
|
-
/**
|
|
80
|
-
* SARIF v2.1.0 Log — top-level structure
|
|
81
|
-
*/
|
|
82
222
|
interface SarifLog {
|
|
83
223
|
$schema: string;
|
|
84
224
|
version: "2.1.0";
|
|
@@ -165,34 +305,22 @@ interface SarifArtifact {
|
|
|
165
305
|
length?: number;
|
|
166
306
|
}
|
|
167
307
|
/**
|
|
168
|
-
* Generate a SARIF v2.1.0 log from
|
|
308
|
+
* Generate a SARIF v2.1.0 log from a VulcnReport.
|
|
169
309
|
*
|
|
170
310
|
* Usage:
|
|
171
|
-
* const
|
|
311
|
+
* const report = buildReport(session, result, generatedAt, "0.5.0");
|
|
312
|
+
* const sarif = generateSarif(report);
|
|
172
313
|
* await writeFile("vulcn-report.sarif", JSON.stringify(sarif, null, 2));
|
|
173
|
-
*
|
|
174
|
-
* The output can be uploaded to:
|
|
175
|
-
* - GitHub Code Scanning: `gh api /repos/{owner}/{repo}/code-scanning/sarifs`
|
|
176
|
-
* - GitHub Actions: `github/codeql-action/upload-sarif@v3`
|
|
177
|
-
* - Azure DevOps: SARIF SAST Scans Tab extension
|
|
178
|
-
*
|
|
179
|
-
* @param session - The session that was executed
|
|
180
|
-
* @param result - The run result with findings
|
|
181
|
-
* @param generatedAt - ISO timestamp
|
|
182
|
-
* @param engineVersion - Vulcn engine version
|
|
183
314
|
*/
|
|
184
|
-
declare function generateSarif(
|
|
315
|
+
declare function generateSarif(report: VulcnReport): SarifLog;
|
|
185
316
|
|
|
186
317
|
/**
|
|
187
318
|
* @vulcn/plugin-report
|
|
188
319
|
* Report Generation Plugin for Vulcn
|
|
189
320
|
*
|
|
190
321
|
* Generates security reports in HTML, JSON, YAML, and SARIF formats
|
|
191
|
-
* after a run completes.
|
|
192
|
-
*
|
|
193
|
-
* - Machine-readable JSON for CI/CD integration
|
|
194
|
-
* - Human-readable YAML for documentation
|
|
195
|
-
* - SARIF v2.1.0 for GitHub Code Scanning and IDE integration
|
|
322
|
+
* after a run completes. All formats are projections of the canonical
|
|
323
|
+
* VulcnReport model, built once via buildReport().
|
|
196
324
|
*
|
|
197
325
|
* Configuration:
|
|
198
326
|
* format: "html" | "json" | "yaml" | "sarif" | "all" (default: "html")
|
|
@@ -247,4 +375,4 @@ type ReportConfig = z.infer<typeof configSchema>;
|
|
|
247
375
|
*/
|
|
248
376
|
declare const plugin: VulcnPlugin;
|
|
249
377
|
|
|
250
|
-
export { type
|
|
378
|
+
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 };
|