최상위 그룹을 위한 감사 이벤트 스트리밍 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
      }
    }
  }
}

GraphQL externalAuditEventDestinationCreate 뮤테이션을 사용하여 기본 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
      }
    }
  }
}

GraphQL externalAuditEventDestinationCreate 뮤테이션을 사용하여 기본 GitLab에서 생성된 대신 고유한 대상 이름을 지정할 수도 있습니다. 이름의 길이는 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 헤더를 나열하여 헤더 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 객체가 비어 있으면 헤더가 삭제됩니다.

스트리밍 대상 삭제

최상위 그룹의 스트리밍 대상을 삭제합니다.

마지막 대상이 성공적으로 삭제되면 해당 그룹의 스트리밍이 비활성화됩니다.

Prerequisites:

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

그룹의 소유자 역할을 가진 사용자는 externalAuditEventDestinationDestroy 뮤테이션 유형을 사용하여 스트리밍 대상을 삭제할 수 있습니다. 대상의 ID는 그룹의 모든 스트리밍 대상을 나열하여 검색할 수 있습니다. 

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

스트리밍 대상이 삭제되는 경우:

  • 반환된 errors 객체가 비어 있는 경우
  • API가 200 OK로 응답하는 경우

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

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

헤더가 삭제되는 경우 반환된 errors 객체가 비어 있습니다.

이벤트 유형 필터

  • 이벤트 유형 필터 API는 GitLab 15.7에서 도입되었습니다.

그룹에 대해 이 기능이 활성화되면 API를 사용하여 일치하는 대상 별로 스트리밍된 감사 이벤트를 필터링할 수 있습니다. 필터가 없이 활성화되면 대상은 모든 감사 이벤트를 수신합니다.

이벤트 유형 필터가 설정된 스트리밍 대상에는 필터링됨 () 라벨이 표시됩니다.

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

Prerequisites:

  • 그룹에 대한 소유자 역할이 있어야 합니다.

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

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

이벤트 유형 필터가 추가되는 경우:

  • 반환된 errors 객체가 비어 있는 경우
  • API가 200 OK로 응답하는 경우

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

Prerequisites:

  • 그룹에 대한 소유자 역할이 있어야 합니다.

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

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

이벤트 유형 필터가 제거되는 경우:

  • 반환된 errors 객체가 비어 있는 경우
  • API가 200 OK로 응답하는 경우

네임스페이스 필터

  • 네임스페이스 필터 API는 GitLab 16.7에서 도입되었습니다.

그룹에 네임스페이스 필터를 적용하면 해당 그룹의 특정 서브 그룹 또는 프로젝트에 대한 대상별 스트리밍된 감사 이벤트를 필터링할 수 있습니다. 그렇지 않으면 해당 대상은 모든 감사 이벤트를 수신합니다.

네임스페이스 필터가 설정된 스트리밍 대상에는 필터링됨 () 라벨이 표시됩니다.

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

Prerequisites:

  • 그룹에 대한 소유자 역할이 있어야 합니다.

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를 사용하여 네임스페이스 필터 제거

Prerequisites:

  • 그룹에 대한 소유자 역할이 있어야 합니다.

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

mutation auditEventsStreamingHttpNamespaceFiltersDelete {
  auditEventsStreamingHttpNamespaceFiltersDelete(input: {
    namespaceFilterId: "gid://gitlab/AuditEvents::Streaming::HTTP::NamespaceFilter/5"
  }) {
    errors
  }
}

네임스페이스 필터가 제거되는 경우:

  • 반환된 errors 객체가 비어 있는 경우
  • API가 200 OK로 응답하는 경우

Google Cloud Logging 대상

  • GitLab 16.1에서 도입되었습니다.

최상위 그룹의 Google Cloud Logging 대상을 관리합니다.

Google Cloud Logging을 통한 스트리밍 감사 이벤트를 설정하기 전에 필수 사항을 충족해야 합니다.

새로운 Google Cloud Logging 대상 추가

최상위 그룹에 새로운 Google Cloud Logging 구성 대상을 추가합니다.

Prerequisites:

  • 최상위 그룹의 소유자 역할.
  • Google Cloud 프로젝트에서 서비스 계정을 생성하고 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를 검색할 수 있습니다. 외부 대상을 모두 나열. 

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를 검색할 수 있습니다. (스트리밍 대상 모두 나열). 

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

다음이 성공하면 스트리밍 구성이 삭제됩니다:

  • 반환된 errors 객체가 비어 있는 경우.
  • API가 200 OK로 응답하는 경우.