流式处理企业审核日志

注意

在特定用例中，Webhook 可能是审核日志或 API 轮询的良好替代方法。 Webhook 是一种 GitHub 在存储库、组织或企业发生特定事件时通知服务器的方法。与 API 或搜索审核日志相比，如果只想了解企业、组织或存储库何时发生某些事件并进行相应记录，Webhook 效率更高。请参阅“Webhooks 文档”。

关于审核日志流式传输

您可以通过使用流式处理保留审核日志数据副本，帮助保护知识产权并保持贵公司的合规性。审核日志详细记录了事件，例如对设置和访问权限的更改；用户成员资格；应用权限等。请参阅企业的审核日志事件、组织的审核日志事件和安全日志事件。

流式处理审核日志数据具有以下优势：

数据探索。使用您首选的工具检查流式事件，以查询大量数据。流包含整个企业帐户中的审核事件和 Git 事件。
数据连续性。暂停流时，它会将缓冲区保留七天，因此第一周不会丢失任何数据。如果流保持暂停状态的时间超过七天，则将从距离当前时间之前一周的时间点恢复。如果暂停三周或更长时间，则流不会保留任何数据，并且将从当前时间戳重新开始。

        **数据保留**。 根据您的需要，保留导出的审核日志和 Git 事件数据。

你可以随时设置、暂停或删除流。流会导出企业中所有组织的审核和 Git 事件数据，用于从启用流后开始的活动。

所有流式传输的审核日志都作为压缩的 JSON 文件发送。文件名格式为 YYYY/MM/HH/MM/<uuid>.json.gz。

注意

GitHub 使用至少一次传递方法。由于某些网络或系统问题，某些事件可能会重复。

审核日志流的运行状况检查

每 24 小时，每个流都要运行一次运行状况检查。如果流设置不正确，则会向企业所有者发送一封电子邮件。为了避免从流中删除审核日志事件，配置错误的流必须在 6 天内修复。

若要修复流媒体配置，请遵循设置审核日志流式处理中的步骤。

设置审核日志流功能

若要设置审核日志流，请按照服务提供商的说明操作：

        [Amazon S3](#setting-up-streaming-to-amazon-s3)

        [Azure Blob 存储](#setting-up-streaming-to-azure-blob-storage)

        [Azure 事件中心](#setting-up-streaming-to-azure-event-hubs)

        [Datadog](#setting-up-streaming-to-datadog)

        [Google 云存储](#setting-up-streaming-to-google-cloud-storage)

        [Splunk](#setting-up-streaming-to-splunk)

注意

要获取 GitHub 用于连接到流式传输终结点的 IP 地址范围列表，请使用 REST API。 GitHub.com 的 meta 终结点包含一个带有 IP 地址列表的 hooks 密钥。请参阅“元数据的 REST API 端点”。

流式传输到多个终结点

注意

此功能目前为公共预览版，可能会更改。

可以将审核日志流式传输到多个终结点。例如，你可以将审核日志流式传输到两个相同类型的终结点，或者流式传输到两个不同的提供程序。要设置多个数据流，请按照各服务提供商提供的说明进行操作。

设置流式传输到 Amazon S3

您可以使用访问密钥设置到 S3 的流式传输，或者使用 OpenID Connect (OIDC) 来避免在 GitHub 上存储长期机密。

        [使用访问密钥设置到 S3 的流式传输](#setting-up-streaming-to-s3-with-access-keys)

        [使用 OpenID Connect 设置 S3 数据流](#setting-up-streaming-to-s3-with-openid-connect)

        [禁用通过 OpenID Connect 到 S3 的流式传输](#disabling-streaming-to-s3-with-openid-connect)

        [与 AWS CloudTrail Lake 集成](#integrating-with-aws-cloudtrail-lake)

使用访问密钥设置到 S3 的流式传输

要设置来自 GitHub 审核日志流式处理，你需要：

AWS 访问密钥 ID
AWS 密钥

有关创建或访问访问密钥 ID 和密钥的信息，请参阅 AWS 文档中的了解和获取你的 AWS 凭据。

从 AWS：

创建 Bucket 并阻止对该 Bucket 的公共访问。请参阅 AWS 文档中的 Creating, configuring, and working with Amazon S3 buckets（创建、配置和使用 Amazon S3 Bucket）。1. 创建允许 GitHub 写入 Bucket 的策略。复制以下 JSON 并将 EXAMPLE-BUCKET 替换为存储桶的名称。 GitHub 只需要此 JSON 中的权限。
```
{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": [
            "s3:PutObject"
         ],
         "Resource": "arn:aws:s3:::EXAMPLE-BUCKET/*"
     }
   ]
}
```
请参阅 AWS 文档中的 Creating IAM policies（创建 IAM 策略）。

来自 GitHub：

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。1. 选择“配置流”**** 下拉菜单，然后单击“Amazon S3”****。
在“身份验证”下，单击“访问密钥”。
配置流设置。
- 在“区域”下，选择存储桶的区域。例如 us-east-1。
- 在“Bucket”下，输入想要流式传输到的 Bucket 名称。例如，auditlog-streaming-test。
- 在“访问密钥 ID”下，键入访问密钥 ID。例如，ABCAIOSFODNN7EXAMPLE1。
- 在“密钥”下，键入密钥。例如，aBcJalrXUtnWXYZ/A1MDENG/zPxRfiCYEXAMPLEKEY。
若要验证 GitHub 是否可以连接并写入 Amazon S3 终结点，请单击“检查终结点”。1. 成功验证终结点后，单击“保存”。

使用 OpenID Connect 设置 S3 数据流

注意

用于带有数据驻留权的 GitHub Enterprise Cloud 的、通过 OpenID Connect 流式传输到 S3 的审核日志目前不可用。请参阅“具有数据驻留功能的 GitHub Enterprise Cloud 功能概述”。

从 AWS：

将 GitHub OIDC 提供者添加到 IAM。请参阅 AWS 文档中的 Creating OpenID Connect (OIDC) identity providers（创建 OpenID Connect (OIDC) 标识提供者）。
- 对于提供者 URL，请使用 https://oidc-configuration.audit-log.githubusercontent.com。
- 对于“受众”，请使用 sts.amazonaws.com。
创建 Bucket 并阻止对该 Bucket 的公共访问。请参阅 AWS 文档中的 Creating, configuring, and working with Amazon S3 buckets（创建、配置和使用 Amazon S3 Bucket）。1. 创建允许 GitHub 写入 Bucket 的策略。复制以下 JSON 并将 EXAMPLE-BUCKET 替换为存储桶的名称。 GitHub 只需要此 JSON 中的权限。
```
{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": [
            "s3:PutObject"
         ],
         "Resource": "arn:aws:s3:::EXAMPLE-BUCKET/*"
     }
   ]
}
```
请参阅 AWS 文档中的 Creating IAM policies（创建 IAM 策略）。
为 GitHub IdP 配置角色和信任策略。请参阅 AWS 文档中的 Creating a role for web identity or OpenID Connect Federation (console)（为 Web 标识或 OpenID Connect 联合身份验证创建角色（控制台））。
- 添加您之前创建的权限策略，以允许对存储桶进行写入操作。
- 编辑信任关系，将 sub 字段添加到验证条件，将 ENTERPRISE 替换为你的企业名称。
  
  注意
  
  ENTERPRISE 值区分大小写。如果企业名称包含大写字母，请在信任策略中使用相同的大小写。
```
"Condition": {
   "StringEquals": {
      "oidc-configuration.audit-log.githubusercontent.com:aud": "sts.amazonaws.com",
      "oidc-configuration.audit-log.githubusercontent.com:sub": "https://github.com/ENTERPRISE"
    }
 }
```
- 记下已创建的角色的 Amazon 资源名称 (ARN)。

来自 GitHub：

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。 1. 选择“配置流”**** 下拉菜单，然后单击“Amazon S3”****。
在“身份验证”下，单击“OpenID Connect”。
配置流设置。
- 在“区域”下，选择存储桶的区域。例如，us-east-1；还可以使用自动发现选项。
- 在“Bucket”下，输入想要流式传输到的 Bucket 名称。例如，auditlog-streaming-test。
- 在“ARN 角色”字段下，填写之前记下的 ARN 角色。例如，arn:aws::iam::1234567890:role/github-audit-log-streaming-role。
若要验证 GitHub 是否可以连接并写入 Amazon S3 终结点，请单击“检查终结点”。1. 成功验证终结点后，单击“保存”。

禁用通过 OpenID Connect 到 S3 的流式传输

若要禁用通过 OIDC 到 S3 的流式传输，请删除您在设置流式传输时在 AWS 中创建的 GitHub OIDC 提供程序。请参阅 AWS 文档中的 Creating OpenID Connect (OIDC) identity providers（创建 OpenID Connect (OIDC) 标识提供者）。

如果由于 OIDC 的安全漏洞而禁用流式传输，在删除提供商后，请使用访问密钥设置流式传输，直至漏洞被修复。请参阅使用访问密钥设置到 S3 的流式传输。

与 AWS CloudTrail Lake 集成

你可以通过将流式传输到 S3 与 AWS CloudTrail Lake 集成来整合审核日志。请参阅 AWS CloudTrail 文档或存储库中的 aws-samples/aws-cloudtrail-lake-github-audit-log。

设置流式传输到 Azure Blob 存储

注意

不支持将审计日志流式传输到 Azure Government 的 blob 存储。

在 GitHub中设置流之前，请先在 Microsoft Azure 中创建存储帐户和容器。请参阅 Microsoft 文档中的 Azure Blob Storage 简介。

需要 SAS 令牌的 URL 才能配置流。

从 Microsoft Azure 门户：

在主页上，单击“存储帐户”。
在“名称”下，单击要使用的存储帐户的名称。
在“数据存储”下，单击“容器”。
单击要使用的容器的名称。
在左侧边栏的“设置”下，单击“共享访问令牌”。
选择“权限”下拉菜单，然后选择 **** 和 Create，并取消选择所有其他选项。
设置符合机密轮换策略的到期日期。
单击“生成 SAS 令牌和 URL”。
复制显示的 Blob SAS URL 字段的值。您将在 GitHub 中使用此 URL。

从 GitHub：

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
选择配置流下拉菜单，然后单击Azure Blob Storage。
在配置页上，输入在Azure中复制的 blob SAS URL。 “容器”字段将根据 URL 自动填充。
点击“检查终结点”以验证 GitHub 是否能够连接并写入 Azure Blob 存储终结点。
成功验证终结点后，单击“保存”。

设置将数据流传输到 Azure 事件中心

注意

在 Azure Government 中不支持事件中心 (Event Hubs) 实例。

在 GitHub 中设置流之前，需要：

Microsoft Azure中的事件中心命名空间
命名空间中的事件中心实例（请参阅 Quickstart：使用 Azure 门户创建事件中心Microsoft文档中）

从 Microsoft Azure 门户：

在页面顶部使用搜索框搜索“事件中心”。
选择“Event Hubs”。你的事件中心的名称将被列出。
记下要流式传输到的事件中心的名称。单击该事件中心。
在左侧菜单中，单击“共享访问策略”。
从策略列表中选择共享访问策略，或创建新策略。
从 Connection string 主键字段中复制connection string。

从 GitHub：

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
选择 Configure stream 下拉列表，然后单击 Azure Event Hubs。
在配置页面上，输入：
- Azure Event Hubs实例的名称。
- 连接字符串。
点击“检查终结点”以验证 GitHub 是否能够连接并写入 Azure 事件中心终结点。
成功验证终结点后，单击“保存”。

设置流式传输到 Datadog

若要设置流式传输到 Datadog，在 Datadog 中创建客户端令牌或 API 密钥，然后使用令牌在 GitHub 中配置审核日志流式传输以进行身份验证。无需在 Datadog 中创建 bucket 或其他存储容器。

设置流式传输到 Datadog 后，可以通过按“github.audit.streaming”进行筛选来查看审核日志数据。请参阅日志管理。

如果还没有 Datadog 帐户，请创建一个。
在 Datadog 中，生成客户端令牌或 API 密钥，然后单击“复制密钥”。请参阅 Datadog 文档中的 API 和应用密钥。
导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
选择“配置流”下拉列表，然后单击“Datadog”。
在“令牌”字段中，粘贴之前复制的令牌。
选择“站点”下拉菜单，然后单击 Datadog 站点。若要确定站点，请将 Datadog URL 与 Datadog 文档的 Datadog 站点中的表进行比较。
要验证 GitHub 是否可以连接并写入 Datadog 终结点，请单击“检查终结点”****。
成功验证终结点后，单击“保存”。
几分钟后，确认审核日志数据是否出现在 Datadog 中的“日志”选项卡上。如果未显示，请确认你在 GitHub 中的令牌和站点正确。

将数据流设置为传输到 Google Cloud Storage

要设置流式传输到 Google Cloud Storage，在 Google Cloud 中使用适当的凭据和权限创建一个服务帐户，然后使用服务帐户的凭据在 GitHub 中配置审核日志流以进行身份验证。

为 Google Cloud 创建一个服务帐户。您无需为此帐户设置访问控制或 IAM 角色。请参阅 Google Cloud 文档中的创建和管理服务帐户。
创建服务帐户的 JSON 密钥，并安全地存储该密钥。请参阅 Google Cloud 文档中的创建和管理服务帐户密钥。
如果尚未创建，请创建一个存储桶。请参阅 Google Cloud 文档中的创建存储桶。
为服务帐户分配存储桶对象创建者角色。请参阅 Google Cloud 文档中的使用 Cloud IAM 权限。
导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
选择“配置流”下拉菜单并单击“Google Cloud Storage”。
在“Bucket（存储桶）”下，键入 Google Cloud Storage 存储桶的名称。
在“JSON Credentials（JSON 凭据）”下，粘贴服务帐户的 JSON 密钥文件的全部内容。
若要验证 GitHub 是否可以连接并写入 Google Cloud Storage 存储桶，请点击“检查终结点”按钮。
成功验证终结点后，单击“保存”。

设置流式传输到 Splunk

要将审核日志流式传输到 Splunk 的 HTTP 事件收集器 (HEC) 端点，确保将终端节点配置为接受 HTTPS 连接。请参阅 Splunk 文档中的在 Splunk Web 中设置和使用 HTTP 事件收集器。

注意

GitHub 通过 <Domain>:port/services/collector 验证 HEC 端点。如果自托管端点（例如通过 OpenTelemetry 使用 Splunk HEC 接收器），请确保可在此目标访问端点。

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
选择“配置流”下拉菜单并单击“Splunk”。
在配置页面上，输入：
- 你要流式传输到的应用程序所托管的域。
  
  如果使用的是 Splunk Cloud，则 Domain 应为 http-inputs-<host>，其中 host 是你在 Splunk Cloud 中使用的域。例如，http-inputs-mycompany.splunkcloud.com。
  
  如果使用的是免费试用版 Splunk Cloud，则 Domain 应为 inputs.<host>，其中 host 是你在 Splunk Cloud 中使用的域。例如，inputs.mycompany.splunkcloud.com。
- 应用程序接受数据的端口。
  
  如果使用 Splunk Cloud，Port 应为 443。
  
  如果使用的是 Splunk Cloud 的免费试用版，则 Port 应为 8088。
- GitHub 用于向第三方应用程序进行身份验证的令牌。
使“启用 SSL 验证”复选框保持选中状态。

审核日志始终作为加密数据进行流式传输，但是，如果选择此选项， GitHub 在传递事件时会验证 Splunk 实例的 SSL 证书。 SSL 验证有助于确保将事件安全地传递到 URL 端点。虽然验证是可选操作，但我们建议将 SSL 验证保持为启用状态。
单击检查 Endpoint以验证 GitHub 是否可以连接至 Splunk Endpoint 并写入数据。
成功验证终结点后，单击“保存”。

暂停审计日志流

暂停流对接收应用程序执行维护，而不会丢失审核数据。审核日志在 GitHub 上最多存储七天，然后在取消暂停流时导出。

Datadog 仅接受过去最多 18 小时内的日志。如果暂停到 Datadog 终端节点的流媒体传输超过 18 小时，则在恢复传输后可能会有丢失 Datadog 不会接受的日志的风险。

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
在配置的流右侧，单击“暂停流”。
将显示确认消息。单击“暂停流”以确认操作。

若要重新开始流媒体，请单击“恢复流”。

删除审核日志流

导航到您的企业。例如，从 GitHub.com 上的公司页面。
在页面顶部，单击 “Settings”********。
在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“日志流式处理”。
在“危险区域”下，单击“删除流”。
将显示确认消息。请单击删除流以确认。

启用 API 请求的审计日志传输

注意

启用此功能后，并非所有 API 请求都包含在审核日志流中。 API 请求流式传输仅限于与安全相关的终结点。

导航到您的企业。例如，从 GitHub.com 上的公司页面。1. 在页面顶部，单击 “Settings”********。1. 在“Settings”下，单击“Audit log”****。
在“审核日志”下，单击“设置”。
在“API 请求”下，选择“启用 API 请求事件”。
单击“ 保存”。

谁可以使用此功能？

在本文中