Skip to main content

Utilizar la API de bitácora de auditoría para tu empresa

Puedes recuperar los eventos de empresa con programación utilizando la API de REST o de GraphQL.

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

Utilizar la API de bitácoras de auditoría

Puedes interactuar con la bitácora de audotaría si utilizas la API de GraphQL o la API de REST.

Las marcas de tiempo y campos de fecha en la respuesta de la API se miden en milisegundos de época UTC.

Consultar la API de bitácora de auditoría de GraphQL

Para garantizar que tu propiedad intelectual está segura y que mantienes el cumplimiento para tu empresa, puedes utilizar la API de GraphQL para bitácoras de auditoría para mantener copias de tus datos de bitácoras de auditoría y monitorear:

  • El acceso a los parámetros de tu organización o repositorio
  • Los cambios en los permisos
  • Los usuarios agregados o eliminados en una organización, repositorio o equipo
  • Los usuarios que se están promoviendo a administradores
  • Cambios a los permisos de una GitHub App

Toma en cuenta que no puedes recuperar eventos de Git utilizando la API de bitácora de auditoría.

La respuesta de GraphQL puede incluir datos de hasta 90 a 120 días.

Ejemplo 1: Los miembros que se agregaron o eliminaron de las organizaciones en una empresa

La siguiente consulta recupera las bitácoras de auditoría para la empresa avocado-corp y devuelve a las primeras 10 organizaciones en ella, en donde las únicas acciones que se llevaron a cabo fue la adición o eliminación de un miembro de una organización. Se devuelven las primeras 20 entradas de bitácora de auditoría para cada organización.

Esta consulta utiliza el campo auditlog del objeto de organización y los objetos OrgAddMemberAuditEntry y OrgRemoveMemberAuditEntry. La cuenta de GitHub que está consultando la bitácora de auditoría empresarial debe ser un propietario de organización para cada organización dentro de la 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
      }
    }
  }
}

La API de GraphQL devolverá por mucho 100 nodos por consulta. Para recuperar los resultados adicionales, necesitarás implementar la paginación. Para obtener más información, consulta la sección "Limitaciones de recursos" en la documentación de la API de GraphQL y Paginación en la documentación oficial de GraphQL.

Ejemplo 2: Eventos en una organización para una fecha y actor específicos

Puedes especificar frases de búsqueda múltiples, tales como created y actor, si las separas en tu secuencia de consulta con un espacio.

La siguiente consulta recupera todas las bitácoras de auditoría para la empresa avocado-corp que se relaciona con la organización octo-org, en donde el usuario octocat realizó las acciones en el 1 de enero de 2022 o después de esta fecha. Se devuelven las primeras 20 entradas de la bitácora de auditoría y la entrada más nueva se muestra primero.

Esta consulta utiliza la interfaz AuditEntry. La cuenta de GitHub que está consultando la bitácora de auditoría empresarial debe ser propietaria de la organización 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 obtener más ejemplos de consultas, dirígete al repositorio platform-samples.

Consultar la API de REST de la bitácora de auditoría

Para garantizar que tu propiedad intelectual está segura y que mantienes el cumplimiento para tu empresa, puedes utilizar la API de REST para bitácoras de auditoría para mantener copias de tus datos de bitácoras de auditoría y monitorear:

  • El acceso a los parámetros de tu organización o repositorio
  • Los cambios en los permisos
  • Los usuarios agregados o eliminados en una organización, repositorio o equipo
  • Los usuarios que se están promoviendo a administradores
  • Cambios a los permisos de una GitHub App

The audit log lists events triggered by activities that affect your enterprise. Audit logs for GitHub Enterprise Server are retained indefinitely, unless an enterprise owner configured a different retention period. For more information, see "Configuring the audit log for your enterprise."

Predeterminadamente, solo se muestran los eventos de los últimos tres meses. Para ver los eventos más viejos, debes especificar un rango de fechas con el parámetro creado. Para obtener más información, consulta la sección "Entender la sintaxis de búsqueda".

Para obtener más información sobre la API de REST de la bitácora de auditoría, consulta la sección "Administración de empresas" y "Organizaciones".

Ejemplo 1: Todos los eventos de una empresa, para una fecha específica, con paginación

La siguiente consulta busca los eventos de la bitácora de auditoría que se crearon el 1 de enero de 2022 en la empresa avocado-corp y devolvió la primera página con un máximo de 100 elementos por página utilizando la Paginación de la API de REST:

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

Ejemplo 2: Eventos para las solicitudes de cambio en una empresa, para un actor y fecha específicos

Puedes especificar frases de búsqueda múltiples, tales como created y actor, si las separas en tu URL formada con el símbolo + o con el código de caracteres ASCII %20.

La siguiente consulta busca los eventos de bitácora de auditoría para las solicitudes de cambios, en donde el evento ocurrió en o después del 1 de enero de 2022 en la empresa avocado-corp y el usuario octocat realizó la acción:

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