Add Find-CommonGroupsForDestination utility#43
Merged
Conversation
Adds Utils/Find-CommonGroupsForDestination.ps1: given a destination asset (FQDN or IP), find the AD groups shared by the source users that accessed it, to help scope identity-based segmentation rules. Highlights: - Fast source-user collection via /activities/network/distinctField/srcUser with fallback to paging /activities/network for older tenants. - Resolves activity SIDs/userNames to ZN users via SID first, then PrincipalName; dedupes by ZN user id. - Parallel group-membership lookups on PowerShell 7+ (-MaxParallel, default 8, threshold 20 users); sequential on Windows PowerShell 5.1. - Retry + exponential backoff + jitter on transient API failures (HTTP 429 / 5xx); honours Retry-After. - CSV output with optional -IncludeSourceUsers column. Also adds Utils/README.md documenting the new folder and script.
Replaces the upfront Get-ZNUser pagination with per-user resolves via GET /users/searchIdByPrincipalName?principalName=DOMAIN\user (and searchIdBySid for the activity-scan fallback). This scales to tenants with 100k+ users where the directory pre-fetch would be slow and mostly wasted work. HTTP 404 from the resolver is treated as "not a ZN user" (system/machine/unknown) and skipped silently. Other changes: - Fuse resolve + group-membership fetch into one per-user unit of work, so each parallel runspace does both API calls. - Raise -MaxParallel ceiling from 16 to 64 for very large destinations (default still 8, threshold still 20 source users). - Streaming progress with live ETA / rate as each result lands. - 404 short-circuits the retry loop (only transient errors retried). Updates Utils/README.md to match.
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
2 participants
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
Adds a new top-level
Utils/folder withFind-CommonGroupsForDestination.ps1: given a destination asset (FQDN or IP), it lists the AD groups shared by the source users that accessed it, to help build identity-based segmentation rules.-DestinationFQDNor-DestinationIP, with optional-MinUserCount,-FromDays,-OutputPath,-IncludeSourceUsers,-MaxParallel.GroupName,GroupId,SourceUserCount, optionalSourceUsers,Destination,LookbackDays), plus a top-10 console summary.$env:ZNApiKey(Set-ZNApiKey/Connect-ZN/ direct assignment).Implementation highlights
/activities/network/distinctField/srcUser(single call), with fallback to paging/activities/networkfor older tenants.userNameto ZN users via SID first, thenPrincipalName; dedupes by ZN user id so case-variant / multi-SID identities are counted once./users/{id}/ancestorslookups on PowerShell 7+ (-MaxParallel, default 8, kicks in at ≥ 20 users) using raw REST to avoid per-runspace module import; sequentialGet-ZNUserMemberOfon Windows PowerShell 5.1.Retry-Afterhonoured.Also adds
Utils/README.mddocumenting the folder and full script reference (parameters, behavior, output, caveats).The main
README.mdis intentionally untouched —.github/workflows/manual_pwsh_update_readme.ymlregenerates it from.ps1synopses on push/PR, so the new script will appear under a## Utilssection automatically.Test plan
-DestinationFQDNagainst a managed asset; verify CSV columns and top-10 console summary.-DestinationIPagainst the same target; confirm equivalent results.-IncludeSourceUsersand confirm the additionalSourceUserscolumn appears.-MaxParallel 1on PS 7+ to force sequential.$env:ZNApiKeyto confirm the auth error message; run with neither destination param to confirm usage is printed.🤖 Generated with Claude Code