Skip to content

Commit 096b584

Browse files
skywalke34skywalke34
committed
docs(parser): add Alert Logic parser documentation
Documents the Alert Logic CSV parser including: - File-export workflow from the Alert Logic console - Default deduplication strategy (unique_id_from_tool + hashcode fallback) - Complete 26-column field mapping table (expandable) - Additional Finding field settings (static/dynamic flags, active default) - Special processing notes covering severity conversion, title truncation, description construction, endpoint multi-IP / IPv6 / port-zero handling, deduplication algorithm, CVE handling, CISA Known Exploited tagging, and UTF-8 BOM + multi-line field handling Authored by T. Walker - DefectDojo
1 parent 21af7db commit 096b584

1 file changed

Lines changed: 135 additions & 0 deletions

File tree

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: "Alert Logic"
3+
toc_hide: true
4+
---
5+
6+
The [Alert Logic](https://www.alertlogic.com/) parser for DefectDojo supports imports from CSV format. This document details the parsing of Alert Logic vulnerability scan exports into DefectDojo field mappings, unmapped fields, and transformation notes for easier troubleshooting and analysis.
7+
8+
## Supported File Types
9+
10+
The Alert Logic parser accepts CSV file format. To generate this file from Alert Logic:
11+
12+
1. Log into the Alert Logic console
13+
2. Navigate to **Validate → Vulnerabilities** (or the equivalent vulnerability listing view)
14+
3. Apply the filters you want included in the export
15+
4. Export the filtered vulnerability list as CSV
16+
5. Save the file with a `.csv` extension
17+
6. Upload to DefectDojo using the "Alert Logic Scan" scan type
18+
19+
The parser handles UTF-8 with byte-order mark (BOM) and multi-line quoted fields commonly present in Description, Evidence, and Resolution columns.
20+
21+
## Default Deduplication Hashcode Fields
22+
23+
Alert Logic provides a stable native vulnerability identifier in the `Vulnerability ID` column. DefectDojo uses it as `unique_id_from_tool` with hashcode fields as a fallback:
24+
25+
- title
26+
- component_name
27+
- vuln_id_from_tool
28+
29+
### Sample Scan Data
30+
31+
Sample Alert Logic scans can be found in the [sample scan data folder](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/alertlogic).
32+
33+
## Link To Tool
34+
35+
- [Alert Logic](https://www.alertlogic.com/)
36+
- [Alert Logic Documentation](https://docs.alertlogic.com/)
37+
38+
## CSV Format
39+
40+
### Total Fields in CSV
41+
42+
- Total data fields: 26
43+
- Total data fields parsed: 26
44+
- Total data fields NOT parsed: 0
45+
46+
### CSV Format Field Mapping Details
47+
48+
<details>
49+
<summary>Click to expand Field Mapping Table</summary>
50+
51+
| Source Field | DefectDojo Field | Notes |
52+
| ----------------------- | --------------------------- | ------------------------------------------------------------------------------ |
53+
| Vulnerability | title | Truncated to 500 characters with "..." suffix if longer |
54+
| Severity | severity | Direct one-to-one mapping (Info / Low / Medium / High / Critical) |
55+
| CVSS Score | cvssv3_score | Parsed as float; empty values produce no score |
56+
| Asset Name | component_name | The affected host or service from the scan |
57+
| IP Address | unsaved_endpoints | Comma-separated IPv4 / IPv6 list; each value becomes a separate endpoint |
58+
| Protocol/Port | unsaved_endpoints | Parsed as `PROTOCOL/PORT`; a port of 0 is omitted |
59+
| CVE | unsaved_vulnerability_ids | Single CVE identifier when present |
60+
| Resolution | mitigation | Direct copy, including multi-line content |
61+
| Vulnerability ID | unique_id_from_tool | Alert Logic's stable native vulnerability identifier (used for deduplication) |
62+
| Description | description | Included in structured description block |
63+
| Evidence | description | Included in structured description block |
64+
| Operating System | description | Included in structured description block (CPE strings preserved) |
65+
| Vulnerability Span ID | description | Included in structured description block |
66+
| Vulnerability Key | description | Included in structured description block |
67+
| Asset Key | description | Included in structured description block |
68+
| Asset Type | description | Included in structured description block |
69+
| Service | description | Included in structured description block |
70+
| Category | description | Included in structured description block |
71+
| VPC/Network | description | Included in structured description block |
72+
| Deployment Name | description | Included in structured description block |
73+
| Customer Account | description | Included in structured description block |
74+
| First Seen | description | Included in structured description block |
75+
| Last Scanned | description | Included in structured description block |
76+
| Published Date | description | Included in structured description block |
77+
| Age (days) | description | Included in structured description block |
78+
| CISA Known Exploited | description, unsaved_tags | Added as `cisa-known-exploited` tag when value is "Yes" |
79+
80+
</details>
81+
82+
### Additional Finding Field Settings (CSV Format)
83+
84+
<details>
85+
<summary>Click to expand Additional Settings Table</summary>
86+
87+
| Finding Field | Default Value | Notes |
88+
| ---------------- | ------------- | ----------------------------------------------------------- |
89+
| static_finding | True | Alert Logic is an infrastructure vulnerability scanner |
90+
| dynamic_finding | False | Alert Logic is an infrastructure vulnerability scanner |
91+
| active | True | Alert Logic exports do not carry a mitigation status column |
92+
93+
</details>
94+
95+
## Special Processing Notes
96+
97+
### Severity Conversion
98+
99+
Alert Logic uses a five-level severity scale that aligns one-to-one with DefectDojo severity levels:
100+
101+
- `Critical` → Critical
102+
- `High` → High
103+
- `Medium` → Medium
104+
- `Low` → Low
105+
- `Info` → Info
106+
107+
Any unrecognized severity value defaults to Info.
108+
109+
### Title Format
110+
111+
Finding titles are derived from the "Vulnerability" column. Titles longer than 500 characters are truncated to 497 characters with a "..." suffix appended. Shorter titles are used as-is without modification.
112+
113+
### Description Construction
114+
115+
The parser constructs a structured markdown description containing all relevant CSV fields not already mapped to dedicated Finding columns. Each field is rendered as `**Label:** value` with blank lines between entries. Fields are included only when they contain a non-empty value, so the description stays tight for sparsely populated rows.
116+
117+
### Endpoint Construction
118+
119+
The "IP Address" column may contain one or more comma-separated IP addresses, mixing IPv4 and IPv6 (for example: `198.51.100.30, fe80::250:56ff:fe96:b97`). Each address becomes a separate endpoint. The "Protocol/Port" column is parsed as `PROTOCOL/PORT` (e.g., `TCP/443`); when the port is `0` the value is treated as "no specific port" and omitted from the endpoint. All endpoints are validated via `endpoint.clean()` before being attached to the finding.
120+
121+
### Deduplication
122+
123+
Alert Logic exports include a stable per-vulnerability identifier in the "Vulnerability ID" column. DefectDojo uses this as `unique_id_from_tool` and the deduplication algorithm `DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL_OR_HASH_CODE`. When the ID is missing (some scan exports omit it for non-vulnerability findings), DefectDojo falls back to the hashcode algorithm using `title`, `component_name`, and `vuln_id_from_tool` (the CVE) as the stable fields.
124+
125+
### CVE Handling
126+
127+
The "CVE" column carries a single CVE identifier or is empty. When present it is attached to the finding via `unsaved_vulnerability_ids`; when absent no CVE is set.
128+
129+
### CISA Known Exploited Tagging
130+
131+
When the "CISA Known Exploited" column equals "Yes", the finding receives a `cisa-known-exploited` tag. This makes it straightforward to filter, route, or escalate findings already known to be exploited in the wild.
132+
133+
### BOM and Multi-Line Field Handling
134+
135+
Alert Logic exports start with a UTF-8 byte-order mark (`\xef\xbb\xbf`). The parser uses `utf-8-sig` decoding to strip the BOM transparently. Description, Evidence, and Resolution columns frequently contain multi-line content (separated by `\r\n` inside the quoted field); these newlines are preserved in the resulting `description` and `mitigation` Finding fields.

0 commit comments

Comments
 (0)