Skip to main content

Streaming the audit log for your enterprise

You can stream audit and Git events data from GitHub to an external data management system.

Who can use this feature

Enterprise owners can configure audit log streaming.

Note: Audit log streaming is currently in beta for GitHub Enterprise Server and is subject to change.

About audit log streaming

To help protect your intellectual property and maintain compliance for your organization, you can use streaming to keep copies of your audit log data and monitor:

  • 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

The benefits of streaming audit data include:

  • Data exploration. You can examine streamed events using your preferred tool for querying large quantities of data. The stream contains both audit events and Git events across the entire enterprise account.
  • Data retention. You can keep your exported audit logs and Git events data as long as you need to.

Enterprise owners can set up or delete a stream at any time. The stream exports the audit and Git events data for all of the organizations in your enterprise.

Setting up audit log streaming

You set up the audit log stream on GitHub Enterprise Server by following the instructions for your provider.

Setting up streaming to Amazon S3

To stream audit logs to Amazon's S3 endpoint, you must have a bucket and access keys. For more information, see Creating, configuring, and working with Amazon S3 buckets in the AWS documentation. Make sure to block public access to the bucket to protect your audit log information.

To set up audit log streaming from GitHub you will need:

  • The name of your Amazon S3 bucket
  • Your AWS access key ID
  • Your AWS secret key

For information on creating or accessing your access key ID and secret key, see Understanding and getting your AWS credentials in the AWS documentation.

  1. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  2. Em "Log de auditoria", clique em Streaming de log.

  3. Selecione a lista suspensa Configurar fluxo e clique em Amazon S3.

    Escolha o Amazon S3 no menu suspenso

  4. Configure the stream settings.

    • Under "Bucket", type the name of the bucket you want to stream to. For example, auditlog-streaming-test.
    • Under "Access Key ID", type your access key ID. For example, ABCAIOSFODNN7EXAMPLE1.
    • Under "Secret Key", type your secret key. For example, aBcJalrXUtnWXYZ/A1MDENG/zPxRfiCYEXAMPLEKEY.
  5. Para verificar se o GitHub pode se conectar ao ponto de extremidade do Amazon S3 e fazer gravações nele, clique em Verificar ponto de extremidade.

    Verificar o ponto de extremidade

  6. Depois de verificar com êxito o ponto de extremidade, clique em Salvar.

Setting up streaming to Azure Blob Storage

Before setting up a stream in GitHub, you must first have created a storage account and a container in Microsoft Azure. For details, see the Microsoft documentation, "Introduction to Azure Blob Storage."

To configure the stream in GitHub you need the URL of a SAS token.

On Microsoft Azure portal:

  1. On the Home page, click Storage Accounts.

  2. Click the name of the storage account you want to use, then click Containers.

    The Containers link in Azure

  3. Click the name of the container you want to use.

  4. Click Shared access tokens.

    The shared access token link in Azure

  5. In the Permissions drop-down menu, change the permissions to only allow Create and Write.

    The permissions drop-down menu

  6. Set an expiry date that complies with your secret rotation policy.

  7. Click Generate SAS token and URL.

  8. Copy the value of the Blob SAS URL field that's displayed. You will use this URL in GitHub.

On GitHub:

  1. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  2. Em "Log de auditoria", clique em Streaming de log.

  3. Click Configure stream and select Azure Blob Storage.

    Choose Azure Blob Storage from the drop-down menu

  4. On the configuration page, enter the blob SAS URL that you copied in Azure. The Container field is auto-filled based on the URL.

    Enter the stream settings

  5. Click Check endpoint to verify that GitHub can connect and write to the Azure Blob Storage endpoint.

    Check the endpoint

  6. Depois de verificar com êxito o ponto de extremidade, clique em Salvar.

Setting up streaming to Azure Event Hubs

Before setting up a stream in GitHub, you must first have an event hub namespace in Microsoft Azure. Next, you must create an event hub instance within the namespace. You'll need the details of this event hub instance when you set up the stream. For details, see the Microsoft documentation, "Quickstart: Create an event hub using Azure portal."

You need two pieces of information about your event hub: its instance name and the connection string.

On Microsoft Azure portal:

  1. Search for "Event Hubs".

    The Azure portal search box

  2. Select Event Hubs. The names of your event hubs are listed.

    A list of event hubs

  3. Make a note of the name of the event hub you want to stream to.

  4. Click the required event hub. Then, in the left menu, select Shared Access Policies.

  5. Select a shared access policy in the list of policies, or create a new policy.

    A list of shared access policies

  6. Click the button to the right of the Connection string-primary key field to copy the connection string.

    The event hub connection string

On GitHub:

  1. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  2. Em "Log de auditoria", clique em Streaming de log.

  3. Click Configure stream and select Azure Event Hubs.

    Choose Azure Events Hub from the drop-down menu

  4. On the configuration page, enter:

    • The name of the Azure Event Hubs instance.
    • The connection string.

    Enter the stream settings

  5. Click Check endpoint to verify that GitHub can connect and write to the Azure Events Hub endpoint.

    Check the endpoint

  6. Depois de verificar com êxito o ponto de extremidade, clique em Salvar.

Setting up streaming to Google Cloud Storage

To set up streaming to Google Cloud Storage, you must create a service account in Google Cloud with the appropriate credentials and permissions, then configure audit log streaming in GitHub Enterprise Server using the service account's credentials for authentication.

  1. Create a service account for Google Cloud. You do not need to set access controls or IAM roles for the service account. For more information, see Creating and managing service accounts in the Google Cloud documentation.

  2. Create a JSON key for the service account, and store the key securely. For more information, see Creating and managing service account keys in the Google Cloud documentation.

  3. If you haven't created a bucket yet, create the bucket. For more information, see Creating storage buckets in the Google Cloud documentation.

  4. Give the service account the Storage Object Creator role for the bucket. For more information, see Using Cloud IAM permissions in the Google Cloud documentation.

  5. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  6. Em "Log de auditoria", clique em Streaming de log.

  7. Select the Configure stream drop-down menu and click Google Cloud Storage.

    Screenshot of the "Configure stream" drop-down menu

  8. Under "Bucket", type the name of your Google Cloud Storage bucket.

    Screenshot of the "Bucket" text field

  9. Under "JSON Credentials", paste the entire contents of the file for your service account's JSON key.

    Screenshot of the "JSON Credentials" text field

  10. To verify that GitHub can connect and write to the Google Cloud Storage bucket, click Check endpoint.

    Screenshot of the "Check endpoint" button

  11. Depois de verificar com êxito o ponto de extremidade, clique em Salvar.

Setting up streaming to Splunk

To stream audit logs to Splunk's HTTP Event Collector (HEC) endpoint you must make sure that the endpoint is configured to accept HTTPS connections. For more information, see Set up and use HTTP Event Collector in Splunk Web in the Splunk documentation.

  1. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  2. Em "Log de auditoria", clique em Streaming de log.

  3. Click Configure stream and select Splunk.

    Choose Splunk from the drop-down menu

  4. On the configuration page, enter:

    • The domain on which the application you want to stream to is hosted.

      If you are using Splunk Cloud, Domain should be http-inputs-<host>, where host is the domain you use in Splunk Cloud. For example: http-inputs-mycompany.splunkcloud.com.

    • The port on which the application accepts data.

      If you are using Splunk Cloud, Port should be 443 if you haven't changed the port configuration. If you are using the free trial version of Splunk Cloud, Port should be 8088.

    • A token that GitHub can use to authenticate to the third-party application.

    Enter the stream settings

  5. Leave the Enable SSL verification check box selected.

    Audit logs are always streamed as encrypted data, however, with this option selected, GitHub verifies the SSL certificate of your Splunk instance when delivering events. SSL verification helps ensure that events are delivered to your URL endpoint securely. You can clear the selection of this option, but we recommend you leave SSL verification enabled.

  6. Click Check endpoint to verify that GitHub can connect and write to the Splunk endpoint. Check the endpoint

  7. Depois de verificar com êxito o ponto de extremidade, clique em Salvar.

Deleting the audit log stream

  1. No canto superior à direita de GitHub Enterprise Server, clique na foto do perfil e clique em Configurações da empresa. "Configurações da empresa" no menu suspenso da foto do perfil em GitHub Enterprise Server 1. Na barra lateral da conta corporativa, clique em Configurações. Guia Configurações na barra lateral das contas corporativas 1. Em " Configurações", clique em Log de auditoria. Guia Log de auditoria na barra lateral da conta corporativa

  2. Em "Log de auditoria", clique em Streaming de log.

  3. Click Delete stream.

    Delete the stream

  4. A confirmation message is displayed. Click Delete stream to confirm.