監査イベントストリーミングGraphQL API

監査イベントストリーミングの送信先は、GraphQL APIを使ってメンテナーすることができます。

トップレベルのグループストリーミングデスティネーション

トップレベルグループのストリーミング配信先を管理します。

HTTP配信先

トップレベルグループのHTTPストリーミング先を管理します。

新しいストリーミング先を追加

新しいストリーミング配信先をトップレベルグループに追加します。

caution
ストリーミング先は、機密情報を含む可能性のあるすべての監査イベントデータを受信します。ストリーミングデスティネーションが信頼できることを確認してください。

前提条件：

  • トップレベルグループのオーナーロール。

ストリーミングを有効にして、宛先をトップレベルグループに追加するには、externalAuditEventDestinationCreate 変異を使用します。

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", groupPath: "my-group" } ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

オプションで、GraphQLexternalAuditEventDestinationCreate 変異を使って（GitLab が生成したデフォルトのものではなく）独自の検証トークンを指定することができます。検証トークンの長さは16文字から24文字以内で、末尾の空白はトリミングされません。暗号的にランダムでユニークな値を設定する必要があります。例えば

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", groupPath: "my-group", verificationToken: "unique-random-verification-token-here" } ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

オプションで、（GitLabが生成したデフォルトの名前ではなく）独自の宛先名をGraphQLexternalAuditEventDestinationCreate mutationを使って指定することができます。名前の長さは72文字以内で、末尾の空白はトリミングされません。この値はグループに対して一意でなければなりません。例えば

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here", groupPath: "my-group" }) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

イベントストリーミングが有効な場合：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

GraphQLauditEventsStreamingHeadersCreate 変異を使用して HTTP ヘッダーを追加できます。グループのすべてのストリーミング配信先をリストするか、上記の変異から配信先 ID を取得できます。

mutation {
  auditEventsStreamingHeadersCreate(input: { destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/24601", key: "foo", value: "bar" }) {
    errors
  }
}

ヘッダーは、返されたerrors オブジェクトが空の場合に作成されます。

ストリーミング先のリスト

トップレベルグループの配信先を一覧表示します。

前提条件：

  • トップレベルグループのオーナーロール。

externalAuditEventDestinations クエリタイプを使用して、トップレベルグループのストリーミング先のリストを表示できます。

query {
  group(fullPath: "my-group") {
    id
    externalAuditEventDestinations {
      nodes {
        destinationUrl
        verificationToken
        id
        name
        headers {
          nodes {
            key
            value
            id
          }
        }
        eventTypeFilters
      }
    }
  }
}

結果のリストが空の場合、そのグループの監査ストリーミングは有効になっていません。

ストリーミング先の更新

トップレベルグループのストリーミング配信先を更新します。

前提条件：

  • トップレベルグループのオーナーロール。

グループのオーナーロールを持つユーザーは、auditEventsStreamingHeadersUpdate 変異タイプを使用して、ストリーミング先のカスタムHTTPヘッダーを更新できます。グループのすべてのカスタムHTTPヘッダーを一覧表示すると、カスタムHTTPヘッダーIDを取得できます。

mutation {
  externalAuditEventDestinationUpdate(input: {
    id:"gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    destinationUrl: "https://www.new-domain.com/webhook",
    name: "destination-name"} ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

以下の場合、ストリーミング配信先が更新されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

グループのオーナーは、GraphQLauditEventsStreamingHeadersDestroy mutation を使用して HTTP ヘッダーを削除できます。グループのすべてのカスタム HTTP ヘッダーをリストすることで、ヘッダー ID を取得できます。

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

返されたerrors オブジェクトが空の場合、ヘッダーは削除されます。

ストリーミング先の削除

最上位グループの配信先を削除します。

最後の宛先が正常に削除されると、そのグループのストリーミングは無効になります。

前提条件：

  • トップレベルグループのオーナーロール。

グループのオーナーロールを持つユーザーは、externalAuditEventDestinationDestroy 変異タイプを使用して、ストリーミング配信先を削除できます。グループの全ストリーミング配信先を一覧表示することで、配信先IDを取得できます。

mutation {
  externalAuditEventDestinationDestroy(input: { id: destination }) {
    errors
  }
}

ストリーミング配信先は、以下の場合に削除されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

グループのオーナーは、GraphQLauditEventsStreamingHeadersDestroy mutation を使用して HTTP ヘッダーを削除できます。グループのすべてのカスタム HTTP ヘッダーをリストすることで、ヘッダー ID を取得できます。

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

返されたerrors オブジェクトが空の場合、ヘッダーは削除されます。

イベントタイプフィルター

GitLab 15.7で導入されたイベントタイプフィルタAPIです。

この機能がグループで有効になっている場合、APIを使用してユーザーがストリームされた監査イベントを宛先ごとにフィルタリングすることを許可することができます。この機能がフィルタなしで有効になっている場合、宛先はすべての監査イベントを受信します。

イベントタイプのフィルタが設定されているストリーミング宛先には、フィルタ済み({filter})ラベルがあります。

APIを使用してイベントタイプフィルタを追加します。

前提条件：

  • グループのオーナーロールを持っている必要があります。

auditEventsStreamingDestinationEventsAdd クエリ タイプを使用して、イベント タイプ フィルタのリストを追加できます：

mutation {
    auditEventsStreamingDestinationEventsAdd(input: {
        destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
        eventTypeFilters: ["list of event type filters"]}){
        errors
        eventTypeFilters
    }
}

イベント・タイプ・フィルターは以下の場合に追加されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。
APIを使用してイベントタイプのフィルタを削除します。

前提条件：

  • グループのオーナーロールを持っている必要があります。

auditEventsStreamingDestinationEventsRemove 変異タイプを使用して、イベント タイプ フィルタのリストを削除できます：

mutation {
    auditEventsStreamingDestinationEventsRemove(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    eventTypeFilters: ["list of event type filters"]
  }){
    errors
  }
}

イベントタイプフィルターは以下の場合に削除されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

Google Cloud ログ取得先

GitLab 16.1 で導入されました。

トップレベルグループのGoogle Cloud Logging送信先を管理します。

Google Cloud Logging ストリーミング監査イベントを設定する前に、前提条件を満たす必要があります。

新しい Google Cloud Logging の宛先を追加します。

新しい Google Cloud Logging 設定先をトップレベルグループに追加します。

前提条件：

  • トップレベルグループのオーナーロール。
  • サービスアカウントを作成し、Google Cloud Loggingを有効にするために必要な権限を持つGoogle Cloudプロジェクト。

ストリーミングを有効にして設定を追加するには、GraphQL API のgoogleCloudLoggingConfigurationCreate 変異を使用します。

mutation {
  googleCloudLoggingConfigurationCreate(input: { groupPath: "my-group", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events" } ) {
    errors
    googleCloudLoggingConfiguration {
      id
      googleProjectIdName
      logIdName
      privateKey
      clientEmail
    }
    errors
  }
}

イベントストリーミングが有効な場合：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

Google Cloud Logging の設定一覧

トップレベルグループのすべての Google Cloud Logging 設定先を一覧表示します。

前提条件

  • トップレベルグループのオーナーロール。

googleCloudLoggingConfigurations クエリタイプを使用すると、トップレベルグループのストリーミング設定のリストを表示できます。

query {
  group(fullPath: "my-group") {
    id
    googleCloudLoggingConfigurations {
      nodes {
        id
        logIdName
        googleProjectIdName
        privateKey
        clientEmail
      }
    }
  }
}

結果のリストが空の場合、監査ストリーミングはグループで有効になっていません。

このクエリによって返される ID 値は、更新および削除の変異に必要です。

Google Cloud Logging 設定の更新

トップレベルグループのGoogle Cloud Logging設定先を更新します。

前提条件

  • トップレベルグループのオーナーロール。

トップレベルグループのストリーミング設定を更新するには、googleCloudLoggingConfigurationUpdate 変異タイプを使用します。すべての外部送信先をリストすることで、設定IDを取得できます。

mutation {
  googleCloudLoggingConfigurationUpdate(
    input: {id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events"}
  ) {
    errors
    googleCloudLoggingConfiguration {
      id
      logIdName
      privateKey
      googleProjectIdName
      clientEmail
    }
  }
}

ストリーミング設定は以下の場合に更新されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

Google Cloud Logging 設定の削除

最上位グループの配信先を削除します。

最後の宛先が正常に削除されると、そのグループのストリーミングは無効になります。

前提条件

  • トップレベルグループのオーナーロール。

グループのオーナーロールを持つユーザーは、googleCloudLoggingConfigurationDestroy 変異タイプを使用して、ストリーミング設定を削除できます。設定IDは、グループのすべてのストリーミング配信先を一覧表示することで取得できます。

mutation {
  googleCloudLoggingConfigurationDestroy(input: { id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1" }) {
    errors
  }
}

以下の場合、ストリーミング設定は削除されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

インスタンスのストリーミング先

フラグ: セルフマネジメントのGitLabでは、デフォルトでこの機能が有効になっています。無効にするには、管理者がff_external_audit_eventsという機能フラグを無効にします。GitLab.comでは、この機能は利用可能ですが、GitLab.com管理者のみが設定できます。この機能は本番環境でも使用可能です。

インスタンス全体のHTTPストリーミング先を管理。

新しいHTTPデスティネーションの追加

インスタンスに新しいHTTPストリーミング・デスティネーションを追加します。

前提条件：

  • インスタンスの管理者アクセス。

ストリーミングを有効にして宛先を追加するには、GraphQL API のinstanceExternalAuditEventDestinationCreate 変異を使用します。

mutation {
  instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest"}) {
    errors
    instanceExternalAuditEventDestination {
      destinationUrl
      id
      name
      verificationToken
    }
  }
}

イベントストリーミングが有効な場合：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

オプションで、（GitLabが生成したデフォルトの名前ではなく）独自の宛先名をGraphQLinstanceExternalAuditEventDestinationCreate mutationを使って指定することができます。名前の長さは72文字以内で、末尾の空白はトリミングされません。この値は一意でなければなりません。例えば

mutation {
  instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here"}) {
    errors
    instanceExternalAuditEventDestination {
      destinationUrl
      id
      name
      verificationToken
    }
  }
}

インスタンス管理者は GraphQLauditEventsStreamingInstanceHeadersCreate 変異を使用して HTTP ヘッダーを追加できます。インスタンスのすべてのストリーミング送信先をリストするか、上記の変異から送信先 ID を取得できます。

mutation {
  auditEventsStreamingInstanceHeadersCreate(input:
    {
      destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/42",
      key: "foo",
      value: "bar"
    }) {
    errors
    header {
      id
      key
      value
    }
  }
}

ヘッダーは、返されたerrors オブジェクトが空の場合に作成されます。

ストリーミング先のリスト

インスタンスのすべての HTTP ストリーミング・デスティネーションを一覧表示します。

前提条件：

  • インスタンスの管理者アクセス。

インスタンスのストリーミング先のリストを表示するには、instanceExternalAuditEventDestinations クエリ・タイプを使用します。

query {
  instanceExternalAuditEventDestinations {
    nodes {
      id
      name
      destinationUrl
      verificationToken
      headers {
        nodes {
          id
          key
          value
        }
      }
      eventTypeFilters
    }
  }
}

結果のリストが空の場合は、インスタンスで監査ストリーミングが有効になっていません。

このクエリによって返される ID 値は、更新および削除の変異に必要です。

ストリーミング先の更新

インスタンスの HTTP ストリーミング・デスティネーションを更新します。

前提条件：

  • インスタンスの管理者アクセス。

インスタンスのストリーミング・デスティネーションを更新するには、instanceExternalAuditEventDestinationUpdate 変異タイプを使用します。インスタンスのすべての外部デスティネーションをリストすることで、デスティネーションIDを取得できます。

mutation {
  instanceExternalAuditEventDestinationUpdate(input: {
    id: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1",
    destinationUrl: "https://www.new-domain.com/webhook",
    name: "destination-name"}) {
    errors
    instanceExternalAuditEventDestination {
      destinationUrl
      id
      name
      verificationToken
    }
  }
}

以下の場合、ストリーミング配信先が更新されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

インスタンス管理者は、auditEventsStreamingInstanceHeadersUpdate 変異タイプを使用して、ストリーミング先のカスタム HTTP ヘッダーを更新できます。インスタンスのすべてのカスタム HTTP ヘッダーをリストすることで、カスタム HTTP ヘッダー ID を取得できます。

mutation {
  auditEventsStreamingInstanceHeadersUpdate(input: { headerId: "gid://gitlab/AuditEvents::Streaming::InstanceHeader/2", key: "new-key", value: "new-value" }) {
    errors
    header {
      id
      key
      value
    }
  }
}

返されたerrors オブジェクトが空の場合、ヘッダーは更新されます。

ストリーミング先の削除

インスタンス全体のストリーミング・デスティネーションを削除します。

最後の宛先が正常に削除されると、インスタンスのストリーミングが無効になります。

前提条件：

  • インスタンスの管理者アクセス。

ストリーミング・デスティネーションを削除するには、instanceExternalAuditEventDestinationDestroy 変異タイプを使用します。インスタンスのすべてのストリーミング・デスティネーションをリストすることで、デスティネーションIDを取得できます。

mutation {
  instanceExternalAuditEventDestinationDestroy(input: { id: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1" }) {
    errors
  }
}

ストリーミング配信先は、以下の場合に削除されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

HTTP ヘッダーを削除するには、GraphQLauditEventsStreamingInstanceHeadersDestroy 変異を使用します。ヘッダー ID を取得するには、インスタンスのすべてのカスタム HTTP ヘッダーをリストします。

mutation {
  auditEventsStreamingInstanceHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::InstanceHeader/<id>" }) {
    errors
  }
}

返されたerrors オブジェクトが空の場合、ヘッダーは削除されます。

イベントタイプフィルター

GitLab 16.2で導入されたイベントタイプフィルタAPIです。

この機能がインスタンスで有効になっている場合、APIを使用してユーザーがストリームされた監査イベントをデスティネーションごとにフィルタすることを許可することができます。この機能がフィルタなしで有効になっている場合、デスティネーションはすべての監査イベントを受信します。

イベントタイプのフィルタが設定されているストリーミング宛先には、フィルタ済み({filter})ラベルがあります。

APIを使用してイベントタイプフィルタを追加します。

前提条件：

  • インスタンスの管理者アクセス権が必要です。

auditEventsStreamingDestinationInstanceEventsAdd 変異を使用して、イベント タイプ フィルタのリストを追加できます：

mutation {
    auditEventsStreamingDestinationInstanceEventsAdd(input: {
        destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1",
        eventTypeFilters: ["list of event type filters"]}){
        errors
        eventTypeFilters
    }
}

イベント・タイプ・フィルターは以下の場合に追加されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。

APIを使用してイベントタイプのフィルタを削除します。

前提条件：

  • インスタンスの管理者アクセス権が必要です。

auditEventsStreamingDestinationInstanceEventsRemove 変異を使用して、イベント タイプ フィルタのリストを削除できます：

mutation {
    auditEventsStreamingDestinationInstanceEventsRemove(input: {
    destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1",
    eventTypeFilters: ["list of event type filters"]
  }){
    errors
  }
}

イベントタイプフィルターは以下の場合に削除されます：

  • 返されたerrors オブジェクトが空の場合。
  • API は200 OK で応答します。