• 감사 이벤트란 무엇인가요?
• 감사 이벤트가 아닌 것은 무엇인가요?
• 감사 이벤트 스키마
• 새로운 감사 이벤트 도입 방법
  • 블록을 사용하여 여러 이벤트 기록하기
  • 표준 메서드 호출을 사용하여 단일 이벤트 기록하기
  • 데이터 볼륨 고려 사항
• 감사 이벤트 계측 흐름
  • 블록을 사용하여 여러 이벤트 기록하기
  • 표준 메서드 호출을 사용하여 단일 이벤트 기록하기
• 이벤트 유형 정의
  • 새로운 감사 이벤트 유형 추가
  • 스키마
  • 문서 생성
• 이벤트 스트리밍
  • I18N 및 감사 이벤트 :message 속성

감사 이벤트 개발 가이드라인

이 가이드는 감사 이벤트가 어떻게 작동하는지와 새로운 감사 이벤트를 도입하는 방법에 대한 개요를 제공합니다.

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

감사 이벤트는 GitLab 소유자와 관리자가 애플리케이션 전반에서 수행된 중요한 작업의 기록을 볼 수 있는 도구입니다.

감사 이벤트가 아닌 것은 무엇인가요?

모든 이벤트가 감사 이벤트를 유발할 수 있지만, 모든 이벤트가 감사 이벤트로 적합하지는 않습니다. 일반적으로 감사 이벤트에 대해 적합하지 않은 이벤트는 다음과 같습니다:

• 특정 사용자에게 귀속되지 않는 경우.
• 관리자 또는 소유자 페르소나에 특정한 관심이 없는 경우.
• 제품 기능 채택 추적 정보인 경우.
• 예정되지 않은 사항에 대한 방향 페이지의 논의에 포함된 경우.

질문이 있는 경우, 감사 이벤트 또는 다른 접근 방식이 귀하의 이벤트에 가장 적합한지 확인하기 위해 @gitlab-org/govern/compliance에 문의하세요.

감사 이벤트 스키마

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

새로운 감사 이벤트 도입 방법

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에서 감사 이벤트를 기록할 때 추출됩니다.

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

이 메서드는 더 직관적인 흐름을 가지고 있으며, EventQueue와 로컬 스레드에 의존하지 않습니다.

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

이벤트 유형 정의

• GitLab 15.4에 도입됨.

모든 새로운 감사 이벤트는 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을 사용하도록 합니다.

스키마

문서 생성

감사 이벤트 유형 문서는 자동으로 생성되며 게시됨 GitLab 문서 사이트에.

새로운 감사 이벤트 유형을 추가한 경우, 문서를 업데이트하기 위해 gitlab:audit_event_types:compile_docs Rake 작업을 실행합니다:

bundle exec rake gitlab:audit_event_types:compile_docs

문서가 최신인지 확인하기 위해 gitlab:audit_event_types:check_docs Rake 작업을 실행합니다:

bundle exec rake gitlab:audit_event_types:check_docs

이벤트 스트리밍

Group 또는 Project가 엔터티인 모든 이벤트는 감사 로그에 기록되며, 하나 이상의 이벤트 스트리밍 목적지로 스트리밍됩니다. 엔터티가 다음인 경우:

• Group, 이벤트는 그룹의 루트 조상 이벤트 스트리밍 목적지로 스트리밍됩니다.
• Project, 이벤트는 프로젝트의 루트 조상 이벤트 스트리밍 목적지로 스트리밍됩니다.

데이터베이스에 저장되지 않는 스트리밍 전용 이벤트를 추가할 수 있습니다. 스트리밍 전용 이벤트는 대량의 데이터를 생성하는 작업에 주로 사용됩니다. 이 병합 요청을 참조하세요. 이 기능은 활발하게 개발 중입니다. 기능 개발에 대한 업데이트는 부모 에픽을 따르세요.

I18N 및 감사 이벤트 :message 속성

우리는 감사 이벤트 메시지를 의도적으로 번역하지 않습니다. 번역된 메시지는 데이터베이스에 저장되어 사용자의 로케일 설정과 관계없이 사용자에게 제공됩니다.

예를 들어, 이는 인증된 사용자의 로케일을 사용하여 감사 이벤트 메시지를 기록하고 잘못된 언어로 해당 스트리밍 대상에 메시지를 스트리밍할 수 있음을 의미할 수 있습니다. 사용자들은 이를 혼란스러워할 수 있습니다.