Audit log API を使用する
監査ログは、GraphQL API または REST API を使用して操作できます。これらの API を介して read:audit_log
スコープを使用して、監査ログにアクセスできます。
API 応答のタイムスタンプと日付フィールドは UTC エポック ミリ秒単位で計測されます。
監査ログ GraphQL API のクエリを実行する
知的財産が確実にセキュアに保たれるようにし、エンタープライズのコンプライアンスを維持するために、監査ログ GraphQL API を使って監査ログのデータのコピーを保持し、モニタリングできます: * 組織またはリポジトリの設定へのアクセス
- アクセス許可の変更
- 組織、リポジトリ、またはチームの追加または削除されたユーザー
- 管理者に昇格されるユーザー
- GitHub Appの権限の変更
GraphQL API を使って Git イベントを取得することができないことに注意してください。 Git イベントを取得するには、代わりに REST API を使用してください。 詳しくは、「エンタープライズの監査ログ イベント」の git
カテゴリ アクション、および REST API ドキュメントの「GitHub Enterprise の管理」と「Organizations」の監査ログ エンドポイントを参照してください。
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 の公式ドキュメントの「Pagination (改ページ位置の自動修正)」を参照してください。
例 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の権限の変更 * Git イベント (複製、フェッチ、プッシュなど)
監査ログには、Enterprise に影響するアクティビティによってトリガーされるイベントの一覧が表示されます (現在の月内および過去 6 か月間まで)。 監査ログには、Git イベントが 7 日間保持されます。
既定では、過去 3 か月のイベントのみが表示されます。 古いイベントを表示するには、created
パラメーターを使って日付範囲を指定します。 詳しくは、「検索構文を理解する」を参照してください。
監査ログ REST API の詳細については、「GitHub Enterprise の管理」と「Organizations」を参照してください。
例 1: 特定の日付を対象としたエンタープライズ内のすべてのイベント (ページ分割あり)
カーソル ベースの改ページ位置の自動修正を使用できます。 改ページ位置の自動修正について詳しくは、「REST API 内での改ページ位置の自動修正の使用」をご覧ください。
次のクエリは、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"