- 감사 이벤트란 무엇인가요?
- 감사 이벤트로 처리되지 않아야 하는 것은 무엇인가요?
- 감사 이벤트 스키마
- 새로운 감사 이벤트를 도구화하는 방법
- 감사 이벤트 계측 플로우
- 이벤트 유형 정의
- 이벤트 스트리밍
Audit event development guidelines
이 가이드는 감사 이벤트가 어떻게 작동하며, 어떻게 새로운 감사 이벤트를 도구화하는지에 대한 개요를 제공합니다.
감사 이벤트란 무엇인가요?
감사 이벤트는 GitLab 소유자 및 관리자가 애플리케이션 전반에서 수행된 중요한 작업의 레코드를 볼 수 있는 도구입니다.
감사 이벤트로 처리되지 않아야 하는 것은 무엇인가요?
아무 이벤트나 감사 이벤트를 트리거할 수 있지만, 모든 이벤트가 그렇지는 않습니다. 일반적으로 감사 이벤트로 적합하지 않은 이벤트는 다음과 같습니다:
- 특정 사용자에게 귀속되지 않음.
- 관리자나 소유자 역할에게 특별히 흥미로운 내용이 아님.
- 제품 기능 채택 정보를 추적함.
- 계획되지 않은 것`에 대한 방향 페이지의 토론에서 다루는 사항들입니다.
질문이 있으시면, @gitlab-org/govern/compliance
에 문의하여 감사 이벤트 또는 다른 접근 방법이 이벤트에 가장 적합한지 확인하세요.
감사 이벤트 스키마
감사 이벤트를 도구화하기 위해 다음 속성을 제공해야 합니다:
속성 | 유형 | 필수 여부 | 설명 |
---|---|---|---|
name
| String | false | 감사할 작업 이름. 이벤트 유형 정의를 나타냅니다. 에러 추적에 사용됨 |
author
| User | true | 변경 작성자. 내부 사용자일 수 있습니다. 예: inactive project deletion 감사 이벤트는 GitLab-Admin-Bot 이 작성합니다.
|
scope
| User, Project, Group 또는 InstanceScope | true | 감사 이벤트가 속한 스코프 |
target
| Object | true | 감사 대상 객체 |
message
| String | true | 작업을 설명하는 메시지 (번역되지 않음) |
created_at
| DateTime | false | 작업이 발생한 시간. 기본값은 DateTime.current 입니다.
|
새로운 감사 이벤트를 도구화하는 방법
- 새로운 감사 이벤트에 대한 YAML 유형 정의를 만듭니다.
- 작업 블록을 전달하여
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: 'Approval rule을 업데이트하려고 시도함'
}
::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
및 로컬 스레드에 의존하지 않습니다.
데이터베이스에 레코드를 추가하는 것 외에도 이러한 이벤트를 a log file에 기록합니다.
이벤트 유형 정의
- GitLab 15.4에서 도입되었습니다.
새로운 감사 이벤트는 config/audit_events/types/
또는 ee/config/audit_events/types/
에 저장된 유형 정의를 가져야 합니다. 여기에는 GitLab의 각 감사 가능한 이벤트에 대한 단일 정보 원천이 포함되어야 합니다.
새로운 감사 이벤트 유형 추가
새로운 감사 이벤트 유형을 추가하려면:
- YAML 정의를 만듭니다. 다음 중 하나를 선택할 수 있습니다:
-
bin/audit-event-type
CLI를 사용하여 YAML 정의를 자동으로 생성합니다. -
config/audit_events/types/
에 새 파일을 수동으로 만들어 이벤트 유형의 이름과 일치하는 파일 이름에 추가합니다. 예를 들어, 프로젝트에 사용자가 추가될 때 트리거된 이벤트 유형에 대한 정의는config/audit_events/types/project_add_user.yml
에 저장될 수 있습니다.
-
- 파일에 내용을 추가하여
config/audit_events/types/type_schema.json
에 정의된 스키마와 일치하도록 합니다. -
Gitlab::Audit::Auditor
를 사용하는 모든 호출에서 파일에서 정의된name
을 사용하는지 확인합니다.
스키마
필드 | 필수 | 설명 |
---|---|---|
name
| 예 | 이벤트 유형을 설명하는 고유한, 소문자 및 밑줄로 구성된 이름. 파일 이름과 일치해야 합니다. |
description
| 예 | 이 이벤트가 어떻게 트리거되는지에 대한 인간이 읽을 수 있는 설명 |
group
| 예 | 이 감사 이벤트를 도입한 그룹의 이름입니다. 예를 들어 manage::compliance 와 같이
|
introduced_by_issue
| 예 | 이 유형 추가를 제안한 이슈 URL |
introduced_by_mr
| 예 | 이 새 유형을 추가한 MR URL |
milestone
| 예 | 이 유형이 추가된 마일스톤 |
saved_to_database
| 예 | 이벤트를 데이터베이스 및 JSON 로그에 유지할지 여부를 나타내는 플래그 |
streamed
| 예 | 이벤트가 외부 서비스로 스트리밍되어야 하는지 여부를 나타내는 플래그 |
문서 생성
감사 이벤트 유형 문서는 자동으로 생성되며 게시됩니다 GitLab 문서 사이트에.
새로운 감사 이벤트 유형을 추가하면
gitlab:audit_event_types:compile_docs
Rake 태스크
를 실행하여 문서를 업데이트합니다:
bundle exec rake gitlab:audit_event_types:compile_docs
gitlab:audit_event_types:check_docs
Rake 태스크
를 실행하여 문서가 최신 상태인지 확인합니다.
이벤트 스트리밍
Group
또는 Project
가 엔티티인 모든 이벤트는 감사 로그에 기록되며 하나 이상의 이벤트 스트리밍 대상지로 스트리밍됩니다. 엔티티가:
-
Group
인 경우, 이벤트가 그룹의 최상위 조상의 이벤트 스트리밍 대상지로 스트리밍됩니다. -
Project
인 경우, 이벤트가 프로젝트의 최상위 조상의 이벤트 스트리밍 대상지로 스트리밍됩니다.
GitLab 데이터베이스에 저장되지 않는 스트리밍 전용 이벤트를 추가할 수 있습니다. 스트리밍 전용 이벤트는 주로 대량의 데이터를 생성하는 작업에 사용됩니다. 예를 들어, 이 병합 요청를 참조하세요. 이 기능은 현재 활발히 개발 중입니다. 기능 개발에 대한 업데이트는 상위 에픽을 팔로우하세요.
I18N 및 감사 이벤트 :message
속성
의도적으로 감사 이벤트 메시지는 번역하지 않습니다. 번역된 메시지는 데이터베이스에 저장되어 사용자의 지역 설정과 관계없이 사용되기 때문입니다.
예를 들어, 인증된 사용자의 로케일을 사용하여 감사 이벤트 메시지를 기록하고 해당 메시지를 해당 대상지의 잘못된 언어로 스트리밍할 수 있습니다. 사용자는 이를 혼동스러울 수 있습니다.