Reporting
Reports & Compliance
Every completed scan can be pulled back out as SARIF, PDF, Markdown, raw JSON, or a compliance crosswalk. One endpoint, one query param, the same auth as the scan itself. Point it at CI to gate a build, hand a PDF to a stakeholder, or generate an auditor-facing control summary from the same findings.
- Export formats
- 5
- Compliance frameworks
- 6
- API key scope
- scan:read
Overview
VulnRadar stores each scan once and renders reports from it on demand. The in-app export menu on a scan runs the report generators client-side; the same generators are exposed over one HTTP endpoint so a pipeline or a script can fetch the exact same output with a Bearer key. There is no separate "report" object to create or poll: you already have a scan id, so you already have every report.
The endpoint lives under https://vulnradar.dev/api/v3/ like the rest of the v3 API. Pick a format with the format query parameter; the response is a file download, not a JSON envelope, so pipe it to a file or hand it straight to whatever consumes it.
The report endpoint
One GET, authenticated exactly like GET /history/{id}. The format parameter selects the generator; the response headers tell you what came back.
/history/{id}/reportExport a Scan Report
Generate a report over a completed scan in the format you ask for. The generators are the same pure functions the in-app export menu runs client-side; this route exposes them so CI and API consumers can pull a SARIF file, a PDF, a Markdown report, or the compliance crosswalk without a browser. Nothing is stored: the report is built on demand from the scan row.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The opaque scan id GET /history returns, the same id GET /history/{id} takes. The legacy integer id still resolves. |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
format | string | No | json | json (default) | sarif | pdf | md (alias markdown) | compliance | csv |
includeSuppressed | boolean | No | false | Include findings you marked a false positive. Off by default, so the export matches the dashboard. |
applyTriage | boolean | No | false | Emit SARIF suppressions for accepted-risk and won't-fix findings. Off by default, so a CI gate never changes without you asking. |
Response 200 OK
// format=sarif -> Content-Type: application/sarif+json
{
"$schema": "https://.../sarif-schema-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "VulnRadar",
"version": "3.x",
"rules": [ /* one entry per unique check id */ ]
}
},
"results": [
{
"ruleId": "hsts-missing",
"level": "warning",
"message": { "text": "HSTS header missing. Evidence: ..." },
"partialFingerprints": { "vulnradarFindingId": "hsts-missing" },
"properties": { "severity": "medium", "category": "headers" }
}
]
}
]
}Error Responses
Report formats
Six outputs off the one endpoint. md and markdown are the same generator under two names; everything else is distinct.
| format | Content-Type | When to use it |
|---|---|---|
| sarif | application/sarif+json | Upload to GitHub Code Scanning so findings show up as annotated alerts on the Security tab instead of a report nobody opens. |
| application/pdf | A branded, self-contained report to hand to a stakeholder or client who will not open a terminal. | |
| md | text/markdown | Paste into a pull request, an issue, a wiki, or a chat message. Renders as a readable severity-ordered report. |
| compliance | text/markdown | The control crosswalk below, as a Markdown summary for an auditor or GRC reviewer to prioritise remediation. |
| csv | text/csv | One row per finding for a spreadsheet: finding id, severity, affected target, triage status, CWE, OWASP, CVE, CVSS, KEV, EPSS, plus the prose fields. The finding id is what makes two weeks' exports diffable. |
| json | application/json | The raw ScanResult (findings, summary, response headers, metadata) when you would rather parse it yourself. This is the default. |
Access control
The report inherits the scan's access model, so there is nothing new to authorise. A caller who can read the scan can pull any format of its report; a caller who cannot gets the same 404 the scan itself returns.
- Two ways to authenticate: a Bearer API key that holds the
scan:readscope, or the session cookie the web app already has. A key withoutscan:readgets403. - Owner or team read: the scan's owner always has access. A teammate has access when the team's resource-access check grants read on that scan. Anyone else, including a valid key on an unrelated account, gets
404, not403, so the endpoint never confirms a scan exists to someone who cannot see it. - Remediation status is private: the owner's report attaches cross-rescan remediation state to each finding (fixed, still open, and so on). A team-read viewer sees the stored findings as they were captured, without that private layer.
- Both paths are metered: a key request counts against that key's daily rate limit and is recorded as usage, so a
429there means the key is out of quota for the day. A session request is not free either: it draws on a separate per-user report-export bucket and gets its own429with aRetry-Afterwhen you exhaust it. Every format is generated synchronously over the whole findings array, so an unmetered session path was a way to pin the process.
SARIF and CI
SARIF is the format worth wiring up first. The export is SARIF 2.1.0, the JSON schema GitHub Code Scanning consumes natively. Critical and high map to level: error, medium to warning, low and info to note. Each result carries a partialFingerprints.vulnradarFindingId equal to the stable check id, so re-running the scan updates the same alert instead of opening a duplicate. When a finding has a real computed CVSS score it is exported as security-severity; otherwise a per-band default is used.
Fetch a SARIF report with curl
curl -sS "https://vulnradar.dev/api/v3/history/123/report?format=sarif" \
-H "Authorization: Bearer vr_live_YOUR_API_KEY" \
-o vulnradar.sarifUpload it to GitHub Code Scanning
Store the key as a repo secret, fetch the SARIF for a completed scan, then hand it to the official upload action. The findings appear on the Security tab, annotated against the target.
- name: Fetch VulnRadar SARIF
run: |
curl -sS "https://vulnradar.dev/api/v3/history/${{ needs.scan.outputs.scan-id }}/report?format=sarif" \
-H "Authorization: Bearer ${{ secrets.VULNRADAR_TOKEN }}" \
-o vulnradar.sarif
- name: Upload to code scanning
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: vulnradar.sarifImport into DefectDojo or Faraday
The same SARIF file imports into the two open-source vulnerability managers without any VulnRadar-specific plumbing. DefectDojo parses it under the built-in SARIF scan type, so findings land beside whatever else you already aggregate there. Point DD_URL at your instance and use an API v2 token.
curl -sS "https://vulnradar.dev/api/v3/history/123/report?format=sarif" \
-H "Authorization: Bearer vr_live_YOUR_API_KEY" \
-o vulnradar.sarif
curl -sS -X POST "$DD_URL/api/v2/import-scan/" \
-H "Authorization: Token $DD_TOKEN" \
-F "scan_type=SARIF" \
-F "engagement=$DD_ENGAGEMENT_ID" \
-F "[email protected]"Faraday reads SARIF too, through faraday-cli: faraday-cli tool report vulnradar.sarif --plugin-id sarif. Use --workspace to pick the target workspace.
Compliance crosswalk
The compliance format expresses each finding as the framework controls it touches, so an engineer or a GRC reviewer can see "these findings are relevant to PCI requirement 6.2.4" without hand-mapping every result. The output is Markdown: a disclaimer, an overview, one section per framework grouped by control, an explicit list of findings that did not map to anything, and a short note on how the mapping is derived.
Frameworks covered
| Framework | References | What a mapping means |
|---|---|---|
| PCI DSS 4.0 | Requirement numbers (e.g. 6.2.4, 4.2.1) | The requirements a finding is relevant to, not an assessed pass or fail. |
| SOC 2 (Trust Services Criteria) | 2017 Common Criteria, CC series (e.g. CC6.1) | The Common Criteria a Type II audit would gather evidence against. |
| ISO/IEC 27001:2022 (Annex A) | Annex A controls (e.g. A.8.28) | The finding is in scope for that control, not that the control is implemented or broken. |
| OWASP ASVS 4.0 | Verification chapters V1 to V14 (e.g. V5) | The verification requirements that cover this class of finding. |
| HIPAA Security Rule | 45 CFR Part 164 safeguards (e.g. 164.312(e)(1)) | The technical or administrative safeguard a finding touches. An external scan cannot judge policies, BAAs, or physical safeguards. |
| GDPR (Art. 32) | Security-of-processing articles (e.g. 32(1)(a)) | The security obligation a finding touches, not lawful basis or data-subject rights. |
How a finding resolves to controls
Every finding is routed through its OWASP Top 10 (2021) category first, then to the controls each framework uses to govern that class of weakness. That routing is the vetted backbone; the frameworks all hang off it.
- If the check tagged the finding with an OWASP category, that tag is used.
- Its CWE id, if present, is run through a CWE to OWASP crosswalk. Both the tag and the CWE can contribute, and the resulting categories are deduplicated.
- Only if neither yields a category does a coarse scanner-category fallback apply (for example
headersandcookiesto A05 Security Misconfiguration). - Each resolved OWASP category expands to its PCI, SOC 2, ISO 27001, ASVS, HIPAA, and GDPR control references, deduplicated across every category the finding matched.
A finding that resolves to no category is not dropped: it lands in the report's Unmapped findings section. DNS, email, and reputation findings live there by design, because those classes do not map cleanly onto these web-application frameworks and force-fitting them would be dishonest.
Fetch the compliance report
curl -sS "https://vulnradar.dev/api/v3/history/123/report?format=compliance" \
-H "Authorization: Bearer vr_live_YOUR_API_KEY" \
-o vulnradar-compliance.mdWhat the crosswalk is not
- A scan observes a target from the outside. It cannot see your policies, processes, evidence, or audit scope, and those are what a real assessment evaluates.
- A mapping to a control means a finding is in scope for it, never that the control passed or failed.
- Certification or attestation has to come from a qualified assessor: a PCI QSA, a licensed CPA firm for SOC 2, or an accredited ISO 27001 certification body.
- HIPAA and GDPR mappings only reach the technical safeguard and security-of-processing parts of those regimes, never their policy, process, or data-subject-rights scope.