Add OSCAL Assessment Results JSON importer

[AAH20]

Scanner Name

OSCAL Assessment Results Scan

NIST OSCAL Assessment Results is a vendor-neutral JSON, XML, or YAML model for reporting assessment observations, findings, risks, evidence, and control-objective status. This request is for a narrow JSON file importer for OSCAL 1.2.x Assessment Results documents.

• Model documentation: https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/
• Current release: https://github.com/usnistgov/OSCAL/releases/tag/v1.2.3
• Official JSON schema: https://github.com/usnistgov/OSCAL/releases/download/v1.2.3/oscal_assessment-results_schema.json

The importer would allow standards-based assessment findings from cloud, Kubernetes, configuration, and continuous-assessment tools to enter DefectDojo without a vendor-specific parser for every producer.

Sample File

Format: JSON (assessment-results root object). The following is a minimal sanitized sample illustrating the proposed mapping; implementation fixtures would also include zero findings, multiple results, linked risks, malformed references, and missing optional fields.

{
  "assessment-results": {
    "uuid": "f6497d04-9b01-4f3f-9991-2c7c9b8b4a58",
    "metadata": {
      "title": "Sanitized automated assessment",
      "last-modified": "2026-08-17T10:00:00Z",
      "version": "1.0.0",
      "oscal-version": "1.2.3"
    },
    "import-ap": {
      "href": "assessment-plan.json"
    },
    "results": [
      {
        "uuid": "cb6bc258-ac20-4e08-a174-996f19a22b75",
        "title": "Automated control checks",
        "description": "Sanitized results for importer testing.",
        "start": "2026-08-17T09:55:00Z",
        "end": "2026-08-17T10:00:00Z",
        "reviewed-controls": {
          "control-selections": [
            {
              "include-controls": [
                { "control-id": "ac-2" }
              ]
            }
          ]
        },
        "observations": [
          {
            "uuid": "6f540467-a46f-47e0-a7cf-8de99684f0de",
            "title": "Privileged account review evidence",
            "description": "A privileged account lacks the required review evidence.",
            "methods": ["EXAMINE"],
            "collected": "2026-08-17T09:58:00Z"
          }
        ],
        "findings": [
          {
            "uuid": "7d53fbf2-a304-481c-882c-c4f549e6fa91",
            "title": "Privileged account review is not evidenced",
            "description": "The assessed objective was not satisfied.",
            "target": {
              "type": "statement-id",
              "target-id": "ac-2_smt",
              "status": {
                "state": "not-satisfied",
                "reason": "fail"
              }
            },
            "related-observations": [
              {
                "observation-uuid": "6f540467-a46f-47e0-a7cf-8de99684f0de"
              }
            ]
          }
        ]
      }
    ]
  }
}

Proposed first-version behavior

• Accept JSON OSCAL Assessment Results documents declaring OSCAL 1.2.x.
• Convert only findings whose target state is not-satisfied into DefectDojo Findings. PASS/satisfied observations are assessment evidence, not vulnerabilities, and should not create findings.
• Use the OSCAL finding UUID verbatim as unique_id_from_tool so Import/Reimport can maintain identity across recurring assessments.
• Resolve related-observations and related-risks only within the uploaded document and preserve their descriptions, timestamps, evidence links, remediation text, and original characterizations in the Finding description/references.
• Preserve target type/ID, result UUID, control IDs, OSCAL version, and relevant source UUIDs as structured tags or references where the Finding model permits.
• Never fetch import-ap, evidence, link, or back-matter URIs. Imported files are untrusted; URI values should remain inert references to avoid SSRF and unexpected network/file access.
• Do not treat risk acceptance, deviations, operational requirements, or adjusted risks as remediated. Preserve their source status without inventing a DefectDojo mitigation decision.
• Map severity only when a characterization explicitly identifies a supported system such as CVSS. Do not interpret arbitrary numeric facets as CVSS. If no supported severity is present, use DefectDojo's required informational severity and retain the original characterization.
• Do not infer endpoints or components from free text. Create them only from an unambiguous OSCAL subject/resource identifier that meets DefectDojo's validation rules.
• Reject malformed JSON, the wrong OSCAL root model, invalid UUID references, and structurally unusable findings with a controlled parser error rather than a 500/KeyError.
• Use the standard library JSON parser and existing DefectDojo utilities; no new runtime dependency is expected.

Proposed tests and documentation

• Required parser fixtures: no findings, one finding, and multiple findings.
• Additional fixtures: satisfied-only result, linked risk/observation, multiple result sets, missing optional data, duplicate UUID, dangling reference, unsupported OSCAL version, external URI, and malicious-looking URI.
• Attribute and reimport identity assertions for title, description, severity, active state, control references, timestamps, and unique_id_from_tool.
• Documentation would clearly state that importing an assessment finding does not make DefectDojo the authoritative Assessment Plan, SSP, certification, authorization, or risk-acceptance system.

I can implement the parser, fixtures, unit tests, deduplication configuration, and supported-tool documentation against the dev branch after maintainers confirm the scope and preferred handling of findings without an explicit supported severity characterization.