Integrar a APIVoid ao Google SecOps

Neste documento, descrevemos como integrar a APIVoid ao Google Security Operations (Google SecOps).

Antes de começar

Antes de configurar a integração da APIVoid no Google SecOps para v2, verifique se você tem o seguinte:

  • Conta da APIVoid v2: uma conta ativa com acesso aos serviços da API v2.

  • Chave de API da APIVoid v2: uma nova chave de API gerada especificamente para APIs v2 no painel do usuário da APIVoid.

  • Endpoints de API atualizados: familiaridade com os URLs de endpoint de API v2 atualizados para os serviços específicos da APIVoid que você planeja usar (como a API IP Reputation e a API Domain Reputation).

Gerar uma chave de API da APIVoid v2

Para gerar sua chave de API da APIVoid v2, siga estas etapas:

  1. Faça login no painel do usuário da APIVoid.

  2. Acesse a seção Chaves de API. O local pode variar dependendo das atualizações do painel.

  3. Gere uma nova chave de API. Copie e armazene a chave imediatamente em um local seguro. Ele só pode ser exibido uma vez.

Rede

Função Porta padrão Direção Protocolo
API Multivalores Saída apikey

Parâmetros de integração

Use os seguintes parâmetros para configurar a integração:

Nome do parâmetro Tipo Valor padrão É obrigatório Descrição
Nome da instância String N/A Não Nome da instância em que você quer configurar a integração.
Descrição String N/A Não Descrição da instância.
Raiz da API String https://endpoint.apivoid.com Sim Endereço da instância do APIVoid.
Chave da API Senha N/A Sim Chave de API gerada no console da APIVoid.
Verificar SSL Caixa de seleção Desmarcado Não Marque esta caixa de seleção se a conexão da APIVoid exigir uma verificação de SSL.
Executar remotamente Caixa de seleção Desmarcado Não Marque o campo para executar a integração configurada remotamente. Depois de marcada, a opção de selecionar o usuário remoto (agente) aparece.

Para instruções sobre como configurar uma integração no Google SecOps, consulte Configurar integrações.

Se necessário, você pode fazer mudanças depois. Depois de configurar uma instância de integração, é possível usá-la em playbooks. Para mais informações sobre como configurar e oferecer suporte a várias instâncias, consulte Como oferecer suporte a várias instâncias.

Ações

Para mais informações sobre ações, consulte Responder a ações pendentes na sua mesa de trabalho e Executar uma ação manual no seu caso.

Ver reputação do domínio

A reputação do domínio verifica se um domínio é excluído por serviços conhecidos e confiáveis de lista de bloqueio de domínios, como URLVir, ThreatLog, OpenPhish, Spam404, PhishTank, ZeuS Tracker e outros. Os vários serviços de lista de bloqueio de domínios identificam sites potencialmente maliciosos e fraudulentos envolvidos na distribuição de malware, incidentes de phishing e lojas on-line falsas.

Parâmetros

Nome do parâmetro Tipo Valor padrão É obrigatório Descrição
Limite String 0 Sim Limite de risco do domínio. O limite precisa ser um valor numérico. Exemplo: 3
Criar insights Caixa de seleção Selecionado Sim Especifique se a ação deve criar insights ou não.

Casos de uso

Um dos casos de uso da API Domain Reputation é verificar se os sites do cliente estão excluídos, verificar URLs enviados por usuários no seu aplicativo ou identificar sites potencialmente maliciosos e não seguros.

Data de execução

Essa ação é executada nas seguintes entidades:

  • Nome do host
  • URL

Resultados da ação

Enriquecimento de entidades

Marcar a entidade como suspeita se o número de mecanismos negativos for igual ou superior ao limite fornecido.

Nome do campo de enriquecimento Lógica: quando aplicar
alexa_top_100k Retorna se existir no resultado JSON
domain_length Retorna se existir no resultado JSON
alexa_top_10k Retorna se existir no resultado JSON
listas de bloqueio Retorna se existir no resultado JSON
servidor Retorna se existir no resultado JSON
host Retorna se existir no resultado JSON
most_abused_tld Retorna se existir no resultado JSON
alexa_top_250k Retorna se existir no resultado JSON
Insights
Gravidade Descrição
Avisar Um insight de aviso é criado para informar sobre o status malicioso da entidade enriquecida. O é criado quando o número de mecanismos detectados é igual ou excede o limite mínimo de suspeita definido antes da verificação.
Resultado do script
Nome do resultado do script Opções de valor Exemplo
sucesso Verdadeiro/falso success:False
Resultado JSON
[
    {
        "EntityResult": {
            "alexa_top_100k": false,
            "domain_length": 17,
            "alexa_top_10k": false,
            "blacklists": {
                "scantime": "0.07",
                "detection_rate": "0%",
                "detections": 0,
                "engines_count": 29,
                "engines": [{
                    "engine": "ThreatLog",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.threatlog.com/"
                }, {
                    "engine": "Threat Sourcing",
                    "detected": false,
                    "confidence": "high",
                    "reference": "https://www.threatsourcing.com/"
                }, {
                    "engine": "URLVir",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.urlvir.com/"
                }]},
            "server": {
                "region_name": null,
                "reverse_dns": " ",
                "ip": " ",
                "isp": null,
                "continent_code": null,
                "latitude": null,
                "city_name": null,
                "longitude": null,
                "country_code": null,
                "country_name": null,
                "continent_name": null
            },
            "host": "example.com",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "example.com"
    }, {
        "EntityResult": {
            "alexa_top_100k": false,
            "domain_length": 9,
            "alexa_top_10k": false,
            "blacklists": {
                "scantime": "0.03",
                "detection_rate": "0%",
                "detections": 0,
                "engines_count": 29,
                "engines": [{
                    "engine": "ThreatLog",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.threatlog.com/"
                }, {
                    "engine": "Threat Sourcing",
                    "detected": false,
                    "confidence": "high",
                    "reference": "https://www.threatsourcing.com/"
                }, {
                    "engine": "URLVir",
                    "detected": false,
                    "confidence": "high",
                    "reference": "http://www.urlvir.com/"
                }]},
            "server": {
                "region_name": null,
                "reverse_dns": " ",
                "ip": " ",
                "isp": null,
                "continent_code": null,
                "latitude": null,
                "city_name": null,
                "longitude": null,
                "country_code": null,
                "country_name": null,
                "continent_name": null
            },
            "host": "192.0.2.1",
            "most_abused_tld": false,
            "alexa_top_250k": false
        },
        "Entity": "192.0.2.1"
    }
]

Receber reputação de IP

A API IP Reputation detecta endereços IP potencialmente maliciosos que são usados com frequência para spam, ataques a sites ou atividades fraudulentas.

Parâmetros

Parâmetro Tipo Valor padrão É obrigatório Descrição
Limite String N/A Sim Limite de risco de IP. O limite precisa ser um valor numérico. Exemplo: 3.
Criar insights Caixa de seleção Selecionado Sim Especifique se a ação deve criar insights ou não.

Data de execução

Essa ação é executada na entidade de endereço IP.

Resultados da ação

Enriquecimento de entidades

Marcar a entidade como suspeita se o número de mecanismos negativos for igual ou superior ao limite fornecido.

Nome do campo de enriquecimento Lógica: quando aplicar
informações Retorna se existir no resultado JSON
listas de bloqueio Retorna se existir no resultado JSON
anonimato Retorna se existir no resultado JSON
ip Retorna se existir no resultado JSON
Insights
Gravidade Descrição
Avisar Um insight de aviso é criado para informar sobre o status malicioso do hash enriquecido. O insight é criado quando o número de mecanismos detectados é igual ou excede o limite mínimo de suspeita definido antes da verificação.
Resultado do script
Nome do resultado do script Opções de valor Exemplo
sucesso Verdadeiro/falso success:False
Resultado JSON
[
    {
        "EntityResult": {
            "information": {
                "is_proxy": false,
                "is_vpn": false,
                "region_name": "Zhejiang",
                "is_webproxy": false,
                "latitude": 28.680280685424805,
                "isp": "ChinaNet Zhejiang Province Network",
                "continent_code": "AS",
                "is_tor": false,
                "reverse_dns": " ",
                "detections": 18,
                "engines_count": 76,
                "longitude": 121.44277954101562,
                "city_name": "Jiaojiang",
                "country_name": "China",
                "continent_name": "Asia",
                "detection_rate": "24%",
                "country_code": "CN",
                "is_hosting": false
            },
            "blacklists": {
                "scantime": "0.57",
                "detection_rate":
                "24%",
                "detections": 18,
                "engines_count": 76,
                "engines": [{
                    "engine": "PlonkatronixBL",
                    "detected": false,
                    "reference": "http://bl.plonkatronix.com/"
                }, {
                    "engine": "Engine",
                    "detected": true,
                    "reference": "https://home.nuug.no/~engine/"
                }, {"engine": "Malc0de",
                    "detected": false,
                    "reference": "http://malc0de.com/database/index.php"
                   }]},
            "anonymity": {
                "is_tor": false,
                "is_proxy": false,
                "is_vpn": false,
                "is_webproxy": false,
                "is_hosting": false
            },
            "ip": "192.0.2.1"
        },
        "Entity": "192.0.2.1"
    }
]

Receber reputação do URL

Receba a reputação de segurança e a pontuação de risco de um URL.

Parâmetros

Nome do parâmetro Tipo Valor padrão É obrigatório Descrição
Limite Inteiro N/A Sim

Limite de risco do URL. O limite precisa ser um valor numérico. Exemplo: 3

Casos de uso

Um analista pode recuperar a reputação do URL, de maneira semelhante a como recuperar a reputação de um domínio ou endereço IP.

Data de execução

Essa ação é executada na entidade de URL.

Resultados da ação

Enriquecimento de entidades

Marcar a entidade como suspeita se o número de mecanismos negativos for igual ou maior que o limite fornecido. Se data.get("report", {}).get("risk_score", {}).get("result") > threshold

Nome do campo de enriquecimento Lógica: quando aplicar
domain_blacklist Retorna se existir no resultado JSON
html_forms Retorna se existir no resultado JSON
server_details Retorna se existir no resultado JSON
response_headers Retorna se existir no resultado JSON
redirecionamento Retorna se existir no resultado JSON
file_type Retorna se existir no resultado JSON
risk_score Retorna se existir no resultado JSON
security_checks Retorna se existir no resultado JSON
geo_location Retorna se existir no resultado JSON
url_parts Retorna se existir no resultado JSON
site_category Retorna se existir no resultado JSON
web_page Retorna se existir no resultado JSON
dns_records Retorna se existir no resultado JSON
Resultado do script
Nome do resultado do script Opções de valor Exemplo
is_success Verdadeiro/falso is_success:False
Resultado JSON
[
    {
        "EntityResult": {
            "domain_blacklist": {
                "detections": 0,
                "engines": [{
                    "detected": false,
                        "name": "SpamhausDBL", "reference": "https://www.spamhaus.org/lookup/"
                    }, {
                        "detected": false,
                        "name": "ThreatLog",
                        "reference": "http://www.threatlog.com/"
                    }, {
                        "detected": false,
                        "name": "OpenPhish",
                        "reference": "http://www.openphish.com/"
                    }, {
                        "detected": false,
                        "name": "PhishTank",
                        "reference": "http://www.phishtank.com/"
                    }, {
                        "detected": false,
                        "name": "Phishing.Database",
                        "reference": "https://github.com/mitchellkrogza/Phishing.Database"
                    }, {
                        "detected": false,
                        "name": "PhishStats",
                        "reference": "https://phishstats.info/"
                    }, {
                        "detected": false,
                        "name": "URLVir",
                        "reference": "http://www.urlvir.com/"
                    }, {
                        "detected": false,
                        "name": "URLhaus",
                        "reference": "https://urlhaus.abuse.ch/"
                    }, {
                        "detected": false,
                        "name": "RPiList Not Serious",
                        "reference": "https://github.com/RPiList/specials"
                    }, {
                        "detected": false,
                        "name": "precisionsec",
                        "reference": "https://precisionsec.com/"
                    }, {
                        "detected": false,
                        "name": "AntiSocial Blacklist",
                        "reference": "https://theantisocialengineer.com/"
                    }, {
                        "detected": false,
                        "name": "PhishFeed",
                        "reference": "https://phishfeed.com/"
                    }, {
                        "detected": false,
                        "name": "Spam404",
                        "reference": "https://www.spam404.com/"
                    }]},
            "html_forms": {
                "number_of_total_input_fields": 0,
                "email_field_present": false,
                "number_of_total_forms": 0,
                "password_field_present": false,
                "two_text_inputs_in_a_form": false,
                "credit_card_field_present": false
            },
            "server_details": {
                "continent_name": "Asia",
                "hostname": "example.com",
                "region_name": "Seoul-teukbyeolsi",
                "ip": "192.0.2.141",
                "isp": "Example Corporation",
                "continent_code": "AS",
                "country_name": "Korea (Republic of)",
                "city_name": "Seoul",
                "longitude": 126.97782897949219,
                "country_code": "KR",
                "latitude": 37.568260192871094
            },
            "response_headers": {
                "status": "HTTP/1.1 404 Not Found",
                "content-length": "177",
                "code": 404,
                "server": "nginx/1.4.6 (Ubuntu)",
                "connection": "keep-alive",
                "date": "Wed, 15 Jul 2020 08:21:54 GMT",
                "content-type": "text/html"
            },
            "redirection": {
                "url": null,
                "found": false,
                "external": false
            },
            "file_type": {
                "headers": "HTML",
                "extension": "HTML",
                "signature": " "
            },
            "risk_score": {
                "result": 10
            },
            "security_checks": {
                "is_suspended_page": false,
                "is_defaced_heuristic": false,
                "is_windows_exe_file": false,
                "is_credit_card_field": false,
                "is_windows_exe_file_on_free_hosting": false,
                "is_masked_linux_elf_file": false,
                "is_exe_on_directory_listing": false,
                "is_php_on_directory_listing": false,
                "is_masked_windows_exe_file": false,
                "is_sinkholed_domain": false,
                "is_robots_noindex": false,
                "is_windows_exe_file_on_free_dynamic_dns": false,
                "is_doc_on_directory_listing": false,
                "is_non_standard_port": false,
                "is_linux_elf_file_on_free_dynamic_dns": false,
                "is_suspicious_domain": false, "is_suspicious_url_pattern": false,
                "is_china_country": false,
                "is_risky_geo_location": false,
                "is_pdf_on_directory_listing": false,
                "is_valid_https": false,
                "is_external_redirect": false, "is_windows_exe_file_on_ipv4": false,
                "is_phishing_heuristic": false,
                "is_linux_elf_file_on_ipv4": false,
                "is_email_address_on_url_query": false,
                "is_uncommon_clickable_url": false,
                "is_most_abused_tld": false,
                "is_domain_blacklisted": false,
                "is_host_an_ipv4": false,
                "is_linux_elf_file_on_free_hosting": false,
                "is_zip_on_directory_listing": false,
                "is_password_field": false,
                "is_linux_elf_file": false,
                "is_empty_page_title": false,
                "is_directory_listing": false,
                "is_masked_file": false,
                "is_suspicious_file_extension": false,
                "is_suspicious_content": false
            },
            "geo_location": {
                "countries": ["KR"]
            },
            "url_parts": {
                "host_nowww": "example.com",
                "host": "www.example.com",
                "path": "/dynamic/example.html",
                "query": null,
                "scheme": "http",
                "port": 80},
            "site_category": {
                "is_vpn_provider": false,
                "is_url_shortener": false,
                "is_anonymizer": false,
                "is_torrent": false,
                "is_free_dynamic_dns": false,
                "is_free_hosting": false
            },
            "web_page": {
                "keywords": "",
                "description": "",
                "title": "404 Not Found"
            },
            "dns_records": {
                "ns": {
                    "records": [{
                        "country_name": "Korea (Republic of)",
                        "ip": "192.0.2.95",
                        "isp": "Example Corporation",
                        "target": "example.com",
                        "country_code": "KR"
                    }, {
                        "country_name": "Korea (Republic of)",
                        "ip": "192.0.2.26",
                        "isp": "LX",
                        "target": "example.com",
                        "country_code": "KR"
                    }]},
                "mx": {
                    "records": []
                }}},
        "Entity": "www.example.com:80/dynamic/example.html"
    }
]
Mural do caso
Tipo de resultado Descrição Tipo
Mensagem de saída*
  1. Entidades bem-sucedidas: "APIVoid: reputação buscada para as seguintes entidades: <lista de identificadores de entidades>
  2. Entidades com falha: "Ocorreu um erro nas seguintes entidades: <lista de identificadores de entidades>"
  3. Entidades ausentes (sem dados): "Não foi possível encontrar a reputação das seguintes entidades: <lista de identificadores de entidades>"
  4. Alerta sem entidades de URL: "APIVoid: nenhum URL encontrado".
 Geral
Mural de casos em CSV

Se houver dados disponíveis, crie uma nova tabela CSV de entidade:

  1. relatório de bloqueio de domínio: data.get("report",{}).get("domain_blacklist",{}).get("engines", [])
 Geral
Aprimoramento

Se houver dados disponíveis, adicione o seguinte como enriquecimento de entidade (não se esqueça de adicionar o prefixo "APIVoid"):

  1. geo_location: data.get("report",{}).get("geo_location",{}).get("countries", [])
  2. is_suspicious_domain: data.get("report",{}).get("security_checks",{}).get("is_suspicious_domain")
  3. is_domain_blacklisted: data.get("report",{}).get("security_checks",{}).get("is_domain_blacklisted")
  4. is_risky_geo_location: data.get("report",{}).get("security_checks",{}).get("is_risky_geo_location")
  5. risk_score: data.get("report", {}).get("risk_score", {}).get("result")
  6. is_external_redirect: data.get("report",{}).get("security_checks",{}).get("is_external_redirect")
 Entidade

Fazer captura de tela

Faça uma captura de tela de alta qualidade de qualquer site ou URL.

Parâmetros

N/A

Casos de uso

Um analista pode capturar capturas de tela de alta qualidade de qualquer site ou URL, no formato da imagem PNG ou JPG.

Data de execução

Essa ação é executada na entidade Usuário.

Resultados da ação

Enriquecimento de entidades

Marcar a entidade como suspeita se o número de mecanismos negativos for igual ou maior que o limite fornecido. is_suspicious: se data.get("score") > threshold

Nome do campo de enriquecimento Lógica: quando aplicar
domínio Retorna se existir no resultado JSON
should_block Retorna se existir no resultado JSON
score Retorna se existir no resultado JSON
descartável Retorna se existir no resultado JSON
has_mx_records Retorna se existir no resultado JSON
has_spf_records Retorna se existir no resultado JSON
Resultado do script
Nome do resultado do script Opções de valor Exemplo
is_success Verdadeiro/falso is_success:False
Resultado JSON
[
    {
        "EntityResult": {
            "domain": "example.com",
            "valid_tld": true,
            "email": "user@example.co",
            "role_address": false,
            "should_block": false,
            "risky_tld": false,
            "dirty_words_username": false,
            "suspicious_domain": false,
            "score": 100,
            "educational_domain": false,
            "dirty_words_domain": false,
            "did_you_mean": " ",
            "username": "user",
            "valid_format": true,
            "is_spoofable ": false,
            "disposable": false,
            "government_domain": false,
            "has_spf_records": true,
            "domain_popular": false,
            "has_mx_records": true,
            "china_free_email": false,
            "free_email": false,
            "russian_free_email": false,
            "police_domain": false,
            "dmarc_enforced": false,
            "suspicious_username": false
        },
        "Entity": "USER@EXAMPLE.COM"
    }
]
Mural do caso
Tipo de resultado Descrição Tipo
Mensagem de saída*
  1. Entidades bem-sucedidas: "APIVoid: capturas de tela adicionadas para as seguintes entidades: <lista de identificadores de entidades>"
  2. Entidades com falha: "Ocorreu um erro nas seguintes entidades: <lista de identificadores de entidades>"
  3. Entidades ausentes (sem dados): "Não foram encontradas capturas de tela para as seguintes entidades: <lista de identificadores de entidades>"
  4. Alerta sem entidades de URL: "APIVoid: nenhuma entidade de URL encontrada para capturar capturas de tela".
  5. Para entidades grandes (tamanho do arquivo de anexo > 3 MB): "Falha ao adicionar capturas de tela como anexos nas seguintes entidades: <<lista de identificadores de entidades>>"
 Geral
Anexos

Se os dados estiverem disponíveis, crie um novo objeto de arquivo:

  1. attachment title: 'Screenshot - {0}'.format(entity.identifier)
  2. O nome de arquivo precisa ser o URL sem o sufixo (HTTPS/HTTP) + "_capture.<formato do arquivo>"
  3. A captura de tela é retornada em uma string codificada em base64 --> o conteúdo do arquivo precisa ser b64decode(data.get('base64_file'))
  4. Não se esqueça de adicionar try, except. Temos uma limitação de 3 MB da plataforma. Em caso de erro, adicione uma mensagem relevante ao logger.
 Geral

Ping

Testar a conectividade.

Parâmetros

N/A

Data de execução

Essa ação é executada em todas as entidades.

Resultados da ação

Resultado do script
Nome do resultado do script Opções de valor Exemplo
sucesso Verdadeiro/falso success:False

Verificar e-mail

Verifique se um e-mail é descartável, tem registros MX e muito mais.

Parâmetros

Nome do parâmetro Tipo Valor padrão É obrigatório Descrição
Limite Inteiro N/A Sim

Limite de risco de e-mail. O limite precisa ser um valor numérico.

Exemplo: 3

Casos de uso

Um analista pode verificar se um e-mail é descartável, receber registros MX e muito mais.

Data de execução

Essa ação é executada na entidade Usuário.

Resultados da ação

Enriquecimento de entidades

Marcar a entidade como suspeita se o número de mecanismos negativos for igual ou maior que o limite fornecido. is_suspicious: se data.get("score") > threshold

Nome do campo de enriquecimento Lógica: quando aplicar
domínio Retorna se existir no resultado JSON
should_block Retorna se existir no resultado JSON
score Retorna se existir no resultado JSON
descartável Retorna se existir no resultado JSON
has_mx_records Retorna se existir no resultado JSON
has_spf_records Retorna se existir no resultado JSON
Resultado do script
Nome do resultado do script Opções de valor Exemplo
is_success Verdadeiro/falso is_success:False
Resultado JSON
[
    {
        "EntityResult": {
            "domain": "example.com",
            "valid_tld": true,
            "email": "user@example.com",
            "role_address": false,
            "should_block": false,
            "risky_tld": false,
            "dirty_words_username": false,
            "suspicious_domain": false,
            "score": 100,
            "educational_domain": false,
            "dirty_words_domain": false,
            "did_you_mean": " ",
            "username": "user",
            "valid_format": true,
            "is_spoofable ": false,
            "disposable": false,
            "government_domain": false,
            "has_spf_records": true,
            "domain_popular": false,
            "has_mx_records": true,
            "china_free_email": false,
            "free_email": false,
            "russian_free_email": false,
            "police_domain": false,
            "dmarc_enforced": false,
            "suspicious_username": false
        },
        "Entity": "USER@EXAMPLE.COm"
    }
]
Mural do caso
Tipo de resultado Descrição Tipo
Mensagem de saída*
  1. entidades bem-sucedidas: "APIVoid: informações buscadas para as seguintes entidades: <lista de identificadores de entidades>
  2. Entidades com falha: "Ocorreu um erro nas seguintes entidades: <lista de identificadores de entidades>"
  3. Entidades ausentes (sem dados): "Não foi possível encontrar informações para as seguintes entidades: <lista de identificadores de entidades>"
  4. Alerta sem entidades de URL: "APIVoid: No emails found."
 Geral
Mural de casos em CSV Conteúdo CSV: dados da entidade(exemplo abaixo) Geral
Aprimoramento

Se houver dados disponíveis, adicione o seguinte como enriquecimento de entidade (não se esqueça de adicionar o prefixo "APIVoid"):

  1. suspicious_domain: data.get("suspicious_domain")
  2. should_block: data.get("should_block")
  3. score: data.get("score")
  4. disposable: data.get("disposable")
  5. has_mx_records: data.get("has_mx_records")
  6. has_spf_records: data.get("has_spf_records")
 Entidade

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