Docs/scope lines and stale fix#37
Closed
royklo wants to merge 3 commits into
Closed
Conversation
…ffFormatted mention - Adds `Required API scope(s):` line to the .SYNOPSIS block of 13 cmdlets that previously lacked it, matching the pattern already used by the Reports cmdlets (Get-InforcerReportRun, Get-InforcerReportType, Invoke-InforcerReport, Save-InforcerReportOutput). `Get-Help <cmdlet>` now surfaces the scope requirement without users needing to open docs/API-REFERENCE.md. - Removes the stale `PolicyDiffFormatted` reference in docs/CMDLET-REFERENCE.md that survived when the property itself was deleted from the module (FINDINGS #63). - 3 cmdlets intentionally excluded from scope lines: Connect-Inforcer, Disconnect-Inforcer, Test-InforcerConnection (no scope-gated API call). Scope values sourced from the existing Cmdlet → Endpoints → Required Scopes table in docs/API-REFERENCE.md. 159/159 Pester tests pass.
… alias
New cmdlet Get-InforcerSecureScore
- Wraps GET /beta/tenants/{tenantId}/secureScores — 90-day score history,
per-category breakdown, and actionable control profiles with remediation.
- Accepts numeric ID, GUID, or tenant name via -TenantId.
- Supports -OutputType JsonObject.
- PSTypeName InforcerCommunity.SecureScore with a ListControl view showing
current/max/percentage plus counts of nested arrays.
- Aliases: CurrentScore, CurrentScorePercentage, MaxScore, LicensedUserCount,
EnabledServices, Scores, ControlProfiles, ControlCategoryScores. Nested
arrays (Scores, ControlProfiles) get their own PascalCase aliases.
Get-InforcerAuditEvent -User
- New parameter that server-side filters audit events by the specified user.
- Sends the value as the `user` field in the POST /beta/auditEvents/search
body. Previously users had to fetch all events and filter client-side.
AuditEvent.Id alias
- AuditEvent objects now expose the raw `id` field as PascalCase `Id`,
consistent with every other object type in the module.
Docs / plumbing
- README, CMDLET-REFERENCE, and API-REFERENCE updated (endpoint section,
three new schemas, cmdlet-to-scope table row, TOC).
- CHANGELOG entry for 0.6.0.
- Module version bumped 0.5.0 → 0.6.0.
- Consistency tests: expected count 20 → 21, new not-connected test, new
SecureScore and AuditEvent alias tests, updated Get-InforcerAuditEvent
param list.
- scripts/Test-AllCmdlets.ps1: new case for Get-InforcerSecureScore.
162/162 Pester tests pass.
There was a problem hiding this comment.
Pull request overview
This PR expands the module’s public surface by adding Secure Score retrieval and improving help/docs by documenting required API scopes inline, while also updating tests and references to keep the “consistency contract” current.
Changes:
- Added new
Get-InforcerSecureScorecmdlet, including output aliases, formatting view, docs, and tests. - Added
-Userfilter toGet-InforcerAuditEventand added anIdalias to audit event output. - Added “Required API scope(s)” lines to comment-based help across multiple cmdlets and updated reference docs/changelog accordingly.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| Tests/Consistency.Tests.ps1 | Updates contract expectations; adds coverage for SecureScore and AuditEvent Id alias. |
| scripts/Test-AllCmdlets.ps1 | Adds smoke-run case for Get-InforcerSecureScore. |
| README.md | Adds Get-InforcerSecureScore to the public cmdlet table. |
| module/Public/Invoke-InforcerAssessment.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerUser.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerTenantPolicies.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerTenant.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerSupportedEventType.ps1 | Adds required API scopes (noted unconfirmed) to help synopsis. |
| module/Public/Get-InforcerSecureScore.ps1 | New cmdlet to retrieve tenant Secure Score (current + history + control profiles). |
| module/Public/Get-InforcerRole.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerGroup.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerBaseline.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerAuditEvent.ps1 | Adds required API scopes to help synopsis; adds -User request-body filter. |
| module/Public/Get-InforcerAssessment.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Get-InforcerAlignmentDetails.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Export-InforcerTenantDocumentation.ps1 | Adds required API scopes to help synopsis. |
| module/Public/Compare-InforcerEnvironments.ps1 | Adds required API scopes to help synopsis. |
| module/Private/Add-InforcerPropertyAliases.ps1 | Adds SecureScore alias mapping; adds AuditEvent.Id alias. |
| module/InforcerCommunity.psd1 | Bumps module version and exports Get-InforcerSecureScore. |
| module/InforcerCommunity.Format.ps1xml | Adds default list view for InforcerCommunity.SecureScore. |
| docs/CMDLET-REFERENCE.md | Updates AuditEvent docs; adds SecureScore cmdlet reference; removes stale doc mention. |
| docs/API-REFERENCE.md | Adds Secure Score endpoint + schemas and updates cmdlet→scope mapping. |
| CHANGELOG.md | Adds 0.6.0 entry describing new cmdlet/parameter/docs updates. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Returns the current and historic Microsoft Secure Score for a tenant. Includes up to 90 days of daily score history, per-category scores, and actionable control profiles. | ||
|
|
||
| **Required scope**: `Tenants.SecureScores.Read` (or `Tenants.Read`) |
…ication Two `Invoke-InforcerApiRequest` callers were missing `-PreserveStructure`, causing the helper's "if .data is a single object with an array property, unwrap to that array" convenience to return the wrong shape for single-object endpoints: - `Get-InforcerSecureScore`: was returning the 90-item `scores` array instead of the top-level `tenantSecureScoreDetails` object. PSTypeName was never applied. Live-verified fix: 90/90 assertions pass, aliases populated on the top-level object plus all three nested arrays. - `Get-InforcerUser -UserId`: same bug pattern — was returning one of the many nested arrays (groups, roles, devices, assignedLicenses, ...) instead of the user object. Live-verified fix. Also: - `SecureScore` aliasing now covers `controlCategoryScores` and its inner `historicScores` array (previously only top-level, `.Scores`, and `.ControlProfiles` were aliased). - `-EventType` tab completion is now dynamic — reads `$global:InforcerCachedEventTypes` (populated by `Get-InforcerSupportedEventType` at module import, refreshed on every authenticated call). New server-side event types show up automatically without a module release. Static fallback list updated to today's live 80 types (from 57). - `ReleaseNotes` in the psd1 manifest updated for 0.6.0 (was still describing 0.5.0). - CHANGELOG entry extended to cover all of the above. 162/162 Pester pass. Live-API verification against uk.inforcer.com: 85 assertions pass, 5 failures are all bugs in the verification harness (hashtable-splat mistakes), not the module.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of changes
Brief description of what this PR does.
Related issue
Fixes #(issue number) — or "None".
Checklist
Invoke-Pester ./Tests/Consistency.Tests.ps1)