Configurações avançadas para notebooks do Jupyter e MSTICPy no Microsoft Sentinel

Este artigo descreve as configurações avançadas para trabalhar com notebooks Jupyter e MSTICPy no Microsoft Sentinel.

Para obter mais informações, consulte Usar notebooks Jupyter para procurar ameaças de segurança e Tutorial: Introdução aos notebooks Jupyter e MSTICPy no Microsoft Sentinel.

Pré-requisitos

Este artigo é uma continuação do Tutorial: Introdução aos notebooks Jupyter e MSTICPy no Microsoft Sentinel. Recomendamos que você execute o tutorial antes de continuar com os procedimentos avançados descritos abaixo.

Especificar parâmetros de autenticação para APIs do Azure e do Microsoft Sentinel

Este procedimento descreve como configurar parâmetros de autenticação para o Microsoft Sentinel e outros recursos de API do Azure em seu arquivo msticpyconfig.yaml.

Para adicionar a autenticação do Azure e as configurações da API do Microsoft Sentinel no editor de configurações do MSTICPy:

1. Prossiga para a próxima célula, com o código a seguir e execute-o:

   mpedit.set_tab("Data Providers")
   mpedit
   

2. Na guia Provedores de dados, selecione AzureCLI>Adicionar.

3. Selecione os métodos de autenticação a serem usados:

   • Embora você possa usar um conjunto diferente de métodos dos padrões do Azure, esse uso não é uma configuração típica.
   • A menos que você queira usar a autenticação env (variável de ambiente), deixe os campos clientId, tenantiIde clientSecret vazios.
   • Embora não seja recomendado, o MSTICPy também dá suporte ao uso de IDs e segredos do aplicativo cliente para sua autenticação. Nesses casos, defina os campos clientId, tenantide clientSecret diretamente na guia Provedores de dados.

4. Selecione Salvar arquivo para salvar as alterações.

Definir provedores de consulta de carregamento automático

Defina os provedores de consulta que você deseja que MSTICPy carregue automaticamente ao executar a função nbinit.init_notebook.

Quando você cria novos notebooks com frequência, os provedores de consulta de carregamento automático podem poupar tempo, garantindo que os provedores necessários sejam carregados antes de outros componentes, como funções dinâmicas e notebooklets.

Adicionar provedores de consulta de carregamento automático:

1. Prossiga para a próxima célula, com o código a seguir e execute-o:

   mpedit.set_tab("Autoload QueryProvs")
   mpedit
   

2. Na guia AutoLoad QueryProv:

   • Para provedores do Microsoft Sentinel, especifique o nome do provedor e o nome do espaço de trabalho ao qual você deseja se conectar.
   • Para outros provedores de consulta, especifique somente o nome do provedor.

   Cada provedor também tem os seguintes valores opcionais:

   • Conexão automática: essa opção é definida como True por padrão e MSTICPy tenta se autenticar no provedor imediatamente após o carregamento. MSTICPy pressupõe que você configurou as credenciais para o provedor em suas configurações.

   • Alias: Quando o MSTICPy carrega um provedor, ele atribui o provedor a um nome de variável do Python. Por padrão, o nome da variável é qryworkspace_name para provedores do Microsoft Sentinel e qryprovider_name para outros provedores.

     Por exemplo, se você carregar um provedor de consultas para o espaço de trabalho ContosoSOC, esse provedor de consulta será criado no ambiente do seu notebook com o nome qry_ContosoSOC. Adicione um alias se desejar usar algo mais curto ou mais fácil de digitar e lembrar. O nome da variável do provedor será qry_<alias>, em que <alias> é substituído pelo nome do alias que você forneceu.

     Os provedores que você carrega por esse mecanismo também são adicionados ao atributo MSTICPy current_providers, que é usado, por exemplo, no código a seguir:

     import msticpy
     msticpy.current_providers
     

3. Selecione Salvar configurações para salvar as alterações.

Definir componentes de MSTICPy carregados automaticamente

Este procedimento descreve como definir outros componentes que são carregados automaticamente pelo MSTICPy quando você executa a função nbinit.init_notebook.

Os componentes com suporte incluem, na seguinte ordem:

1. TILookup: a biblioteca do provedor de TI
2. GeoIP: o provedor de GeoIP que você deseja usar
3. AzureData: o módulo que você usa para consultar detalhes sobre os recursos do Azure
4. AzureSentinelAPI: o módulo que você usa para consultar a API do Microsoft Sentinel
5. Notebooklets: notebooklets do pacote msticnb
6. Tabela dinâmica: funções dinâmicas

Observação

Os componentes são carregados nessa ordem porque o componente dinâmico precisa de consulta e outros provedores carregados para localizar as funções dinâmicas que ele anexa às entidades. Para obter mais informações, veja a documentação de MSTICPy.

Definir componentes de MSTICPy carregados automaticamente:

1. Prossiga para a próxima célula, com o código a seguir e execute-o:

   mpedit.set_tab("Autoload Components")
   mpedit
   

2. Na guia Carregar componentes automaticamente, defina quaisquer valores de parâmetro conforme necessário. Por exemplo:

   • GeoIpLookup. Insira o nome do provedor de GeoIP que você deseja usar, GeoLiteLookup ou IPStack. Para saber mais, vejaAdicionar configurações do provedor de GeoIP.

   • Componentes AzureData e AzureSentinelAPI. Defina os seguintes valores:

     • auth_methods: substitua as configurações padrão para AzureCLI e conecte-se usando os métodos selecionados.
     • Conexão automática: defina como false para carregar sem se conectar.

     Para obter mais informações, consulte Especificar parâmetros de autenticação para APIs do Azure e do Microsoft Sentinel.

   • Notebooklets. O componente Notebooklets tem um único bloco de parâmetro: AzureSentinel.

     Especifique seu espaço de trabalho do Microsoft Sentinel usando a seguinte sintaxe: workspace:\<workspace name>. O nome do espaço de trabalho deve ser um dos espaços de trabalho definidos na guia Microsoft Sentinel.

     Se você quiser adicionar mais parâmetros para enviar para a função notebooklets init, especifique-os como pares chave:valor separados por novas linhas. Por exemplo:

     workspace:<workspace name>
     providers=["LocalData","geolitelookup"]
     

     Para obter mais informações, consulte a documentação do MSTICNB (MSTIC Notebooklets).

   Alguns componentes, como TILookup e Tabela dinâmica não exigem parâmetros.

3. Selecione Salvar configurações para salvar as alterações.

Alternar entre os kernels Python 3.6 e 3.8

Se você estiver alternando entre os kernels Python 3.65 e 3.8, talvez descubra que o MSTICPy e outros pacotes não são instalados conforme o esperado.

Isso pode acontecer quando o comando !pip install pkg for instalado corretamente no primeiro ambiente, mas não for instalado corretamente no segundo. Isso cria uma situação em que o segundo ambiente não consegue importar ou usar o pacote.

Recomendamos que você não use !pip install... para instalar pacotes nos notebooks do Azure ML. Em vez disso, você pode usar uma das seguintes opções:

• Use a mágica da linha %pip em um notebook. Execute:

  
  %pip install --upgrade msticpy
  

• Instalar a partir de um terminal:

  1. Abra um terminal nos notebooks do Azure ML e execute os seguintes comandos:

     conda activate azureml_py38
     pip install --upgrade msticpy
     

  2. Feche o terminal e reinicie o kernel.

Defina uma variável de ambiente para o arquivo msticpyconfig.yaml

Se você estiver executando no Azure ML e tiver o arquivo msticpyconfig.yaml na raiz da sua pasta de usuário, o MSTICPy localizará automaticamente essas configurações. No entanto, se você estiver executando os blocos de anotações em outro ambiente, siga as instruções nesta seção para definir uma variável de ambiente que aponta para o local do arquivo de configuração.

Definir o caminho para o arquivo msticpyconfig.yaml em uma variável de ambiente permite que você armazene o arquivo em um local conhecido e certifique-se de sempre carregar as mesmas configurações.

Use vários arquivos de configuração, com várias variáveis de ambiente, se você quiser usar configurações diferentes para diferentes notebooks.

1. Escolha um local para o arquivo msticpyconfig.yaml, como em ~/.msticpyconfig.yaml ou % userprofile%/msticpyconfig.yaml.

   Usuários do Azure ML: se você armazenar o arquivo de configuração em sua pasta de usuário do Azure ML, a init_notebook função MSTICPy (executar na célula de inicialização) localizará e usará automaticamente o arquivo, e você não precisará definir uma variável de ambiente MSTICPYCONFIG.

   No entanto, se você também tiver segredos armazenados no arquivo, é recomendável armazenar o arquivo de configuração na unidade local de computação. O armazenamento interno de computação é acessível somente para a pessoa que criou a computação, enquanto o armazenamento compartilhado pode ser acessado por qualquer pessoa com acesso ao seu espaço de trabalho do Azure ML.

   Para saber mais, confira O que é uma instância de computação no Azure Machine Learning?.

2. Se necessário, copie o arquivo msticpyconfig.yaml para o local selecionado.

3. Defina a variável de ambiente MSTICPYCONFIG para apontar para esse local.

Use um dos procedimentos a seguir para definir a variável de ambiente MSTICPYCONFIG.

Windows

Por exemplo, para definir a variável de ambiente MSTICPYCONFIG em sistemas Windows:

1. Mova o arquivo msticpyconfig.yaml para a instância de computação, conforme necessário.

2. Abra a caixa de diálogo Propriedades do sistema na guia Avançado.

3. Selecione Variáveis de ambiente... para abrir a caixa de diálogo Variáveis de ambiente.

4. Na área Variáveis do sistema, selecione Novo... e defina os valores da seguinte maneira:

   • Nome da variável: defina como MSTICPYCONFIG
   • Valor da variável: insira o caminho para o arquivo msticpyconfig.yaml

Linux

Este procedimento descreve como atualizar o arquivo .bashrc para definir a variável de ambiente MSTICPYCONFIG em sistemas Linux.

1. Mova o arquivo msticpyconfig.yaml para a instância de computação, conforme necessário.

2. Abra um terminal do Azure ML, como na página Notebooks do Microsoft Sentinel.

3. Verifique se você pode acessar o arquivo msticpyconfig.yaml.

   No terminal do Azure ML, seu diretório atual deve ser o diretório base do repositório de arquivos do Azure ML, montado no sistema Linux de computação. A saída deve ser semelhante ao seguinte exemplo:

   azureuser@alicecontoso-azml7:~/cloudfiles/code/Users/alicecontoso$
   

   Liste todos os arquivos no diretório base, incluindo o arquivo msticpyconfig.yaml, digitando ls.

4. Para mover o arquivo msticpyconfig.yaml para a instância de computação, insira:

   mv msticpyconfig.yaml ~
   

5. Use um dos seguintes processos para editar o arquivo .bashrc para sua variável de ambiente:

   Comando	Etapas
   vim	1. Execute: vim ~/.bashrc 2. Vá até o fim do arquivo pressionando SHIFT+G>End. 3. Crie uma nova linha digitando a e, em seguida, pressionando ENTER. 4. Adicione sua variável de ambiente e pressione ESC para voltar ao modo de comando. 5. Salve o arquivo digitando :wq.
   nano	1. Execute: nano ~/.bashrc 1. Vá até o fim do arquivo pressionando ALT+/ ou OPTION+/ . 1. Adicione a variável de ambiente e, em seguida, salve o arquivo. Pressione CTRL+X e, em seguida, Y.

   Adicione estas variáveis de ambiente:

   • Se você moveu o arquivo msticpyconfig.yaml, execute export MSTICPYCONFIG=~/msticpyconfig.yaml.
   • Se você não moveu o arquivo msticpyconfig.yaml, execute export MSTICPYCONFIG=~/cloudfiles/code/Users/<YOURNAME>/msticpyconfig.yaml.

Opções do Azure ML

Se você precisar armazenar o arquivo msticpyconfig.yaml em algum lugar que não seja a pasta do usuário do Azure ML, use uma das seguintes opções:

• Um arquivo nbuser_settings. py na raiz da sua pasta de usuário. Embora esse processo seja mais simples e menos intrusivo do que editar o arquivo kernel.json, ele só tem suporte quando você executa a função init_notebook no início do código do seu notebook. Embora esse seja o comportamento padrão, se você executar o código do notebook sem primeiro executar init_notebook, MSTICPy talvez não consiga localizar o arquivo de configuração.

  1. No terminal do Azure ML, crie o arquivo nbuser_settings. py na raiz da sua pasta de usuário, que é a pasta com o seu nome.

  2. No arquivo nbuser_settings.py, adicione as seguintes linhas:

       import os
       os.environ["MSTICPYCONFIG"] = "~/msticpyconfig.yaml"
     

  Esse arquivo é importado automaticamente pela função init_notebook e define a variável de ambiente MSTICPYCONFIG para o notebook atual.

• O arquivo kernel.json para seu kernel do Python. Use este procedimento se você planeja executar o notebook manualmente e, possivelmente, sem chamar a função init_notebook no início.

  Há kernels para Python 3.6 e Python 3.8. Se você usar ambos os kernels, edite ambos os arquivos.

  • Local do Python 3.8: /usr/local/share/jupyter/kernels/python38-azureml/kernel.json
  • Local do Python 3.6: /usr/local/share/jupyter/kernels/python3-azureml/kernel.json

  Para definir a variável de ambiente no arquivo kernel.jsonn:

  1. Faça uma cópia do arquivo kernel.json e abra o original em um editor. Talvez seja necessário usar sudo para substituir o arquivo kernel.json e o conteúdo do arquivo é semelhante ao exemplo a seguir:

     {
        "argv": [
        "/anaconda/envs/azureml_py38/bin/python",
        "-m",
        "ipykernel_launcher",
        "-f",
        "{connection_file}"
        ],
        "display_name": "Python 3.8 - AzureML",
        "language": "python"
     }
     

  2. Após o item "language", adicione a seguinte linha: "env": { "MSTICPYCONFIG": "~/msticpyconfig.yaml" }

     Certifique-se de adicionar a vírgula ao final da linha "language": "python". Por exemplo:

     {
         "argv": [
         "/anaconda/envs/azureml_py38/bin/python",
         "-m",
         "ipykernel_launcher",
         "-f",
         "{connection_file}"
         ],
         "display_name": "Python 3.8 - AzureML",
         "language": "python",
         "env": { "MSTICPYCONFIG": "~/msticpyconfig.yaml" }
     }
     

Observação

Para as opções do Linux e do Windows, você precisará reiniciar o servidor Jupyter para que ele pegue a variável de ambiente que você definiu.

Próximas etapas

Para obter mais informações, consulte:

Assunto	Mais referências
MSTICPy	- Configuração do pacote MSTICPy - Editor de Configurações MSTICPy - Configurando o ambiente do notebook. - Notebook MPSettingsEditor. Observação: o repositório do GitHub de notebooks do Azure Sentinel também contém um arquivo de modelo msticpyconfig.yaml com seções comentadas, o que pode ajudá-lo a compreender as configurações.
Notebooks Jupyter e Microsoft Azure Sentinel	- Criar seu primeiro notebook do Microsoft Azure Sentinel (série de blogs) - Notebook Jupyter: uma introdução - Documentação do MSTICPy - Documentação de notebooks do Microsoft Azure Sentinel - Infosec do Jupyterbook - Passo a passo sobre o Notebook Host Explorer do Linux - A motivo de usar o Jupyter para investigações de segurança - Investigações de Segurança com o Microsoft Azure Sentinel e Notebooks - Documentação do Pandas - Documentação do Bokeh