エンタープライズの監査ログ API を使う

Audit log API を使用する

監査ログは、GraphQL API または REST API を使用して操作できます。

API 応答のタイ� スタンプと日付フィールドは UTC エポックミリ秒単位で計測されます。

監査ログ GraphQL API のクエリを実行する

知的財産が確実にセキュアに保たれるようにし、エンタープライズのコンプライアンスを維持するために、監査ログ GraphQL API を使って監査ログのデータのコピーを保持し、モニタリングできます: * 組織またはリポジトリの設定へのアクセス

アクセス許可の変更
組織、リポジトリ、またはチー� の追� または削除されたユーザー
管理者に昇� �されるユーザー
GitHub Appの権限の変更

監査ログ API を使って Git イベントを取得することができないことに注意してく� さい。

GraphQL のレスポンスには、90 日から 120 日までのデータを含めることができます。

例 1: エンタープライズ内の組織に追� された、または組織から削除されたメンバー

次のクエリは、avocado-corp エンタープライズの監査ログをフェッチし、実行された唯一のアクションが組織のメンバーの追� または削除であったエンタープライズ内の最初の 10 の組織を返します。各組織の最初の 20 個の監査ログエントリが返されます。

このクエリでは、組織オブジェクトの auditlog フィールドと、OrgAddMemberAuditEntry と OrgRemoveMemberAuditEntry オブジェクトを使います。エンタープライズの監査ログのクエリを実行する GitHub アカウントは、エンタープライズ内の各組織の組織所有者である必要があります。

{
  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
      }
    }
  }
}

GraphQL API は、クエリごとに最大 100 個のノードを返します。追� の結果を取得するには、ページ分割処理を実装する必要があります。詳細については、GraphQL API ドキュメントの「リソース制限」と、GraphQL の公式ドキュメントの「改ページ位置の自動修正」を参照してく� さい。

例 2: 特定の日付とアクターを対象とした組織内のイベント

クエリ文字列の中でスペースで区切ることで、created と actor のように複数の検索語句を指定できます。

次のクエリは、2022 年 1 月 1 日以降に octocat ユーザーによって実行されたアクションがある octo-org 組織に関連する avocado-corp エンタープライズのすべての監査ログをフェッチします。最初の 20 個の監査ログエントリが返され、最も新しいログエントリが最初に表示されます。

このクエリは、AuditEntry インターフェイスを使います。エンタープライズ監査ログのクエリを実行する GitHub アカウントは、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
                }
              }
            }
          }
        }
      }
    }
  }
}

その他のクエリ例については、platform-samples リポジトリを参照してく� さい。

監査ログ REST API のクエリを実行する

知的財産が確実にセキュアに保たれるようにし、エンタープライズのコンプライアンスを維持するために、監査ログ REST API を使って監査ログのデータのコピーを保持し、モニタリングできます: * 組織またはリポジトリの設定へのアクセス

アクセス許可の変更
組織、リポジトリ、またはチー� の追� または削除されたユーザー
管理者に昇� �されるユーザー
GitHub Appの権限の変更

監査ログには、Enterprise に影響するアクティビティによってトリガーされるイベントの一覧が表示されます。 GitHub Enterprise Server の監査ログは、エンタープライズ所有者が別の保持期間を構成していない限り。

既定では、過去 3 か月のイベントのみが表示されます。古いイベントを表示するには、created パラメーターを使って日付範囲を指定します。詳細については、「Understanding the search syntax」 (検索構文の理解) を参照してく� さい。

監査ログ REST API の詳細については、Enterprise 管理に関するページと「組織」を参照してく� さい。

例 1: 特定の日付を対象としたエンタープライズ内のすべてのイベント (ページ分割あり)

ページベースまたはカーソルベースのページネーションを使用できます。ページネーションの詳細については、「REST API でページネーションを使用する」を参照してく� さい。

ページベースのページネーションの例

次のクエリは、avocado-corp エンタープライズで 2022 年 1 月 1 日に作成された監査ログイベントを検索し、ページネーションを使用して 1 ページあたり最大 100 件の� �目で最初のページを返します。ページネーションの詳細については、「REST API でページネーションを使用する」を参照してく� さい。

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"

カーソルベースのページネーションの例

次のクエリは、avocado-corp エンタープライズで 2022 年 1 月 1 日に作成された監査ログイベントを検索し、ページネーションを使用して 1 ページあたり最大 100 件の� �目で最初のページを返します。ページネーションの詳細については、「REST API でページネーションを使用する」を参照してく� さい。 --include フラグを指定すると、応答と共にヘッダーが返されます。

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"

結果が 100 を超える� �合、link ヘッダーには、次のページ、1 ページ目、前のページの結果をフェッチするための URL が含まれます。

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"

対応するページネーションリンクを次の要求にコピーします。次に例を示します。

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="

例 2: 特定の日付とアクターを対象としたエンタープライズにおける pull request のイベント

created と actor のように複数の検索語句を指定するには、整形された URL の中で + 記号または ASCII 文字コード %20 で区切ります。

次のクエリは、イベントが avocado-corp エンタープライズで 2022 年 1 月 1 日以降に発生し、アクションが octocat ユーザーによって実行された pull request の監査ログイベントを検索します。

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"