Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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
- Conclusão da configuração do Microsoft Perception no seu tenant.
- Microsoft Defender XDR.
- Uma ou mais subscrições do Azure.
Produtos recomendados (opcionais)
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.
Como utilizador com o papel de Administrador de Segurança, inicie sessão no portal Microsoft Defender e aceda a Perceção>Agentes.
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.
No portal do Microsoft Defender, vá a Perception>Agents e abra o Recon Agent.
Copie o ID do objeto do agente a partir da secção Identidade . Use este valor para o parâmetro do
AgentIdscript.Copie o script de atribuição de permissão para um ficheiro chamado
ReconAgent-Permissions.ps1.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>"SubscriptionIdaceita uma ou mais subscrições e é obrigatório paraAllouAzure. O script solicita início de sessão no CLI do Azure quando necessário.Revise os resultados da atribuição de permissões e resolva falhas reportadas antes de iniciar uma sessão.
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:
No painel de navegação, selecione Perceção>.
Selecione Nova sessão.
Selecione o manual Avaliar riscos de identidade .
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.
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.
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:
- 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.
- 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.
- 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.
- 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."