Configurar e gerir o Recon Agent no Microsoft Perception

Os administradores podem utilizar este guia para configurar o Recon Agent no Microsoft Perception, configurar o acesso e iniciar e rever sessões. Crie a identidade do agente no portal e, em seguida, execute o script PowerShell para atribuir as suas permissões apenas de leitura.

Antes de começar, confirme que o Perception está configurado no seu tenant. Consulte os Pré-requisitos para os requisitos de subscrição e acesso.

Prerequisites

Recomendam-se os seguintes produtos para ajudar a melhorar as descobertas do Agente de Recon, mas não são obrigatórios a utilizar o agente:

  • Gestão da Postura de Segurança da Cloud do Microsoft Defender (GPSC do Defender)
  • Microsoft Defender para Servidores Plano 2

Permissões necessárias

Para tarefas de configuração privilegiadas, utilize o acesso just-in-time via Microsoft Entra Privileged Identity Management (PIM), quando disponível. Ative apenas os papéis necessários para a tarefa.

O acesso aos agentes é controlado pelas funções de segurança existentes no Microsoft Defender:

Função O que pode fazer
Administrador de Segurança Configure e defina o Agente de Recon, incluindo a sua identidade e permissões, e remova os agentes. Pelo menos um utilizador na sua organização necessita desta função.
Leitor de Segurança Iniciar sessões, visualizar e interagir com as sessões do agente, e visualizar os detalhes da sessão.

Para delegar a configuração do agente, peça ao administrador do Microsoft Entra que atribua o cargo de Administrador de Segurança. Conceder ao agente as suas permissões Microsoft Graph e Azure requer as funções adicionais listadas em Permissões do Agente.

Permissões do agente

As funções humanas controlam quem pode configurar ou usar o Recon Agent. As permissões do agente autorizam o agente a ler informações do diretório Microsoft Entra ID e informações de recursos do Azure.

O script de atribuição de permissões concede permissões de aplicação do Microsoft Graph e funções do controlo de acesso baseado em funções (RBAC) do Azure. O administrador que concede cada conjunto de permissões necessita da função correspondente:

Conjunto de permissões Função necessária para conceder permissões Permissões concedidas ao agente
Permissões de aplicações Microsoft Graph Administrador de Funções Privilegiadas no Microsoft Entra ID. User.Read.All, Policy.Read.All, RoleManagement.Read.Directory, AuditLog.Read.All, DelegatedPermissionGrant.Read.All, Application.Read.All, GroupMember.Read.All e Organization.Read.All.
Funções Azure RBAC no âmbito da subscrição Role Based Controlo de Acesso Administrator em cada subscrição de destino. Reader, Key Vault Reader, Log Analytics Reader e Security Reader.

Configurar o Recon Agent com PowerShell

Crie a identidade do agente no Perception e, em seguida, utilize o script de atribuição de permissões para conceder as permissões listadas em Permissões do Agente.

Preparar o acesso e as ferramentas

Tenha o PowerShell e a CLI do Azure disponíveis antes de executar o script. Utilize uma conta com Security Admin para a configuração do agente. Atribuir permissões também requer Privileged Role Administrator para Microsoft Graph e Role Based Controlo de Acesso Administrator em cada subscrição-alvo.

Criar a identidade e atribuir permissões

Para ativar o Agente de Recon, crie a sua identidade e atribua permissões apenas de leitura:

Note

O Recon Agent utiliza uma identidade de agente, não uma identidade de utilizador de agente. As identidades dos utilizadores do Agente não suportam as operações só de leitura do Agente de Recon.

  1. Como utilizador com o papel de Administrador de Segurança, inicie sessão no portal Microsoft Defender e aceda a Perceção>Agentes.

  2. Em Pronto para configuração, encontre Recon Agent e selecione Configurar. Crie uma nova identidade de agente. Para informações gerais de configuração, consulte Configurar um agente.

  3. No portal do Microsoft Defender, vá a Perception>Agents e abra o Recon Agent.

  4. Copie o ID do objeto do agente a partir da secção Identidade . Use este valor para o parâmetro do AgentId script.

  5. Copie o script de atribuição de permissão para um ficheiro chamado ReconAgent-Permissions.ps1.

  6. Confirme que CLI do Azure tem sessão iniciada com a conta autorizada a conceder os conjuntos de permissões selecionados. Execute o script no PowerShell com o ID do inquilino, ID do objeto do agente e IDs de subscrição de destino. Para conceder ambos os conjuntos de permissões, utilize uma conta com as funções Microsoft Entra e Azure listadas em Preparar acesso e ferramentas:

    .\ReconAgent-Permissions.ps1 -TenantId "<tenant-id>" -AgentId "<agent-object-id>" -Permissions All -SubscriptionId "<subscription-id>"
    

    Se diferentes administradores concederem os dois conjuntos de permissões, faça com que cada administrador execute apenas o comando correspondente com a sua conta autorizada:

    .\ReconAgent-Permissions.ps1 -TenantId "<tenant-id>" -AgentId "<agent-object-id>" -Permissions Graph
    .\ReconAgent-Permissions.ps1 -TenantId "<tenant-id>" -AgentId "<agent-object-id>" -Permissions Azure -SubscriptionId "<subscription-id>"
    

    SubscriptionId aceita uma ou mais subscrições e é obrigatório para All ou Azure. O script solicita início de sessão no CLI do Azure quando necessário.

  7. Revise os resultados da atribuição de permissões e resolva falhas reportadas antes de iniciar uma sessão.

  8. Complete a configuração do agente no portal.

Script de atribuição de permissões

Guarde o seguinte script como ReconAgent-Permissions.ps1 para conceder permissões de aplicação Microsoft Graph e funções do Azure RBAC ao Agente de Recon.

<#
.SYNOPSIS
    Assigns the Graph API permissions and Azure RBAC roles required by Recon.

.DESCRIPTION
    Assigns the following Graph API application permissions:
      - User.Read.All
      - Organization.Read.All
      - GroupMember.Read.All
      - Application.Read.All
      - DelegatedPermissionGrant.Read.All
      - Policy.Read.All
      - RoleManagement.Read.Directory
      - AuditLog.Read.All

        Assigns the following Azure RBAC roles at subscription scope:
            - Reader
            - Key Vault Reader
            - Log Analytics Reader
            - Security Reader

.PARAMETER TenantId
    The Tenant Id.

.PARAMETER AgentId
    The Entra ID Object ID (principal ID) of the Agent Identity to assign roles to. To get this value,
    1. Go to the Microsoft Defender portal at https://security.microsoft.com/ -> Perception -> Agents
    2. Search for the Recon Agent and click on it to open the agent details page
    3. Copy the value under the "Identity" section

.PARAMETER Permissions
    Permission sets to assign: All, Azure, or Graph. Defaults to All.

.PARAMETER SubscriptionId
    One or more Azure subscriptions to receive the Recon RBAC assignments.
    Values can be comma-delimited, space-delimited, or supplied as an array.
    Required when Permissions is All or Azure.

Example: .\ReconAgent-Permissions.ps1 -TenantId <TenandId> -AgentId <AgentId> -Permissions All -SubscriptionId <SubscriptionId>
Example: .\ReconAgent-Permissions.ps1 -TenantId <TenandId> -AgentId <AgentId> -Permissions Azure -SubscriptionId <SubscriptionId1>, <SubscriptionId2>

#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [ValidatePattern('^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')]
    [string]$TenantId,

    [Parameter(Mandatory = $true)]
    [ValidatePattern('^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$')]
    [string]$AgentId,

    [ValidateSet('All', 'Azure', 'Graph')]
    [string]$Permissions = 'All',

    [string[]]$SubscriptionId,

    [Parameter(ValueFromRemainingArguments = $true, DontShow = $true)]
    [string[]]$AdditionalSubscriptionId
)

$ErrorActionPreference = 'Stop'

$subscriptionIds = @(@($SubscriptionId) + @($AdditionalSubscriptionId) |
    ForEach-Object { $_ -split '[,\s]+' } |
    Where-Object { -not [string]::IsNullOrWhiteSpace($_) } |
    ForEach-Object { $_.Trim() } |
    Sort-Object -Unique)

if ($Permissions -in @('All', 'Azure') -and $subscriptionIds.Count -eq 0) {
    throw '-SubscriptionId requires at least one subscription GUID when -Permissions is All or Azure.'
}

foreach ($id in $subscriptionIds) {
    if ($id -notmatch '^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$') {
        throw "Invalid subscription ID '$id'. Supply one or more GUIDs separated by commas or spaces."
    }
}

function Invoke-AzJson {
    param(
        [Parameter(Mandatory)]
        [string[]]$Arguments
    )

    $output = & az @Arguments 2>&1
    if ($LASTEXITCODE -ne 0) {
        throw "az $($Arguments -join ' ') failed: $($output -join [Environment]::NewLine)"
    }

    if (-not $output) {
        return $null
    }

    return ($output -join [Environment]::NewLine) | ConvertFrom-Json | Write-Output
}

function Test-AzureActionAllowed {
    param(
        [Parameter(Mandatory)]
        [string]$Scope,

        [Parameter(Mandatory)]
        [string]$Action
    )

    $permissionsResponse = Invoke-AzJson -Arguments @(
        'rest', '--method', 'GET',
        '--url', "https://management.azure.com$Scope/providers/Microsoft.Authorization/permissions?api-version=2022-04-01",
        '--output', 'json'
    )

    foreach ($permission in @($permissionsResponse.value)) {
        $isAllowed = @($permission.actions | Where-Object {
            $Action -like [string]$_
        }).Count -gt 0
        $isExcluded = @($permission.notActions | Where-Object {
            $Action -like [string]$_
        }).Count -gt 0

        if ($isAllowed -and -not $isExcluded) {
            return $true
        }
    }

    return $false
}

function Write-Section {
    param([string]$Title)

    Write-Host ''
    Write-Host $Title -ForegroundColor Cyan
    Write-Host ('-' * $Title.Length) -ForegroundColor DarkGray
}

function Write-Step {
    param(
        [string]$Message,
        [ValidateSet('Info', 'OK', 'Warn', 'Err', 'Step')]
        [string]$Level = 'Info'
    )

    $color = switch ($Level) {
        'OK' { 'Green' }
        'Warn' { 'Yellow' }
        'Err' { 'Red' }
        'Step' { 'Cyan' }
        default { 'Gray' }
    }
    $prefix = switch ($Level) {
        'OK' { '[ OK ]' }
        'Warn' { '[WARN]' }
        'Err' { '[FAIL]' }
        'Step' { '[STEP]' }
        default { '[ -- ]' }
    }

    if ($Level -eq 'Step') {
        Write-Host ''
    }

    Write-Host (
        '{0} {1} {2}' -f
        (Get-Date -Format 'HH:mm:ss'), $prefix, $Message
    ) -ForegroundColor $color
}

function Write-ConsoleResults {
    param([object[]]$Results)

    Write-Section 'Granular Recon permission assignment'
    Write-Step `
        -Message "Agent: Recon, EntraObjectId: $AgentId" `
        -Level Step

    foreach ($result in @($Results |
        Sort-Object PermissionSet, SubscriptionId, Role)) {
        $category = if ($result.PermissionSet -eq 'Graph') {
            'Microsoft Graph permission'
        }
        else {
            'Azure RBAC'
        }
        $value = if ($result.PermissionSet -eq 'Azure') {
            "{0} ({1})" -f $result.Role, $result.Scope
        }
        else {
            "Graph $($result.Role)"
        }
        $assignmentResult = switch ($result.Status) {
            'Already assigned' { 'Already existed' }
            'Assigned' { 'Added' }
            default { $result.Status }
        }
        $level = if ($result.Status -eq 'Failed') { 'Err' } else { 'OK' }

        Write-Step `
            -Message "$category`: $value - $assignmentResult" `
            -Level $level
        if ($result.Status -eq 'Failed' -and
            -not [string]::IsNullOrWhiteSpace([string]$result.Details)) {
            Write-Host ("       Details:  {0}" -f $result.Details) `
                -ForegroundColor DarkGray
        }
    }
}

if (-not (Get-Command az -ErrorAction SilentlyContinue)) {
    throw 'Azure CLI is required but the az command was not found.'
}

Write-Host ''
Write-Host 'Recon Agent Permission Assignment' -ForegroundColor Cyan
Write-Host 'Assigns required Microsoft Graph and Azure RBAC permissions' `
    -ForegroundColor DarkGray
Write-Host "Permission set: $Permissions"
Write-Host "Tenant: $TenantId"

# Ensure Azure CLI is signed in to the requested tenant.
$account = $null
try {
    $account = Invoke-AzJson -Arguments @('account', 'show', '--output', 'json')
}
catch {
    # No usable cached Azure CLI session.
}

if (-not $account -or [string]$account.tenantId -ne $TenantId) {
    & az login --tenant $TenantId --allow-no-subscriptions | Out-Null
    if ($LASTEXITCODE -ne 0) {
        throw "Azure CLI sign-in to tenant $TenantId failed."
    }
}

$agentServicePrincipal = Invoke-AzJson -Arguments @(
    'rest', '--method', 'GET',
    '--url', "https://graph.microsoft.com/v1.0/servicePrincipals/$AgentId",
    '--output', 'json'
)
if ([string]$agentServicePrincipal.id -ne $AgentId) {
    throw "Agent service principal $AgentId could not be resolved in tenant $TenantId."
}

$results = @()

if ($Permissions -in @('All', 'Graph')) {
    $graphToken = & az account get-access-token `
        --tenant $TenantId `
        --resource-type ms-graph `
        --query accessToken `
        --output tsv 2>&1
    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace([string]$graphToken)) {
        throw "Unable to acquire a Microsoft Graph token: $($graphToken -join [Environment]::NewLine)"
    }
    $graphHeaders = @{
        Authorization = "Bearer $([string]$graphToken)"
        Accept = 'application/json'
    }

    # Graph API roles (AppRoleId -> Role Name)
    $graphRoleIds = @{
        'df021288-bdef-4463-88db-98f22de89214' = 'User.Read.All'
        '498476ce-e0fe-48b0-b801-37ba7e2685c6' = 'Organization.Read.All'
        '98830695-27a2-44f7-8c18-0c3ebc9698f6' = 'GroupMember.Read.All'
        '9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30' = 'Application.Read.All'
        '81b4724a-58aa-41c1-8a55-84ef97466587' = 'DelegatedPermissionGrant.Read.All'
        '246dd0d5-5bd0-4def-940b-0421030a5b68' = 'Policy.Read.All'
        '483bed4a-2ad3-4361-a73b-c83ccdbdc53c' = 'RoleManagement.Read.Directory'
        'b0afded3-3588-46d8-8b3d-9842eff778da' = 'AuditLog.Read.All'
    }

    $graphServicePrincipal = Invoke-AzJson -Arguments @(
        'ad', 'sp', 'show',
        '--id', '00000003-0000-0000-c000-000000000000',
        '--output', 'json'
    )
    $GraphObjectId = [string]$graphServicePrincipal.id
    if ([string]::IsNullOrWhiteSpace($GraphObjectId)) {
        throw "Microsoft Graph service principal could not be resolved in tenant $TenantId."
    }

    $existingAssignmentsResponse = Invoke-AzJson -Arguments @(
        'rest', '--method', 'GET',
        '--url', "https://graph.microsoft.com/v1.0/servicePrincipals/$AgentId/appRoleAssignments",
        '--output', 'json'
    )
    $existingAssignments = @($existingAssignmentsResponse.value)

    foreach ($rid in $graphRoleIds.Keys) {
        $roleName = $graphRoleIds[$rid]
        $existingAssignment = $existingAssignments |
            Where-Object {
                [string]$_.resourceId -eq $GraphObjectId -and
                [string]$_.appRoleId -eq $rid
            } |
            Select-Object -First 1

        if ($existingAssignment) {
            $results += [pscustomobject]@{
                PermissionSet = 'Graph'
                Role = $roleName
                Status = 'Already assigned'
                Details = ''
            }
            continue
        }

        $body = @{
            principalId = $AgentId
            resourceId = $GraphObjectId
            appRoleId = $rid
        } | ConvertTo-Json -Compress

        try {
            Invoke-RestMethod `
                -Method Post `
                -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$AgentId/appRoleAssignments" `
                -Headers $graphHeaders `
                -ContentType 'application/json' `
                -Body $body | Out-Null
            $results += [pscustomobject]@{
                PermissionSet = 'Graph'
                Role = $roleName
                Status = 'Assigned'
                Details = ''
            }
        }
        catch {
            $details = if ($_.ErrorDetails.Message) {
                $_.ErrorDetails.Message
            }
            else {
                $_.Exception.Message
            }
            $results += [pscustomobject]@{
                PermissionSet = 'Graph'
                Role = $roleName
                Status = 'Failed'
                Details = $details
            }
        }
    }
}

if ($Permissions -in @('All', 'Azure')) {
    $azureRoles = @(
        'Reader'
        'Key Vault Reader'
        'Log Analytics Reader'
        'Security Reader'
    )

    foreach ($currentSubscriptionId in $subscriptionIds) {
        $subscription = Invoke-AzJson -Arguments @(
            'account', 'show',
            '--subscription', $currentSubscriptionId,
            '--output', 'json'
        )
        if ([string]$subscription.tenantId -ne $TenantId) {
            throw "Subscription $currentSubscriptionId belongs to tenant $($subscription.tenantId), not requested tenant $TenantId."
        }

        & az account set --subscription $currentSubscriptionId
        if ($LASTEXITCODE -ne 0) {
            throw "Unable to select Azure subscription $currentSubscriptionId."
        }

        $scope = "/subscriptions/$currentSubscriptionId"
        try {
            $canWriteRoleAssignments = Test-AzureActionAllowed `
                -Scope $scope `
                -Action 'Microsoft.Authorization/roleAssignments/write'
            if (-not $canWriteRoleAssignments) {
                throw "The signed-in account does not have Microsoft.Authorization/roleAssignments/write at $scope. Assign Owner, User Access Administrator, or Role Based Access Control Administrator at this scope or a parent scope."
            }
        }
        catch {
            $results += [pscustomobject]@{
                PermissionSet = 'Azure'
                SubscriptionId = $currentSubscriptionId
                Scope = $scope
                Role = 'Role assignment preflight'
                Status = 'Failed'
                Details = $_.Exception.Message
            }
            continue
        }

        foreach ($roleName in $azureRoles) {
            try {
                $existingRoleAssignments = @(Invoke-AzJson -Arguments @(
                    'role', 'assignment', 'list',
                    '--assignee-object-id', $AgentId,
                    '--role', $roleName,
                    '--scope', $scope,
                    '--output', 'json'
                ))

                if ($existingRoleAssignments.Count -gt 0) {
                    $results += [pscustomobject]@{
                        PermissionSet = 'Azure'
                        SubscriptionId = $currentSubscriptionId
                        Scope = $scope
                        Role = $roleName
                        Status = 'Already assigned'
                        Details = ''
                    }
                    continue
                }

                Invoke-AzJson -Arguments @(
                    'role', 'assignment', 'create',
                    '--assignee-object-id', $AgentId,
                    '--assignee-principal-type', 'ServicePrincipal',
                    '--role', $roleName,
                    '--scope', $scope,
                    '--output', 'json'
                ) | Out-Null

                $results += [pscustomobject]@{
                    PermissionSet = 'Azure'
                    SubscriptionId = $currentSubscriptionId
                    Scope = $scope
                    Role = $roleName
                    Status = 'Assigned'
                    Details = ''
                }
            }
            catch {
                $results += [pscustomobject]@{
                    PermissionSet = 'Azure'
                    SubscriptionId = $currentSubscriptionId
                    Scope = $scope
                    Role = $roleName
                    Status = 'Failed'
                    Details = $_.Exception.Message
                }
            }
        }
    }
}

Write-ConsoleResults -Results $results
Write-Host

if ($results.Status -contains 'Failed') {
    exit 1
}

exit 0

Permitir o acesso de outros utilizadores

Peça ao administrador do Microsoft Entra que atribua o Security Reader ou o Security Admin às pessoas que precisam de usar o agente. Estes papéis permitem-lhes visualizar e interagir com as sessões após a configuração.

Inicie uma sessão do Recon Agent

Para informações sobre os pontos de entrada disponíveis para a sessão, consulte Iniciar uma nova sessão.

Selecione um playbook em Escolher um caso de uso Recon. Os passos seguintes mostram como iniciar uma sessão Assess identity risks:

  1. No painel de navegação, selecione Perceção>.

  2. Selecione Nova sessão.

  3. Selecione o manual Avaliar riscos de identidade .

    Captura de ecrã das opções do playbook do Microsoft Perception para iniciar uma nova sessão.

    O painel Entradas adicionais necessárias abre-se. São necessários dois dados de entrada:

    Field Description
    Subscrição Azure O ID ou nome da subscrição do Azure ao qual associar a sessão. Cada sessão está limitada a uma subscrição. O administrador pré-configura esta lista durante a configuração do Recon Agent e só pode usar subscrições pré-configuradas.
    Identidade gerenciada Selecione Identidade gerida.

    Captura de ecrã do playbook Avaliar riscos de identidade com nomes fictícios de subscrição e identidade gerida.

    Note

    Quando inicia uma sessão Identificar caminhos de ataque, o seletor de subscrição lista as subscrições disponíveis para o utilizador com sessão iniciada, e não a aplicação Recon Agent. Esse utilizador necessita de acesso de leitura à subscrição completa selecionada. Depois de a sessão começar, o Recon usa a sua própria identidade para reconhecimento.

  4. Preencha ambos os campos e selecione Iniciar sessão.

A sessão é iniciada com o estado Em execução. O agente mostra o seu progresso enquanto elabora uma lista de tarefas e começa o seu trabalho.

Monitorizar o progresso da sessão

Enquanto a sessão está a decorrer, o painel do lado direito mostra:

  • Visão geral: Mostra o resumo da sessão e o estado atual.
  • Progresso: Acompanha os passos concluídos. Por exemplo, o valor muda de 0/1 para 1/1 quando a tarefa está concluída.
  • Recon Agent: Identifica o agente ativo para a sessão.
  • Entradas: Mostra o ambiente alvo e o caso de uso que forneceu.
  • Saídas: Lista ficheiros gerados até ao momento e atualizações à medida que a sessão avança.

Se a sessão reportar falhas na recolha ou permissões insuficientes, corrija essas limitações antes de tirar conclusões sobre o âmbito afetado.

Entenda o relatório

Analise o relatório em relação à pergunta que se propôs a responder:

  1. Verifique o âmbito e as limitações. Revise quaisquer suposições declaradas, dados em falta ou passos de recolha falhados. Não trate uma sessão como uma avaliação exaustiva do seu ambiente.
  2. Inspecione as evidências. Revise os recursos, identidades, permissões e relações citadas num resultado. Verifique as alegações relevantes antes de as utilizar para tomar uma decisão de segurança.
  3. Separe as observações das suposições. Um potencial caminho de ataque não é prova de que um atacante o utilizou ou de que a exploração teria sucesso.
  4. Decida o que precisa de acompanhamento. Identifique quais os resultados que necessitam de investigação adicional, revisão por um proprietário de recursos ou da identidade, ou testes autorizados separadamente.

Importante

Os resultados do Recon Agent são gerados por IA e baseiam-se em dados disponíveis através de acesso só de leitura à API. Revise as conclusões para garantir a precisão antes de as usar para planear remediações ou comunicar riscos. O relatório inclui o banner "O conteúdo gerado por IA pode estar incorreto. Verifica se é preciso."

Passos seguintes