Skip to content

Commit fda154a

Browse files
mfyllmfyll
committed
docs: Add OpenReports file import docs
1 parent 709587e commit fda154a

File tree

2 files changed

+138
-2
lines changed

2 files changed

+138
-2
lines changed

‎docs/content/en/connecting_your_tools/parsers/file/openreports.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: "OpenReports"
3+
toc_hide: true
4+
---
5+
6+
Import vulnerability scan reports formatted as [OpenReports](https://github.com/openreports/reports-api).
7+
8+
OpenReports is a Kubernetes-native reporting framework that aggregates vulnerability scan results and compliance checks from various security tools into a unified format. It provides a standardized API for collecting and reporting security findings across your Kubernetes infrastructure.
9+
10+
### File Types
11+
12+
DefectDojo parser accepts a .json file.
13+
14+
### Exporting Reports from Kubernetes
15+
16+
To export OpenReports from your Kubernetes cluster, use kubectl:
17+
18+
```bash
19+
kubectl get reports -A -ojson > reports.json
20+
```
21+
22+
This command retrieves all Report objects from all namespaces and saves them in JSON format. You can then import the `reports.json` file into DefectDojo.
23+
24+
To export reports from a specific namespace:
25+
26+
```bash
27+
kubectl get reports -n <namespace> -ojson > reports.json
28+
```
29+
30+
### Report Formats
31+
32+
The parser supports multiple input formats:
33+
34+
- Single Report object
35+
- Array of Report objects
36+
- Kubernetes List object containing Report items
37+
38+
### Sample Scan Data
39+
40+
Sample OpenReports scans can be found in the [unittests/scans/openreports directory](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/openreports).
41+
42+
### Supported Fields
43+
44+
The parser extracts the following information from OpenReports JSON:
45+
46+
- **Metadata**: Report name, namespace, UID for stable deduplication
47+
- **Scope**: Kubernetes resource information (kind, name, namespace)
48+
- **Results**: Individual security findings with:
49+
- Message and description
50+
- Policy ID (e.g., CVE identifiers)
51+
- Severity (critical, high, medium, low, info)
52+
- Category (e.g., "vulnerability scan", "compliance check")
53+
- Source scanner information
54+
- Package details (name, installed version, fixed version)
55+
- References and URLs
56+
57+
### Severity Mapping
58+
59+
OpenReports severity levels are mapped to DefectDojo as follows:
60+
61+
| OpenReports Severity | DefectDojo Severity |
62+
|----------------------|---------------------|
63+
| critical | Critical |
64+
| high | High |
65+
| medium | Medium |
66+
| low | Low |
67+
| info | Info |
68+
69+
### Result Status Mapping
70+
71+
The `result` field in OpenReports is mapped to DefectDojo finding status:
72+
73+
| OpenReports Result | Active | Verified | Description |
74+
|--------------------|--------|----------|------------------------------------------------|
75+
| fail | True | True | Finding requires attention |
76+
| warn | True | True | Warning-level finding |
77+
| pass | False | False | Check passed, no vulnerability found |
78+
| skip | False | False | Check was skipped |
79+
80+
### Features
81+
82+
**CVE Tracking**: Findings with CVE policy IDs are automatically tagged with vulnerability identifiers.
83+
84+
**Fix Availability**: The parser automatically sets the `fix_available` flag when a fixed version is provided.
85+
86+
**Service Mapping**: Findings are mapped to services based on Kubernetes scope (namespace/kind/name).
87+
88+
**Stable Deduplication**: Uses report UID from metadata for consistent deduplication across reimports.
89+
90+
**Tagging**: Findings are automatically tagged with category, source scanner, and Kubernetes resource kind.
91+
92+
### Example JSON Format
93+
94+
```json
95+
{
96+
"apiVersion": "openreports.io/v1alpha1",
97+
"kind": "Report",
98+
"metadata": {
99+
"name": "deployment-test-app-630fc",
100+
"namespace": "test",
101+
"uid": "b1fcca57-2efd-44d3-89e9-949e29b61936"
102+
},
103+
"scope": {
104+
"kind": "Deployment",
105+
"name": "test-app"
106+
},
107+
"results": [
108+
{
109+
"category": "vulnerability scan",
110+
"message": "openssl: Out-of-bounds read in HTTP client",
111+
"policy": "CVE-2025-9232",
112+
"properties": {
113+
"fixedVersion": "3.5.4-r0",
114+
"installedVersion": "3.5.2-r1",
115+
"pkgName": "libcrypto3",
116+
"primaryURL": "https://avd.aquasec.com/nvd/cve-2025-9232"
117+
},
118+
"result": "warn",
119+
"severity": "low",
120+
"source": "image-scanner"
121+
}
122+
]
123+
}
124+
```
125+
126+
### Default Deduplication Hashcode Fields
127+
128+
By default, DefectDojo identifies duplicate Findings using these [hashcode fields](https://docs.defectdojo.com/en/working_with_findings/finding_deduplication/about_deduplication/):
129+
130+
- unique_id_from_tool (format: `report_uid:policy:package_name`)
131+
- title
132+
- severity
133+
- vulnerability ids (for CVE findings)
134+
- description
135+
136+
The parser uses the report UID from metadata to create a stable `unique_id_from_tool` that persists across reimports.

‎unittests/tools/test_openreports_parser.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ def test_single_report(self):
3535
self.assertEqual(1, len(finding1.unsaved_vulnerability_ids))
3636
self.assertEqual("CVE-2025-9232", finding1.unsaved_vulnerability_ids[0])
3737
self.assertEqual(
38-
"b1fcca57-2efd-44d3-89e9-949e29b61936:CVE-2025-9232:libcrypto3", finding1.unique_id_from_tool
38+
"b1fcca57-2efd-44d3-89e9-949e29b61936:CVE-2025-9232:libcrypto3", finding1.unique_id_from_tool,
3939
)
4040
self.assertIn("vulnerability scan", finding1.tags)
4141
self.assertIn("image-scanner", finding1.tags)
@@ -72,7 +72,7 @@ def test_single_report(self):
7272
# Non-CVE policies should not have vulnerability IDs
7373
self.assertIsNone(finding3.unsaved_vulnerability_ids)
7474
self.assertEqual(
75-
"b1fcca57-2efd-44d3-89e9-949e29b61936:CIS-BENCH-001:web-server", finding3.unique_id_from_tool
75+
"b1fcca57-2efd-44d3-89e9-949e29b61936:CIS-BENCH-001:web-server", finding3.unique_id_from_tool,
7676
)
7777
self.assertIn("compliance check", finding3.tags)
7878
self.assertIn("compliance-scanner", finding3.tags)

0 commit comments

Comments
 (0)