Modify the ScubaResults.json schema to better define omission/annotation fields

[mitchelbaker-cisa]

Prerequisites

• This issue has an informative and human-readable title.

💡 Summary

In the "Results" top-level key, the ScubaResults.json contains the following fields for each control object:

{
  "Control ID":  "MS.EXO.4.2v1",
  "Requirement":  "The DMARC message rejection option SHALL be p=reject.",
  "Result":  "Fail",
  "Criticality":  "Shall",
  "Details":  "3 agency domain(s) found in violation: domain1.onmicrosoft.com, 
    domain2.onmicrosoft.com, domain3.onmicrosoft.com. View DNS logs, #dns-logs for more 
    details.<span class='component-heading'>User comment</span>\"We're failing because 
    reasons, we will fix soon.\"<span class='component-heading'>Anticipated remediation
    date</span>\"2025-12-05\"",
  "OmittedEvaluationResult":  "N/A",
  "OmittedEvaluationDetails":  "N/A",
  "IncorrectResult":  "N/A",
  "IncorrectResultDetails":  "N/A"
},
...

The purpose of this issue is to define six new fields for the control object. These fields more clearly define the separation between original report result/details. It will also abstract the comment and remediation/expiration dates into their own fields instead of having to parse the Details field for the same information.

List of proposed fields:

• OriginalResult
• OriginalDetails
• Comments
• ResolutionDate

{
  "Control ID":  "MS.EXO.4.2v1",
  "Requirement":  "The DMARC message rejection option SHALL be p=reject.",
  "Result":  "Fail",
  "Criticality":  "Shall",
  "Details":  "3 agency domain(s) found in violation: domain1.onmicrosoft.com, 
    domain2.onmicrosoft.com, domain3.onmicrosoft.com. View DNS logs, #dns-logs for more 
    details.<span class='component-heading'>User comment</span>\"We're failing because 
    reasons, we will fix soon.\"<span class='component-heading'>Anticipated remediation
    date</span>\"2025-12-05\"",
  "OmittedEvaluationResult":  "N/A",
  "OmittedEvaluationDetails":  "N/A",
  "IncorrectResult":  "N/A",
  "IncorrectResultDetails":  "N/A",
  "OriginalResult": "Fail",
  "OriginalDetails": "3 agency domain(s) found in violation: domain1.onmicrosoft.com, 
    domain2.onmicrosoft.com, domain3.onmicrosoft.com. View DNS logs, #dns-logs for more 
    details.",
  "Comments: ["We're failing because reasons, we will fix soon."],
  "ResolutionDate": "2025-12-05"
},
...

Motivation and context

• ScubaResults.json files are processed by other services and the current JSON schema is not designed for interoperability.
• Currently the omission/annotation comments and remediation dates can only be pulled from the Details field. Creating unique fields for this data removes the need for string manipulation and/or other complex methods.

Implementation notes

1. Finalize new JSON schema for control objects.
2. Update CreateReport.psm1 and/or other PowerShell modules to update control object with new fields.
3. Generate a sample report with new JSON schema.
4. Consult with CISA stakeholders to discuss JSON schema and determine if any other requirements are necessary.
5. Update schema spreadsheet with new fields.

Acceptance criteria

• JSON schema is finalized.
• schema spreadsheet is updated with new fields
• ScubaGear is updated to generate ScubaResults.json files with new fields.
• CISA stakeholders agree that these change meet their requirements, and have all the context they need to proceed with additional work.

[adhilto]

For consistency with the other fields, I'd recommend that if OmissionComment and OmissionExpirationDate are not provided, they be "N/A" instead of null.