Add output and docs for defender to securitysuite transition

[DickTracyII]

Add output and docs for Defender-to-SecuritySuite transition

🗣 Description

Adds user-facing guidance and configuration validation to help users migrate from the deprecated defender product to the renamed securitysuite baseline.

• New transition guide: docs/configuration/defender-to-securitysuite-transition.md explaining the rename, the migrated policy IDs, and the recommended actions.
• Orchestrator updates (Orchestrator.psm1): accounts for securitysuite in both Invoke-SCuBA -ProductNames and -ConfigFilePath code paths, and emits a RECOMMENDED ACTION block when a legacy Defender config is detected.
• Config validation (ScubaConfigValidator.psm1): new ValidateDefenderMigration logic that warns when a config:
  • lists the deprecated defender value in ProductNames,
  • contains the deprecated top-level Defender section, or
  • references a policy ID that has been migrated (looked up in mappings\scuba-baseline-policy-migrations.csv).
• Generic migration label: the per-policy-ID migration message now uses a product-neutral Policy migration warning: prefix instead of Defender migration warning:, since the migration mapping also includes AAD/EXO version bumps (e.g. MS.AAD.3.2v1 → MS.AAD.3.2v2) that are not Defender policies. The two genuinely Defender-specific warnings (deprecated defender product name and deprecated Defender config section) keep their Defender-specific wording.
• Supporting additions to ScubaConfigDefaults.json and configuration.md.

💭 Motivation and context

The Defender product was renamed to securitysuite and many Defender, Exchange Online, and Teams policies were migrated into the MS.SECURITYSUITE.* baseline. Existing configuration files referencing defender or old policy IDs previously ran with no guidance, or surfaced confusing warnings (an AAD policy migration was mislabeled as a "Defender migration warning"). This change gives users clear, accurate warnings and documentation on how to update their configs.

Closes #2262

🧪 Testing

Ran Invoke-SCuBA -ConfigFilePath against ternant config files containing legacy references and confirmed:

• A config with defender in ProductNames + an OmitPolicy for MS.DEFENDER.1.1v1 produces the Defender rename warning, the policy-ID migration warning (MS.DEFENDER.1.1v1 → MS.SECURITYSUITE.1.4v1), and the RECOMMENDED ACTION block.
• A config referencing MS.AAD.3.2v1 and MS.EXO.2.2v2 now reports Policy migration warning: (not Defender migration warning:) pointing to MS.AAD.3.2v2 and MS.EXO.2.2v3.
• A clean/updated config produces no migration warnings.

Reviewers can reproduce by running Invoke-SCuBA -ConfigFilePath <legacy.yaml> and inspecting the Configuration validation found X warnings output, or by running the ScubaConfig unit tests under Testing/Unit/PowerShell/ScubaConfig/.

📷 Screenshots (if appropriate)

Running config with defender:

Running config with securitysuite

Running Invoke-Scuba with defender (no config)

✅ Pre-approval checklist

• This PR has an informative and human-readable title.
• PR targets the correct parent branch (e.g., main or release-name) for merge.
• Changes are limited to a single goal - eschew scope creep!
• Changes are sized such that they do not touch excessive number of files.
• All future TODOs are captured in issues, which are referenced in code comments.
• These code changes follow the ScubaGear content style guide.
• Related issues these changes resolve are linked preferably via closing keywords.
• All relevant type-of-change labels added.
• All relevant project fields are set.
• All relevant repo and/or project documentation updated to reflect these changes.
• Unit tests added/updated to cover PowerShell and Rego changes.
• Functional tests added/updated to cover PowerShell and Rego changes.
• All automated checks (e.g., linting, static analysis, unit/smoke tests) passed.

✅ Pre-merge checklist

• PR passed smoke test check.

• PR/feature branch passes functional tests for relevant products, if applicable.

• Feature branch has been rebased against changes from parent branch, as needed.

  Use Update branch button below or use this reference to rebase from the command line.

• Resolved all merge conflicts on branch.

• Squash all commits into one PR level commit using the Squash and merge button.

✅ Post-merge checklist

• Feature branch deleted after merge to clean up repository.
• Close issues resolved by this PR if the closing keywords did not activate.
• Verified that all checks pass on parent branch (e.g., main or release-name) after merge.

[skirkpatrickMSFT]

Overall, I see good progress, but I think an update is needed.

Issue: defender-to-securitysuite-transition.md lines 126-138 are out of sync with the code

The doc says:

You will see a Defender migration warning for each of the following situations:

and lists 4 bullet points (deprecated product name, deprecated section, migrated policy ID, removed policy ID). The example output on line 138 shows:

"Defender migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to..."

But the actual code in ScubaConfigValidator.psm1 uses "Policy migration warning:" for migrated/removed policy IDs (not "Defender migration warning:"). Only the first two warnings (deprecated product name and deprecated section) use the Defender migration warning: prefix.

You can verify from my output — the legacy defender config produced:
"--- Defender migration warnings ---
Defender migration warning: The product name 'defender' is deprecated...
Defender migration warning: The 'Defender' configuration section is deprecated...

--- Other warnings --- ← lands here, not above
Policy migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to...
Policy migration warning: Policy ID 'MS.DEFENDER.1.1v1' has been migrated to..."

Consequence: The "Defender migration warnings" bucket pattern in ScubaConfigDefaults.json (^Defender\s+migration\s+warning:) doesn't match "Policy migration warning:", so those warnings fall into "Other warnings" and only get the generic recommended action — not the defenderMigration recommended action. A user who has only migrated policy IDs (without defender in ProductNames or a Defender: section) won't see the migration-specific recommended action block at all (the warning text itself does still reference the docs, so it's not a total loss).

Suggested fixes:

1. Update the doc's "Validator warnings" section to distinguish Defender migration warning: (for the two Defender-specific items) from Policy migration warning: (for migrated/removed policy IDs)
2. Update the example console output to show Policy migration warning: instead of Defender migration warning: for the policy ID line
   3.Optionally add a "Policy migration warnings" pattern bucket in [ScubaConfigDefaults.json] so those warnings also get the defenderMigration recommended action, or broaden the existing pattern

[DickTracyII]

Overall, I see good progress, but I think an update is needed.

Issue: defender-to-securitysuite-transition.md lines 126-138 are out of sync with the code

The doc says:

You will see a Defender migration warning for each of the following situations:

and lists 4 bullet points (deprecated product name, deprecated section, migrated policy ID, removed policy ID). The example output on line 138 shows:

"Defender migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to..."

But the actual code in ScubaConfigValidator.psm1 uses "Policy migration warning:" for migrated/removed policy IDs (not "Defender migration warning:"). Only the first two warnings (deprecated product name and deprecated section) use the Defender migration warning: prefix.

You can verify from my output — the legacy defender config produced: "--- Defender migration warnings --- Defender migration warning: The product name 'defender' is deprecated... Defender migration warning: The 'Defender' configuration section is deprecated...

--- Other warnings --- ← lands here, not above Policy migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to... Policy migration warning: Policy ID 'MS.DEFENDER.1.1v1' has been migrated to..."

Consequence: The "Defender migration warnings" bucket pattern in ScubaConfigDefaults.json (^Defender\s+migration\s+warning:) doesn't match "Policy migration warning:", so those warnings fall into "Other warnings" and only get the generic recommended action — not the defenderMigration recommended action. A user who has only migrated policy IDs (without defender in ProductNames or a Defender: section) won't see the migration-specific recommended action block at all (the warning text itself does still reference the docs, so it's not a total loss).

Suggested fixes:

1. Update the doc's "Validator warnings" section to distinguish Defender migration warning: (for the two Defender-specific items) from Policy migration warning: (for migrated/removed policy IDs)
2. Update the example console output to show Policy migration warning: instead of Defender migration warning: for the policy ID line
   3.Optionally add a "Policy migration warnings" pattern bucket in [ScubaConfigDefaults.json] so those warnings also get the defenderMigration recommended action, or broaden the existing pattern

this makes sense but just so I understand better

Something like this:

[skirkpatrickMSFT]

Overall, I see good progress, but I think an update is needed.
Issue: defender-to-securitysuite-transition.md lines 126-138 are out of sync with the code
The doc says:
You will see a Defender migration warning for each of the following situations:
and lists 4 bullet points (deprecated product name, deprecated section, migrated policy ID, removed policy ID). The example output on line 138 shows:
"Defender migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to..."
But the actual code in ScubaConfigValidator.psm1 uses "Policy migration warning:" for migrated/removed policy IDs (not "Defender migration warning:"). Only the first two warnings (deprecated product name and deprecated section) use the Defender migration warning: prefix.
You can verify from my output — the legacy defender config produced: "--- Defender migration warnings --- Defender migration warning: The product name 'defender' is deprecated... Defender migration warning: The 'Defender' configuration section is deprecated...
--- Other warnings --- ← lands here, not above Policy migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to... Policy migration warning: Policy ID 'MS.DEFENDER.1.1v1' has been migrated to..."
Consequence: The "Defender migration warnings" bucket pattern in ScubaConfigDefaults.json (^Defender\s+migration\s+warning:) doesn't match "Policy migration warning:", so those warnings fall into "Other warnings" and only get the generic recommended action — not the defenderMigration recommended action. A user who has only migrated policy IDs (without defender in ProductNames or a Defender: section) won't see the migration-specific recommended action block at all (the warning text itself does still reference the docs, so it's not a total loss).
Suggested fixes:

1. Update the doc's "Validator warnings" section to distinguish Defender migration warning: (for the two Defender-specific items) from Policy migration warning: (for migrated/removed policy IDs)
2. Update the example console output to show Policy migration warning: instead of Defender migration warning: for the policy ID line
   3.Optionally add a "Policy migration warnings" pattern bucket in [ScubaConfigDefaults.json] so those warnings also get the defenderMigration recommended action, or broaden the existing pattern

this makes sense but just so I understand better

Something like this:

Overall, I see good progress, but I think an update is needed.
Issue: defender-to-securitysuite-transition.md lines 126-138 are out of sync with the code
The doc says:
You will see a Defender migration warning for each of the following situations:
and lists 4 bullet points (deprecated product name, deprecated section, migrated policy ID, removed policy ID). The example output on line 138 shows:
"Defender migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to..."
But the actual code in ScubaConfigValidator.psm1 uses "Policy migration warning:" for migrated/removed policy IDs (not "Defender migration warning:"). Only the first two warnings (deprecated product name and deprecated section) use the Defender migration warning: prefix.
You can verify from my output — the legacy defender config produced: "--- Defender migration warnings --- Defender migration warning: The product name 'defender' is deprecated... Defender migration warning: The 'Defender' configuration section is deprecated...
--- Other warnings --- ← lands here, not above Policy migration warning: Policy ID 'MS.DEFENDER.2.1v1' has been migrated to... Policy migration warning: Policy ID 'MS.DEFENDER.1.1v1' has been migrated to..."
Consequence: The "Defender migration warnings" bucket pattern in ScubaConfigDefaults.json (^Defender\s+migration\s+warning:) doesn't match "Policy migration warning:", so those warnings fall into "Other warnings" and only get the generic recommended action — not the defenderMigration recommended action. A user who has only migrated policy IDs (without defender in ProductNames or a Defender: section) won't see the migration-specific recommended action block at all (the warning text itself does still reference the docs, so it's not a total loss).
Suggested fixes:

1. Update the doc's "Validator warnings" section to distinguish Defender migration warning: (for the two Defender-specific items) from Policy migration warning: (for migrated/removed policy IDs)
2. Update the example console output to show Policy migration warning: instead of Defender migration warning: for the policy ID line
   3.Optionally add a "Policy migration warnings" pattern bucket in [ScubaConfigDefaults.json] so those warnings also get the defenderMigration recommended action, or broaden the existing pattern

this makes sense but just so I understand better

Something like this:

You hit the nail on the head!