ownerlens 0.1.0

package/tools/README.md

@@ -0,0 +1,108 @@
+# OwnerLens Tools
+
+PowerShell scripts in this directory create the JSON snapshot files consumed by the OwnerLens app.
+
+## Core Files
+
+- `prepare-resource-snapshot.ps1` creates the Azure resource snapshot used by the app. It exports subscriptions, resource groups, resources, managed identities, role assignments, and optional Azure Monitor activity logs.
+- `prepare-entra-snapshot.ps1` creates the Entra snapshot used by the app. It exports service principals, application registrations, and groups so ownership and identity relationships can be resolved.
+
+Run these commands from the repository root so the default output paths write into `.\data`.
+
+## Prerequisites
+
+- PowerShell 7 or Windows PowerShell
+- Azure PowerShell modules:
+
+```powershell
+Install-Module Az -Scope CurrentUser
+Install-Module Az.ManagedServiceIdentity -Scope CurrentUser
+Install-Module Microsoft.Graph -Scope CurrentUser
+```
+
+If `Invoke-AzRestMethod` is missing, update `Az.Accounts`:
+
+```powershell
+Update-Module Az.Accounts
+```
+
+## Sign In
+
+Sign in to Azure before creating the resource snapshot:
+
+```powershell
+Connect-AzAccount
+```
+
+Sign in to Microsoft Graph before creating the Entra snapshot:
+
+```powershell
+Connect-MgGraph -TenantId "<tenant-id>" -Scopes "Application.Read.All","Group.Read.All","Directory.Read.All"
+```
+
+## Create Snapshots
+
+Create the Azure resource snapshot:
+
+```powershell
+.\tools\collect-azure.ps1
+```
+
+By default this writes `.\data\snapshot.json`, using the current Azure subscription and the last 90 days of activity logs.
+
+Common resource snapshot options:
+
+```powershell
+.\tools\collect-azure.ps1 -SubscriptionIds "sub-id-1,sub-id-2"
+.\tools\collect-azure.ps1 -OutputPath ".\data\snapshot-prod.json"
+.\tools\collect-azure.ps1 -ActivityDays 30 -MaxActivityRecords 5000
+.\tools\collect-azure.ps1 -SkipAuditLogsExport
+.\tools\collect-azure.ps1 -ExpandResourceProperties
+```
+
+Resource property expansion is disabled by default because OwnerLens reads the standard resource fields plus identity data from the resource list response. Use `-ExpandResourceProperties` only when debugging or when you need Azure's additional expanded metadata in a raw snapshot.
+
+Create the Entra snapshot:
+
+```powershell
+.\tools\collect-entra.ps1
+```
+
+By default this writes `.\data\entra-snapshot.json`.
+
+Common Entra snapshot option:
+
+```powershell
+.\tools\collect-entra.ps1 -TenantId "<tenant-id>"
+.\tools\collect-entra.ps1 -OutputPath ".\data\entra-snapshot-prod.json"
+```
+
+After both files exist, start the app with `npm run dev` and refresh the browser.
+
+The same collectors are available through npm scripts:
+
+```bash
+npm run collect:azure -- -SubscriptionIds "sub-id-1,sub-id-2"
+npm run collect:entra -- -TenantId "<tenant-id>"
+```
+
+After publishing the package, the equivalent `npx` commands are:
+
+```bash
+npx ownerlens collect:azure -SubscriptionIds "sub-id-1,sub-id-2"
+npx ownerlens collect:entra -TenantId "<tenant-id>"
+```
+
+## Scripts
+
+- `collect-azure.ps1` signs in when needed, then calls `prepare-resource-snapshot.ps1`.
+- `collect-entra.ps1` signs in when needed, then calls `prepare-entra-snapshot.ps1`.
+- `prepare-resource-snapshot.ps1` exports Azure subscriptions, resource groups, resources, user-assigned managed identities, role assignments, and optional Azure Monitor activity logs.
+- `prepare-entra-snapshot.ps1` exports Entra service principals, application registrations, and groups.
+- `azure-activity-check.ps1` is a helper loaded by `prepare-resource-snapshot.ps1`; it is not usually run directly.
+
+## Notes
+
+- Snapshot files can contain tenant, subscription, resource, identity, application registration, group, credential metadata, and activity-log metadata. Review them before sharing.
+- The app discovers files in `.\data` whose names end with `snapshot.json`, such as `snapshot.json`, `entra-snapshot.json`, or `snapshot-prod.json`.
+- If scripts fail with a missing connection error, run the relevant sign-in command again and retry.

package/tools/azure-activity-check.ps1

@@ -0,0 +1,164 @@
+if (-not $script:AzureActivityLogCache) {
+  $script:AzureActivityLogCache = @{}
+}
+
+function Get-ActivityLogValue {
+  param(
+    [object]$Object,
+    [string]$PropertyName
+  )
+
+  if (-not $Object) {
+    return $null
+  }
+
+  $property = $Object.PSObject.Properties[$PropertyName]
+  if (-not $property) {
+    return $null
+  }
+
+  return $property.Value
+}
+
+function Get-ActivityLogField {
+  param(
+    [object]$Entry,
+    [string]$PropertyName
+  )
+
+  $value = Get-ActivityLogValue $Entry $PropertyName
+  if ($null -ne $value) {
+    return $value
+  }
+
+  $properties = Get-ActivityLogValue $Entry "properties"
+  return Get-ActivityLogValue $properties $PropertyName
+}
+
+function Get-ActivityLogClaim {
+  param(
+    [object]$Claims,
+    [string[]]$ClaimNames
+  )
+
+  if (-not $Claims) {
+    return $null
+  }
+
+  foreach ($claimName in $ClaimNames) {
+    $value = Get-ActivityLogValue $Claims $claimName
+    if ($null -ne $value -and -not [string]::IsNullOrWhiteSpace([string]$value)) {
+      return $value
+    }
+  }
+
+  return $null
+}
+
+function Get-ActivityLogCacheKey {
+  param(
+    [string]$SubscriptionId,
+    [datetime]$StartTime,
+    [int]$MaxRecord
+  )
+
+  $normalizedStartTime = $StartTime.ToUniversalTime().ToString("o")
+  return "$SubscriptionId|$normalizedStartTime|$MaxRecord"
+}
+
+function Get-AzureMonitorActivityLogs {
+  param(
+    [string]$SubscriptionId,
+    [datetime]$StartTime,
+    [int]$MaxRecord
+  )
+
+  $logs = [System.Collections.Generic.List[object]]::new()
+  if ($MaxRecord -le 0) {
+    return $logs
+  }
+
+  $cacheKey = Get-ActivityLogCacheKey -SubscriptionId $SubscriptionId -StartTime $StartTime -MaxRecord $MaxRecord
+  if ($script:AzureActivityLogCache.ContainsKey($cacheKey)) {
+    return $script:AzureActivityLogCache[$cacheKey]
+  }
+
+  $endTime = Get-Date
+  $filter = "eventTimestamp ge '$($StartTime.ToUniversalTime().ToString("o"))' and eventTimestamp le '$($endTime.ToUniversalTime().ToString("o"))'"
+  $encodedFilter = [Uri]::EscapeDataString($filter)
+  $requestPath = "/subscriptions/$SubscriptionId/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&`$filter=$encodedFilter"
+
+  while ($requestPath -and $logs.Count -lt $MaxRecord) {
+    if ($requestPath -match "^https?://") {
+      $response = Invoke-AzRestMethod -Method GET -Uri $requestPath
+    } else {
+      $response = Invoke-AzRestMethod -Method GET -Path $requestPath
+    }
+
+    $content = $response.Content | ConvertFrom-Json
+    foreach ($entry in @($content.value)) {
+      if ($logs.Count -ge $MaxRecord) {
+        break
+      }
+
+      $operationName = Get-ActivityLogField $entry "operationName"
+      $status = Get-ActivityLogField $entry "status"
+      $subStatus = Get-ActivityLogField $entry "subStatus"
+      $category = Get-ActivityLogField $entry "category"
+      $resourceProviderName = Get-ActivityLogField $entry "resourceProviderName"
+      $resourceType = Get-ActivityLogField $entry "resourceType"
+      $authorization = Get-ActivityLogField $entry "authorization"
+      $claims = Get-ActivityLogField $entry "claims"
+
+      $logs.Add([pscustomobject]@{
+        eventTimestamp = Get-ActivityLogField $entry "eventTimestamp"
+        submissionTimestamp = Get-ActivityLogField $entry "submissionTimestamp"
+        caller = Get-ActivityLogField $entry "caller"
+        callerUserPrincipalName = Get-ActivityLogClaim $claims @(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+          "unique_name",
+          "upn",
+          "preferred_username"
+        )
+        callerName = Get-ActivityLogClaim $claims @(
+          "name",
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
+        )
+        callerEmail = Get-ActivityLogClaim $claims @(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+          "email",
+          "emails",
+          "preferred_username"
+        )
+        callerObjectId = Get-ActivityLogClaim $claims @(
+          "http://schemas.microsoft.com/identity/claims/objectidentifier",
+          "oid",
+          "objectidentifier"
+        )
+        callerIdentityType = Get-ActivityLogClaim $claims @("idtyp")
+        callerAppId = Get-ActivityLogClaim $claims @("appid", "azp")
+        callerIpAddress = Get-ActivityLogClaim $claims @("ipaddr")
+        callerTenantId = Get-ActivityLogClaim $claims @(
+          "http://schemas.microsoft.com/identity/claims/tenantid",
+          "tid"
+        )
+        operationName = Get-ActivityLogValue $operationName "localizedValue"
+        operationNameValue = Get-ActivityLogValue $operationName "value"
+        status = Get-ActivityLogValue $status "localizedValue"
+        subStatus = Get-ActivityLogValue $subStatus "localizedValue"
+        category = Get-ActivityLogValue $category "localizedValue"
+        resourceGroupName = Get-ActivityLogField $entry "resourceGroupName"
+        resourceId = Get-ActivityLogField $entry "resourceId"
+        resourceProviderName = Get-ActivityLogValue $resourceProviderName "localizedValue"
+        resourceType = Get-ActivityLogValue $resourceType "localizedValue"
+        authorizationAction = Get-ActivityLogValue $authorization "action"
+        authorizationScope = Get-ActivityLogValue $authorization "scope"
+      }) | Out-Null
+    }
+
+    $requestPath = Get-ActivityLogValue $content "nextLink"
+  }
+
+  $script:AzureActivityLogCache[$cacheKey] = $logs
+  return $script:AzureActivityLogCache[$cacheKey]
+}

package/tools/collect-azure.ps1

@@ -0,0 +1,54 @@
+param(
+  [string]$OutputDir = ".\data",
+  [string]$OutputPath = "",
+  [int]$ActivityDays = 90,
+  [int]$MaxActivityRecords = 10000,
+  [switch]$SkipAuditLogsExport,
+  [string]$SubscriptionIds = "",
+  [switch]$ExpandResourceProperties,
+  [switch]$SkipLogin
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-CollectProgress {
+  param([string]$Message)
+
+  $timestamp = (Get-Date).ToString("yyyy-MM-dd HH:mm:ss")
+  Write-Host "[$timestamp] $Message"
+}
+
+$resolvedOutputPath = $OutputPath
+if ([string]::IsNullOrWhiteSpace($resolvedOutputPath)) {
+  $resolvedOutputPath = Join-Path $OutputDir "snapshot.json"
+}
+
+if (-not (Get-Command Get-AzContext -ErrorAction SilentlyContinue)) {
+  throw "Az PowerShell module missing. Install: Install-Module Az -Scope CurrentUser"
+}
+
+$context = Get-AzContext
+if (-not $SkipLogin -and -not $context) {
+  Write-CollectProgress "Azure context not found. Starting Connect-AzAccount."
+  Connect-AzAccount | Out-Null
+}
+
+Write-CollectProgress "Collecting Azure resource snapshot"
+Write-CollectProgress "Output path: $resolvedOutputPath"
+
+$prepareParams = @{
+  OutputPath = $resolvedOutputPath
+  ActivityDays = $ActivityDays
+  MaxActivityRecords = $MaxActivityRecords
+  SubscriptionIds = $SubscriptionIds
+}
+
+if ($SkipAuditLogsExport) {
+  $prepareParams.SkipAuditLogsExport = $true
+}
+
+if ($ExpandResourceProperties) {
+  $prepareParams.ExpandResourceProperties = $true
+}
+
+& "$PSScriptRoot\prepare-resource-snapshot.ps1" @prepareParams

package/tools/collect-entra.ps1

@@ -0,0 +1,47 @@
+param(
+  [string]$OutputDir = ".\data",
+  [string]$OutputPath = "",
+  [string]$TenantId = "",
+  [string[]]$Scopes = @("Application.Read.All", "Group.Read.All", "Directory.Read.All"),
+  [switch]$SkipLogin
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-CollectProgress {
+  param([string]$Message)
+
+  $timestamp = (Get-Date).ToString("yyyy-MM-dd HH:mm:ss")
+  Write-Host "[$timestamp] $Message"
+}
+
+$resolvedOutputPath = $OutputPath
+if ([string]::IsNullOrWhiteSpace($resolvedOutputPath)) {
+  $resolvedOutputPath = Join-Path $OutputDir "entra-snapshot.json"
+}
+
+try {
+  Import-Module Microsoft.Graph.Authentication -ErrorAction Stop
+} catch {
+  throw "Microsoft Graph PowerShell module missing: Microsoft.Graph.Authentication. Install: Install-Module Microsoft.Graph -Scope CurrentUser"
+}
+
+$context = Get-MgContext
+if (-not $SkipLogin -and -not $context) {
+  Write-CollectProgress "Microsoft Graph context not found. Starting Connect-MgGraph."
+
+  $connectParams = @{
+    Scopes = $Scopes
+  }
+
+  if (-not [string]::IsNullOrWhiteSpace($TenantId)) {
+    $connectParams.TenantId = $TenantId
+  }
+
+  Connect-MgGraph @connectParams | Out-Null
+}
+
+Write-CollectProgress "Collecting Microsoft Entra snapshot"
+Write-CollectProgress "Output path: $resolvedOutputPath"
+
+& "$PSScriptRoot\prepare-entra-snapshot.ps1" -OutputPath $resolvedOutputPath

package/tools/collect-scripts.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const packageJson = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8"));
+const cli = readFileSync(join(process.cwd(), "bin/ownerlens.js"), "utf8");
+const collectEntra = readFileSync(join(process.cwd(), "tools/collect-entra.ps1"), "utf8");
+const collectAzure = readFileSync(join(process.cwd(), "tools/collect-azure.ps1"), "utf8");
+
+test("package exposes OwnerLens collect commands through the npm bin", () => {
+  expect(packageJson.bin.ownerlens).toBe("./bin/ownerlens.js");
+  expect(packageJson.scripts["collect:entra"]).toBe("node ./bin/ownerlens.js collect:entra");
+  expect(packageJson.scripts["collect:azure"]).toBe("node ./bin/ownerlens.js collect:azure");
+  expect(cli).toContain('["collect:entra", "collect-entra.ps1"]');
+  expect(cli).toContain('["collect:azure", "collect-azure.ps1"]');
+});
+
+test("collect wrappers delegate to the snapshot exporters used by the runtime", () => {
+  expect(collectEntra).toContain("prepare-entra-snapshot.ps1");
+  expect(collectEntra).toContain('Join-Path $OutputDir "entra-snapshot.json"');
+  expect(collectAzure).toContain("prepare-resource-snapshot.ps1");
+  expect(collectAzure).toContain('Join-Path $OutputDir "snapshot.json"');
+});