監査イベント開発ガイドライン

このガイドでは、監査イベントの仕組みの概要と、新しい監査イベントを作成する方法を説明します。

監査イベントとは？

監査イベントは、GitLabオーナーや管理者がアプリケーション全体で実行された重要なアクションの記録を見るためのツールです。

監査イベントにすべきでないものとは？

どのようなイベントも監査イベントのトリガーになり得ますが、すべてのイベントが監査イベントになるわけではありません。一般的に、監査イベントとしてふさわしくないイベントは以下の通りです：

  • 特定のユーザーに起因しないもの。
  • 管理者またはオーナーのペルソナに特定の関心がないこと。
  • 製品の機能採用の追跡情報です。
  • ディレクションページの「予定されていないこと」の議論に含まれています。

ご質問がある場合は、@gitlab-org/govern/compliance 、監査イベント、または他のアプローチがあなたのイベントに最適かどうかをご確認ください。

監査イベントのスキーマ

監査イベントをインストゥルメントするには、以下の属性を指定する必要があります：

属性種類必須ですか？説明
name文字列false監査対象のアクション名。イベントのタイプを表します。エラー追跡に使用します。
authorユーザーtrue変更作成者ユーザー。内部ユーザーを指定できます。たとえば、非アクティブなプロジェクト削除監査イベントは、GitLab-Admin-Botによって作成されます。
scopeユーザー、プロジェクト、グループ、またはインスタンススコープtrue監査イベントが属するスコープ
targetオブジェクトtrue監査対象のオブジェクト
message文字列trueアクションを説明するメッセージ（翻訳されていません）
created_at日付falseアクションが発生した時刻。デフォルトはDateTime.current

新しい監査イベントの設定方法

  1. 新しい監査イベントのYAML タイプ定義を作成します。
  2. Gitlab::Audit::Auditor.audit を呼び出し、アクションブロックを渡します。

監査イベントをインスツルメンテーションする以下の方法は非推奨です：

  • ee/lib/ee/audit/ に新しいクラスを作成し、そのクラスを継承します。AuditEventService
  • アクション成功後にAuditEventService を呼び出します。

Gitlab::Audit::Auditor サービスでは、2つの方法で監査イベントを計測できます：

  • 複数のイベントに対してブロックを使用する方法。
  • 単一イベントには標準メソッド呼び出しを使用。

複数のイベントを記録するためのブロックの使用

イベントがコールスタックの奥深くで発生する場合に、このメソッドを使用できます。

たとえば、ユーザーがマージリクエスト承認ルールを更新したときに複数の監査イベントを記録できます。このユーザーフローの一環として、承認者と承認グループの両方に対する変更を監査したいとします。開始サービス（たとえば、MergeRequestRuleUpdateService ）では、execute 呼び出しを次のようにラップできます：

# in the initiating service
audit_context = {
  name: 'update_merge_approval_rule',
  author: current_user,
  scope: project_alpha,
  target: merge_approval_rule,
  message: 'Attempted to update an approval rule'
}

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

モデル（たとえば、ApprovalProjectRule ）では、モデルコールバック（たとえば、after_save またはafter_add）に監査イベントをプッシュできます。

# in the model
include Auditable

def audit_add(model)
  push_audit_event('Added an approver on Security rule')
end

def audit_remove(model)
  push_audit_event('Removed an approver on Security rule')
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 a new approval rule',
    created_at: DateTime.current # Useful for pre-dating an audit event when created asynchronously.
  }

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

データ量の考慮

監査イベントはすべてデータベースに永続化されるため、新しい監査イベントについては、生成されると予想されるデータ量と生成速度を考慮してください。データベースに多くのデータを生成する新しい監査イベントについては、代わりにストリーミングのみの監査イベントを追加することを検討してください。この件に関して質問がある場合は、@gitlab-org/govern/compliance/backend までイシューまたはマージリクエストでお気軽にお問い合わせください。

監査イベントのインストルメンテーションフロー

監査イベントをインスツルメンテーションする2つの方法には、それぞれ異なるフローがあります。

複数のイベントを記録するためのブロックの使用

オペレーションブロックをGitlab::Audit::Auditor で囲みます。このブロックは、オペレーションが開始された時点で利用可能な初期監査コンテキスト（つまり、author,scope,target）オブジェクトをキャプチャします。

Gitlab::Audit::EventQueue を介して監査イベントを監査イベント・キューに追加するために、Auditable mixin と連鎖する相互作用するクラスでは、追加のインスツルメンテーションが必要です。

EventQueue はSafeRequestStore 経由で内部スレッドに保存され、Gitlab::Audit::Auditorで監査イベントを記録するときに取り出されます。

単一のイベントを記録するための標準メソッド呼び出し

この方法は、EventQueue やローカル・スレッドに依存しない、よりわかりやすいフローを持っています。

データベースに記録するだけでなく、これらのイベントをログファイルに書き込みます。

イベントタイプの定義

GitLab 15.4で導入されました。

すべての新しい監査イベントには、config/audit_events/types/ に保存されたタイプ定義が必要です。このタイプ定義には、GitLabのすべての監査可能なイベントに対する単一の真実のソースが含まれています。

新しい監査イベントタイプを追加します。

新しい監査イベントタイプを追加します：

  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 を使用するようにしてください。

スキーマ

項目必須説明
nameyesイベントのタイプを表すユニークな小文字のアンダースコア名。ファイル名と一致する必要があります。
descriptionyesこのイベントがどのようにトリガーされるかについての人間が読める説明
groupyesこの監査イベントを導入したグループの名前。例えばmanage::compliance
introduced_by_issueyesこのタイプの追加を提案したイシューのURL
introduced_by_mryesこの新しいタイプを追加した MR URL
milestoneyesこのタイプが追加されたマイルストーン
saved_to_databaseyesイベントをデータベースおよびJSONログに永続化するかどうかを指定します。
streamedyesイベントが外部サービスにストリーミングされることを示す（設定されている場合）

ドキュメントの生成

監査イベントタイプのドキュメントは自動的に生成され、GitLabドキュメントサイトに公開されます。

新しい監査イベントタイプを追加したら、gitlab:audit_event_types:compile_docs Rake task を実行してドキュメントを更新してください：

bundle exec rake gitlab:audit_event_types:compile_docs

gitlab:audit_event_types:check_docs Rakeタスク を実行して、ドキュメントが最新かどうかをチェックしてください。

イベントストリーミング

エンティティがGroup またはProject であるすべてのイベントは、監査ログに記録され、1 つ以上のイベントストリーミング先にストリーミングされます。エンティティが

  • Groupの場合、イベントはグループのルート祖先のイベントストリーミング先にストリーミングされます。
  • Projectイベントは、プロジェクトのルート祖先のイベント・ストリーミング先にストリーミングされます。

GitLabデータベースに保存されないストリーミング専用のイベントを追加することができます。ストリーミング専用イベントは、主に大量のデータを生成するアクションに使うことを想定しています。このマージリクエストの例を参照してください。この機能は現在開発中です。機能開発の最新情報は親エピックに従ってください。

国際化と監査イベント:message 属性

なぜなら翻訳されたメッセージはデータベースに保存され、ユーザーのロケール設定に関係なくユーザーに提供されるからです。

例えば、これは、認証されたユーザーのロケールを使用して監査イベントメッセージを記録し、そのメッセージを外部のストリーミング先に、そのストリーミング先の間違った言語でストリーミングすることを意味します。ユーザーは混乱するかもしれません。