Usando a API do log de auditoria
É possível interagir com o log de auditoria usando a API do GraphQL ou a API REST. É possível usar o escopo read:audit_log para acessar o log de auditoria por meio das APIs.
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 GraphQL. Para recuperar eventos do Git, use a API REST. Para saber mais, confira as ações de categoria git em "Auditar eventos de log para sua empresa" e também os pontos de extremidade de log de auditoria "Administração do GitHub Enterprise" e "Organizações na documentação da API REST".
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 saber mais, 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 * Eventos do Git, como clonagem, busca e push
O log de auditoria lista os eventos disparados por atividades que afetam sua empresa dentro do mês atual e até os seis meses anteriores. 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".
Para saber mais sobre a API REST do log de auditoria, confira "Administração do GitHub Enterprise" 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 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"