Write and review DefectDojo parsers
A parser ingests a security tool's scan report and returns unsaved Finding objects.
Parsers live at dojo/tools/<parser_dir>/parser.py and are auto-discovered by
dojo/tools/factory.py — there is no central list to edit. This skill is both an authoring
guide and a reviewer checklist; the two share the same rules, most of which are enforced by
the meta-test unittests/test_parsers.py (so violating them fails CI).
Canonical references in-repo:
docs/content/get_started/contributing/how-to-write-a-parser.md — the authoritative guide.
docs/content/get_started/contributing/parser-documentation-template.md — docs template.
unittests/test_parsers.py — the meta-test that enforces layout/docs.
dojo/tools/factory.py — discovery/registration.
dojo/tools/acunetix/parser.py — a clean, well-documented reference parser.
dojo/tools/picus/parser.py, dojo/tools/alertlogic/parser.py — clean CSV parsers with a
SEVERITY_MAPPING that defaults unknown values to Info.
Inputs
- A new parser to write (the scanner name and a sample report), or
- A parser PR / directory to review (parser dir name, e.g.
acunetix).
Helper script
new-parser-checklist.sh <parser_dir> (in this skill directory) mirrors the CI meta-test
locally: given a parser directory name it checks that the required files exist —
dojo/tools/<dir>/parser.py, unittests/tools/test_<dir>_parser.py,
unittests/scans/<dir>/, and the docs page (docs/content/supported_tools/parsers/file/<dir>.md,
or .../api/<name>.md for an api_<name> dir) — validates the docs front-matter
(title:, toc_hide: true, and for file parsers ### Sample Scan Data + the scans link),
and flags common code smells (lxml import, .read() without utf-8). Run
./run-unittest.sh --test-case unittests.test_parsers for the real, authoritative check.
Required layout (meta-test enforced)
| Artifact |
Path |
| Package init (empty) |
dojo/tools/<dir>/__init__.py |
| Parser code |
dojo/tools/<dir>/parser.py |
| Sample scans dir |
unittests/scans/<dir>/ |
| Unit test (exact name) |
unittests/tools/test_<dir>_parser.py |
| Docs (file parser) |
docs/content/supported_tools/parsers/file/<dir>.md |
| Docs (API parser) |
docs/content/supported_tools/parsers/api/<name>.md (dir is api_<name>) |
| Dedup/hashcode config |
dojo/settings/settings.dist.py |
Authoring rules
Factory contract. The class name is the directory name with underscores removed +
Parser (module dependency_check → DependencyCheckParser). It must have an empty
constructor and implement exactly:
get_scan_types(self) → list of scan-type strings
get_label_for_scan_types(self, scan_type) → short UI label
get_description_for_scan_types(self, scan_type) → long UI description
get_findings(self, file, test) → list of unsaved Finding objects
Add set_mode(self, mode) only if the parser exposes more than one scan type (e.g. a
"... detailed" variant). Store no per-scan state on the instance — the factory reuses
one instance across all imports, so instance/class attributes leak between scans (this has
caused real bugs; reset any state inside get_findings). The same leak happens within a
single call when loop-local variables (gem_name, severity, a title, etc.) are only
partially reset between records — a record missing an optional field then inherits the
previous record's value. Reset every per-record variable to None at the top of each
iteration, and build the finding only from fields actually present.
Robust get_findings. Guard every optional field: data.get("k"), if "k" in data,
and data.get("list") or [] (guards null). An unhandled KeyError becomes a 500 on
import. Do not fill missing fields with placeholder junk like "NA" — leave the
attribute unset. On a garbled or wrong-format file, raise ValueError with a hint
rather than silently importing zero findings (a legitimately empty report is fine and
should log an INFO line, not raise).
Severity. Valid severities are exactly Info / Low / Medium / High / Critical
(Finding.SEVERITIES). Map vendor values through a dict with a default:
SEVERITY_MAPPING.get(raw, "Info") (map synonyms like Informational → Info). Two distinct
default cases — keep them straight:
- A value was present but unmapped (a synonym you didn't handle fell through) → default
to
Info, and consider it a mapping gap to fix.
- The report carries no severity at all for this tool → a documented non-
Info default
(e.g. Medium) can be reasonable, but it must be called out in the parser's docs page.
An undocumented Medium default is a review finding.
Do not hand-roll a CVSS-score→severity ladder — use from dojo.utils import parse_cvss_data
(returns severity, cvssv3, cvssv4, major_version) or the cvss module.
XML uses defusedxml, never lxml or stdlib ElementTree. PRs with lxml are rejected
outright (XXE risk).
Endpoints / URLs. Never hand-parse URLs. Use Endpoint.from_uri(...) (or the
hyperlink module if unavoidable) and assign to finding.unsaved_endpoints.
Encoding. Any .read() in parser code must specify utf-8 within a few lines
(.read().decode("utf-8") or encoding="utf-8") — the meta-test fails otherwise.
Deduplication (the single most common review miss)
Register the parser's dedup behavior in dojo/settings/settings.dist.py. Forgetting this is
the most frequent maintainer callout on parser PRs — without it the parser silently falls
back to the legacy algorithm. Two blocks must agree:
DEDUPLICATION_ALGORITHM_PER_PARSER — map the scan type to one of DEDUPE_ALGO_HASH_CODE,
DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL, or DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL_OR_HASH_CODE.
HASHCODE_FIELDS_PER_SCANNER — the list of Finding fields the hash is computed from
(required whenever the algorithm uses HASH_CODE).
Every scan type the parser returns from get_scan_types() needs its own dedup entries —
the config is keyed by scan-type string, so a parser that emits two aliases (e.g. a friendly
name and a legacy one) must register both, or the unregistered alias silently falls back to
legacy dedup. Prefer emitting a single scan type unless there's a real reason for more.
Rules that recur in review:
unique_id_from_tool / vuln_id_from_tool must come verbatim from the report — never a
value the parser computes or derives. They must be unique per finding and stable across
scans. If a stable id exists, prefer deduping on it directly rather than hashing it.
- Keep
severity out of the hash unless it is provably stable across scans (it usually
isn't — it drifts as occurrences change).
Dedup changes to existing data (close the open loop)
Any change that alters the dedup key for an existing scan type is a data-migration
concern, not just a code change — treat it as a release-gating review item. The dedup key
changes when a PR touches HASHCODE_FIELDS_PER_SCANNER, DEDUPLICATION_ALGORITHM_PER_PARSER,
how unique_id_from_tool/vuln_id_from_tool is populated, or any parser field that feeds the
hash (title, component, file_path, line, etc.). Also flag parser output changes that shift
those fields even when the config is untouched.
Why it matters for customers with existing data: hash_code is computed once at import and
stored on the Finding row — it is not recomputed retroactively. So after the change, old
findings keep their old key and new imports compute a different one. Two concrete failures:
- Duplicates instead of dedup — the next scan's findings no longer match the stored ones,
so they import as brand-new findings.
- The close/reopen loop breaks — reimport closes findings absent from the new report and
reopens ones that return, by matching on the dedup key. When the key shifts, reimport can
fail to mitigate findings that were actually fixed, or reopen findings that were already
closed — noisy and alarming for users.
What the PR (and your review) must ensure:
- Call it out explicitly in the PR description and the release note — this is a behavior
change for existing data, not a silent internal tweak.
- Provide the recompute path. Existing rows need
hash_code recomputed and dedup re-run:
python manage.py dedupe --parser "<Scan Type>" --hash_code_only (recompute only), then
--dedupe_only (re-run dedup), or the full manage.py dedupe. Note this is heavy on large
instances (mass update over all findings for the scan type, async by default) — it's ops
guidance for the customer, not something the import path does automatically.
- Validate the config with
python manage.py validatededupeconfig.
- Prefer additive / opt-in. Reopening a customer's closed findings on upgrade is a strong
reason to reject or redesign; favor changes that don't retroactively alter the key, or that
ship with a clear recompute runbook.
Unit-test strategy
- Minimum three sample files:
no_vuln, one_vuln, many_vulns (correct extension),
with matching test methods. Assert the empty file yields 0 findings and the multi file the
exact count.
- Assert concrete attributes, not just counts — for representative findings check
title,
severity (assertIn(finding.severity, Finding.SEVERITIES)), active/verified/
duplicate, unique_id_from_tool/vuln_id_from_tool, cwe, CVSS fields,
vulnerability_ids, dates, tags. Wrap per-finding checks in with self.subTest(...).
- Open sample files with the
with ... .open(encoding="utf-8") pattern, using
get_unit_tests_scans_path("<dir>") / "one_vuln.json" from unittests/dojo_test_case.py.
Subclass DojoTestCase.
- Endpoint parsers: call
endpoint.clean() on every finding.unsaved_endpoints in a test
to prove RFC-valid endpoints.
- API parsers: also add
unittests/tools/test_api_<name>_importer.py and mock the API with
unittest.mock.patch.
- Regression fixtures: when fixing a specific bug, add a small targeted sample named
issue_<number>.<ext> (the repo-wide convention) rather than bloating an existing file.
- Run:
./run-unittest.sh --test-case unittests.tools.test_<dir>_parser.<TestClass>.
Sample-file rules (sanitization & size)
- Sanitize sample scans. Strip real IPs, hostnames, tokens/credentials, customer names,
and other PII — use
example.com / obviously fabricated data. (This is a strong convention
the maintainers hold; it is not written as a numeric rule in the repo, so apply judgment and
call it out explicitly in review.)
- Keep the set minimal.
no_vuln / one_vuln / many_vulns is the baseline; add small,
targeted cases for specific edge conditions instead of committing large real-world dumps.
There is no hard committed-fixture size cap, but the runtime upload limit is
DD_SCAN_FILE_MAX_SIZE (default 100 MB) — samples should be far smaller. Prefer the
smallest report that still exercises the behavior.
Documentation (meta-test enforced)
The docs page must exist at the path above and contain front-matter title: and
toc_hide: true. File parsers must also include a ### Sample Scan Data heading and a
link to https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans. Follow
parser-documentation-template.md (file types + how to export, field mapping, dedup handling,
default severity, sample link). Do not put source-code line numbers in the field-mapping
table — they drift and get rejected in review.
Reviewer checklist (highest-frequency issues)
- Dedup registered in
settings.dist.py — both the algorithm map and (for hashcode)
HASHCODE_FIELDS_PER_SCANNER?
unique_id_from_tool taken verbatim from the report, not computed?
severity excluded from the hash unless provably stable?
- Dedup-key change on an existing scan type? If the PR shifts
HASHCODE_FIELDS_PER_SCANNER,
the algorithm, unique_id_from_tool, or a hashed field, is there a recompute/reimport
runbook (manage.py dedupe) and a release note? Existing findings won't recompute
hash_code automatically, so imports can duplicate and the close/reopen loop can break.
- Unrecognized file raises, doesn't silently import 0 findings?
- 0 / 1 / many sample files + attribute-level assertions, opened with
with?
- Sample files sanitized and minimal (no real IPs/hosts/tokens/customers; no giant dumps)?
- Docs page present with
title:, toc_hide: true, ### Sample Scan Data + scans link,
and no source line numbers?
- Ruff clean; utf-8 after
.read(); defusedxml (no lxml); Endpoint.from_uri()?
- No leaked state — no per-instance attributes across imports, and per-record loop
variables fully reset each iteration (a record missing an optional field must not inherit
the previous record's value)?
PR hygiene (parser PRs specifically)
- Keep the diff to the parser's own files. A parser PR should touch
dojo/tools/<dir>/,
its test + samples, its docs page, and (for dedup) settings.dist.py — nothing else. Flag
unrelated edits riding along, especially requirements.txt / dependency bumps; ask for them
to be split out.
- Screen the PR description. Community parser PRs sometimes carry vendor marketing or paid-
service links in the body. Flag promotional content for a maintainer — it's not a code defect
but the project cares about it.
- Trust green Actions + the real diff, not bot noise. The authoritative signals are the
green GitHub Actions checks and the actual
gh pr diff (base...head). Third-party bot walls
(e.g. DryRun "sensitive codepath modified") are advisory and are routinely dismissed by
maintainers as false positives — don't treat them as blockers; verify against the real diff.
Notes
- New parser = a feature → targets
dev; a parser bugfix targets bugfix. Label the PR
Import Scans. Defer to AGENTS.md for the branch/milestone policy.
- New API parsers from the community are currently not accepted (supportability) — flag
this in review of an inbound API parser.
- A scaffolding template exists:
https://github.com/DefectDojo/cookiecutter-scanner-parser.
- Common meta-test exemptions (shared/common modules) are hard-coded in
unittests/test_parsers.py (e.g. wizcli_common_parsers, sysdig_common,
checkmarx_osa) — a genuinely new parser is not one of these.
1---2name: defectdojo-parser3description: Author and review DefectDojo parsers (scan-report importers under dojo/tools/<name>/parser.py) to the project's real conventions — the factory contract, required Finding fields, deduplication registration in settings.dist.py, defusedxml/utf-8/Endpoint.from_uri rules, the 0/1/many unit-test set with attribute-level assertions, sample-file sanitization and size discipline, and the CI meta-test (unittests/test_parsers.py) that enforces the directory/docs layout. Use when writing a new parser, adding a scan type, reviewing a parser PR, or debugging a failing parser/test_parsers test.4metadata:5 source: https://skillmd.com/skills/defectdojo/defectdojo-parser6---78# Write and review DefectDojo parsers910A parser ingests a security tool's scan report and returns unsaved `Finding` objects.11Parsers live at `dojo/tools/<parser_dir>/parser.py` and are **auto-discovered** by12`dojo/tools/factory.py` — there is no central list to edit. This skill is both an authoring13guide and a reviewer checklist; the two share the same rules, most of which are enforced by14the meta-test `unittests/test_parsers.py` (so violating them fails CI).1516Canonical references in-repo:17- `docs/content/get_started/contributing/how-to-write-a-parser.md` — the authoritative guide.18- `docs/content/get_started/contributing/parser-documentation-template.md` — docs template.19- `unittests/test_parsers.py` — the meta-test that enforces layout/docs.20- `dojo/tools/factory.py` — discovery/registration.21- `dojo/tools/acunetix/parser.py` — a clean, well-documented reference parser.22- `dojo/tools/picus/parser.py`, `dojo/tools/alertlogic/parser.py` — clean CSV parsers with a23 `SEVERITY_MAPPING` that defaults unknown values to `Info`.2425## Inputs2627- **A new parser to write** (the scanner name and a sample report), **or**28- **A parser PR / directory to review** (parser dir name, e.g. `acunetix`).2930## Helper script3132`new-parser-checklist.sh <parser_dir>` (in this skill directory) mirrors the CI meta-test33locally: given a parser directory name it checks that the required files exist —34`dojo/tools/<dir>/parser.py`, `unittests/tools/test_<dir>_parser.py`,35`unittests/scans/<dir>/`, and the docs page (`docs/content/supported_tools/parsers/file/<dir>.md`,36or `.../api/<name>.md` for an `api_<name>` dir) — validates the docs front-matter37(`title:`, `toc_hide: true`, and for file parsers `### Sample Scan Data` + the scans link),38and flags common code smells (`lxml` import, `.read()` without utf-8). Run39`./run-unittest.sh --test-case unittests.test_parsers` for the real, authoritative check.4041## Required layout (meta-test enforced)4243| Artifact | Path |44|---|---|45| Package init (empty) | `dojo/tools/<dir>/__init__.py` |46| Parser code | `dojo/tools/<dir>/parser.py` |47| Sample scans dir | `unittests/scans/<dir>/` |48| Unit test (exact name) | `unittests/tools/test_<dir>_parser.py` |49| Docs (file parser) | `docs/content/supported_tools/parsers/file/<dir>.md` |50| Docs (API parser) | `docs/content/supported_tools/parsers/api/<name>.md` (dir is `api_<name>`) |51| Dedup/hashcode config | `dojo/settings/settings.dist.py` |5253## Authoring rules54551. **Factory contract.** The class name is the directory name with underscores removed +56 `Parser` (module `dependency_check` → `DependencyCheckParser`). It must have an **empty57 constructor** and implement exactly:58 - `get_scan_types(self)` → list of scan-type strings59 - `get_label_for_scan_types(self, scan_type)` → short UI label60 - `get_description_for_scan_types(self, scan_type)` → long UI description61 - `get_findings(self, file, test)` → list of unsaved `Finding` objects6263 Add `set_mode(self, mode)` only if the parser exposes more than one scan type (e.g. a64 `"... detailed"` variant). **Store no per-scan state on the instance** — the factory reuses65 one instance across all imports, so instance/class attributes leak between scans (this has66 caused real bugs; reset any state inside `get_findings`). The same leak happens **within a67 single call** when loop-local variables (`gem_name`, `severity`, a title, etc.) are only68 partially reset between records — a record missing an optional field then inherits the69 previous record's value. Reset every per-record variable to `None` at the top of each70 iteration, and build the finding only from fields actually present.71722. **Robust `get_findings`.** Guard every optional field: `data.get("k")`, `if "k" in data`,73 and `data.get("list") or []` (guards `null`). An unhandled `KeyError` becomes a 500 on74 import. Do **not** fill missing fields with placeholder junk like `"NA"` — leave the75 attribute unset. On a garbled or wrong-format file, **raise** `ValueError` with a hint76 rather than silently importing zero findings (a legitimately empty report is fine and77 should log an INFO line, not raise).78793. **Severity.** Valid severities are exactly `Info / Low / Medium / High / Critical`80 (`Finding.SEVERITIES`). Map vendor values through a dict with a default:81 `SEVERITY_MAPPING.get(raw, "Info")` (map synonyms like `Informational → Info`). Two distinct82 default cases — keep them straight:83 - **A value was present but unmapped** (a synonym you didn't handle fell through) → default84 to **`Info`**, and consider it a mapping gap to fix.85 - **The report carries no severity at all** for this tool → a documented non-`Info` default86 (e.g. `Medium`) can be reasonable, but it must be **called out in the parser's docs page**.87 An undocumented `Medium` default is a review finding.8889 Do **not** hand-roll a CVSS-score→severity ladder — use `from dojo.utils import parse_cvss_data`90 (returns `severity`, `cvssv3`, `cvssv4`, `major_version`) or the `cvss` module.91924. **XML uses `defusedxml`, never `lxml` or stdlib ElementTree.** PRs with `lxml` are rejected93 outright (XXE risk).94955. **Endpoints / URLs.** Never hand-parse URLs. Use `Endpoint.from_uri(...)` (or the96 `hyperlink` module if unavoidable) and assign to `finding.unsaved_endpoints`.97986. **Encoding.** Any `.read()` in parser code must specify utf-8 within a few lines99 (`.read().decode("utf-8")` or `encoding="utf-8"`) — the meta-test fails otherwise.100101## Deduplication (the single most common review miss)102103Register the parser's dedup behavior in `dojo/settings/settings.dist.py`. Forgetting this is104the most frequent maintainer callout on parser PRs — without it the parser silently falls105back to the legacy algorithm. Two blocks must agree:106- **`DEDUPLICATION_ALGORITHM_PER_PARSER`** — map the scan type to one of `DEDUPE_ALGO_HASH_CODE`,107 `DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL`, or `DEDUPE_ALGO_UNIQUE_ID_FROM_TOOL_OR_HASH_CODE`.108- **`HASHCODE_FIELDS_PER_SCANNER`** — the list of `Finding` fields the hash is computed from109 (required whenever the algorithm uses `HASH_CODE`).110111**Every scan type the parser returns from `get_scan_types()` needs its own dedup entries** —112the config is keyed by scan-type string, so a parser that emits two aliases (e.g. a friendly113name and a legacy one) must register both, or the unregistered alias silently falls back to114legacy dedup. Prefer emitting a single scan type unless there's a real reason for more.115116Rules that recur in review:117- **`unique_id_from_tool` / `vuln_id_from_tool` must come verbatim from the report** — never a118 value the parser computes or derives. They must be unique per finding and stable across119 scans. If a stable id exists, prefer deduping on it directly rather than hashing it.120- **Keep `severity` out of the hash** unless it is provably stable across scans (it usually121 isn't — it drifts as occurrences change).122123### Dedup changes to existing data (close the open loop)124125**Any change that alters the dedup key for an existing scan type is a data-migration126concern, not just a code change — treat it as a release-gating review item.** The dedup key127changes when a PR touches `HASHCODE_FIELDS_PER_SCANNER`, `DEDUPLICATION_ALGORITHM_PER_PARSER`,128how `unique_id_from_tool`/`vuln_id_from_tool` is populated, or any parser field that feeds the129hash (title, component, file_path, line, etc.). Also flag parser output changes that shift130those fields even when the config is untouched.131132Why it matters for customers with existing data: **`hash_code` is computed once at import and133stored on the `Finding` row — it is not recomputed retroactively.** So after the change, old134findings keep their old key and new imports compute a different one. Two concrete failures:135- **Duplicates instead of dedup** — the next scan's findings no longer match the stored ones,136 so they import as brand-new findings.137- **The close/reopen loop breaks** — reimport closes findings absent from the new report and138 reopens ones that return, by matching on the dedup key. When the key shifts, reimport can139 fail to mitigate findings that were actually fixed, or **reopen findings that were already140 closed** — noisy and alarming for users.141142What the PR (and your review) must ensure:143- **Call it out explicitly** in the PR description and the release note — this is a behavior144 change for existing data, not a silent internal tweak.145- **Provide the recompute path.** Existing rows need `hash_code` recomputed and dedup re-run:146 `python manage.py dedupe --parser "<Scan Type>" --hash_code_only` (recompute only), then147 `--dedupe_only` (re-run dedup), or the full `manage.py dedupe`. Note this is heavy on large148 instances (mass update over all findings for the scan type, async by default) — it's ops149 guidance for the customer, not something the import path does automatically.150- **Validate the config** with `python manage.py validatededupeconfig`.151- **Prefer additive / opt-in.** Reopening a customer's closed findings on upgrade is a strong152 reason to reject or redesign; favor changes that don't retroactively alter the key, or that153 ship with a clear recompute runbook.154155## Unit-test strategy156157- **Minimum three sample files: `no_vuln`, `one_vuln`, `many_vulns`** (correct extension),158 with matching test methods. Assert the empty file yields `0` findings and the multi file the159 exact count.160- **Assert concrete attributes, not just counts** — for representative findings check `title`,161 `severity` (`assertIn(finding.severity, Finding.SEVERITIES)`), `active`/`verified`/162 `duplicate`, `unique_id_from_tool`/`vuln_id_from_tool`, `cwe`, CVSS fields,163 `vulnerability_ids`, dates, tags. Wrap per-finding checks in `with self.subTest(...)`.164- **Open sample files with the `with ... .open(encoding="utf-8")` pattern**, using165 `get_unit_tests_scans_path("<dir>") / "one_vuln.json"` from `unittests/dojo_test_case.py`.166 Subclass `DojoTestCase`.167- **Endpoint parsers:** call `endpoint.clean()` on every `finding.unsaved_endpoints` in a test168 to prove RFC-valid endpoints.169- **API parsers:** also add `unittests/tools/test_api_<name>_importer.py` and mock the API with170 `unittest.mock.patch`.171- **Regression fixtures:** when fixing a specific bug, add a small targeted sample named172 `issue_<number>.<ext>` (the repo-wide convention) rather than bloating an existing file.173- Run: `./run-unittest.sh --test-case unittests.tools.test_<dir>_parser.<TestClass>`.174175## Sample-file rules (sanitization & size)176177- **Sanitize sample scans.** Strip real IPs, hostnames, tokens/credentials, customer names,178 and other PII — use `example.com` / obviously fabricated data. (This is a strong convention179 the maintainers hold; it is not written as a numeric rule in the repo, so apply judgment and180 call it out explicitly in review.)181- **Keep the set minimal.** `no_vuln` / `one_vuln` / `many_vulns` is the baseline; add small,182 targeted cases for specific edge conditions instead of committing large real-world dumps.183 There is no hard committed-fixture size cap, but the runtime upload limit is184 `DD_SCAN_FILE_MAX_SIZE` (default 100 MB) — samples should be far smaller. Prefer the185 smallest report that still exercises the behavior.186187## Documentation (meta-test enforced)188189The docs page must exist at the path above and contain front-matter `title:` and190`toc_hide: true`. **File parsers** must also include a `### Sample Scan Data` heading and a191link to `https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans`. Follow192`parser-documentation-template.md` (file types + how to export, field mapping, dedup handling,193default severity, sample link). **Do not put source-code line numbers in the field-mapping194table** — they drift and get rejected in review.195196## Reviewer checklist (highest-frequency issues)1971981. **Dedup registered** in `settings.dist.py` — both the algorithm map and (for hashcode)199 `HASHCODE_FIELDS_PER_SCANNER`?2002. **`unique_id_from_tool` taken verbatim** from the report, not computed?2013. **`severity` excluded from the hash** unless provably stable?2024. **Dedup-key change on an existing scan type?** If the PR shifts `HASHCODE_FIELDS_PER_SCANNER`,203 the algorithm, `unique_id_from_tool`, or a hashed field, is there a recompute/reimport204 runbook (`manage.py dedupe`) and a release note? Existing findings won't recompute205 `hash_code` automatically, so imports can duplicate and the close/reopen loop can break.2065. **Unrecognized file raises**, doesn't silently import 0 findings?2076. **0 / 1 / many sample files + attribute-level assertions**, opened with `with`?2087. **Sample files sanitized and minimal** (no real IPs/hosts/tokens/customers; no giant dumps)?2098. **Docs page present** with `title:`, `toc_hide: true`, `### Sample Scan Data` + scans link,210 and **no source line numbers**?2119. **Ruff clean; utf-8 after `.read()`; `defusedxml` (no lxml); `Endpoint.from_uri()`**?21210. **No leaked state** — no per-instance attributes across imports, and per-record loop213 variables fully reset each iteration (a record missing an optional field must not inherit214 the previous record's value)?215216## PR hygiene (parser PRs specifically)217218- **Keep the diff to the parser's own files.** A parser PR should touch `dojo/tools/<dir>/`,219 its test + samples, its docs page, and (for dedup) `settings.dist.py` — nothing else. Flag220 unrelated edits riding along, especially `requirements.txt` / dependency bumps; ask for them221 to be split out.222- **Screen the PR description.** Community parser PRs sometimes carry vendor marketing or paid-223 service links in the body. Flag promotional content for a maintainer — it's not a code defect224 but the project cares about it.225- **Trust green Actions + the real diff, not bot noise.** The authoritative signals are the226 green GitHub Actions checks and the actual `gh pr diff` (base...head). Third-party bot walls227 (e.g. DryRun "sensitive codepath modified") are advisory and are routinely dismissed by228 maintainers as false positives — don't treat them as blockers; verify against the real diff.229230## Notes231232- **New parser = a feature → targets `dev`**; a parser bugfix targets `bugfix`. Label the PR233 `Import Scans`. Defer to `AGENTS.md` for the branch/milestone policy.234- **New API parsers from the community are currently not accepted** (supportability) — flag235 this in review of an inbound API parser.236- A scaffolding template exists: `https://github.com/DefectDojo/cookiecutter-scanner-parser`.237- Common meta-test exemptions (shared/common modules) are hard-coded in238 `unittests/test_parsers.py` (e.g. `wizcli_common_parsers`, `sysdig_common`,239 `checkmarx_osa`) — a genuinely new parser is not one of these.