Skip to content

Commit 7f62a67

Browse files
skywalke34skywalke34
committed
docs: Update DrHeader parser documentation
1 parent d56960d commit 7f62a67

1 file changed

Lines changed: 176 additions & 6 deletions

File tree

‎docs/content/supported_tools/parsers/file/drheader.md‎

Lines changed: 176 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,185 @@
11
---
2-
title: "DrHeader"
2+
title: "DrHeader JSON Importer"
33
toc_hide: true
44
---
5-
Import of JSON report from
6-
<https://github.com/Santandersecurityresearch/DrHeader>
75

8-
### Sample Scan Data
9-
Sample DrHeader scans can be found [here](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/drheader).
6+
# DrHeader JSON Importer Parser Documentation
7+
8+
The [DrHeader](https://github.com/Santandersecurityresearch/DrHeader) parser for DefectDojo supports imports from JSON format exports. This document details the parsing of DrHeader security header analysis reports into DefectDojo field mappings, unmapped fields, and location of each field's parsing code for easier troubleshooting and analysis.
9+
10+
## Supported File Types
11+
12+
The DrHeader JSON Importer parser accepts JSON file format. DrHeader is a runtime HTTP header security scanner that analyzes security headers in web application responses. The parser supports two JSON structures:
13+
14+
1. **Structured format**: Array of objects with `url` and `report` fields
15+
2. **Flat format**: Direct array of findings without URL grouping
16+
17+
To generate a DrHeader JSON report, run:
18+
```bash
19+
drheader scan single https://example.com --json --output report.json
20+
```
21+
22+
## Default Deduplication Hashcode Fields
1023

11-
### Default Deduplication Hashcode Fields
1224
By default, DefectDojo identifies duplicate Findings using these [hashcode fields](https://docs.defectdojo.com/en/working_with_findings/finding_deduplication/about_deduplication/):
1325

1426
- title
1527
- description
28+
29+
The parser does not set `unique_id_from_tool`, so DefectDojo generates a hash code based on the finding's attributes for deduplication purposes.
30+
31+
## Sample Scan Data
32+
33+
Sample DrHeader scans can be found in the [sample scan data folder](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/drheader).
34+
35+
## Link To Tool
36+
37+
- [DrHeader](https://github.com/Santandersecurityresearch/DrHeader)
38+
- [DrHeader Documentation](https://github.com/Santandersecurityresearch/DrHeader/blob/master/README.md)
39+
40+
## DrHeader JSON Format (DrHeaderParser)
41+
42+
### Total Fields in DrHeader JSON Format
43+
44+
- Total data fields: 7
45+
- Total data fields parsed: 6
46+
- Total data fields NOT parsed: 1
47+
48+
### DrHeader JSON Format Field Mapping Details
49+
50+
<details>
51+
<summary>Click to expand Field Mapping Table</summary>
52+
53+
| Scanner Field Name | DefectDojo Field | Parser Line # | Notes |
54+
| ------------------- | ------------------- | ------------------- | ------------------- |
55+
| url | unsaved_endpoints | 48 | Converted to Endpoint object using `Endpoint.from_uri()` |
56+
| rule | title | 23 | Prepended with "Header : " prefix |
57+
| message | description | 24-25 | First component of description, concatenated with URL |
58+
| severity | severity | 33 | Converted to title case using `.title()` method (e.g., "high" → "High") |
59+
| expected | description | 27-32 | Appended to description as "Expected values: " followed by semicolon-separated list |
60+
| value | description | 26 | Appended to description as "Observed values: " if present |
61+
62+
</details>
63+
64+
### Additional Finding Field Settings (DrHeader JSON Format)
65+
66+
<details>
67+
<summary>Click to expand Additional Settings Table</summary>
68+
69+
| Finding Field | Default Value | Parser Line # | Notes |
70+
|---------------|---------------|---------------|-------|
71+
| static_finding | False | 37 | All findings explicitly marked as dynamic (runtime scanner) |
72+
| active | True | N/A | DefectDojo Finding model default |
73+
| verified | False | N/A | DefectDojo Finding model default |
74+
| false_p | False | N/A | DefectDojo Finding model default |
75+
| test | test object | 34, 47, 50 | All findings associated with the test object passed to `get_findings()` |
76+
77+
</details>
78+
79+
### Fields Not Parsed
80+
81+
The following fields are present in DrHeader exports but are not currently parsed:
82+
83+
- **delimiter**: Present in scanner export (e.g., ";" for X-XSS-Protection) but not referenced in parser code
84+
85+
## Special Processing Notes
86+
87+
<details>
88+
<summary>Click to expand Special Processing Details</summary>
89+
90+
### Date Processing
91+
92+
No date processing is performed. DrHeader does not include timestamp information in its JSON output.
93+
94+
### Status Conversion
95+
96+
No explicit status conversion is performed. All findings are created with default DefectDojo Finding status values:
97+
- `active=True` (default)
98+
- `verified=False` (default)
99+
- `false_p=False` (default)
100+
101+
These are set by DefectDojo's Finding model defaults, not explicitly in the parser.
102+
103+
### Severity Conversion
104+
105+
**Line 33**: Direct mapping with title case transformation:
106+
- Scanner values: `"high"`, `"medium"`, `"low"` (lowercase strings)
107+
- DefectDojo values: `"High"`, `"Medium"`, `"Low"` (title case)
108+
- Transformation: `finding["severity"].title()`
109+
110+
No numerical severity conversion is performed - DefectDojo automatically assigns numerical severity based on the categorical value.
111+
112+
### Description Construction
113+
114+
**Lines 24-32**: The description field is built by concatenating multiple components in this order:
115+
116+
1. **Base message** (line 24): `finding["message"]`
117+
2. **URL** (line 24): Appended as `"\nURL : " + url` if URL is present
118+
3. **Observed values** (lines 25-26): If `value` field exists, appended as `"\nObserved values: " + finding["value"]`
119+
4. **Expected values** (lines 27-32): If `expected` array exists, appended as `"\nExpected values: "` followed by semicolon-separated list of expected values
120+
121+
**Example construction:**
122+
```
123+
Header not included in response
124+
URL : https://example.com
125+
Expected values: DENY; SAMEORIGIN
126+
```
127+
128+
The `expected` array is processed with special formatting:
129+
- Values are joined with `"; "` separator
130+
- Last value has no trailing separator (checked with `if expect == finding["expected"][-1]`)
131+
- This creates a semicolon-separated list in the description
132+
133+
### Title Format
134+
135+
**Line 23**: Title is constructed by prepending "Header : " to the rule name:
136+
- Format: `"Header : " + finding["rule"]`
137+
- Example: `"Header : Content-Security-Policy"`
138+
139+
### Mitigation Construction
140+
141+
No mitigation field is populated by the parser. DrHeader does not provide remediation guidance in its JSON output.
142+
143+
### Deduplication
144+
145+
The parser does not set `unique_id_from_tool`. DefectDojo will generate a hash code based on the finding's attributes (title, description, severity, etc.) for deduplication purposes.
146+
147+
### Static vs Dynamic Finding Classification
148+
149+
**Line 37**: All findings are explicitly marked as dynamic:
150+
- `static_finding=False`
151+
152+
This is appropriate for DrHeader, which is a runtime HTTP header security scanner that analyzes live HTTP responses.
153+
154+
### Endpoint Creation
155+
156+
**Lines 48-49**: Endpoints are created conditionally:
157+
- If `url` field is present in the top-level object, an Endpoint is created using `Endpoint.from_uri(url)`
158+
- The endpoint is stored in `unsaved_endpoints` array
159+
- If no URL is present, no endpoint is attached to the finding
160+
161+
### Conditional Processing Logic
162+
163+
**Lines 43-50**: The parser handles two different JSON structures:
164+
165+
1. **Structured format** (lines 45-47): Array of objects with `url` and `report` fields
166+
- Checks if `data[0].get("url")` is not None
167+
- Iterates through each URL's report array
168+
- Passes URL to `return_finding()` for endpoint creation
169+
170+
2. **Flat format** (line 50): Direct array of findings without URL grouping
171+
- Falls back if structured format not detected
172+
- Processes findings without URL/endpoint information
173+
174+
### Error Handling
175+
176+
**Lines 40-42**: The parser includes basic error handling for invalid JSON:
177+
```python
178+
try:
179+
data = json.load(filename)
180+
except ValueError:
181+
data = {}
182+
```
183+
If JSON parsing fails, an empty dictionary is returned, resulting in no findings.
184+
185+
</details>

0 commit comments

Comments
 (0)