Get-RiskyUsersReport.ps1

#Requires -Modules Microsoft.Graph.Identity.SignIns

<#
.SYNOPSIS
    Retrieve all risky users with risk level, state, last sign-in, and recommended action.

.DESCRIPTION
    Exports a focused report on risky users from Entra ID Protection.
    Includes risk level, risk state, last risk update time, and last sign-in.
    Optionally filters to only users that need attention (At risk, not yet remediated).

.PARAMETER RiskLevelFilter
    Filter by risk level. Valid: low, medium, high. Default: high, medium.

.PARAMETER AtRiskOnly
    Return only users in 'atRisk' state (excludes remediated and dismissed).

.PARAMETER IncludeLastSignIn
    Attempt to fetch last sign-in time for each risky user (requires AuditLog.Read.All).
    Adds latency. Default: false.

.PARAMETER ExportPath
    Path to export CSV. Default: .\RiskyUsersReport_<timestamp>.csv

.PARAMETER ConfirmCompromised
    List of User Object IDs to mark as Confirmed Compromised before exporting.
    Use with caution — this sets user risk to High and triggers CA02.

.PARAMETER DismissRisk
    List of User Object IDs to dismiss risk before exporting.
    Use for confirmed false positives.

.EXAMPLE
    .\Get-RiskyUsersReport.ps1

.EXAMPLE
    .\Get-RiskyUsersReport.ps1 -AtRiskOnly -RiskLevelFilter 'high'

.EXAMPLE
    # Dismiss a false-positive risky user
    .\Get-RiskyUsersReport.ps1 -DismissRisk @('00000000-0000-0000-0000-000000000001')

.NOTES
    Author:  Lokesh Karnam
    Purpose: Portfolio demonstration — Entra ID Protection (Project 6)

    Required permissions:
    - IdentityRiskyUser.Read.All
    - IdentityRiskyUser.ReadWrite.All (if using -ConfirmCompromised or -DismissRisk)
    - AuditLog.Read.All (if using -IncludeLastSignIn)

    Risk states:
    - atRisk          : Risk detected, not yet actioned
    - confirmedSafe   : Admin confirmed this user is not compromised
    - remediated      : User changed password (CA02 triggered)
    - dismissed       : Admin dismissed the risk
    - confirmedCompromised : Admin confirmed user is compromised
#>

[CmdletBinding(SupportsShouldProcess)]
param(
    [ValidateSet('low', 'medium', 'high')]
    [string[]]$RiskLevelFilter = @('high', 'medium'),

    [switch]$AtRiskOnly,

    [switch]$IncludeLastSignIn,

    [string]$ExportPath,

    [string[]]$ConfirmCompromised,

    [string[]]$DismissRisk
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

function Write-Step    { param([string]$M) Write-Host "`n[$([datetime]::Now.ToString('HH:mm:ss'))] $M" -ForegroundColor Cyan }
function Write-Success { param([string]$M) Write-Host "  ✓ $M" -ForegroundColor Green }
function Write-Warn    { param([string]$M) Write-Host "  ⚠ $M" -ForegroundColor Yellow }

Write-Step "Connecting to Microsoft Graph"
$scopes = @('IdentityRiskyUser.Read.All')
if ($ConfirmCompromised -or $DismissRisk) { $scopes += 'IdentityRiskyUser.ReadWrite.All' }
if ($IncludeLastSignIn) { $scopes += 'AuditLog.Read.All' }

$mgContext = Get-MgContext -ErrorAction SilentlyContinue
if (-not $mgContext) {
    Connect-MgGraph -Scopes $scopes -NoWelcome
}
Write-Success "Connected as: $($(Get-MgContext).Account)"

#region Optional bulk actions before reporting
if ($ConfirmCompromised) {
    Write-Step "Marking $($ConfirmCompromised.Count) users as Confirmed Compromised"
    foreach ($uid in $ConfirmCompromised) {
        if ($PSCmdlet.ShouldProcess($uid, 'Confirm Compromised')) {
            Confirm-MgRiskyUserCompromised -UserIds @($uid)
            Write-Success "Confirmed compromised: $uid"
        }
    }
}

if ($DismissRisk) {
    Write-Step "Dismissing risk for $($DismissRisk.Count) users"
    foreach ($uid in $DismissRisk) {
        if ($PSCmdlet.ShouldProcess($uid, 'Dismiss Risk')) {
            Invoke-MgDismissRiskyUser -UserIds @($uid)
            Write-Success "Risk dismissed: $uid"
        }
    }
}
#endregion

Write-Step "Retrieving risky users"
$allRiskyUsers = Get-MgRiskyUser -All

# Apply local filters
if ($RiskLevelFilter) {
    $allRiskyUsers = $allRiskyUsers | Where-Object { $_.RiskLevel -in $RiskLevelFilter }
}
if ($AtRiskOnly) {
    $allRiskyUsers = $allRiskyUsers | Where-Object { $_.RiskState -eq 'atRisk' }
}

Write-Success "Found $($allRiskyUsers.Count) risky users (after filters)"

Write-Step "Building report"
$report = foreach ($user in $allRiskyUsers) {

    $lastSignIn = ''
    if ($IncludeLastSignIn) {
        try {
            $signIn = Get-MgAuditLogSignIn -Filter "userId eq '$($user.Id)'" `
                -Top 1 -Sort 'createdDateTime desc' -ErrorAction SilentlyContinue
            $lastSignIn = $signIn.CreatedDateTime
        } catch { $lastSignIn = 'N/A' }
    }

    $recommendedAction = switch ($user.RiskState) {
        'atRisk'               { 'Investigate — confirm compromised or dismiss if false positive' }
        'confirmedCompromised' { 'Immediate: disable account, force password reset, review audit logs' }
        'remediated'           { 'Monitor — password was reset via CA02; verify user is not re-flagged' }
        'dismissed'            { 'Dismissed — verify this was a confirmed false positive' }
        'confirmedSafe'        { 'No action required' }
        default                { 'Review' }
    }

    [PSCustomObject]@{
        UserId              = $user.Id
        UserPrincipalName   = $user.UserPrincipalName
        UserDisplayName     = $user.UserDisplayName
        RiskLevel           = $user.RiskLevel
        RiskState           = $user.RiskState
        RiskDetail          = $user.RiskDetail
        RiskLastUpdated     = $user.RiskLastUpdatedDateTime
        LastSignIn          = $lastSignIn
        IsDeleted           = $user.IsDeleted
        IsProcessing        = $user.IsProcessing
        RecommendedAction   = $recommendedAction
    }
}

# Summary
$byLevel = $report | Group-Object RiskLevel | Sort-Object Name
$byState = $report | Group-Object RiskState | Sort-Object Name

Write-Step "Report Summary"
Write-Host ""
Write-Host "  Total Risky Users : $($report.Count)" -ForegroundColor White
Write-Host ""
Write-Host "  By Risk Level:" -ForegroundColor Yellow
$byLevel | ForEach-Object { Write-Host "    $($_.Name): $($_.Count)" -ForegroundColor White }
Write-Host ""
Write-Host "  By Risk State:" -ForegroundColor Yellow
$byState | ForEach-Object { Write-Host "    $($_.Name): $($_.Count)" -ForegroundColor White }

$atRiskHigh = ($report | Where-Object { $_.RiskLevel -eq 'high' -and $_.RiskState -eq 'atRisk' }).Count
if ($atRiskHigh -gt 0) {
    Write-Host ""
    Write-Warn "$atRiskHigh user(s) at HIGH risk and not yet remediated — immediate attention required"
}

if (-not $ExportPath) {
    $ts = Get-Date -Format 'yyyyMMdd_HHmmss'
    $ExportPath = ".\RiskyUsersReport_$ts.csv"
}

$report | Export-Csv -Path $ExportPath -NoTypeInformation -Encoding UTF8
Write-Success "Exported to: $ExportPath"