Como usar a API do log de auditoria para sua empresa

Você pode recuperar eventos empresariais programaticamente com a API REST.

Quem pode usar esse recurso?

Enterprise owners can use the audit log API.

Neste artigo

Usando a API do log de auditoria

Observação: Webhooks podem ser uma boa alternativa ao log de auditoria ou à pesquisa de API para determinados casos de uso. Os webhooks são uma maneira de o GitHub notificar seu servidor quando houver eventos específicos para um repositório, organização ou empresa. Em comparação com a API ou com a pesquisa de log de auditoria, os webhooks podem ser mais eficientes se você quiser apenas conhecer e, possivelmente, registrar quando determinados eventos ocorrerem em sua empresa, organização ou repositório. Para obter mais informações, confira "Documentação de webhooks".

Você pode manter a conformidade de sua empresa e proteger sua propriedade intelectual interagindo com o log de auditoria usando a API REST. Para obter mais informações sobre os eventos específicos que você pode acessar por meio da API de log de auditoria, consulte os artigos a seguir.

O log de auditoria lista os eventos disparados por atividades que afetam sua empresa nos últimos 180 dias. O log de auditoria mantém os eventos do Git por sete dias.

Por padrão, são exibidos apenas os eventos dos últimos três meses. Para ver eventos mais antigos, você deve especificar um intervalo de datas com o parâmetro created. Para obter mais informações, confira "Noções básicas de sintaxe de pesquisa".

Os carimbos de data e hora e os campos de data na resposta da API são medidos em milissegundos de época UTC.

É possível usar o escopo read:audit_log para acessar o log de auditoria por meio da API.

Cada ponto de extremidade da API de log de auditoria tem um limite de taxa de 1.750 consultas por hora para uma determinada combinação de endereço IP e usuário. Para evitar a limitação de taxa, as integrações que consultam a API de log de auditoria devem consultar em uma frequência máxima de 1.750 consultas por hora. Além disso, se a sua integração receber um erro de limite de taxa (normalmente uma resposta 403 ou 429), ela deverá aguardar antes de fazer outra solicitação à API. Para obter mais informações, confira "Limites de taxa para a API REST" e "Práticas recomendadas para usar a API REST".

Para saber mais sobre a API REST do log de auditoria, confira "Pontos de extremidade da API REST para logs de auditoria corporativa" e "Pontos de extremidade de API REST para organizações".

Exemplo 1: todos os eventos em uma empresa, para uma data específica, com paginação

Você pode usar a paginação baseada em cursor. Para saber mais sobre paginação, confira "Como usar paginação na API REST".

A consulta abaixo procura eventos de log de auditoria criados em 1º de janeiro de 2022 na empresa avocado-corp e retorna a primeira página com no máximo 100 itens por página usando paginação. Para saber mais sobre paginação, confira "Como usar paginação na API REST". O sinalizador --include faz com que os cabeçalhos sejam retornados junto com a resposta.

curl --include -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&per_page=100"

Se houver mais de 100 resultados, o cabeçalho link incluirá URLs para buscar a primeira e a próxima páginas de resultados, bem como a anterior.

link: <https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42NjQzODMzNTk5MjdlKzEyfDloQzBxdURzaFdVbVlLWjkxRU9mNXc%3D&before=>; rel="next",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=>; rel="first",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=MS42Njc4NDA2MjM4MzNlKzEyfExqeG5sUElvNEZMbG1XZHA5akdKTVE%3D>; rel="prev"

Copie o link de paginação correspondente na próxima solicitação. Por exemplo:

curl -I -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42Njc4NDA2MjM5NDFlKzEyfHRYa3AwSkxUd2xyRjA5bWxfOS1RbFE%3D&before="

Exemplo 2: eventos para solicitações de pull em uma empresa, para uma data e um ator específicos

Você pode especificar várias frases de pesquisa, como created e actor, separando-as na URL formada com o símbolo + ou o código de caractere ASCII %20.

A consulta abaixo pesquisa eventos de log de auditoria para solicitações de pull, em que o evento ocorreu em 1º de janeiro de 2022 ou após essa data na empresa avocado-corp e em que a ação foi executada pelo usuário octocat:

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"

Exemplo 3: eventos para atividade do Git em uma empresa, para uma data e ator específicos

Você pode pesquisar eventos do Git em uma empresa, como clonagem, pesquisa e envio, adicionando include=git como parâmetro na URL. Como alternativa, você pode usar include=all para pesquisar eventos da Web e eventos do Git.

A consulta abaixo procura eventos de log de auditoria para atividades do Git, em que o evento ocorreu após 1º de janeiro de 2024, na empresa avocado-corp, e a ação foi executada pelo usuário octocat.

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git"