Desenvolver uma solução de notebook para o Microsoft Sentinel

Como parceiro ISV, pode desenvolver, testar, criar pacotes para e publicar soluções de análise em notebooks Jupyter na Microsoft Security Store como ofertas SaaS. O Microsoft Sentinel data lake suporta notebooks Jupyter que funcionam em pools Spark geridos contra grandes conjuntos de dados de segurança. Estes blocos de notas são ideais para a deteção de ataques discretos e prolongados, o estabelecimento de padrões de referência comportamentais, análises baseadas em IA/ML, o mapeamento dos percursos de dados sensíveis, visualizações de dados e enriquecimento de dados que as deteções tradicionais em KQL não conseguem exprimir.

Uma solução de plataforma de cadernos é tipicamente concebida para análise histórica, transformações complexas de dados e fluxos de trabalho recorrentes de processamento de dados. Escreve a saída numa tabela personalizada no data lake, na qual regras analíticas subsequentes, consultas de investigação, agentes do Security Copilot ou ferramentas MCP podem consumir os resultados da solução de notebook. O pacote .zip que submete ao Partner Center é declarado como sendo do tipo SentinelLake e contém os notebooks e, opcionalmente, um modelo ARM para os recursos do Azure a jusante de que o notebook necessita.

Este artigo guia-o pela construção, teste, embalagem e publicação de uma solução de portátil da plataforma Microsoft Sentinel para a Microsoft Security Store. Depois de completar este guia, terá:

Um caderno Jupyter funcional que lê dados do lago de dados Sentinel
Uma tarefa agendada que executa o notebook num agrupamento do Spark gerido
Um SentinelLake pacote ZIP (PackageManifest + pasta do notebook)
Listagem de uma oferta SaaS do Partner Center na Microsoft Security Store

Pré-requisitos

O seu locatário tem de estar integrado no data lake do Microsoft Sentinel. Verifica o teu estado de integração no portal Defender. Navegue atéDefinições>do Sistema>Microsoft Sentinel>Data Lake. O estado é Provisionado se o seu inquilino estiver pronto. Para obter instruções de ativação, consulte Ativar o data lake do Microsoft Sentinel.

Permissões necessárias

Operação/Recursos	Função necessária
A bordo do lago de dados Sentinel	Microsoft Entra ID - Administrador de Segurança ou Administrador Global
Integrar a área de trabalho do Sentinel no portal Defender	Proprietário da Subscrição ou Administrador de Acesso do Utilizador ao nível da subscrição e Contribuidor do Microsoft Sentinel ao nível da subscrição ou do grupo de recursos
Integrar espaço de trabalho do Sentinel no Data Lake	Proprietário da subscrição ou Contribuidor do Microsoft Sentinel ao nível da subscrição ou do grupo de recursos
Executar cadernos no data lake	Microsoft Sentinel Leitor ou Contribuidor
Log Analytics workspace (para reescrita na camada de análise)	Colaborador do Log Analytics atribuído à identidade gerida do data-lake `msg-resources-<guid>`
Centro de Parceiros Microsoft	Conta de publicador do Marketplace (uma única vez; mesma conta usada para a publicação de agentes do Security Copilot)

Note

A função de proprietário da subscrição é necessária para uma tarefa pontual de integração inicial no data lake. Use Microsoft Entra Privileged Identity Management (PIM) para subir temporariamente a esta função apenas quando necessário, e depois remova o acesso após a conclusão da integração.

Ferramentas necessárias

Código do Visual Studio.
Extensão Microsoft Sentinel VS Code
A extensão do VS Code GitHub Copilot é recomendada para acelerar a criação de notebooks.
Python 3.10+ instalado localmente. O kernel do Spark corre no Azure, mas o VS Code precisa de um interpretador local para edição de células.

Descrição geral do processo

O processo de publicação começa com o desenvolvimento local de notebooks e evolui para uma oferta SaaS empacotada, detetável na Microsoft Security Store.

Desenvolvimento local de notebooks (VS Code + extensão Sentinel)
Correr interativamente contra a plataforma Sentinela
Testar com dados representativos; validar que a tabela de saída é preenchida
Agendar como uma tarefa (a pedido ou agendada)
Empacotar como SentinelLake .zip (PackageManifest.yaml + pasta)
Criar Oferta SaaS no Centro de Parceiros Microsoft
Carregar o pacote, criar metadados, planear e fixar preços
Rever e Publicar, revisão automática, Lançar
Disponível na Microsoft Security Store

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

Todo o desenvolvimento de notebooks ocorre localmente no VS Code com a extensão Microsoft Sentinel instalada. O kernel do Spark corre no Azure — o VS Code é o editor e cliente de submissão.

Descarregue o Visual Studio Code a partir de https://code.visualstudio.com/ e instale-o com as opções predefinidas.
Abra o marketplace do VS Code >Extensões (Ctrl+Shift+X ou Cmd+Shift+X).
Pesquise por Sentinel e instale a extensão Microsoft Sentinel (publicador: ms-security).

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

Copilot conhece o MicrosoftSentinelProvider API e autocompleta as transformações PySpark.
Selecione o ícone do Microsoft Sentinel na barra de ferramentas à esquerda.
Aprove o diálogo de início de sessão e depois selecione a conta com Sentinel Reader / Contributor no seu espaço de trabalho.

O painel esquerdo mostra as tabelas do lago de dados e as Tarefas, confirmando que a extensão chegou ao lago de dados.

Atenção

Se tiveres vários locatários convidados com sessão iniciada, ao mudares de conta no canto inferior esquerdo do VS Code, todas as sessões ativas do PySpark são terminadas — precisas de reiniciar o kernel depois de mudares de conta. Planeie as mudanças de conta entre execuções, não durante as mesmas.

Desenvolva o seu caderno

Os cadernos usam este padrão de autoria:

Leia uma tabela data-lake num Spark DataFrame
Transformar com PySpark
Opcionalmente, enriquecer com dados externos
Escrever resultados numa tabela personalizada que o Sentinel possa consumir

Explore o painel das mesas do lago

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

Selecione o ícone do Sentinela e expanda as tabelas do Lago.
As tabelas estão agrupadas por base de dados e categoria (Sistema, Personalizada, Federada). Selecione qualquer tabela para ver as suas definições e tipos de colunas.
Identifica as tabelas de entrada que o teu caderno lê e anota os nomes exatos.

Criar um novo bloco de notas

Para criar um novo caderno Jupyter para a sua solução, complete os seguintes passos:

Prima Ctrl+Shift+P / Cmd+Shift+P> escreva Create New Jupyter Notebook, ou selecione File>New File>Jupyter Notebook.
Guarde o caderno com um nome descritivo (por exemplo, failed-signin-baseline.ipynb).

Leia 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 tempo de execução e execute a célula

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

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

A primeira corrida demora entre 3 a 5 minutos a pôr a sessão de Spark em marcha. As células subsequentes funcionam em segundos.

Transformar e reescrever numa tabela personalizada

O método save_as_table() grava um DataFrame numa tabela personalizada na camada lake (ou camada de análise). A tabela de destino é criada na primeira escrita.

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 blocos de notas

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

Padrão	Quando utilizá-lo
Linha de base + deriva	Calcular o comportamento normal para cada utilizador ou anfitrião; assinalar as linhas que se desviam do valor de referência. Clássico para análises de falhas no início de sessão e de execução de processos.
Junção entre tabelas	Junte-se à tabela lake que possui com tabelas incorporadas (LoginLogs, SecurityAlert, DeviceProcessEvents) em entidades partilhadas (UPN, host, IP).
Pontuação em ML	Treine ou carregue um modelo pré-treinado no notebook; atribua uma pontuação a cada linha; grave as N linhas de maior risco numa tabela de saída personalizada para alertas subsequentes.
Investigação visual	Plotar linhas temporais, mapas de calor e árvores de processos com matplotlib ou plotly; exportar o caderno como HTML para transferência.

Sugestão

Utilize células Markdown com frequência para documentar o seu código. Um revisor da Security Store — e o analista SOC que gere o seu caderno — precisa de perceber o que cada secção faz sem ler o código. Coloque uma célula de markdown acima de cada bloco de código explicando o propósito, entradas, saídas e saída esperada. Os revisores tratam cadernos pouco claros como uma falha total.

Testar o portátil

Os testes requerem provar que o caderno corre de ponta a ponta com dados realistas e produz uma tabela de saída utilizável.

Teste de fumo em piscina pequena

Execute o caderno de ponta a ponta para confirmar que cada célula está completa sem erro:

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

Se uma célula de transformação demorar mais de 5 minutos em Pequeno, os teus filtros de entrada estão demasiado soltos. Aperte a projeção de data ou coluna antes de aumentar a escala.

Validar a tabela de saída

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

No painel de tabelas Lake da extensão Sentinel, atualize e confirme que a sua tabela de saída aparece com o esquema esperado.
Executar 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 escala em piscina média ou grande

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

Execute novamente o notebook em Médio (e em Grande, se o seu conjunto de dados o justificar).
Confirme que o número de linhas e as distribuições das colunas correspondem à execução pequena. Se divergirem, tem uma transformação não determinística que precisa de ser investigada.

Testar casos limite

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 falhar abruptamente.
Desvio do esquema: Se a sua tabela de entrada ganhar uma coluna, o notebook deve continuar a ser executado. Nunca presumas a ordem posicional.

Agende o caderno como um trabalho

A maioria das soluções de notebooks publicadas é executada segundo um agendamento — linha de base de hora a hora, análise diária de anomalias, entre outros casos. A extensão Sentinel transforma qualquer caderno guardado num trabalho agendado que corre sem vigilância num pool Spark gerido.

Criar a tarefa

Para converter o caderno numa tarefa agendada, complete os seguintes passos:

Abra o seu caderno no VS Code.
Selecione Criar Trabalho de Agendamento no caderno e depois escolha Usar caderno 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:

Introduza um Nome da tarefa em kebab-case que descreva o bloco de notas (por exemplo, failed-signin-baseline-hourly).
Introduza uma Descrição numa frase que descreva a finalidade da tarefa e a respetiva tabela de saída.
Selecione o tamanho do pool do Spark que validou durante os testes. Não sobredimensionem — os trabalhos correm neste pool em todas as invocações.
Para o Agendamento, escolha A pedido para execuções manuais, ou Agendado com uma frequência de repetição (por minuto, de hora a hora, diária, semanal ou mensal).
Selecione Enviar para publicar o trabalho.

Verificar a tarefa

Depois de submeter, confirme que o trabalho está a correr corretamente:

Mude para o painel de Empregos na extensão Sentinel — o seu trabalho deve aparecer.
Selecione o trabalho >Executar agora para uma execução imediata de validação.
Depois da execução terminar, mude para o separador Histórico de Execuções para inspecionar registos e temporização.

Importante

Os trabalhos submetidos são desacoplados do teu ficheiro local .ipynb . Editar o ficheiro local não atualiza o trabalho em execução. Para atualizar um trabalho: abre-o no painel >Descarregar o caderno> editar >Editar trabalho>Submeter para carregar a versão atualizada.

Veja o trabalho no portal Defender

Navegue até Microsoft Sentinel>Exploração do data lake>Tarefas. Pode ativar ou desativar o agendamento e ver o histórico de execuções aqui, mas não pode editar o bloco de notas no portal.

Empacote e publique a solução do seu notebook

Assim que o seu portátil estiver testado e materializado, empacote-o para distribuição aos clientes. Para instruções detalhadas de embalagem, consulte Empacotar e publicar soluções para grafos e cadernos Microsoft Sentinel.

Troubleshooting

Criação de cadernos

Symptom	Causa provável e solução
`MicrosoftSentinelProvider` não encontrado	Extensão não iniciada, ou então abriste um kernel não Spark. Inicie sessão na extensão Microsoft Sentinel e selecione o runtime Microsoft Sentinel quando solicitado.
A célula fica bloqueada na "Sessão de início do Spark"	O arranque da primeira célula demora entre 3 a 5 minutos. Após 6 minutos, verifique o indicador de utilização do vCore na barra de estado — a sua piscina pode estar cheia. Experimenta uma piscina de tamanho menor.
`save_as_table` falha devido a permissão negada no escalão de análise	A identidade gerida do data lake `msg-resources-<guid>` não tem a função Log Analytics Contributor no espaço de trabalho do Log Analytics. Atribui-o conforme os pré-requisitos e tenta novamente.
A tabela de saída aparece no painel de tabelas Lake , mas está vazia	A `.filter()` provavelmente removeu todas as linhas. Adicione uma impressão com contagem de linhas imediatamente antes `save_as_table` para localizar o problema.

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

Agendamento de tarefas

Symptom	Causa provável e solução
As alterações no local `.ipynb` não são refletidas na tarefa agendada	Os trabalhos submetidos são desacoplados do ficheiro local. Descarrega o trabalho do VS Code, edita-o e depois usa Editar Enviar Trabalho> para carregar a nova versão.
A tarefa é executada mas não produz qualquer saída	Verifique o separador Histórico de Execuções no painel de Trabalhos — o registo de execução normalmente mostra a célula com falha. A causa mais comum é o notebook estar a ler dados de uma tabela à qual a identidade utilizada na execução não tem acesso.