Skip to main content

Como usar a API do log de auditoria para sua empresa

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

Who can use this feature

Enterprise owners and site administrators can use the audit log API.

Usando a API do log de auditoria

É possível interagir com o log de auditoria usando a API do GraphQL ou a API REST.

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

Como consultar a API do GraphQL do log de auditoria

Para garantir que a sua propriedade intelectual esteja segura e que você está mantendo a conformidade na sua empresa, use a API do GraphQL do log de auditoria para manter cópias dos seus dados de log de auditoria e monitore: * O acesso às configurações da organização ou do repositório

  • As alterações nas permissões
  • Os usuários adicionados ou removidos em uma organização, um repositório ou uma equipe
  • Os usuários promovidos para administradores
  • Alterações nas permissões de um GitHub App

Observe que você não pode recuperar eventos do Git usando a API do log de auditoria.

A resposta do GraphQL pode incluir dados por até 90 a 120 dias.

Exemplo 1: membros adicionados a organizações em uma empresa ou removidos dela

A consulta abaixo busca os logs de auditoria da empresa avocado-corp e retorna as dez primeiras organizações da empresa, em que as únicas ações executadas foram adicionar ou remover um membro de uma organização. As vinte primeiras entradas do log de auditoria para cada organização são retornadas.

Essa consulta usa o campo auditlog do objeto Organization e os objetos OrgAddMemberAuditEntry e OrgRemoveMemberAuditEntry. A conta do GitHub que consulta o log de auditoria da empresa precisa ser um proprietário da organização para cada organização na empresa.

{
  enterprise(slug: "avocado-corp") {
    organizations(first: 10, orderBy: {field: LOGIN, direction: DESC}) {
      nodes {
        name
        auditLog(first: 20) {
          edges {
            node {
              ... on OrgAddMemberAuditEntry {
                action
                actorLogin
                createdAt
              }
              ... on OrgRemoveMemberAuditEntry {
                action
                actorLogin
                createdAt
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

A API do GraphQL retornará, no máximo, 100 nós por consulta. Para recuperar resultados adicionais, você precisará implementar a paginação. Para obter mais informações, confira "Limitações de recursos" na documentação da API do GraphQL e Paginação na documentação oficial do GraphQL.

Exemplo 2: eventos em uma organização, para uma data e um ator específicos

Você pode especificar várias frases de pesquisa, como created e actor, separando-as na cadeia de consulta com um espaço.

A consulta abaixo busca todos os logs de auditoria para a empresa avocado-corp relacionados à organização octo-org, em que as ações foram executadas pelo usuário octocat em 1º de janeiro de 2022 ou após essa data. As vinte primeiras entradas do log de auditoria são retornadas, com a entrada de log mais recente aparecendo primeiro.

Essa consulta usa a interface AuditEntry. A conta do GitHub que consulta o log de auditoria da empresa precisa ser um proprietário da organização octo-org.

{
  enterprise(slug: "avocado-corp") {
    organizations(first: 1, query: "octo-org") {
      nodes {
        name
        auditLog(first: 20, query: "actor:octocat created:>=2022-01-01T00:00:00.000Z", orderBy: {field: CREATED_AT, direction: DESC}) {
          edges {
            node {
              ... on AuditEntry {
                action
                actorLogin
                createdAt
                user {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

Para obter mais exemplos de consulta, confira o repositório platform-samples.

Como consultar a API REST do log de auditoria

Para garantir que a sua propriedade intelectual esteja segura e que você está mantendo a conformidade na sua empresa, use a API REST do log de auditoria para manter cópias dos seus dados de log de auditoria e monitore: * O acesso às configurações da organização ou do repositório

  • As alterações nas permissões
  • Os usuários adicionados ou removidos em uma organização, um repositório ou uma equipe
  • Os usuários promovidos para administradores
  • Alterações nas permissões de um GitHub App

O log de auditoria lista os eventos disparados por atividades que afetam sua empresa. Os logs de auditoria de GitHub Enterprise Server são retidos indefinidamente, a menos que um proprietário da empresa configure um período de retenção diferente. Para obter mais informações, confira "Configurar o log de auditoria da sua empresa".

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 sobre a sintaxe de pesquisa".

Para obter mais informações sobre a API REST do log de auditoria, confira "Administração da empresa" e "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 página ou a paginação baseada em cursor. Para obter mais informações sobre paginação, confira "Como usar paginação na API REST".

Exemplo com paginação baseada em página

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 obter mais informações sobre paginação, confira "Como usar paginação na API REST".

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

Exemplo com paginação baseada em cursor

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 obter mais informações 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"