Regras de contribuição da comunidade para integrações de respostas

Compatível com:

Google secops SOAR

Este documento descreve as diretrizes para enviar integrações de respostas ao Google SecOps através de contribuições da comunidade. Todas as integrações enviadas são sujeitas a um processo de validação pela equipa oficial de SecOps da Google, com foco nos requisitos realçados neste documento.

Metadados de integração de respostas

Nome

O Nome deve corresponder ao nome do produto com o qual a integração vai ser integrada e não deve conter carateres especiais.

O Nome a apresentar deve ser escrito com espaços em branco; por exemplo, Vertex AI e não VertexAI.

Identificador de integração

O identificador de integração é um identificador exclusivo da integração. Não é possível alterar este valor depois de criar a integração. O identificador deve ter o mesmo valor que Name, mas com os espaços em branco removidos.

O identificador está disponível na maioria dos locais na plataforma.

Descrição

A descrição deve fornecer uma vista geral de alto nível do produto com o qual a integração é criada e não deve exceder os 500 carateres. Tem de conter as seguintes informações:

This integration is owned by the "{vendor name}". Support Contact: {email}.

Evite colocar URLs na descrição.

Logótipos

Cada integração deve ser fornecida com um ícone SVG. Este ícone deve adaptar-se aos temas na plataforma. Os ícones só devem herdar o tema da plataforma.

Deve validar o logótipo nas seguintes páginas:

• Resposta > Configuração da integração
• Resposta > Guias interativos > Designer de guias interativos
• Casos > Alerta > Vista do plano de ação de alertas

Segue-se um exemplo de um logótipo SVG concebido para corresponder ao nosso guia de estilo:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>
        

Certifique-se de que codifica o SVG antes de o adicionar ao ficheiro de definição da integração, como pode encontrar noutras integrações no mercado.

Link da documentação

Como parte da integração, pode adicionar um link que direcione os utilizadores para a documentação. Esta documentação deve ser alojada por si.

Os utilizadores podem aceder ao link da documentação a partir da secção Parâmetros do diálogo Configurar instância.

Parâmetros de configuração

Todas as integrações devem conter parâmetros de configuração (API Root + parâmetros de autenticação), a menos que a API subjacente não exija autenticação e a API Root possa ser codificada. Para todas as integrações em que a autenticação é necessária, deve existir um parâmetro Verify SSL.

Todos os parâmetros devem ter uma descrição. A descrição deve ajudar os utilizadores a configurar a integração a partir da plataforma. Evite colocar URLs na descrição dos parâmetros.

Ação de ping

A ação Ping é uma ação especial usada pela plataforma para validar a conetividade da API. Esta ação é obrigatória, mesmo que a sua integração não tenha outras ações. Sempre que o utilizador premir o botão Testar na configuração da integração, deve ser apresentado um estado preciso da conetividade.

Notas de lançamento

A estrutura geral da nota de lançamento deve seguir o seguinte formato:

• {integration item} - {update}
• Por exemplo: Get Case Details - Added ability to fetch information about affected IOCs

Consoante a situação, existem notas de lançamento únicas para cenários específicos:

• Se for uma nova integração: New Integration Added - {integration name}
• Se for adicionada uma nova ação: New Action Added - {action name}
• Se for adicionado um novo conetor: New Connector Added - {connector name}
• Se for adicionada uma nova tarefa: New Job Added - {job name}
• Se for adicionado um widget predefinido a uma ação: {action name} - Added Predefined Widget.
• Se um widget predefinido for atualizado: {action name} - Updated Predefined Widget.
• Para alterações que afetam todos os itens de integração: Integration - {Update}
• Para alterações que afetam todas as ações: Integration's Actions - {Update}
• Para alterações que afetam todos os conetores: Integration's Connectors - {Update}
• Para alterações que afetam todas as tarefas: Integration's Jobs - {Update}

Se o lançamento contiver uma alteração regressiva, tem de especificar REGRESSIVE! na nota de lançamento. Por exemplo, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

As notas de lançamento estão disponíveis no painel lateral Detalhes da integração que é apresentado quando clica no botão Detalhes na integração.

Controlo de versões

Cada atualização da integração deve ser seguida de uma atualização +1 à versão da integração. As versões devem ser representadas como um número inteiro. Não são permitidas versões secundárias, como 11.1.3 ou 11.1.

Etiquetas

Opcionalmente, pode adicionar etiquetas à sua integração. Evite criar novos tipos de etiquetas. Use as que já estão na plataforma. Se não vir uma etiqueta adequada para si, consulte a equipa de validação.

Notas gerais

• Teste todo o conteúdo de integração antes do envio.
• Reveja todo o conteúdo de integração para verificar a existência de potenciais vulnerabilidades e dependências vulneráveis.
• Use sempre a versão suportada mais recente do Python durante o desenvolvimento (Python 3.11).

Ações

Nome

O Nome da ação deve apontar para a atividade que está a ser realizada; por exemplo, Obter detalhes do registo, Listar eventos de entidades ou Executar pesquisa.

Se a ação for concebida para funcionar principalmente com entidades, é preferível colocar Entity no nome; por exemplo, Enrich Entities.

Os nomes das ações devem ser transmitidos em 2 a 3 palavras.

Descrição

A descrição da ação deve realçar ao utilizador qual será o resultado da execução da ação.

Se a ação funcionar com entidades, tem de anexar informações sobre que tipo de entidades são suportadas. Por exemplo:

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Se a ação funcionar no modo Async, tem de fornecer a seguinte nota na descrição:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Tente limitar a descrição a 500 carateres.

Parâmetros de ações

Os parâmetros de configuração de ações devem ter um nome intuitivo. Evite usar carateres especiais e tente limitar o nome do parâmetro de ação a 2 a 4 palavras.

A descrição do parâmetro deve explicar ao utilizador o impacto que esse parâmetro tem na execução da ação. Se o parâmetro suportar uma quantidade predeterminada de valores suportados, na descrição, forneça a seguinte secção: Possible Values: {value 1}, {value 2}

Resultado da ação (resultado do script)

O resultado do script deve representar um resultado simples da ação. Na maioria dos casos, deve apontar para uma variável denominada is_success, que pode assumir os valores true ou false.

Em geral, se a ação tiver terminado a execução e realizado uma operação, is_success deve ser true.

Resultado da ação (resultado JSON)

O resultado JSON é o resultado mais importante da ação. Todos os dados disponíveis no resultado JSON vão estar acessíveis durante a execução do manual de procedimentos. Verifique se está a ser enviado um objeto JSON válido para a saída.

Os resultados JSON têm um limite de 15 MB.

Quando cria um resultado JSON, certifique-se de que não existem chaves que sejam únicas durante a execução. Por exemplo, o seguinte objeto JSON representa uma estrutura deficiente, uma vez que seria inutilizável em manuais de procedimentos:

{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}
    

Em vez disso, formate-o da seguinte forma:

[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]
   

Se estiver a usar entidades na ação e a devolver resultados por entidade, a prática recomendada é estruturar o resultado JSON da seguinte forma:

[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]
    

Considere sempre como o resultado da ação pode ser usado na automatização.

Certifique-se de que existe um exemplo JSON para a sua ação.

O exemplo JSON é usado pela plataforma no Criador de expressões durante o processo de criação do guião. Um exemplo de JSON preciso melhora significativamente a experiência de criação de manuais de procedimentos. Remova todas as informações de PII dos exemplos JSON.

Resultados da ação (enriquecimento de entidades)

Se as ações estiverem a ser executadas em entidades, durante a execução das ações, pode anexar-lhes metadados adicionais. A estrutura desses metadados deve seguir este formato: {integration identifier}_{key}. Por exemplo: WebRisk_is_malicious.

Pode encontrar os metadados adicionados na página de detalhes das entidades.

Resultados da ação (mensagem de saída)

A mensagem de saída deve explicar ao utilizador como a execução da ação decorreu de forma mais descritiva. Deve indicar ao utilizador o resultado da execução da ação.

Se alguns recursos foram enriquecidos com êxito, mas outros não, a prática recomendada é fornecer informações de estado para cada recurso fornecido na mensagem.

Se considerar que ocorreu um erro crítico durante a execução da ação, certifique-se de que existe uma mensagem detalhada para esta situação e que a ação falha. Quando a ação falha, o manual de soluções correspondente interrompe a execução até o erro ser resolvido ou ignorado manualmente.

Alguns exemplos de mensagens de saída:

• Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
• Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
• None of the provided entities were found in VirusTotal.
• Successfully executed query "{query}" in Google SecOps.

Se a ação falhar e parar a execução do manual de procedimentos, é recomendado que a mensagem de saída tenha a seguinte estrutura:

"Error executing action "{action name}". Reason: {error}'

Evite colocar todo o rastreio de erros. Em alternativa, tente indicar ao utilizador o problema real em linguagem natural.

Conetores

Nome

O Nome do conector deve direcionar o utilizador para os dados que vão ser carregados. Em geral, a estrutura do nome deve ser a seguinte:

• {integration display name} - {data that is being ingested} Connector
• Por exemplo: Crowdstrike - Pull Alerts Connector

Descrição

A descrição do conetor deve realçar para o utilizador o que vai ser carregado pelo conetor; por exemplo, Pull alerts from Crowdstrike. Além disso, tem de fornecer informações sobre o suporte de listas dinâmicas; por exemplo, Dynamic List works with the display_name parameter.

Neste caso, a descrição final teria o seguinte aspeto:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Tente limitar a descrição a 500 carateres.

Parâmetros do conetor

Os parâmetros de configuração do conector devem ter um nome intuitivo. Evite usar carateres especiais e tente limitar o nome do parâmetro de ação a 2 a 4 palavras.

A descrição do parâmetro deve explicar ao utilizador o impacto que esse parâmetro tem na execução do conetor.

Se o parâmetro suportar uma quantidade predeterminada de valores suportados, então, na descrição, forneça a seguinte secção: Possible Values: {value 1}, {value 2}. deve ter os seguintes parâmetros:

• Máximo de alertas a obter: determina quantos {object} devem ser processados durante 1 iteração do conetor.
• Máximo de {horas/dias} para trás: determina a hora de início na primeira iteração do conector. Por exemplo, se Máximo de horas para trás estiver definido como 1, o conector começa a extrair dados de uma hora antes.
• Validar SSL: valida a conetividade à API/instância.

Mapeamento de ontologias

Para cada conector criado, recomendamos que forneça um mapeamento da ontologia para verificar se os clientes mútuos têm a melhor experiência.

O mapeamento de ontologias é usado para criar automaticamente entidades (IOCs e recursos). Além disso, os metadados críticos dos campos do sistema, como a Hora de início e a Hora de fim, são definidos aí.

Lista dinâmica

A lista dinâmica é uma funcionalidade opcional que lhe permite criar um filtro avançado para carregamento. Tem a flexibilidade de criar qualquer lógica personalizada com ele, ao mesmo tempo que tem uma experiência do utilizador única. O exemplo de utilização mais comum é definir uma lista de permissões ou uma lista de bloqueios para a carregamento.

Se estiver a criar lógica personalizada para a lista dinâmica, certifique-se de que esta é fornecida na descrição do conector. Além disso, é recomendado ter um parâmetro Usar lista dinâmica como lista de bloqueios para também ter a lógica inversa suportada.

Empregos

Nome

O Nome da tarefa deve explicar ao utilizador o que esta tarefa está a fazer. Em geral, a estrutura do nome deve ser a seguinte:

• {integration display name} - {process} Job
• Por exemplo: ServiceNow - Sync Incidents Job

Descrição

A Descrição da tarefa deve realçar para o utilizador o que a tarefa está a fazer durante as iterações; por exemplo, This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Tente limitar a descrição a 500 carateres.

Parâmetros de trabalho

Os parâmetros de configuração da tarefa devem ter um nome intuitivo. Evite usar carateres especiais e tente limitar o nome do parâmetro de ação a 2 a 4 palavras.

A descrição do parâmetro deve explicar ao utilizador o impacto que esse parâmetro tem na execução da tarefa.

Se o parâmetro suportar uma quantidade predeterminada de valores suportados, inclua a seguinte secção na descrição:

Possible Values: {value 1}, {value 2}.

Além dos parâmetros de autenticação, todas as tarefas devem ter os seguintes parâmetros:

• Máximo de {horas/dias} para trás: determina a hora de início na primeira iteração da tarefa.
• Validar SSL: valida a conetividade à API/instância.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais da Google SecOps.