Como usar a API do log de auditoria para sua empresa

Saiba como recuperar eventos corporativos programaticamente com a API REST.

Quem pode usar esse recurso?

Enterprise owners

Neste artigo

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. Confira Documentação de webhooks.

Mantenha a conformidade e proteja a propriedade intelectual com pontos de extremidade relacionados ao 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.

Para obter mais informações sobre os eventos específicos que você pode acessar por meio dos pontos de extremidade do log de auditoria, consulte os artigos a seguir.

Detalhes do log de auditoria

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. 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.

Você pode usar o escopo read:audit_log para acessar o log de auditoria por meio da API.

Limite de taxa

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 usuário e endereço IP. 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. Confira Limites de taxa para a API REST e Práticas recomendadas para usar a API REST.

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 a 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 a 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"