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

Compatível com:

Este documento descreve as diretrizes para enviar integrações de resposta à Google SecOps por contribuições da comunidade. Todas as integrações enviadas passam por um processo de análise da equipe oficial do Google SecOps, com foco nos requisitos destacados neste documento.

Metadados de integração de resposta

Nome

O Nome precisa corresponder ao nome do produto com que a integração será feita e não pode conter caracteres especiais.

O Nome de exibição precisa ser escrito com espaços em branco. Por exemplo, Vertex AI e não VertexAI.

Identificador de integração

O identificador da integração é um identificador exclusivo da integração. Depois que a integração é criada, esse valor não pode ser mudado. O identificador precisa ter o mesmo valor de Name, mas com os espaços em branco removidos.

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

Descrição

A descrição precisa fornecer uma visão geral do produto com que a integração foi criada e não pode exceder 500 caracteres. Ele precisa conter as seguintes informações:

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

Evite colocar URLs na descrição.

Logotipos

Cada integração precisa ter um ícone SVG. Esse ícone precisa se adaptar aos temas da plataforma. Os ícones só podem herdar o tema da plataforma.

Valide o logotipo nas seguintes páginas:

Confira um exemplo de logotipo SVG, projetado 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>

Codifique o SVG antes de adicioná-lo ao arquivo de definição de integração, como pode ser encontrado em outras integrações no marketplace.

Como parte da integração, você pode adicionar um link que direciona os usuários à documentação. Essa documentação precisa ser hospedada por você.

Os usuários podem acessar o link da documentação na seção Parâmetros da caixa de diálogo Configurar instância.

Parâmetros de configuração

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

Todos os parâmetros precisam ter uma descrição. A descrição precisa ajudar os usuários a configurar a integração na plataforma. Evite colocar URLs na descrição dos parâmetros.

Ação de ping

A ação de ping é especial e usada pela plataforma para validar a conectividade da API. Essa ação é obrigatória mesmo que sua integração não tenha outras ações. Sempre que o usuário pressionar o botão Testar na configuração da integração, um status preciso da conectividade vai aparecer.

Notas de lançamento

A estrutura geral da nota da versão deve seguir este formato:

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

Dependendo da situação, há notas de versão exclusivas para cenários específicos:

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

Se a versão tiver uma mudança regressiva, especifique REGRESSIVE! na nota da versão. Por exemplo, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

As notas da versão estão disponíveis no painel lateral Detalhes da integração, que aparece quando você clica no botão Detalhes na integração.

Controle de versões

Cada atualização de integração precisa ser seguida por uma atualização +1 na versão da integração. As versões precisam ser representadas como um número inteiro. Versões secundárias, como 11.1.3 ou 11.1, não são permitidas.

Tags

Se quiser, adicione tags à sua integração. Evite criar novos tipos de tags. Use as que já estão na plataforma. Se você não encontrar uma tag adequada, consulte a equipe de análise.

Observações gerais

  • Teste todo o conteúdo de integração antes do envio.
  • Analise todo o conteúdo da integração em busca de possíveis vulnerabilidades e dependências vulneráveis.
  • Sempre use a versão mais recente compatível do Python durante o desenvolvimento (Python 3.11).

Ações

Nome

O Nome da ação precisa apontar para a atividade que está sendo realizada. Por exemplo, Receber detalhes do caso, Listar eventos da entidade ou Executar pesquisa.

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

Os nomes das ações precisam ser transmitidos em duas ou três palavras.

Descrição

A descrição da ação precisa destacar para o usuário qual será o resultado da execução.

Se a ação funcionar com entidades, adicione informações sobre quais tipos são compatíveis. 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, inclua a seguinte observação 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 caracteres.

Parâmetros de ação

Os parâmetros de configuração de ação precisam ter um nome intuitivo. Evite usar caracteres especiais e tente limitar o nome do parâmetro de ação a duas a quatro palavras.

A descrição do parâmetro precisa explicar ao usuário qual é o impacto dele na execução da ação. Se o parâmetro aceitar uma quantidade predeterminada de valores compatíveis, forneça a seguinte seção na descrição: Possible Values: {value 1}, {value 2}

Saída da ação (resultado do script)

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

Em geral, se a ação terminar a execução e realizar uma operação, is_success será true.

Saída da ação (resultado em JSON)

O resultado em JSON é a saída mais importante da ação. Todos os dados disponíveis no resultado JSON poderão ser acessados durante a execução do playbook. Verifique se um objeto JSON válido está sendo enviado para a saída.

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

Ao criar um resultado JSON, verifique se não há chaves que serão exclusivas durante a execução. Por exemplo, o objeto JSON a seguir representa uma estrutura ruim, já que não pode ser usado em playbooks:


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

Em vez disso, formate assim:


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

Se você estiver usando entidades dentro da ação e retornando resultados por entidade, a prática recomendada é estruturar o resultado JSON assim:


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

Sempre considere como a saída da ação pode ser usada na automação.

Verifique se há um exemplo de JSON para sua ação.

A amostra JSON é usada pela plataforma no Criador de expressões durante o processo de criação do playbook. Uma amostra de JSON precisa melhora muito a experiência de criação de playbook. Remova todas as informações de PII das amostras JSON.

Saídas de ação (enriquecimento de entidade)

Se as ações estiverem sendo executadas em entidades, você poderá anexar mais metadados a elas durante a execução. A estrutura desses metadados precisa seguir este formato: {integration identifier}_{key}. Por exemplo: WebRisk_is_malicious.

Os metadados adicionados estão na página de detalhes das entidades.

Saídas de ação (mensagem de saída)

A mensagem de saída precisa explicar ao usuário como a execução da ação foi realizada de maneira mais descritiva. Ele deve indicar ao usuário o resultado da execução da ação.

Se algumas entidades foram enriquecidas, mas outras não, a prática recomendada é fornecer informações de status para cada entidade na mensagem.

Se você acredita que um erro crítico foi encontrado durante a execução da ação, verifique se há uma mensagem detalhada para essa situação e falhe a ação. Quando a ação falha, o playbook correspondente interrompe a execução até que o erro seja 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 interromper a execução do manual, é recomendável que a mensagem de saída tenha a seguinte estrutura:

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

Evite colocar todo o rastreamento de erros. Em vez disso, tente apontar o problema real para o usuário em linguagem natural.

Conectores

Nome

O Nome do conector precisa indicar ao usuário os dados que serão ingeridos. Em geral, a estrutura do nome deve ser assim:

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

Descrição

A Descrição do conector precisa destacar para o usuário o que será ingerido por ele, por exemplo, Pull alerts from Crowdstrike. Além disso, você precisa fornecer informações sobre o suporte a listas dinâmicas, por exemplo, Dynamic List works with the display_name parameter..

A descrição final neste caso ficaria assim:

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

Tente limitar a descrição a 500 caracteres.

Parâmetros do conector

Os parâmetros de configuração do conector precisam ter um nome intuitivo. Evite usar caracteres especiais e tente limitar o nome do parâmetro de ação a duas a quatro palavras.

A descrição do parâmetro precisa explicar ao usuário qual é o impacto dele na execução do conector.

Se o parâmetro aceitar uma quantidade predeterminada de valores compatíveis, forneça a seguinte seção na descrição: Possible Values: {value 1}, {value 2}. precisa ter os seguintes parâmetros:

  • Máximo de alertas a serem buscados: determina quantos {object} serão processados durante uma iteração do conector.
  • Máximo {Horas/Dias} para trás: determina o horário 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 vai começar a extrair dados de uma hora antes.
  • Verificar SSL: verifica a conectividade com a API/instância.

Mapeamento de ontologia

Para cada conector criado, é recomendável fornecer um mapeamento de ontologia para verificar se os clientes em comum têm a melhor experiência.

O mapeamento de ontologia é usado para criar entidades automaticamente (IOCs e recursos). Além disso, os metadados críticos de campos do sistema, como Horário de início e Horário de término, são definidos lá.

Lista dinâmica

A lista dinâmica é um recurso opcional que permite criar um filtro avançado para ingestão. Você tem a flexibilidade de criar qualquer lógica personalizada com ele, além de ter uma UX exclusiva. O caso de uso mais comum é definir uma lista de permissões ou de bloqueio para ingestão.

Se você estiver criando uma lógica personalizada para lista dinâmica, verifique se ela está na descrição do conector. Além disso, é recomendável ter um parâmetro Usar lista dinâmica como uma lista de bloqueio para que a lógica inversa também seja compatível.

Jobs

Nome

O nome do trabalho precisa explicar ao usuário o que ele está fazendo. Em geral, a estrutura do nome deve ser assim:

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

Descrição

A Descrição do job precisa destacar para o usuário o que o job está fazendo 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 caracteres.

Parâmetros do job

Os parâmetros de configuração do job precisam ter um nome intuitivo. Evite usar caracteres especiais e tente limitar o nome do parâmetro de ação a duas ou quatro palavras.

A descrição do parâmetro precisa explicar ao usuário qual é o impacto dele na execução do job.

Se o parâmetro aceitar uma quantidade predeterminada de valores compatíveis, forneça a seguinte seção na descrição:

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

Além dos parâmetros de autenticação, todos os jobs precisam ter os seguintes parâmetros:

  • Máximo de {horas/dias} para trás: determina o horário de início na primeira iteração do job.
  • Verificar SSL: verifica a conectividade com a API/instância.

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