[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/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{}