API do AI Pilot

Mantido por: Aether365 Team Público-alvo: Programadores Âmbito: Endpoints de remediação do AI Pilot - gerar, rever e aplicar correções automatizadas

O AI Pilot transforma resultados falhados das suas análises Compliance e Exposure em correções automatizadas. Através da API pode gerar um plano de remediação para uma análise, rever as alterações propostas e aplicar as que aprovar. Aplicar uma correção é sempre uma chamada explícita que faz: nada é alterado até que o solicite.

Requisitos

Os endpoints do AI Pilot requerem o direito de utilização AI Pilot (Pro ou Enterprise) e uma ligação Microsoft 365 estabelecida em modo AI Pilot (write-consent). Uma ligação só de leitura pode gerar e ler planos, mas não pode aplicar correções. As chamadas devolvem 403 AUTH_INSUFFICIENT_SCOPE quando o direito de utilização não está presente.

Listar Verificações Remediáveis Automaticamente

Devolve os IDs de verificação que o AI Pilot sabe corrigir automaticamente. Utilize-o para decidir, por cada resultado, se existe uma correção automatizada disponível.

GET /tenants/me/remediation/capabilities

Exemplo de Resposta

{
  "success": true,
  "data": { "autoRemediableTestIds": ["AE.1068", "CIS.M365.5.1.2.3", "AE.1102"] }
}

---

Gerar um Plano de Remediação

Cria um plano de remediação para uma análise concluída: um item por cada resultado falhado corrigível, cada um com o valor atual, o valor seguro proposto e a definição que visa. A leitura do valor atual utiliza o âmbito de leitura da ligação do AI Pilot; nenhuma alteração é escrita.

POST /tenants/me/scans/{scanId}/remediation-plan

Exemplo de Pedido

curl -X POST https://api.aether365.io/tenants/me/scans/scan_abc123/remediation-plan \
  -H "Authorization: Bearer ak_live_..."

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "plan_abc123",
    "scanId": "scan_abc123",
    "msTenantId": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "createdAt": "2026-06-17T09:00:00Z",
    "items": [
      {
        "id": "item_1",
        "testId": "AE.1068",
        "coveredTestIds": ["AE.1068", "CIS.M365.5.1.2.3"],
        "actionKey": "require_mfa_admins",
        "title": "Require MFA for administrator roles",
        "settingKey": "conditionalAccess.requireMfaAdmins",
        "currentValue": false,
        "proposedValue": true,
        "status": "pending",
        "appliedBy": null,
        "appliedAt": null,
        "error": null
      }
    ]
  }
}

---

Listar Planos de Remediação

Devolve os planos de remediação do tenant, do mais recente para o mais antigo, cada um com os seus itens e o estado agregado.

GET /tenants/me/remediation-plans

Valores de estado do plano

Estado	Significado
pending	Gerado, nada aplicado ainda
completed	Todos os itens aplicados e verificados
partially_applied	Alguns itens aplicados, outros falharam ou pendentes
failed	Nenhum item pôde ser aplicado

---

Obter um Plano de Remediação

GET /tenants/me/remediation-plans/{planId}

Devolve um único plano (com os seus itens) limitado ao seu tenant. Um plano que pertença a outro tenant devolve 404 NOT_FOUND.

---

Aplicar um Plano de Remediação

Aplica os itens selecionados através da ligação do AI Pilot: cada definição é escrita via Microsoft Graph e depois relida para confirmar que a alteração teve efeito. Os itens que não listar permanecem intactos, e um item já verificado nunca é reaplicado.

POST /tenants/me/remediation-plans/{planId}/apply

Corpo do Pedido

Campo	Tipo	Descrição
itemIds	string[]	IDs dos itens do plano a aplicar

Exemplo de Pedido

curl -X POST https://api.aether365.io/tenants/me/remediation-plans/plan_abc123/apply \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["item_1", "item_2"] }'

Exemplo de Resposta

O plano completo é devolvido com o status atualizado de cada item e, em caso de falha, um error que explica a razão.

{
  "success": true,
  "data": {
    "id": "plan_abc123",
    "status": "partially_applied",
    "items": [
      {
        "id": "item_1",
        "title": "Require MFA for administrator roles",
        "status": "verified",
        "appliedAt": "2026-06-17T09:05:00Z",
        "error": null
      },
      {
        "id": "item_2",
        "title": "Disable legacy authentication",
        "status": "failed",
        "error": "Write consent is missing or has expired"
      }
    ]
  }
}

Valores de estado do item

Estado	Significado
verified	Aplicado e confirmado por uma releitura
applied	Aplicado; a Microsoft ainda não confirmou a propagação (reverificado depois)
failed	Não foi possível aplicar - ver error (por exemplo, write consent em falta)
pending	Não aplicado nesta chamada

A aprovação humana é preservada

Não existe um atalho de "aplicar tudo". É você que escolhe o plano e os itens exatos a aplicar, por isso um fluxo de trabalho automatizado mantém na mesma uma pessoa (ou uma decisão deliberada) no processo.