Adding in document for Goggles Output File Schema by mdueltgen · Pull Request #938 · cisagov/ScubaGoggles

mdueltgen · 2026-02-27T19:35:27Z

🗣 Description

Creates markdown file, based on the previously used stand-alone spreadsheet, to document the output schema for the ScubaResults.json file

💭 Motivation and context

Closes #937

🧪 Testing

Since it is just an additional MD file for users to read, testing would just be done by comparing to the spreadsheet that was used in the past to document the ouput schema

✅ Pre-approval checklist

✅ Pre-merge Checklist

This PR has been smoke tested to ensure main is in a functional state when this PR is merged.
Squash all commits into one PR level commit using the Squash and merge button.

✅ Post-merge Checklist

Delete the branch to clean up.
Close issues resolved by this PR if the closing keywords did not activate.

ahuynhECS

left a few comments

ahuynhECS · 2026-03-11T18:22:07Z

docs/misc/tooloutputschema.md

+| Result | String | The decision made by the ScubaGear assessment whether the tenant ScubaGear was run against meets required configuration stated by the policy. | Warning | Possible values include:<ul><li><code>Pass</code></li><li><code>Fail</code></li><li><code>Warning</code></li><li><code>N/A</code> (typically indicates a manual check needed)</li><li><code>Omitted</code></li><li><code>Incorrect Result</code></li><li><code>Error - Test results missing</code></li><li><code>Error</code></li><li><code>No events found</code> (this is a ScubaGoggles only item and should eventually disappear someday)</li></ul> |
+| Criticality | String | Based RFC 2119. SHALL means the policy is required, SHOULD means the policy is recommend,  3rd Party means that the policy may be implemented via a 3rd Party service (e.g., malware protections are required don't have to be done via Defender). | Should | Possible values include:<ul><li><code>Shall</code></li><li><code>Should</code></li><li><code>Shall/3rd Party</code></li><li><code>Should/3rd Party</code></li><li><code>Shall/Not-implemented</code></li><li><code>Should/Not-implemented</code></li></ul> |
+| Details | String | The exact information of either how the tenant ScubaGear is run against either does or does not meet the SCuBA Secure Configuration Baseline Policy Requirement | 1 meeting policy(ies) found that does not restrict installation of Microsoft Apps by default: Global | Any annotations will be included in HTML formatted string |
+| OmittedEvaluationResult | String | For controls, that were omitted, what the result would have been if it hadn't been omitted. For controls that were not omitted, this value will be set to "N/A". | Fail | Will continue to be output by ScubaGear for backwards compatibility, but we are deprecating this field and it will be removed in the next major release |


dont have this in goggles

whoops my comments selected the entire section rather than pinpoint what wasn't appliable to goggles. The sections / information to delete because they are not in the goggles reports are below:

Control Object section

OmittedEvaluationResult

OmittedEvaluationDetails

IncorrectResult

IncorrectResultDetails

ahuynhECS · 2026-03-11T18:29:41Z

docs/misc/tooloutputschema.md

+| query_method | String | The method used for resolving the DNS query: either "traditional" or "DoH." | traditional |
+| query_result | String | String description of the result of the DNS query. | Query returned 1 txt records |
+| query_name | String | The domain name. | example.onmicrosoft.com |
+


we also have query_answers which is when the query returned txt recods. example: "v=DMARC1; p=reject; rua=mailto:reports@dmarc.cyber.dhs.gov; pct=100; ruf=mailto:reports@dmarc.cyber.dhs.gov"

ahuynhECS · 2026-03-11T18:30:24Z

docs/misc/tooloutputschema.md

+
+| Field Name | Type | Description | Example |
+| --- | --- | --- | --- |
+| AlertName | String | The name of the rule associated with the alert. | New user added |


update to "Alert Name"

ahuynhECS · 2026-03-11T18:32:01Z

docs/misc/tooloutputschema.md

+</details>
+
+<details>
+<summary>License Object</summary>


license objects not found in goggles

ahuynhECS · 2026-03-11T18:43:55Z

docs/misc/tooloutputschema.md

+| AnnotatedFailedPolicies | Object | Collection of failed SHALL policies along with any annotations for those policies the user included in their config file. Maps control IDs to '<AnnotationObject>' objects. See the "Annotation Object" tab of this spreadsheet for more details. | Annotations are appended to the "Details" column. | "AnnotatedFailedPolicies": {"MS.EXO.4.2v1": {"Comment": "We're failing because reasons, we will fix soon.", "RemediationDate": "2024-08-01", "IncorrectResult": false}} |
+| Summary | Object | Map of product names to numerical summaries of the assessment results for each SCuBA product (`<SummaryObject>` objects). See the "Summary Object" tab of this spreadsheet for more details. The specific keys included under the Summary key are the short forms of the names of the products assessed (see both MetaData.ProductsAssessed and MetaData.ProductAbbreviationMapping). | N/A| "Results": {"gmail": `<SummaryObject>`, "calendar": `<SummaryObject>`} |
+| Results | Object | Map of product names to the assessment results for each SCuBA product (arrays of `<ResultsObject>` objects). See the "Results Object" tab of this spreadsheet for more details. The specific keys included under the Summary key are the short forms of the names of the products assessed (see both MetaData.ProductsAssessed and MetaData.ProductAbbreviationMapping). | On each individual HTML report page. The policy group numbers, policy names and the html tables containing the assessment results. | "Results": {"gmail": [`<ResultsObject>`, `<ResultsObject>`], "calendar": [`<ResultsObject>`]} |
+| Raw | Object | The raw JSON output of a ScubaGear assessment. This contains the data returned by the various API calls used by ScubaGear/Goggles to conduct a conformance assessment of the tenant's configuration against SCuBA's Security Configuration Baseline policies. This is the original ProviderSettingsExport.json file found from a normal ScubaGear run. Values under this field may or may not be present, depending on which products were included in an assessment for a given execution of ScubaGear/ScubaGoggles. | N/A| N/A|


overall raw section needs to be updated to match GWS variant and applicable objects

mitchelbaker-cisa

@mdueltgen Went through the spreadsheet you sent. Additional fields not included in the "Raw" section of the ScubaGoggles output:

Raw.date
Raw.timestamp_zulu
Raw.tenant_details
Raw.dkim_config (we have Raw.dkim_records)

mitchelbaker-cisa · 2026-03-11T20:15:10Z

docs/misc/tooloutputschema.md

+| MetaData.TenantId | String | A unique identifier assigned to each M365 tenant/GWS customer. | On the report summary page under "Tenant ID" (ScubaGear only). | 32c412d2-b044-3425-8ed1-ab220b70d3d1 |
+| MetaData.DisplayName | String | The display name of the M365 tenant/GWS customer. | On both the report summary page and the individual report for each baseline under "Tenant Display Name" (ScubaGear only). | Example Tenant Name |
+| MetaData.DomainName | String | The primary domain of the customer (ScubaGoggles) or the initial and immutable .onmicrosoft.com domain of an Entra ID tenant (ScubaGear). | On the report summary page under "Customer Domain" (ScubaGoggles) or "Tenant Domain Name" (ScubaGear). | example.com |
+| MetaData.ProductSuite | String | Name of the SCuBA baseline product suite that is being assessed with the current SCuBA tool. | N/A| Microsoft 365 |


mitchelbaker-cisa · 2026-03-11T20:16:05Z

docs/misc/tooloutputschema.md

+| MetaData.DisplayName | String | The display name of the M365 tenant/GWS customer. | On both the report summary page and the individual report for each baseline under "Tenant Display Name" (ScubaGear only). | Example Tenant Name |
+| MetaData.DomainName | String | The primary domain of the customer (ScubaGoggles) or the initial and immutable .onmicrosoft.com domain of an Entra ID tenant (ScubaGear). | On the report summary page under "Customer Domain" (ScubaGoggles) or "Tenant Domain Name" (ScubaGear). | example.com |
+| MetaData.ProductSuite | String | Name of the SCuBA baseline product suite that is being assessed with the current SCuBA tool. | N/A| Microsoft 365 |
+| MetaData.ProductsAssessed | Array | List of products scanned by the SCuBA tool. | On the report summary page, the values in the "Baseline Conformance Reports" column. | ["Azure Active Directory", "Microsoft 365 Defender"] |


Same with ProductsAssessed and ProductAbbreviationMapping. Use ["Common Controls", "Gmail"] and GWS specific names.

mitchelbaker-cisa · 2026-03-11T20:16:28Z

docs/misc/tooloutputschema.md

+| MetaData.ProductSuite | String | Name of the SCuBA baseline product suite that is being assessed with the current SCuBA tool. | N/A| Microsoft 365 |
+| MetaData.ProductsAssessed | Array | List of products scanned by the SCuBA tool. | On the report summary page, the values in the "Baseline Conformance Reports" column. | ["Azure Active Directory", "Microsoft 365 Defender"] |
+| MetaData.ProductAbbreviationMapping | Object | A mapping of the list of products assessed during a run of the SCuBA tool to the abbreviations used in the policy identifiers and policy groups in the SCuBA secure configuration baseline documents. | N/A| {"Azure Active Directory":  "AAD", "Microsoft 365 Defender": "Defender"} |
+| MetaData.Tool | String | Name of the current SCuBA tool conducting the assessment. | On the footer of the report summary page, e.g., "Report generated with CISA's ScubaGear tool v1.7.1." | ScubaGear |


Adding in first pass of Googles Output Schema

0a5172f

mdueltgen added this to the Hammerhead milestone Feb 27, 2026

mdueltgen self-assigned this Feb 27, 2026

mdueltgen added the enhancement label Feb 27, 2026

mdueltgen linked an issue Feb 27, 2026 that may be closed by this pull request

Document Goggles Output schema #937

Open

3 tasks

mdueltgen requested review from ahuynhECS and mitchelbaker-cisa March 2, 2026 18:38

removing cap rule section

e824bbe

ahuynhECS requested changes Mar 11, 2026

View reviewed changes

ahuynhECS reviewed Mar 11, 2026

View reviewed changes

mitchelbaker-cisa requested changes Mar 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding in document for Goggles Output File Schema#938

Adding in document for Goggles Output File Schema#938
mdueltgen wants to merge 2 commits intomainfrom
937-document-goggles-utput-schema

mdueltgen commented Feb 27, 2026

Uh oh!

ahuynhECS left a comment

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

ahuynhECS Mar 11, 2026

Uh oh!

mitchelbaker-cisa left a comment

Uh oh!

mitchelbaker-cisa Mar 11, 2026

Uh oh!

mitchelbaker-cisa Mar 11, 2026

Uh oh!

mitchelbaker-cisa Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	\| MetaData.ProductSuite \| String \| Name of the SCuBA baseline product suite that is being assessed with the current SCuBA tool. \| N/A\| Microsoft 365 \|
	\| MetaData.ProductSuite \| String \| Name of the SCuBA baseline product suite that is being assessed with the current SCuBA tool. \| N/A\| Google Workspace \|

	\| MetaData.Tool \| String \| Name of the current SCuBA tool conducting the assessment. \| On the footer of the report summary page, e.g., "Report generated with CISA's ScubaGear tool v1.7.1." \| ScubaGear \|
	\| MetaData.Tool \| String \| Name of the current SCuBA tool conducting the assessment. \| On the footer of the report summary page, e.g., "Report generated with CISA's ScubaGoggles tool v0.6.0." \| ScubaGoggles \|

Conversation

mdueltgen commented Feb 27, 2026

🗣 Description

💭 Motivation and context

🧪 Testing

✅ Pre-approval checklist

✅ Pre-merge Checklist

✅ Post-merge Checklist

Uh oh!

ahuynhECS left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mitchelbaker-cisa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants