From f243d5d990c7341f1172c126c6effa4980d0d0d2 Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Fri, 7 Aug 2026 16:18:46 -0600 Subject: [PATCH] docs(import): DISA STIG checklist import, and the CCI control crosswalk (#15571) Documents the DISA STIG Checklist scan type: the two STIG Viewer formats it reads, how the four checklist statuses become finding states, how DISA categories and assessor severity overrides map to severity, what each finding carries, and how findings are identified. Two points get more than a passing mention because they change how someone organizes their imports. Findings are identified by V-number *on the assessed asset*, so the same rule failing on two hosts stays two findings and a STIG release upgrade keeps history. And closing on re-import is driven by an item's absence from the report, so a test holding several assets' checklists needs Close Old Findings turned off. On the compliance side, STIG rules cite CCIs rather than naming controls, so control coverage gains a section on the CCI crosswalk, the precedence between mapping sources, and the fact that the backfill command now runs both passes. The compliance profile's configuration-test-types note gains the STIG case, including why it is not switched on for you. Co-authored-by: devGregA (cherry picked from commit 460889bc6b9d771fe42da75dc29193ce4b804096) --- .../federal_compliance/compliance_profile.md | 6 +- .../federal_compliance/control_coverage.md | 39 ++++++- .../pro/specialized_import/stig_checklists.md | 109 ++++++++++++++++++ 3 files changed, 149 insertions(+), 5 deletions(-) create mode 100644 docs/content/import_data/pro/specialized_import/stig_checklists.md diff --git a/docs/content/federal_compliance/compliance_profile.md b/docs/content/federal_compliance/compliance_profile.md index ac3b9b68d6..cc3085d9a1 100644 --- a/docs/content/federal_compliance/compliance_profile.md +++ b/docs/content/federal_compliance/compliance_profile.md @@ -49,7 +49,11 @@ Two profile settings are not on the form and are set through the compliance API: *do* carry their own control references are mapped from those instead; see [Control Coverage](../control_coverage). * **Configuration test types** — the test types whose findings are treated as configuration items, - which is what drives CM-6 consolidation in the ledger. + which is what drives CM-6 consolidation in the ledger. Adding the **DISA STIG Checklist** test + type here rolls a checklist's failed items into the single consolidated CM-6 item rather than + filing one POA&M item per rule — see + [DISA STIG Checklists](/import_data/pro/specialized_import/stig_checklists/). Whether checklist + items are configuration items is a per-system decision, so it is not set for you. ## Auditability diff --git a/docs/content/federal_compliance/control_coverage.md b/docs/content/federal_compliance/control_coverage.md index aa32359789..a70504c4a8 100644 --- a/docs/content/federal_compliance/control_coverage.md +++ b/docs/content/federal_compliance/control_coverage.md @@ -25,17 +25,48 @@ never produces a mapping. Findings that carry no control references of their own are attributed to the default scan controls on the Compliance Profile — see [Compliance Profile](../compliance_profile). +### DISA STIG checklists, through their CCIs + +A STIG rule does not name an 800-53 control. It cites one or more **CCIs** (Control Correlation +Identifiers), which is DISA's own index into the control catalog — `CCI-000366`, for example, is +the configuration-settings CCI and resolves to `CM-6`. + +DefectDojo crosswalks those CCIs to their controls using DISA's published CCI list, so importing a +checklist populates control coverage with no extra configuration. See +[DISA STIG Checklists](/import_data/pro/specialized_import/stig_checklists/) for the import itself. + +The crosswalk covers the NIST 800-53 Rev 5 references DISA publishes, and like reference +extraction it is grounded in the imported catalog. Checklists assessed against a control set the +bundled catalog does not cover produce no mappings rather than approximate ones. + +### When two sources disagree + +A finding can pick up a control mapping from more than one source. Where they disagree, the more +authoritative one wins, in this order: + +1. A mapping **you set by hand**. +2. A **CCI crosswalk** from a STIG checklist. +3. A control reference **extracted from the finding's own text**. +4. The profile's **default scan controls**. + +A CCI crosswalk outranks text extraction because the CCI is published by the same authority that +wrote the checklist, where an extracted reference is read out of free-form scanner output. + ### Backfilling existing findings -Extraction runs as findings arrive. To map findings that were already imported before the feature -was enabled, backfill them: +Mapping runs as findings arrive. To map findings that were already imported before the feature was +enabled, backfill them: ``` manage.py extract_control_mappings --product ``` -Use `--all` to scan every active finding instead of one Asset. The command reports how many -mappings it created, and it leaves manual and suppressed mappings alone. +Use `--all` to scan every active finding instead of one Asset. Both passes — reference +extraction and the CCI crosswalk — run by default; `--skip-scanner-refs` and `--skip-crosswalk` +run one without the other. The command reports how many mappings each pass created, and it leaves +manual and suppressed mappings alone. + +Re-running it is safe: a mapping that is already correct is left untouched. ## Correcting a mapping diff --git a/docs/content/import_data/pro/specialized_import/stig_checklists.md b/docs/content/import_data/pro/specialized_import/stig_checklists.md new file mode 100644 index 0000000000..85fdf6cf97 --- /dev/null +++ b/docs/content/import_data/pro/specialized_import/stig_checklists.md @@ -0,0 +1,109 @@ +--- +title: "DISA STIG Checklists" +description: "Import .ckl and .cklb checklists and track the open items as findings" +weight: 4 +audience: pro +--- +Note: STIG checklist import is only available in DefectDojo Pro. + +DefectDojo Pro imports DISA STIG Viewer checklists directly, so the items an assessor marked +**Open** become findings you can age against an SLA, assign, report on, and remediate alongside +everything else. + +Choose the **DISA STIG Checklist** scan type on the Add Findings page, or pass +`scan_type=DISA STIG Checklist` to the import API. + +## Supported files + +Both STIG Viewer formats are read by the same scan type: + +* **`.ckl`** — STIG Viewer 2.x, XML. +* **`.cklb`** — STIG Viewer 3.x, JSON. + +The format is detected from the file's contents rather than its name, so a checklist that was +renamed, or exported by a tool that uses a different extension, imports the same way. A checklist +that records several STIGs against one asset is fully imported: every benchmark's items are +included, and each finding names the STIG it came from. + +One checklist describes one asset. See [Importing more than one asset](#importing-more-than-one-asset) +below for how to organize them. + +## How checklist statuses map to findings + +Every status is imported, so the finding list mirrors the checklist rather than only its failures. + +| Checklist status | Finding state | Meaning | +| --- | --- | --- | +| Open | Active, Verified | Needs remediation | +| Not Reviewed | Active, not Verified | Still to be assessed | +| Not A Finding | Mitigated (inactive) | Assessed as compliant | +| Not Applicable | Out of Scope (inactive) | Does not apply to this asset | + +Importing **Not Reviewed** items as active-but-unverified is deliberate: on a freshly generated +checklist most items carry that status, and they represent assessment work that has not happened +yet. Filter the finding list on **Verified** to separate confirmed failures from items still +awaiting review. + +Re-importing an updated checklist for the same asset moves findings between these states. An item +you have since fixed (Open → Not A Finding) closes, an item that has regressed (Not A Finding → +Open) reopens, and an item you removed from the checklist entirely is closed as no longer reported. + +## Severity + +STIG severity is the rule's DISA category, and it maps to DefectDojo severity directly: + +| DISA category | Severity | +| --- | --- | +| CAT I (high) | High | +| CAT II (medium) | Medium | +| CAT III (low) | Low | + +The category itself is recorded in the finding's **Impact** field. If an assessor overrode the +severity in the checklist, the override is what the finding carries, the assessor's reason is kept +in **Severity Justification**, and Impact still shows the rule's own category — so a downgrade is +visible rather than silent. + +## What each finding contains + +| Finding field | From the checklist | +| --- | --- | +| Title | The V-number and the rule title | +| Description | Group title, rule version (STIG-ID), rule ID, the STIG itself, the discussion, and any finding details or comments the assessor recorded | +| Mitigation | The rule's fix text | +| Steps to Reproduce | The rule's check content — how to assess the item | +| References | The STIG and release, and every CCI the rule cites | +| Component | The STIG and its version and release, for example `RHEL_9_STIG` `V2R3` | +| Endpoint | The asset the checklist was run against | + +The asset is taken from the checklist's own target data, preferring its FQDN, then its host name, +then its IP address. A checklist saved without any of the three still imports; its findings simply +carry no endpoint. + +## Deduplication + +A finding is identified by its **V-number on the asset it was assessed against**. Two consequences +worth knowing: + +* The same rule failing on two different assets stays **two findings**, so per-asset remediation + is tracked separately. +* Upgrading to a newer release of the same STIG **keeps finding history**. The rule ID carries a + revision suffix that changes with every STIG release, so it is recorded for reference only and + never used to identify a finding. + +## Importing more than one asset + +Because closing on re-import is driven by an item's absence from the report, give **each asset its +own test** and re-import that asset's newer checklist into it. That is the arrangement the import +defaults assume. + +If you would rather collect several assets' checklists in a single test, turn **Close Old Findings** +off when you import, otherwise each upload will close the previous asset's items. + +## Compliance control coverage + +STIG rules cite **CCIs** (Control Correlation Identifiers), DISA's index into the NIST control +catalog, and every CCI on a rule is recorded in the finding's references. If the +[Federal Compliance](/federal_compliance/) feature is enabled, those CCIs are crosswalked to their +NIST 800-53 controls automatically, so a checklist import populates +[Control Coverage](/federal_compliance/control_coverage/) and carries control attribution into the +POA&M ledger without any further configuration.