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

プラン: Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

GitLab 16.0でff_external_audit_eventsフラグとともに導入されました。デフォルトでは無効になっています。
インスタンスレベルのストリーミング先のカスタムHTTPヘッダーのAPIは、GitLab 16.1で導入されました。ff_external_audit_eventsという名前のフラグ付き。デフォルトでは無効になっています。
機能フラグff_external_audit_eventsは、GitLab 16.2でデフォルトで有効になっています。
ユーザー指定のストリーミング先名APIサポートは、GitLab 16.2で導入されました。
インスタンスのストリーミング先は、GitLab 16.4で一般提供されました。機能フラグff_external_audit_eventsは削除されました。

GraphQL APIを使用して、インスタンスの監査イベントストリーミング先を管理します。

HTTPの送信先

インスタンス全体の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で応答します。

オプションで、GraphQL instanceExternalAuditEventDestinationCreateミューテーションを使用して、（デフォルトのGitLab生成の代わりに）独自のストリーミング先名を指定できます。名前の長さは72文字を超えてはならず、末尾の空白はトリミングされません。この値は一意である必要があります。例:

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

インスタンスの管理者は、GraphQL auditEventsStreamingInstanceHeadersCreateミューテーションを使用してHTTPヘッダーを追加できます。ストリーミング先IDは、インスタンスのストリーミング先をすべて一覧表示するか、前のミューテーションから取得することができます。

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

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

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

インスタンスのすべてのHTTPストリーミング先を一覧表示します。

前提要件:

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

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

query {
  instanceExternalAuditEventDestinations {
    nodes {
      id
      name
      destinationUrl
      verificationToken
      headers {
        nodes {
          id
          key
          value
          active
        }
      }
      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ヘッダーIDは、インスタンスのカスタムHTTPヘッダーをすべて一覧表示することで取得することができます。

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

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

ストリーミング先を削除する

インスタンス全体のストリーミング先を削除します。

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

前提要件:

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

ストリーミング先を削除するには、instanceExternalAuditEventDestinationDestroyミューテーションタイプを使用します。ストリーミング先IDは、インスタンスのストリーミング先をすべて一覧表示することで取得することができます。

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

ストリーミング先が削除されるのは、次の場合です:

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

HTTPヘッダーを削除するには、GraphQL auditEventsStreamingInstanceHeadersDestroyミューテーションを使用します。ヘッダーIDを取得するには、インスタンスのカスタムHTTPヘッダーをすべて一覧表示します。

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

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

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

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

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

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で応答します。

Google Cloud Loggingの送信先

インスタンス全体のGoogle Cloud Loggingの送信先を管理します。

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

新しいGoogle Cloud Loggingの送信先を追加

新しいGoogle Cloud Logging設定のストリーミング先をインスタンスに追加します。

前提要件:

インスタンスへの管理者アクセス権が必要です。
サービスアカウントを作成し、Google Cloud Loggingを有効にするために必要な権限を持つGoogle Cloudプロジェクトが必要です。

ストリーミングを有効にして設定を追加するには、GraphQL APIでinstanceGoogleCloudLoggingConfigurationCreateミューテーションを使用します。

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

イベントストリーミングが有効になるのは、次の場合です:

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

Google Cloud Logging設定を一覧表示する

インスタンスのすべてのGoogle Cloud Logging設定のストリーミング先を一覧表示します。

前提要件:

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

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

query {
  instanceGoogleCloudLoggingConfigurations {
    nodes {
      id
      logIdName
      googleProjectIdName
      clientEmail
      name
    }
  }
}

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

更新および削除ミューテーションには、このクエリから返されたID値が必要です。

Google Cloud Logging設定を更新する

インスタンスのGoogle Cloud Logging設定のストリーミング先を更新します。

前提要件:

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

インスタンスの設定を更新するには、instanceGoogleCloudLoggingConfigurationUpdateミューテーションタイプを使用します。設定IDは、外部のストリーミング先をすべて一覧表示ことで取得することができます。

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

ストリーミングの設定が更新されるのは、次の場合です:

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

Google Cloud Logging設定を削除する

インスタンスのストリーミング先を削除します。

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

前提要件:

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

設定を削除するには、instanceGoogleCloudLoggingConfigurationDestroyミューテーションタイプを使用します。設定IDは、インスタンスのストリーミング先をすべて一覧表示することで取得することができます。

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

ストリーミングの設定が削除されるのは、次の場合です:

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