최상위 그룹을 위한 감사 이벤트 스트리밍 GraphQL API

Tier: Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

최상위 그룹에 대한 감사 이벤트 스트리밍 대상을 GraphQL API를 사용하여 관리합니다.

HTTP 대상

최상위 그룹에 대한 HTTP 스트리밍 대상을 관리합니다.

새로운 스트리밍 대상 추가

최상위 그룹에 새로운 스트리밍 대상을 추가합니다.

경고:
스트리밍 대상은 모든 감사 이벤트 데이터를 수신하며, 여기에는 민감한 정보가 포함될 수 있습니다. 스트리밍 대상을 신뢰하는지 확인하세요.

전제 조건:

  • 최상위 그룹의 소유자 역할.

스트리밍을 활성화하고 최상위 그룹에 대상을 추가하려면 externalAuditEventDestinationCreate 변이를 사용하세요.

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

기본 GitLab 생성 검증 토큰 대신 자체 검증 토큰을 선택적으로 지정할 수 있습니다. GraphQL
externalAuditEventDestinationCreate
변이를 사용합니다. 검증 토큰 길이는 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 생성 이름 대신 자체 대상 이름을 선택적으로 지정할 수 있습니다. GraphQL
externalAuditEventDestinationCreate
변이를 사용합니다. 이름 길이는 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로 응답한다.

GraphQL auditEventsStreamingHeadersCreate 변이를 사용하여 HTTP 헤더를 추가할 수 있습니다. 스트리밍 대상을 나열하여 그룹의 대상 ID를 검색하거나 위의 변이에서 가져올 수 있습니다.

mutation {
  auditEventsStreamingHeadersCreate(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
     key: "foo",
     value: "bar",
     active: false
  }) {
    errors
    header {
      id
      key
      value
      active
    }
  }
}

반환된 errors 객체가 비어 있으면 헤더가 생성됩니다.

스트리밍 대상을 나열하기

최상위 그룹에 대한 스트리밍 대상을 나열합니다.

전제 조건:

  • 최상위 그룹에 대한 소유자 역할.

최상위 그룹에 대한 스트리밍 대상을 보려면 externalAuditEventDestinations 쿼리 유형을 사용하십시오.

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

결과 목록이 비어 있으면 해당 그룹에 대한 감사 스트리밍이 활성화되지 않은 것입니다.

스트리밍 대상을 업데이트하기

최상위 그룹에 대한 스트리밍 대상을 업데이트합니다.

전제 조건:

  • 최상위 그룹에 대한 소유자 역할.

그룹에 대한 스트리밍 대상을 업데이트하려면 externalAuditEventDestinationUpdate 변형 유형을 사용하십시오. 스트리밍 대상을 나열하여 대상 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로 응답합니다.

그룹에 대한 소유자 역할을 가진 사용자는 auditEventsStreamingHeadersUpdate 변형 유형을 사용하여 스트리밍 대상의 사용자 정의 HTTP 헤더를 업데이트할 수 있습니다. 사용자 정의 HTTP 헤더를 나열하여 사용자 정의 HTTP 헤더 ID를 검색할 수 있습니다.

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

그룹 소유자는 GraphQL auditEventsStreamingHeadersDestroy 변형을 사용하여 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로 응답합니다.

그룹 소유자는 GraphQL auditEventsStreamingHeadersDestroy 변형을 사용하여 HTTP 헤더를 제거할 수 있습니다. 사용자 정의 HTTP 헤더를 나열하여 헤더 ID를 검색할 수 있습니다.

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

반환된 errors 객체가 비어 있으면 헤더가 삭제됩니다.

이벤트 유형 필터

  • GitLab 15.7에서 도입된 이벤트 유형 필터 API 소개됨.

이 기능이 그룹에 대해 활성화되면, 사용자는 API를 사용하여 스트리밍 감사 이벤트를 목적지별로 필터링할 수 있습니다.

기능이 필터 없이 활성화된 경우, 목적지는 모든 감사 이벤트를 수신하게 됩니다.

이벤트 유형 필터가 설정된 스트리밍 목적지는 filtered ( ) 레이블이 있습니다.

API를 사용하여 이벤트 유형 필터 추가하기

전제 조건:

  • 그룹에 대한 소유자 역할을 가져야 합니다.

auditEventsStreamingDestinationEventsAdd 쿼리 유형을 사용하여 이벤트 유형 필터 목록을 추가할 수 있습니다:

mutation {
    auditEventsStreamingDestinationEventsAdd(input: {
        destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
        eventTypeFilters: ["이벤트 유형 필터 목록"]}){
        errors
        eventTypeFilters
    }
}

이벤트 유형 필터는 다음과 같이 추가됩니다:

  • 반환된 errors 객체가 비어 있습니다.
  • API 응답이 200 OK입니다.

API를 사용하여 이벤트 유형 필터 제거하기

전제 조건:

  • 그룹에 대한 소유자 역할을 가져야 합니다.

auditEventsStreamingDestinationEventsRemove 뮤테이션 유형을 사용하여 이벤트 유형 필터 목록을 제거할 수 있습니다:

mutation {
    auditEventsStreamingDestinationEventsRemove(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    eventTypeFilters: ["이벤트 유형 필터 목록"]
  }){
    errors
  }
}

이벤트 유형 필터는 다음과 같이 제거됩니다:

  • 반환된 errors 객체가 비어 있습니다.
  • API 응답이 200 OK입니다.

네임스페이스 필터

  • GitLab 16.7에서 도입된 네임스페이스 필터 API 소개됨.

그룹에 네임스페이스 필터를 적용하면 사용자는 특정 하위 그룹 또는 그룹의 프로젝트별로 스트리밍 감사 이벤트를 필터링할 수 있습니다. 그렇지 않으면,

목적지는 모든 감사 이벤트를 수신하게 됩니다.

네임스페이스 필터가 설정된 스트리밍 목적지는 filtered ( ) 레이블이 있습니다.

API를 사용하여 네임스페이스 필터 추가하기

전제 조건:

  • 그룹에 대한 소유자 역할을 가져야 합니다.

하위 그룹과 프로젝트 모두에 대해 auditEventsStreamingHttpNamespaceFiltersAdd 뮤테이션 유형을 사용하여 네임스페이스 필터를 추가할 수 있습니다.

네임스페이스 필터는 다음과 같이 추가됩니다:

  • API가 비어 있는 errors 객체를 반환합니다.
  • API 응답이 200 OK입니다.
하위 그룹을 위한 뮤테이션 
mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    groupPath: "path/to/subgroup"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}
프로젝트를 위한 뮤테이션 
mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    projectPath: "path/to/project"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}

API를 사용하여 네임스페이스 필터 제거하기

전제 조건:

  • 그룹에 대한 소유자 역할을 가져야 합니다.

auditEventsStreamingHttpNamespaceFiltersDelete 뮤테이션 유형을 사용하여 네임스페이스 필터를 제거할 수 있습니다:

mutation auditEventsStreamingHttpNamespaceFiltersDelete {
  auditEventsStreamingHttpNamespaceFiltersDelete(input: {
    namespaceFilterId: "gid://gitlab/AuditEvents::Streaming::HTTP::NamespaceFilter/5"
  }) {
    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에서 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", name: "destination-name" } ) {
    errors
    googleCloudLoggingConfiguration {
      id
      googleProjectIdName
      logIdName
      clientEmail
      name
    }
    errors
  }
}

이벤트 스트리밍이 활성화된 경우:

  • 반환된 errors 객체가 비어 있습니다.
  • API가 200 OK로 응답합니다.

Google Cloud Logging 구성 목록

최상위 그룹에 대한 모든 Google Cloud Logging 구성 대행지를 나열합니다.

전제 조건:

  • 최상위 그룹에 대한 소유자 역할.

최상위 그룹에 대한 스트리밍 구성 목록을 보려면 googleCloudLoggingConfigurations 쿼리 유형을 사용하세요.

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

결과 목록이 비어 있으면 그룹에 대해 감사 스트리밍이 활성화되지 않은 것입니다.

업데이트 및 삭제 뮤테이션을 위해 이 쿼리에서 반환된 ID 값이 필요합니다.

Google Cloud Logging 구성 업데이트

최상위 그룹에 대한 Google Cloud Logging 구성 대행지를 업데이트합니다.

전제 조건:

  • 최상위 그룹에 대한 소유자 역할.

최상위 그룹에 대한 스트리밍 구성을 업데이트하려면 googleCloudLoggingConfigurationUpdate 뮤테이션 유형을 사용하세요. 모든 외부 대행지를 나열하여 구성 ID를 검색할 수 있습니다. Google Cloud Logging 구성 목록.

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", name: "updated-destination-name" }
  ) {
    errors
    googleCloudLoggingConfiguration {
      id
      logIdName
      googleProjectIdName
      clientEmail
      name
    }
  }
}

스트리밍 구성은 다음의 경우에 업데이트됩니다:

  • 반환된 errors 객체가 비어 있습니다.
  • API가 200 OK로 응답합니다.

Google Cloud Logging 구성 삭제

최상위 그룹에 대한 스트리밍 대행지를 삭제합니다.

마지막 대행지가 성공적으로 삭제되면 그룹에 대한 스트리밍이 비활성화됩니다.

전제 조건:

  • 최상위 그룹에 대한 소유자 역할.

그룹에 대한 스트리밍 구성을 삭제할 수 있는 소유자 역할을 가진 사용자는 googleCloudLoggingConfigurationDestroy 뮤테이션 유형을 사용하여 삭제할 수 있습니다. 그룹에 대한 모든 스트리밍 대행지를 나열하여 구성 ID를 검색할 수 있습니다. Google Cloud Logging 구성 목록.

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

스트리밍 구성은 다음의 경우에 삭제됩니다:

  • 반환된 errors 객체가 비어 있습니다.
  • API가 200 OK로 응답합니다.