api_utils

api_utils

Exemplos de programas para acessar a API

API de chamada

Aqui estão dois programas, um em Python e outro em Perl para ajudar na execução e acesso aos dados através das API's.

Para que qualquer um desses programas funcione, eles esperam que exista um arquivo chamado ~/.shadowserver.api e contenha sua chave e segredo de API. Por exemplo:

 [api]
key = <<API-KEY>>
secret = <<SECRET>>
uri = https://transform.shadowserver.org/api2/

Se ocorrer um erro como esse, significa que a consulta está passando por muitos dados e o timeout do programa deve ser aumentado:

 $ ./call-api.py reports/query '{"report":"united-states", "date":"2020-10-27", "query":{"city":"ashburn"}, "limit":3}' pretty
API Exception: The read operation timed out

Detalhes adicionais podem ser encontrados em https://github.com/The-Shadowserver-Foundation/api_utils/wiki.

gerente de relatórios

Este programa utiliza a API de relatórios para manter uma árvore do sistema de arquivos com a opção de enviar notificações quando novos relatórios são baixados para processamento.

Opções de fila:

• Apache Kafka
• Redis
• STOMP (ActiveMQ, RabbitMQ)

Uso: report-manager.py /path/to/config.ini [ days ]

O argumento opcional 'dias' é o número de dias anteriores para download de relatórios. O padrão é 2.

Exemplo de arquivo de configuração:

 [reports]
directory = /var/tmp/reports
min_disk_free = 512
notifier = none
url_prefix = http://myserver/reports/

[stomp]
server = 127.0.0.1
port = 61613
user = guest
password = guest
queue = /queue/mytest

[redis]
server = 127.0.0.1
port = 6379
;password = guest
queue = mytest

[kafka]
server = 127.0.0.1
port = 9092
queue = mytest

A seção [relatórios] é obrigatória e deve conter a chave 'diretório'.

Configurações:

• diretório: diretório de nível superior para armazenar relatórios
• min_disk_free: mínimo de disco livre em MB para tentativa de download (padrão 512)
• notificador: especifique um tipo de fila de notificação [none, stomp, redis ou kafka]
• url_prefix: substituição do prefixo de URL para o diretório de nível superior para mensagens de notificação
• relatórios: lista opcional de nomes de listas de discussão que você deseja filtrar
• type: tipo de relatório opcional para filtrar

Se um 'notificador' estiver configurado na seção [relatórios], será necessária uma seção adicional com um nome correspondente.

Configurações:

• servidor: endereço IP do servidor ou nome do host
• porta: porta do servidor
• fila: identificador da fila
• usuário: nome de usuário (se necessário)
• senha: senha (se necessário)

A entrada de notificação é um objeto JSON que contém carimbo de data/hora, data do relatório, tipo de relatório e uri:

 {
   "timestamp" : "2022-09-01 11:32:45",
   "report_date" : "2022-08-31",
   "report_type" : "scan_stun",
   "uri" : "http://myserver/reports/2022/08/31/2022-08-31-scan_stun_example_com-asn.csv"
}

Exemplo de crontab para verificar novos downloads uma vez por hora:

 15 * * * * /opt/shadowserver/report-manager.py /opt/shadowserver/reports.ini