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

감사 이벤트 개발 지침

이 안내서는 감사 이벤트가 작동하는 방법과 새로운 감사 이벤트를 계측하는 방법에 대한 개요를 제공합니다.

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

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

감사 이벤트로 설정하면 안 되는 것은 무엇인가요?

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

• 특정 사용자에게 할당할 수 없음.
• 관리자나 소유자 페르소나에게 특별히 관심 있는 사건이 아님.
• 제품 기능 채택을 위한 정보 추적 중.
• 방향 페이지의 계획되지 않은 것에 대한 토론에 포함된 것.

질문이 있으면 이벤트에 대해 가장 적합한 감사 이벤트 또는 기타 접근 방법을 확인하려면 @gitlab-org/govern/compliance에 연락하세요.

감사 이벤트 스키마

감사 이벤트를 계측하려면 다음 속성을 제공해야 합니다:

새로운 감사 이벤트를 계측하는 방법

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

표준 방법으로 감사 이벤트를 계측하는 것은 중지된 상태입니다:

• ee/lib/ee/audit/에 새 클래스를 만들고 AuditEventService를 확장하기
• 성공적인 작업 후 AuditEventService 호출

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

• 여러 이벤트에 대해 블록을 사용하는 방법.
• 하나의 이벤트를 기록하기 위해 표준 메서드 호출을 사용하는 방법.

여러 이벤트를 기록하기 위해 블록을 사용하는 방법

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

예를 들어 사용자가 Merge Request 승인 규칙을 업데이트할 때 여러 감사 이벤트를 기록할 수 있습니다. 이 사용자 흐름의 일부로 우리는 승인자와 승인 그룹의 변경 내용을 모두 감사하고자 합니다. 초기화 서비스(예: 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

데이터 양 고려 사항

각 감사 이벤트가 데이터베이스에 지속되기 때문에 새로운 감사 이벤트의 데이터 양과 생성 속도를 고려해야 합니다. 데이터베이스에 많은 데이터를 생성하는 새 감사 이벤트의 경우 스트리밍 전용 감사 이벤트를 추가하는 것을 고려해보세요. 이에 대해 궁금한 사항이 있다면 문제 또는 Merge Request에서 @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. 파일에 schema에 따른 내용을 추가합니다.
3. 모든 Gitlab::Audit::Auditor 호출이 파일에서 정의한 name을 사용하는지 확인합니다.

Schema

문서 생성

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

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

bundle exec rake gitlab:audit_event_types:compile_docs

문서가 최신 상태인지 확인하려면 gitlab:audit_event_types:check_docs Rake 작업을 실행하세요.

이벤트 스트리밍

엔터티가 그룹 또는 프로젝트인 모든 이벤트는 감사 로그에 기록되며 하나 이상의 이벤트 스트리밍 대상으로 스트리밍됩니다. 엔터티가 다음 중 하나인 경우:

• 그룹: 이벤트는 그룹의 루트 조상의 이벤트 스트리밍 대상으로 스트리밍됩니다.
• 프로젝트: 이벤트는 프로젝트의 루트 조상의 이벤트 스트리밍 대상으로 스트리밍됩니다.

GitLab 데이터베이스에 저장되지 않는 스트리밍 전용 이벤트를 추가할 수 있습니다. 스트리밍 전용 이벤트는 주로 많은 양의 데이터를 생성하는 작업에 사용됩니다. 예: 이 MR.

이 기능은 활발히 개발 중입니다. 기능 개발에 대한 업데이트는 상위 에픽을 팔로우하세요.

I18N 및 감사 이벤트 :message 속성

의도적으로 감사 이벤트 메시지를 번역하지 않습니다. 번역된 메시지는 데이터베이스에 저장되어 사용자의 지역 설정에 관계 없이 사용자에게 제공될 수 있기 때문입니다.

예를 들어, 인증된 사용자의 로캘을 사용하여 감사 이벤트 메시지를 기록하고 그 메시지를 해당 대상 지역의 잘못된 언어로 외부 스트리밍 대상으로 스트리밍할 수 있습니다. 사용자는 그것을 혼란스러워할 수 있습니다.