[MM-64686] Expose audit logging functionality via plugin API (#31204)

This commit exposes audit logging functionality to plugins via the plugin API, allowing plugins to create and log audit records. Additionally, it addresses a gob encoding issue that could cause plugin crashes when audit data contains nil pointers or unregistered types.

server/public/model/audit_record.go

@@ -0,0 +1,149 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package model
+
+const (
+	AuditKeyActor     = "actor"
+	AuditKeyAPIPath   = "api_path"
+	AuditKeyEvent     = "event"
+	AuditKeyEventData = "event_data"
+	AuditKeyEventName = "event_name"
+	AuditKeyMeta      = "meta"
+	AuditKeyError     = "error"
+	AuditKeyStatus    = "status"
+	AuditKeyUserID    = "user_id"
+	AuditKeySessionID = "session_id"
+	AuditKeyClient    = "client"
+	AuditKeyIPAddress = "ip_address"
+	AuditKeyClusterID = "cluster_id"
+
+	AuditStatusSuccess = "success"
+	AuditStatusAttempt = "attempt"
+	AuditStatusFail    = "fail"
+)
+
+// AuditRecord provides a consistent set of fields used for all audit logging.
+type AuditRecord struct {
+	EventName string          `json:"event_name"`
+	Status    string          `json:"status"`
+	EventData AuditEventData  `json:"event"`
+	Actor     AuditEventActor `json:"actor"`
+	Meta      map[string]any  `json:"meta"`
+	Error     AuditEventError `json:"error,omitempty"`
+}
+
+// AuditEventData contains all event specific data about the modified entity
+type AuditEventData struct {
+	Parameters  map[string]any `json:"parameters"`      // Payload and parameters being processed as part of the request
+	PriorState  map[string]any `json:"prior_state"`     // Prior state of the object being modified, nil if no prior state
+	ResultState map[string]any `json:"resulting_state"` // Resulting object after creating or modifying it
+	ObjectType  string         `json:"object_type"`     // String representation of the object type. eg. "post"
+}
+
+// AuditEventActor is the subject triggering the event
+type AuditEventActor struct {
+	UserId        string `json:"user_id"`
+	SessionId     string `json:"session_id"`
+	Client        string `json:"client"`
+	IpAddress     string `json:"ip_address"`
+	XForwardedFor string `json:"x_forwarded_for"`
+}
+
+// EventMeta is a key-value store to store related information to the event that is not directly related to the modified entity
+type EventMeta struct {
+	ApiPath   string `json:"api_path"`
+	ClusterId string `json:"cluster_id"`
+}
+
+// AuditEventError contains error information in case of failure of the event
+type AuditEventError struct {
+	Description string `json:"description,omitempty"`
+	Code        int    `json:"status_code,omitempty"`
+}
+
+// Auditable for sensitive object classes, consider implementing Auditable and include whatever the
+// AuditableObject returns. For example: it's likely OK to write a user object to the
+// audit logs, but not the user password in cleartext or hashed form
+type Auditable interface {
+	Auditable() map[string]any
+}
+
+// Success marks the audit record status as successful.
+func (rec *AuditRecord) Success() {
+	rec.Status = AuditStatusSuccess
+}
+
+// Fail marks the audit record status as failed.
+func (rec *AuditRecord) Fail() {
+	rec.Status = AuditStatusFail
+}
+
+// AddEventParameterToAuditRec adds a parameter, e.g. query or post body, to the event
+func AddEventParameterToAuditRec[T string | bool | int | int64 | []string | map[string]string](rec *AuditRecord, key string, val T) {
+	if rec.EventData.Parameters == nil {
+		rec.EventData.Parameters = make(map[string]any)
+	}
+
+	rec.EventData.Parameters[key] = val
+}
+
+// AddEventParameterAuditableToAuditRec adds an object that is of type Auditable to the event
+func AddEventParameterAuditableToAuditRec(rec *AuditRecord, key string, val Auditable) {
+	if rec.EventData.Parameters == nil {
+		rec.EventData.Parameters = make(map[string]any)
+	}
+
+	rec.EventData.Parameters[key] = val.Auditable()
+}
+
+// AddEventParameterAuditableArrayToAuditRec adds an array of objects of type Auditable to the event
+func AddEventParameterAuditableArrayToAuditRec[T Auditable](rec *AuditRecord, key string, val []T) {
+	if rec.EventData.Parameters == nil {
+		rec.EventData.Parameters = make(map[string]any)
+	}
+
+	processedAuditables := make([]map[string]any, 0, len(val))
+	for _, auditableVal := range val {
+		processedAuditables = append(processedAuditables, auditableVal.Auditable())
+	}
+
+	rec.EventData.Parameters[key] = processedAuditables
+}
+
+// AddEventPriorState adds the prior state of the modified object to the audit record
+func (rec *AuditRecord) AddEventPriorState(object Auditable) {
+	rec.EventData.PriorState = object.Auditable()
+}
+
+// AddEventResultState adds the result state of the modified object to the audit record
+func (rec *AuditRecord) AddEventResultState(object Auditable) {
+	rec.EventData.ResultState = object.Auditable()
+}
+
+// AddEventObjectType adds the object type of the modified object to the audit record
+func (rec *AuditRecord) AddEventObjectType(objectType string) {
+	rec.EventData.ObjectType = objectType
+}
+
+// AddMeta adds a key/value entry to the audit record that can be used for related information not directly related to
+// the modified object, e.g. authentication method
+func (rec *AuditRecord) AddMeta(name string, val any) {
+	rec.Meta[name] = val
+}
+
+// AddErrorCode adds the error code for a failed event to the audit record
+func (rec *AuditRecord) AddErrorCode(code int) {
+	rec.Error.Code = code
+}
+
+// AddErrorDesc adds the error description for a failed event to the audit record
+func (rec *AuditRecord) AddErrorDesc(description string) {
+	rec.Error.Description = description
+}
+
+// AddAppError adds an AppError to the audit record
+func (rec *AuditRecord) AddAppError(err *AppError) {
+	rec.AddErrorCode(err.StatusCode)
+	rec.AddErrorDesc(err.Error())
+}

server/public/plugin/api.go

@@ -10,6 +10,7 @@ import (
 	plugin "github.com/hashicorp/go-plugin"
 
 	"github.com/mattermost/mattermost/server/public/model"
+	"github.com/mattermost/mattermost/server/public/shared/mlog"
 )
 
 // The API can be used to retrieve data or perform actions on behalf of the plugin. Most methods
@@ -1537,6 +1538,18 @@ type API interface {
 	// @tag PropertyValue
 	// Minimum server version: 10.10
 	DeletePropertyValuesForField(groupID, fieldID string) error
+
+	// LogAuditRec logs an audit record using the default audit logger.
+	//
+	// @tag Audit
+	// Minimum server version: 10.10
+	LogAuditRec(rec *model.AuditRecord)
+
+	// LogAuditRecWithLevel logs an audit record with a specific log level.
+	//
+	// @tag Audit
+	// Minimum server version: 10.10
+	LogAuditRecWithLevel(rec *model.AuditRecord, level mlog.Level)
 }
 
 var handshake = plugin.HandshakeConfig{

server/public/plugin/api_timer_layer_generated.go

@@ -12,6 +12,7 @@ import (
 	timePkg "time"
 
 	"github.com/mattermost/mattermost/server/public/model"
+	"github.com/mattermost/mattermost/server/public/shared/mlog"
 )
 
 type apiTimerLayer struct {
@@ -1644,3 +1645,15 @@ func (api *apiTimerLayer) DeletePropertyValuesForField(groupID, fieldID string)
 	api.recordTime(startTime, "DeletePropertyValuesForField", _returnsA == nil)
 	return _returnsA
 }
+
+func (api *apiTimerLayer) LogAuditRec(rec *model.AuditRecord) {
+	startTime := timePkg.Now()
+	api.apiImpl.LogAuditRec(rec)
+	api.recordTime(startTime, "LogAuditRec", true)
+}
+
+func (api *apiTimerLayer) LogAuditRecWithLevel(rec *model.AuditRecord, level mlog.Level) {
+	startTime := timePkg.Now()
+	api.apiImpl.LogAuditRecWithLevel(rec, level)
+	api.recordTime(startTime, "LogAuditRecWithLevel", true)
+}

server/public/plugin/audit.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package plugin
+
+import (
+	"encoding/json"
+
+	"github.com/mattermost/mattermost/server/public/model"
+)
+
+// MakeAuditRecord creates a new audit record with basic information for plugin use.
+// This function creates a minimal audit record that can be populated with additional data.
+// Use this when you don't have access to request context or want to manually populate fields.
+func MakeAuditRecord(event string, initialStatus string) *model.AuditRecord {
+	return &model.AuditRecord{
+		EventName: event,
+		Status:    initialStatus,
+		Meta:      make(map[string]any),
+		Actor: model.AuditEventActor{
+			UserId:        "",
+			SessionId:     "",
+			Client:        "",
+			IpAddress:     "",
+			XForwardedFor: "",
+		},
+		EventData: model.AuditEventData{
+			Parameters:  map[string]any{},
+			PriorState:  make(map[string]any),
+			ResultState: make(map[string]any),
+			ObjectType:  "",
+		},
+	}
+}
+
+// MakeAuditRecordWithContext creates a new audit record populated with plugin context information.
+// This is the recommended way for plugins to create audit records when they have request context.
+// The Context should come from plugin hook parameters or HTTP request handlers.
+func MakeAuditRecordWithContext(event string, initialStatus string, ctx *Context, userId, apiPath string) *model.AuditRecord {
+	rec := MakeAuditRecord(event, initialStatus)
+	rec.AddMeta(model.AuditKeyAPIPath, apiPath)
+	rec.Actor.UserId = userId
+	rec.Actor.SessionId = ctx.SessionId
+	rec.Actor.Client = ctx.UserAgent
+	rec.Actor.IpAddress = ctx.IPAddress
+	return rec
+}
+
+func makeAuditRecordGobSafe(record model.AuditRecord) model.AuditRecord {
+	record.EventData.Parameters = makeMapGobSafe(record.EventData.Parameters)
+	record.EventData.PriorState = makeMapGobSafe(record.EventData.PriorState)
+	record.EventData.ResultState = makeMapGobSafe(record.EventData.ResultState)
+	record.Meta = makeMapGobSafe(record.Meta)
+	return record
+}
+
+// makeMapGobSafe converts map data to a gob-safe representation via JSON round-trip.
+// This eliminates problematic types like nil pointers in interfaces that cause gob
+// encoding to fail when sending audit data over RPC via the plugin API.
+func makeMapGobSafe(m map[string]any) map[string]any {
+	jsonBytes, err := json.Marshal(m)
+	if err != nil {
+		return map[string]any{"error": "failed to serialize audit data"}
+	}
+	var gobSafe map[string]any
+	if err := json.Unmarshal(jsonBytes, &gobSafe); err != nil {
+		return map[string]any{"error": "failed to deserialize audit data"}
+	}
+	return gobSafe
+}

server/public/plugin/client_rpc.go

@@ -882,6 +882,62 @@ func (s *apiRPCServer) LogError(args *Z_LogErrorArgs, returns *Z_LogErrorReturns
 	return nil
 }
 
+type Z_LogAuditRecArgs struct {
+	A *model.AuditRecord
+}
+
+type Z_LogAuditRecReturns struct {
+}
+
+// Custom audit logging methods with gob safety checks
+func (g *apiRPCClient) LogAuditRec(rec *model.AuditRecord) {
+	gobSafeRec := makeAuditRecordGobSafe(*rec)
+	_args := &Z_LogAuditRecArgs{&gobSafeRec}
+	_returns := &Z_LogAuditRecReturns{}
+	if err := g.client.Call("Plugin.LogAuditRec", _args, _returns); err != nil {
+		log.Printf("RPC call to LogAuditRec API failed: %s", err.Error())
+	}
+}
+
+func (s *apiRPCServer) LogAuditRec(args *Z_LogAuditRecArgs, returns *Z_LogAuditRecReturns) error {
+	if hook, ok := s.impl.(interface {
+		LogAuditRec(rec *model.AuditRecord)
+	}); ok {
+		hook.LogAuditRec(args.A)
+	} else {
+		return encodableError(fmt.Errorf("API LogAuditRec called but not implemented"))
+	}
+	return nil
+}
+
+type Z_LogAuditRecWithLevelArgs struct {
+	A *model.AuditRecord
+	B mlog.Level
+}
+
+type Z_LogAuditRecWithLevelReturns struct {
+}
+
+func (g *apiRPCClient) LogAuditRecWithLevel(rec *model.AuditRecord, level mlog.Level) {
+	gobSafeRec := makeAuditRecordGobSafe(*rec)
+	_args := &Z_LogAuditRecWithLevelArgs{&gobSafeRec, level}
+	_returns := &Z_LogAuditRecWithLevelReturns{}
+	if err := g.client.Call("Plugin.LogAuditRecWithLevel", _args, _returns); err != nil {
+		log.Printf("RPC call to LogAuditRecWithLevel API failed: %s", err.Error())
+	}
+}
+
+func (s *apiRPCServer) LogAuditRecWithLevel(args *Z_LogAuditRecWithLevelArgs, returns *Z_LogAuditRecWithLevelReturns) error {
+	if hook, ok := s.impl.(interface {
+		LogAuditRecWithLevel(rec *model.AuditRecord, level mlog.Level)
+	}); ok {
+		hook.LogAuditRecWithLevel(args.A, args.B)
+	} else {
+		return encodableError(fmt.Errorf("API LogAuditRecWithLevel called but not implemented"))
+	}
+	return nil
+}
+
 type Z_InstallPluginArgs struct {
 	PluginStreamID uint32
 	B              bool

server/public/plugin/interface_generator/main.go

@@ -26,6 +26,8 @@ var excludedPluginHooks = []string{
 	"Implemented",
 	"LoadPluginConfiguration",
 	"InstallPlugin",
+	"LogAuditRec",
+	"LogAuditRecWithLevel",
 	"LogDebug",
 	"LogError",
 	"LogInfo",

server/public/plugin/plugintest/api.go

@@ -8,6 +8,8 @@ import (
 	io "io"
 	http "net/http"
 
+	logr "github.com/mattermost/logr/v2"
+
 	mock "github.com/stretchr/testify/mock"
 
 	model "github.com/mattermost/mattermost/server/public/model"
@@ -4312,6 +4314,16 @@ func (_m *API) LoadPluginConfiguration(dest interface{}) error {
 	return r0
 }
 
+// LogAuditRec provides a mock function with given fields: rec
+func (_m *API) LogAuditRec(rec *model.AuditRecord) {
+	_m.Called(rec)
+}
+
+// LogAuditRecWithLevel provides a mock function with given fields: rec, level
+func (_m *API) LogAuditRecWithLevel(rec *model.AuditRecord, level logr.Level) {
+	_m.Called(rec, level)
+}
+
 // LogDebug provides a mock function with given fields: msg, keyValuePairs
 func (_m *API) LogDebug(msg string, keyValuePairs ...interface{}) {
 	var _ca []interface{}