Add centralized logging module for Scuba Runs

[DickTracyII]

Description

This PR introduces a new module, ScubaLogging.psm1, and integrates it into Orchestrator.psm1 to provide centralized logging for Scuba runs. Logging is handled in one place, avoiding the need to modify individual provider or support modules.

Key behaviors:

• Creates a verbose log artifact for each Scuba run in the M365BaselineConformance_<date>\DebugLogs folder.
• Uses Start-Transcript to capture execution output.
• Leverages PowerShell debug preferences to capture cmdlet/function output and verbose diagnostics.

Changes are intentionally scoped to adding the logging module and wiring it into the orchestrator.

Motivation / Context

Troubleshooting Scuba runs can be difficult without a single, complete log capturing command output and runtime flow. Previous approaches would require inserting logging across many modules, which increases maintenance and risk.

This change centralizes logging so:

• Users and maintainers can consistently collect a single verbose log per run.
• Troubleshooting is faster and repeatable.
• The solution stays maintainable without requiring changes across multiple modules.

Closes: #1326

Testing

• Run Scuba with -DebugScuba parameter and verified a transcript/log file is written to the M365BaselineConformance_<date>\DebugLogs folder.
• Confirmed the transcript captures:
  • cmdlet output
  • function call output
  • verbose/debug messages governed by debug preferences
• Verified standard Scuba execution behavior is unchanged when debug/logging is not enabled (no baseline logic changes).

Screenshots

Pre-approval checklist

• PR has an informative, human-readable title
• PR targets the correct parent branch (main or release branch)
• Changes are limited to a single goal (no scope creep)
• Changes are appropriately sized (no excessive file touch)
• Code changes follow ScubaGear style guidance
• Documentation updated to reflect changes (if applicable)
• Relevant labels / project fields applied

Pre-merge checklist

• PR passed smoke test checks
• Feature branch rebased against parent branch (use "Rebase branch" or CLI)
• Merge conflicts resolved (if any)
• Merge coordinator notified / PR marked ready for merge (if applicable)
• Changes demonstrated to team for questions/comments (Medium+ only)

Post-merge checklist

• Feature branch deleted after merge (repo cleanup)
• Repository checks pass on parent branch after merge

[tkol2022]

Starting my review.

[tkol2022]

Couple of comments regarding the privacy of the information captured. The original intent of #1326 is captured in the screenshot below for context:

So if we want to capture information that a user that is having problems can upload to the ScubaGear team, we have some options to offer the user:

• Have them upload the logs to the public repo issue.
• Have them send the logs to a CISA email address. This may be preferable for users that are concerned about the privacy of the information captured in the logs.

User might not feel comfortable sharing the type of data captured below, especially if they planned to upload to the public repo:

We can talk through this at a next parking lot.

[tkol2022]

@DickTracyII The lion's share of the Transcript file is an iterative list of import statements. Do you think we will use this? It makes it difficult to scroll through the file.

I ran the DebugScuba mode a couple of times again after my initial run and the Transcript file is much smaller, without the import cmdlet detailed messages. When does your code write those imports versus when it does not?

[mitchelbaker-cisa]

Couple of comments regarding the privacy of the information captured. The original intent of #1326 is captured in the screenshot below for context:

So if we want to capture information that a user that is having problems can upload to the ScubaGear team, we have some options to offer the user:

* Have them upload the logs to the public repo issue.

* Have them send the logs to a CISA email address. This may be preferable for users that are concerned about the privacy of the information captured in the logs.

User might not feel comfortable sharing the type of data captured below, especially if they planned to upload to the public repo:

We can talk through this at a next parking lot.

@DickTracyII Can we redact content like "Username" and "RunAs User"? We should comb through the transcript file for any other sensitive data that's output as well.

[tkol2022]

I am wondering if we should consider avoiding a write to the console and only capture the detailed transcript to the file? Not sure if that is even possible? When I ran against Teams, not much of an issue, but when I ran AAD, the detailed messages include a lot of JSON to the console so it was voluminous (6 MB of text) and likely slowed down the execution of the program considerably to render all that text to the screen.

[tkol2022]

Upon further testing it seems that the AAD transcript writes some private data like group and service principal identifiers, potentially others so we would likely need to search replace these identifiers with random values.

[tkol2022]

One thing I found pretty cool was that in the AAD transcript you can see it calling the Graph batch endpoint with full details of the request.

[tkol2022]

If ScubaGear authenticates, even if there are errors after the authentication, you get a message in the console that a log file was created with its path:

But if ScubaGear fails to authenticate (e.g. MS Graph sign in problem like wrong password or whatever), that message with the log file path doesn't make it to the console:

Do we care that the message with the log file path is missing from the console after an authentication error? It is more of a nitpick and not the most important thing to worry about. Good news is that I checked the transcript file and it does contain the details of the authentication error and I suppose that is the important part.

[tkol2022]

Would it be possible to add the output of the Get-Module command to the transcript file? This would help use determine which versions of the dependency modules were loaded for ScubaGear to reference. This can come in real handy especially since modules like Microsoft.Graph.Authentication have been making some major changes so we might need to know which specific one a given user has on their system.

Would it help to also capture the output of the ScubaGear dependency checker?

[tkol2022]

Side note. This likely has nothing to do with your new logging code, but I noticed that every time a Graph endpoint is called, it turns back the complete list of service plans in this large JSON text inside the provisionedPlans node. I found 96 references to the same provisionedPlans node in the file. I wonder if there is a way we can avoid fetching that object every single time we make a Graph API invocation since we are already getting the provisioned plans licensing data at the top of the AAD provider? This may speed up the REST calls a bit and give ScubaGear a little boost.