감사 이벤트 개발 지침

이 가이드는 감사 이벤트가 작동하는 방식과 새로운 감사 이벤트를 도구화하는 개요를 제공합니다.

감사 이벤트란 무엇인가요?

감사 이벤트는 GitLab 소유자 및 관리자가 응용 프로그램에서 수행된 중요한 작업 기록을 볼 수 있는 도구입니다.

어떤 것들이 감사 이벤트가 아니어야 하나요?

어떤 이벤트든 감사 이벤트를 트리거할 수 있지만, 모든 이벤트가 그렇지는 않습니다. 일반적으로 감사 이벤트에 적합하지 않은 이벤트는 다음과 같습니다.

  • 특정한 사용자에게 속하지 않음
  • 관리자나 소유자 페르소나에게 특별한 관심을 끌지 않음
  • 제품 기능 채택에 대한 정보 추적
  • 계획되지 않은 사항에 대한 방향 페이지의 논의에 포함됨

질문이 있으면 감사 이벤트나 다른 방법이 이벤트에 가장 적합한지 여부를 확인하려면 @gitlab-org/govern/compliance에 문의하세요.

감사 이벤트 스키마

감사 이벤트를 도구화하기 위해 다음 속성을 제공해야 합니다:

속성 유형 필수여부 설명
name String false 감사될 작업 이름. 이벤트 유형을 나타냅니다. 오류 추적에 사용됨
author 사용자 true 변경을 작성한 사용자. 내부 사용자일 수 있음. 예를 들어, 비활성 프로젝트 삭제의 감사 이벤트는 GitLab-Admin-Bot이 작성함.
scope 사용자, 프로젝트, 그룹 또는 인스턴스 true 감사 이벤트가 속한 범위
target Object true 감사 대상인 객체
message String true 작업을 설명하는 메시지 (번역되지 않음)
created_at DateTime false 작업이 발생한 시간. 기본값은 DateTime.current

새로운 감사 이벤트를 도구화하는 방법

  1. 새로운 감사 이벤트에 대한 YAML 유형 정의를 작성하세요.
  2. 액션 블록을 전달하여 Gitlab::Audit::Auditor.audit를 호출하세요.

다음과 같은 방법으로 감사 이벤트를 도구화하는 방법은 사용이 중단되었습니다:

  • ee/lib/ee/audit/에 새 클래스 작성 및 AuditEventService 확장
  • 성공적인 작업 후 AuditEventService 호출

Gitlab::Audit::Auditor 서비스를 사용하면 두 가지 방법으로 감사 이벤트를 도구화할 수 있습니다:

  • 여러 이벤트를 기록하기 위해 블록 사용
  • 단일 이벤트를 기록하기 위해 표준 메서드 호출 사용

여러 이벤트를 기록하기 위해 블록 사용

이 방법은 이벤트가 호출 스택에서 깊이 발생할 때 사용할 수 있습니다.

예를 들어, 사용자가 병합 요청 승인 규칙을 업데이트할 때 여러 감사 이벤트를 기록할 수 있습니다. 이 사용자 흐름의 일부로, 우리는 결재자와 승인 그룹에 대한 변경 사항을 모두 감사하고자 합니다. 이 때, 초기화 서비스(예: MergeRequestRuleUpdateService)에서 execute 호출을 다음과 같이 래핑할 수 있습니다: 

# 초기화 서비스에서
audit_context = {
  name: 'update_merge_approval_rule',
  author: current_user,
  scope: project_alpha,
  target: merge_approval_rule,
  message: '승인 규칙을 업데이트하려고 시도함'
}

::Gitlab::Audit::Auditor.audit(audit_context) do
  service.execute
end

모델에서(예: ApprovalProjectRule)는 모델 콜백(예: after_save 또는 after_add)에서 감사 이벤트를 푸시할 수 있습니다. 

# 모델에서
include Auditable

def audit_add(model)
  push_audit_event('보안 규칙에 결재자 추가')
end

def audit_remove(model)
  push_audit_event('보안 규칙에서 결재자 제거')
end

이 방법은 비동기로 실행되거나 여러 프로세스에 걸쳐 진행되는 작업을 지원하지 않습니다(예: 백그라운드 작업).

표준 메서드 호출을 사용하여 단일 이벤트 기록

이 방법은 단일 감사 이벤트를 기록하고 더 적은 요소를 포함합니다. 

if merge_approval_rule.save
  audit_context = {
    name: 'create_merge_approval_rule',
    author: current_user,
    scope: project_alpha,
    target: merge_approval_rule,
    message: '새로운 승인 규칙 생성',
    created_at: DateTime.current # 비동기로 생성될 경우 감사 이벤트를 미리 날짜 지정에 유용함
  }

  ::Gitlab::Audit::Auditor.audit(audit_context)
end

데이터 양 고려 사항

모든 감사 이벤트가 데이터베이스에 유지되기 때문에, 새로운 감사 이벤트에 기대되는 데이터 양과 생성 속도를 고려하세요. 데이터베이스에서 많은 데이터를 생성하는 새로운 감사 이벤트의 경우, 스트림 전용 감사 이벤트를 추가하는 것을 고려해 보세요. 이에 대한 질문이 있다면 이에 대해 문의하거나 의견을 물어보기 위해 이슈 또는 병합 요청에서 @gitlab-org/govern/compliance/backend에 자유롭게 메시지를 남기세요.

감사 이벤트 기구화 흐름

감사 이벤트를 도구화하는 두 가지 방법에는 다른 흐름이 있습니다.

여러 이벤트를 기록하기 위해 블록 사용

우리는 Gitlab::Audit::Auditor 내에서 작업 블록을 래핑하여 초기 감사 컨텍스트(author, scope, target) 객체를 캡처합니다.

Auditable 믹스인을 사용하여 상호 작용하는 클래스에서 감사 이벤트를 Gitlab::Audit::EventQueue를 통해 감사 이벤트 큐에 추가하기 위해 추가적인 도구화가 필요합니다.

EventQueue는 SafeRequestStore를 사용하여 로컬 스레드에 저장된 후 나중에 Gitlab::Audit::Auditor에서 감사 이벤트를 기록할 때 추출됩니다.

데이터베이스에 기록하는 것 외에도, 이러한 이벤트를 로그 파일에도 기록합니다.

이벤트 유형 정의

새로운 감사 이벤트는 GitLab의 모든 감사 가능한 이벤트에 대한 단일 진실의 원천을 포함하는 config/audit_events/types/ 또는 ee/config/audit_events/types/에 저장된 유형 정의를 가져야 합니다.

새로운 감사 이벤트 유형 추가

새로운 감사 이벤트 유형을 추가하려면:

  1. YAML 정의를 생성합니다. 다음 중 하나를 사용할 수 있습니다:
    • bin/audit-event-type CLI를 사용하여 YAML 정의를 자동으로 생성합니다.
    • config/audit_events/types/에 새 파일을 만들기 위해 수동 단계를 수행하고, 파일 이름을 이벤트 유형의 이름과 일치하게 합니다. 예를 들어, 사용자가 프로젝트에 추가될 때 트리거되는 이벤트 유형에 대한 정의는 config/audit_events/types/project_add_user.yml에 저장될 수 있습니다.
  2. 파일에 스키마와 일치하는 내용을 추가합니다. 이 스키마는 config/audit_events/types/type_schema.json에 정의되어 있습니다.
  3. Gitlab::Audit::Auditor에 대한 모든 호출이 파일에서 정의된 name을 사용하도록 합니다.

스키마

필드 필요여부 설명
name 예 이벤트 유형을 설명하는 고유한 소문자 및 밑줄로 구분된 이름. 파일 이름과 일치해야 합니다.
description 예 이 이벤트가 어떻게 트리거되는지에 대한 인간이 읽기 쉬운 설명
group 예 이 감사 이벤트를 도입한 그룹의 이름. 예: manage::compliance
introduced_by_issue 예 이 유형의 추가를 제안한 이슈 URL
introduced_by_mr 예 이 새로운 유형을 추가한 MR URL
milestone 예 이 유형이 추가된 마일스톤
saved_to_database 예 이벤트를 데이터베이스와 JSON 로그에 저장할지 여부를 나타내는 플래그
streamed 예 이벤트를 외부 서비스로 스트리밍할지 여부를 나타내는 플래그 (구성된 경우)
scope 예 해당 감사 이벤트 유형을 사용할 수 있는 범위 목록. Project, User, Group, 또는 Instance 중 하나 이상을 포함하는 배열이어야 합니다.

문서 생성

감사 이벤트 유형 문서는 자동으로 생성되고 게시됩니다.

새로운 감사 이벤트 유형을 추가하면 gitlab:audit_event_types:compile_docs Rake task를 실행하여 문서를 업데이트하세요: 

bundle exec rake gitlab:audit_event_types:compile_docs

문서가 최신 상태인지 확인하려면 gitlab:audit_event_types:check_docs Rake task를 실행하세요: 

bundle exec rake gitlab:audit_event_types:check_docs

이벤트 스트리밍

엔티티가 Group 또는 Project인 모든 이벤트는 감사 로그에 기록되고, 한 개 이상의 이벤트 스트리밍 대상으로 스트리밍됩니다. 엔티티가:

  • Group인 경우 이벤트는 그룹의 최상위 조상의 이벤트 스트리밍 대상으로 스트리밍됩니다.
  • Project인 경우 이벤트는 프로젝트의 최상위 조상의 이벤트 스트리밍 대상으로 스트리밍됩니다.

GitLab 데이터베이스에 저장되지 않는 스트리밍 전용 이벤트를 추가할 수 있습니다. 스트리밍 전용 이벤트는 주로 많은 양의 데이터를 생성하는 작업에 사용됩니다. 예: 이 변경 사항. 이 기능은 무거운 개발 과정에 있습니다. 기능 개발에 대한 업데이트는 상위 Epic을 확인하세요.

I18N 및 감사 이벤트의 :message 속성

모든 의도적으로 감사 이벤트 메시지를 번역하지 않습니다. 번역된 메시지는 데이터베이스에 저장되어 사용자가 지정한 로캘 설정과 관계없이 사용자에게 제공될 수 있기 때문에, 올바르지 않은 언어로 외부 스트리밍 대상에 메시지를 스트리밍하는 문제가 발생할 수 있기 때문입니다.

예를 들어, 이것은 인증된 사용자의 로캘을 사용하여 감사 이벤트 메시지를 기록하고 이 메시지를 특정 외부 스트리밍 대상으로 스트리밍하는 경우에 해당 외부 스트리밍 대상에 대해 잘못된 언어로 제공될 수 있음을 의미합니다. 사용자는 이를 혼동스러울 수 있습니다. ```