Desenvolver uma solução de notebook para Microsoft Sentinel

Como parceiro ISV, você pode criar, testar, empacotar e publicar soluções de análise em notebooks Jupyter na Segurança da Microsoft Store como ofertas SaaS. O data lake do Microsoft Sentinel suporta Jupyter Notebooks que são executados em pools Spark gerenciados com grandes conjuntos de dados de segurança. Esses notebooks são ideais para detecção de ataques lentos e de baixa intensidade, estabelecimento de linhas de base comportamentais, análises baseadas em IA/ML, mapeamento dos fluxos de dados confidenciais, visualizações de dados e processos de enriquecimento que as detecções tradicionais em KQL não conseguem expressar.

Uma solução de plataforma de cadernos é tipicamente projetada para análise histórica, transformações complexas de dados e fluxos de trabalho recorrentes de processamento de dados. Ele grava a saída em uma tabela personalizada no data lake, onde regras analíticas downstream, consultas de busca, agentes do Security Copilot ou ferramentas MCP podem consumir os resultados da solução em notebook. O pacote .zip que você envia para o Partner Center é declarado como tipo SentinelLake e contém os notebooks e, opcionalmente, um modelo ARM para os recursos do Azure subsequentes que o notebook precisa.

Este artigo guia você sobre a construção, teste, embalagem e publicação de uma solução de notebook da plataforma Microsoft Sentinel para a Segurança da Microsoft Store. Depois de concluir este guia, você terá:

Um notebook Jupyter funcional que lê dados do data lake do Sentinel
Uma tarefa agendada que executa o notebook em um pool gerenciado do Spark
Um SentinelLake pacote zip (PackageManifest + pasta do notebook)
Uma listagem de uma oferta SaaS do Partner Center na Segurança da Microsoft Store

Pré-requisitos

Seu locatário deve estar conectado ao data lake Microsoft Sentinel. Verifique o status de integração no portal do Defender. Navegue até Sistema>Configurações>Microsoft Sentinel>Data lake. O status indica Provisionado se o seu locatário estiver pronto. Para obter instruções de integração inicial, consulte Fazer a integração com o data lake do Microsoft Sentinel.

Permissões necessárias

Operação/Recursos	Função necessária
Integrar-se ao data lake Sentinel	Microsoft Entra ID – Administrador de Segurança ou Administrador Global
Integrar o espaço de trabalho do Sentinel ao portal Defender	Proprietário da assinatura ou Administrador de acesso do usuário no escopo da assinatura e Colaborador do Microsoft Sentinel no escopo da assinatura ou do grupo de recursos
Integrar o espaço de trabalho do Sentinel ao data lake	Proprietário da assinatura ou Colaborador do Microsoft Sentinel no escopo da assinatura ou do grupo de recursos
Executar notebooks no data lake	Microsoft Sentinel Leitor ou Colaborador
Espaço de trabalho do Log Analytics (para gravação de volta na camada de análise)	Colaborador do Log Analytics atribuído à identidade gerenciada do data lake `msg-resources-<guid>`
Centro de Parceiros da Microsoft	Conta de publicador do Marketplace (configurada uma única vez; mesma conta usada para publicar agentes do Security Copilot)

Note

A função de Proprietário da Assinatura é necessária para uma tarefa de integração inicial ao data lake realizada uma única vez. Use Microsoft Entra Privileged Identity Management (PIM) para elevar temporariamente a essa função somente quando necessário e remover o acesso após a conclusão da integração.

Ferramentas necessárias

Visual Studio Code.
Extensão do Microsoft Sentinel para VS Code
A extensão GitHub Copilot para VS Code é recomendada para acelerar a criação de notebooks.
Python 3.10+ instalado localmente. O kernel spark é executado em Azure mas o VS Code precisa de um interpretador local para edição de célula.

Visão geral do processo

O processo de publicação começa com o desenvolvimento local de notebooks, migrando para uma oferta SaaS empacotada e detectável na Segurança da Microsoft Store.

Desenvolvimento de notebook local (extensão VS Code + Sentinel)
Executar interativamente na plataforma Sentinel
Teste em relação a dados representativos; validar populações da tabela de saída
Agende como uma Tarefa (sob demanda ou agendada)
Empacote como SentinelLake.zip (PackageManifest.yaml + pasta)
Criar oferta de SaaS no Microsoft Partner Center
Fazer upload do pacote, criar metadados, plano e preços
Revisão e publicação, revisão automatizada, Go Live
Disponível na Loja de Segurança da Microsoft

Instalar o Visual Studio Code e a extensão do Microsoft Sentinel

Todo o desenvolvimento do notebook ocorre localmente no VS Code com a extensão Microsoft Sentinel instalada. O kernel spark é executado em Azure— o VS Code é o editor e o cliente de envio.

Baixe Visual Studio Code https://code.visualstudio.com/ e instale com opções padrão.
Abra o marketplace > do VS Code (Ctrl+Shift+X ou Cmd+Shift+X).
Pesquise o Sentinel e instale a extensão Microsoft Sentinel (publisher: ms-security).

Após a instalação, o ícone Microsoft Sentinel aparece na barra de ferramentas à esquerda.
(Recomendado) Pesquise GitHub Copilot no marketplace, instale-o e entre no GitHub quando solicitado.

O Copilot conhece a MicrosoftSentinelProvider API e autocompleta transformações do PySpark.
Selecione o ícone Microsoft Sentinel na barra de ferramentas à esquerda.
Aprove a caixa de diálogo de login e selecione a conta com a função Sentinel Reader/Contributor em seu espaço de trabalho.

O painel esquerdo mostra Tabelas do Lake e Tarefas, confirmando que a extensão alcançou o data lake.

Cuidado

Se você tiver vários tenants convidados conectados, a troca de contas no canto inferior esquerdo do VS Code encerrará todas as sessões PySpark ativas — você precisará reiniciar o kernel após a troca. Planeje a troca de contas entre as execuções, não durante elas.

Desenvolva seu notebook

Os notebooks usam esse padrão de criação:

Ler uma tabela do data lake para um DataFrame do Spark
Transformar com o PySpark
Opcionalmente, enriqueça com dados externos
Gravar resultados em uma tabela personalizada que o Sentinel pode consumir

Explorar o painel de tabelas do Lake

Para identificar as tabelas de entrada que seu notebook usa, explore o painel Tabelas do Lake:

Selecione o ícone sentinela e expanda as tabelas do Lake.
As tabelas são agrupadas por banco de dados e categoria (Sistema, Personalizado, Federado). Selecione qualquer tabela para ver suas definições e tipos de coluna.
Identifique as tabelas de entrada que seu bloco de anotações lê e anote os nomes exatos.

Criar um novo bloco de notas

Para criar um novo jupyter notebook para sua solução, conclua as seguintes etapas:

Ou pressione Ctrl+Shift+P / Cmd+Shift+P>, digite Criar um Novo Notebook Jupyter ou selecione Arquivo>Novo Arquivo>Jupyter Notebook.
Salve o bloco de anotações com um nome descritivo (por exemplo, failed-signin-baseline.ipynb).

Ler uma tabela

Cole este modelo na primeira célula e substitua o nome da tabela pelo seu:

from sentinel_lake.providers import MicrosoftSentinelProvider
data_provider = MicrosoftSentinelProvider(spark)

# Read a table from the data lake
table_name = "EntraGroups"
df = data_provider.read_table(table_name)

# Quick sanity check—show 100 rows
df.select("displayName", "groupTypes", "mail", "tenantId").show(100, truncate=False)

Selecione um pool de runtime e execute a célula

Para executar a célula no data lake, selecione um pool e envie:

Selecione o triângulo Executar na célula.
Quando solicitado, escolha Microsoft Sentinel como o runtime.
Escolha um tamanho de pool: pequeno para exploração, Médio para transformações, Grande para ML ou agregações em dezenas de milhões de linhas.

A primeira execução leva de 3 a 5 minutos para iniciar a sessão do Spark. As células subsequentes são executadas em segundos.

Transformar e gravar novamente em uma tabela personalizada

O save_as_table() método grava um DataFrame em uma tabela personalizada na camada lake (ou na camada de análise). A tabela de destino é criada na primeira gravação.

df_transformed = (
    df.filter(df.mail.isNotNull())
    .select("displayName", "groupTypes", "mail", "mailNickname", "description", "tenantId")
)

write_options = {"mode": "overwrite"}
data_provider.save_as_table(
    df_transformed,
    "EntraGroups_Processed_SPRK",
    write_options=write_options,
)

Padrões de criação de notebooks

Os seguintes padrões abrangem os cenários mais comuns:

Pattern	Quando utilizá-lo
Linha de base + deriva	Calcule o comportamento normal por usuário ou por host; marque as linhas que se desviam da linha de base. Classic para análises de falha de login e de execução de processos.
Junção entre tabelas	Combine a tabela do data lake que você tem com tabelas integradas (SigninLogs, SecurityAlert, DeviceProcessEvents) em entidades compartilhadas (UPN, host, IP).
Pontuação de ML	Treine ou carregue um modelo pré-treinado no notebook; atribua uma pontuação a cada linha; grave as N linhas de maior risco em uma tabela de saída personalizada para alertas posteriores.
Investigação visual	Plote linhas do tempo, mapas de calor e árvores de processos com matplotlib ou plotly; exporte o notebook como HTML para entrega.

Tip

Use células markdown liberalmente para documentar seu código. Um revisor do Security Store — e o analista de SOC que executa o seu notebook — precisa entender o que cada seção faz sem ler o código. Coloque uma célula markdown acima de cada bloco de código explicando a finalidade, as entradas, as saídas e a saída esperada. Revisores consideram notebooks pouco claros como reprovação obrigatória.

Testar o notebook

O teste exige comprovar que o notebook funciona de ponta a ponta com dados realistas e produz uma tabela de saída útil.

Teste de fumaça em pool pequeno

Execute o notebook de ponta a ponta para confirmar se todas as células são concluídas sem erros:

Reinicie o kernel para limpar qualquer estado obsoleto.
Execute todas as células de cima para baixo, cada célula deve ser concluída sem erros.

Se uma célula de transformação demorar mais de 5 minutos no nível Pequeno, seus filtros de entrada estão muito frouxos. Ajuste a projeção de data ou coluna antes de aumentar a escala.

Validar a tabela de saída

Confirme se a tabela de saída foi criada e contém os dados esperados:

No painel Tabelas Lake da extensão Sentinel, atualize e confirme se a tabela de saída aparece com o esquema esperado.
Execute uma célula de verificação:

verify_df = data_provider.read_table("EntraGroups_Processed_SPRK")
print("Row count:", verify_df.count())
verify_df.printSchema()
verify_df.show(5, truncate=False)

Teste de escalabilidade em conjunto médio ou grande

Verifique se o notebook produz resultados consistentes em tamanhos de pool maiores:

Execute novamente o notebook na configuração Média (e na Grande, caso seu conjunto de dados exija isso).
Confirme se a contagem de linhas e a distribuição de colunas correspondem à execução no nível Pequeno. Se eles divergirem, você tem uma transformação não determinística que precisa de investigação.

Testar casos extremos

Entrada vazia: aponte para uma tabela ou intervalo de datas com zero linhas. O notebook deve falhar de forma controlada ou gerar uma saída vazia — não travar.
Desvio de esquema: Se a tabela de entrada ganhar uma coluna, o notebook ainda deverá funcionar. Nunca presuma a ordem posicional.

Agendar o notebook como uma tarefa

A maioria das soluções de notebook publicadas são executadas em um cronograma — linha de base horária, verificação diária de anomalias e assim por diante. A extensão do Sentinel transforma qualquer notebook salvo em um trabalho agendado executado sem supervisão em um pool gerenciado do Spark.

Criar a tarefa

Para converter o notebook em um trabalho agendado, conclua as seguintes etapas:

Abra seu bloco de anotações no VS Code.
Selecione Criar trabalho de agenda no bloco de anotações e, em seguida, escolha Usar bloco de anotações existente quando solicitado.

Para obter mais informações, veja Criar e gerir tarefas de blocos de notas do Jupyter.

Configurar a tarefa

Para configurar o trabalho agendado, preencha os seguintes campos:

Insira um Nome do Job no formato kebab-case que descreva o notebook (por exemplo, failed-signin-baseline-hourly).
Insira uma Descrição de uma frase que abranja a finalidade do job e a tabela de saída.
Selecione o tamanho do pool do Spark que você validou durante o teste. Não use um tamanho excessivo — os jobs são executados neste pool a cada invocação.
Para o Agendamento, escolha Sob demanda para execuções manuais ou Agendado com uma frequência de repetição (minuto, hora, diária, semanal ou mensal).
Selecione Enviar para publicar o trabalho.

Verificar a tarefa

Depois de enviar, confirme se o trabalho está sendo executado corretamente:

Mude para o painel Jobs na extensão Sentinel — sua tarefa deverá aparecer.
Selecione o trabalho >Executar agora para uma execução de validação imediata.
Após a execução ser concluída, vá para a guia Histórico de execuções para verificar os logs e os tempos.

Importante

Os trabalhos enviados são dissociados do arquivo local .ipynb . A edição do arquivo local não atualiza o trabalho em execução. Para atualizar um trabalho: abra-o no painel Jobs>Baixe o notebook> edite >Editar trabalho>Enviar para carregar a versão atualizada.

Ver a tarefa no portal do Defender

Acesse Microsoft Sentinel>Exploração do Data Lake>Tarefas. Você pode habilitar ou desabilitar o agendamento e visualizar o histórico de execução aqui, mas não pode editar o notebook pelo portal.

Empacote e publique sua solução em notebook

Depois que seu notebook for testado e materializado, empacote-o para implantação aos clientes. Para obter instruções detalhadas de empacotamento, consulte Empacotar e publicar soluções de gráfico e notebook do Microsoft Sentinel.

Solução de problemas

Criação de notebooks

Sintoma	Causa e correção prováveis
`MicrosoftSentinelProvider` não encontrado	A extensão não entrou ou você abriu um kernel não Spark. Entre na extensão Microsoft Sentinel e selecione o Microsoft Sentinel runtime quando solicitado.
A célula trava em "Iniciando a sessão do Spark"	A inicialização da primeira célula leva de 3 a 5 minutos. Após 6 minutos, verifique o indicador de utilização de vCore na barra de status — o pool pode ter atingido a capacidade máxima. Experimente um tamanho de pool menor.
`save_as_table` falha com permissão negada na camada de análise	A identidade gerenciada por data-lake `msg-resources-<guid>` não possui o Log Analytics Contributor no workspace do Log Analytics. Atribua-o de acordo com os pré-requisitos e tente novamente.
A tabela de saída aparece no painel Tabelas do Lake mas está vazia	`.filter()` provavelmente removeu todas as linhas. Adicione uma impressão da contagem de linhas imediatamente antes de `save_as_table` para localizar o problema.

Para obter mais informações, consulte Solução de problemas de Notebooks.

Agendamento de trabalho

Sintoma	Causa e correção prováveis
Edições locais em `.ipynb` não são refletidas na tarefa agendada	Os trabalhos enviados são dissociados do arquivo local. Baixe a tarefa do VS Code, edite-a e, em seguida, use Editar tarefa>Enviar para carregar a nova versão.
A tarefa é executada, mas não gera saída	Verifique a guia Histórico de execuções no painel Trabalhos—o registro de execução geralmente mostra a célula que falhou. A causa mais comum é o notebook estar lendo de uma tabela à qual a identidade em execução não tem acesso.