feat(compliance)!: measure controls on the event store and make the report a document someone signs

Author: Kbayero

backend/database/migrations.go

@@ -56,9 +56,9 @@ func Models() []any {
 		arr_domain.UtmIncidentAction{},
 		arr_domain.UtmIncidentActionCommand{},
 		arr_domain.UtmIncidentJob{},
-		compliance_domain.UtmComplianceReportSchedule{},
-		compliance_domain.UtmComplianceControlStatusOverride{},
-		compliance_domain.UtmComplianceControlNote{},
+		compliance_domain.ReportSchedule{},
+		compliance_domain.Report{},
+		compliance_domain.ReportScore{},
 		opensearch_domain.UtmIndexPattern{},
 		integrations_domain.UtmModule{},
 		incidents_domain.Incident{},

backend/go.mod

@@ -26,7 +26,7 @@ require (
 	github.com/swaggo/files v1.0.1
 	github.com/swaggo/gin-swagger v1.6.1
 	github.com/swaggo/swag v1.16.6
-	github.com/threatwinds/go-sdk v1.1.27-0.20260805161341-89331a9dad80
+	github.com/threatwinds/go-sdk v1.1.27-0.20260808112451-a0c815800e09
 	github.com/tidwall/gjson v1.19.0
 	github.com/utmstack/license-manager-sdk v0.1.0
 	golang.org/x/crypto v0.54.0

backend/go.sum

@@ -417,6 +417,8 @@ github.com/swaggo/swag v1.16.6 h1:qBNcx53ZaX+M5dxVyTrgQ0PJ/ACK+NzhwcbieTt+9yI=
 github.com/swaggo/swag v1.16.6/go.mod h1:ngP2etMK5a0P3QBizic5MEwpRmluJZPHjXcMoj4Xesg=
 github.com/threatwinds/go-sdk v1.1.27-0.20260805161341-89331a9dad80 h1:2j0aqm3poypbkY+GQk5nd/H0PcrqBRKaeeCtCKqequg=
 github.com/threatwinds/go-sdk v1.1.27-0.20260805161341-89331a9dad80/go.mod h1:Mr5r+NTTe8k28gVS7EgEorn76VPtf0vPSaUCD2bWRSU=
+github.com/threatwinds/go-sdk v1.1.27-0.20260808112451-a0c815800e09 h1:5yIMEE1iQDQdyqVafjOGzPkC0rAlb1XIebm+oTQ2JwI=
+github.com/threatwinds/go-sdk v1.1.27-0.20260808112451-a0c815800e09/go.mod h1:Mr5r+NTTe8k28gVS7EgEorn76VPtf0vPSaUCD2bWRSU=
 github.com/tidwall/gjson v1.19.0 h1:xwxm7n691Uf3u5OFjzngavjGTh55KX5q/9w9xHW88JU=
 github.com/tidwall/gjson v1.19.0/go.mod h1:V37/opeE/JbLUOfH0QTXiNez2l0RUjYUhpT4szFQAfc=
 github.com/tidwall/match v1.2.0 h1:0pt8FlkOwjN2fPt4bIl4BoNxb98gGHN2ObFEDkrfZnM=

backend/migrations/000001_init.up.sql

@@ -57,8 +57,8 @@ INSERT INTO permissions (name, description) VALUES
     ('incidents.write',       'Create and manage incidents, their alerts and notes'),
     ('soar.read',             'List and view SOAR response flows'),
     ('soar.write',            'Create and run SOAR response flows'),
-    ('compliance.read',       'List and view frameworks, controls, reports and evaluation history'),
-    ('compliance.write',      'Manage controls, evidence, exceptions and report schedules'),
+    ('compliance.read',       'List and view frameworks, controls, reports and score history'),
+    ('compliance.write',      'Manage frameworks and controls, run evaluations, record verdicts on a report and manage report schedules'),
     ('dashboards.read',       'List and view dashboards, visualizations and their layouts'),
     ('dashboards.write',      'Create, update and delete dashboards, visualizations and layouts'),
     ('loganalyzer.read',      'Explore logs and view saved queries'),

backend/modules.go

@@ -46,8 +46,6 @@ import (
 	"github.com/utmstack/utmstack/backend/modules/socai"
 	socai_repository "github.com/utmstack/utmstack/backend/modules/socai/repository"
 	"github.com/utmstack/utmstack/backend/modules/tenant"
-	tenant_domain "github.com/utmstack/utmstack/backend/modules/tenant/domain"
-	tenant_dto "github.com/utmstack/utmstack/backend/modules/tenant/dto"
 	"github.com/utmstack/utmstack/backend/modules/threatintel"
 	"github.com/utmstack/utmstack/backend/pkg/agentmanager"
 	"github.com/utmstack/utmstack/backend/pkg/env"
@@ -146,26 +144,7 @@ func initModules(db *gorm.DB, cfg *config) *modules {
 	if events != nil {
 		complianceEventReader = events
 	}
-	// tenantMod is built further down but the compliance eval loop needs to
-	// enumerate active tenants at tick time — a closure late-binds it.
-	var tenantModRef *tenant.Module
-	complianceTenantLister := compliance.TenantLister(func(ctx context.Context) ([]string, error) {
-		if tenantModRef == nil {
-			return nil, nil
-		}
-		items, _, err := tenantModRef.GetTenantUsecase().List(ctx, tenant_dto.Filter{Size: 1000})
-		if err != nil {
-			return nil, err
-		}
-		out := make([]string, 0, len(items))
-		for _, t := range items {
-			if t.Status == tenant_domain.StatusActive {
-				out = append(out, t.ID.String())
-			}
-		}
-		return out, nil
-	})
-	complianceMod := compliance.NewModule(db, complianceEventReader, mailMod.Service(), complianceBranding{uc: brand, uploadDir: cfg.uploadDir}, complianceTenantLister, joblease.New(db),
+	complianceMod := compliance.NewModule(db, complianceEventReader, mailMod.Service(), complianceBranding{uc: brand, uploadDir: cfg.uploadDir},
 		func() bool { return billingMod.License().Current().IsEnterprise() })
 	var eventReader dash_usecase.Reader
 	if events != nil {
@@ -246,7 +225,6 @@ func initModules(db *gorm.DB, cfg *config) *modules {
 	iamMod.SetSessionPurger(iam_usecase.NewSessionPurger(refreshRepo, joblease.New(db)))
 
 	tenantMod := tenant.NewModule(db, userUsecase)
-	tenantModRef = tenantMod
 
 	aiUsage := socai_repository.NewUsageRepo(db)
 	aiQuota := &socai.AIQuota{
@@ -354,6 +332,7 @@ func (a complianceBranding) ReportBrand(ctx context.Context) compliance_connecto
 	return compliance_connectors.ReportBrand{
 		Name:      b.ProductName,
 		LogoPath:  uploadFilePath(a.uploadDir, logoURL),
+		CoverPath: uploadFilePath(a.uploadDir, b.ReportCoverURL),
 		AccentHex: b.AccentColor,
 	}
 }

backend/modules/audit/domain/event_type.go

@@ -221,8 +221,10 @@ const (
 	COMPLIANCE_SCHEDULE_DELETE_SUCCESS ApplicationEventType = "COMPLIANCE_SCHEDULE_DELETE_SUCCESS"
 	COMPLIANCE_REPORT_DELETE_ATTEMPT   ApplicationEventType = "COMPLIANCE_REPORT_DELETE_ATTEMPT"
 	COMPLIANCE_REPORT_DELETE_SUCCESS   ApplicationEventType = "COMPLIANCE_REPORT_DELETE_SUCCESS"
+	COMPLIANCE_REPORT_EVALUATE_ATTEMPT ApplicationEventType = "COMPLIANCE_REPORT_EVALUATE_ATTEMPT"
+	COMPLIANCE_REPORT_EVALUATE_SUCCESS ApplicationEventType = "COMPLIANCE_REPORT_EVALUATE_SUCCESS"
 	// Compliance control + framework user-overlay CRUD (create custom, edit via
-	// copy-on-write, delete, enable/disable). SetEnabled is audited as UPDATE.
+	// copy-on-write, delete). Each tenant writes to its own overlay.
 	COMPLIANCE_CONTROL_CREATE_ATTEMPT   ApplicationEventType = "COMPLIANCE_CONTROL_CREATE_ATTEMPT"
 	COMPLIANCE_CONTROL_CREATE_SUCCESS   ApplicationEventType = "COMPLIANCE_CONTROL_CREATE_SUCCESS"
 	COMPLIANCE_CONTROL_UPDATE_ATTEMPT   ApplicationEventType = "COMPLIANCE_CONTROL_UPDATE_ATTEMPT"

backend/modules/compliance/connectors/external.go

@@ -3,5 +3,5 @@ package connectors
 import "context"
 
 type MailSender interface {
-	SendComplianceReport(ctx context.Context, toEmail, subject string, pdfData []byte) error
+	SendComplianceReport(ctx context.Context, to, cc []string, subject string, pdfData []byte) error
 }

backend/modules/compliance/connectors/repository.go

@@ -8,50 +8,43 @@ import (
 
 	"github.com/utmstack/utmstack/backend/modules/compliance/domain"
 	"github.com/utmstack/utmstack/backend/modules/compliance/dto"
+	"github.com/utmstack/utmstack/backend/pkg/common_models"
 )
 
 type ScheduleRepository interface {
-	Create(ctx context.Context, s *domain.UtmComplianceReportSchedule) error
-	Update(ctx context.Context, s *domain.UtmComplianceReportSchedule) error
-	GetByID(ctx context.Context, id int64) (*domain.UtmComplianceReportSchedule, error)
-	ListByUser(ctx context.Context, userID uuid.UUID, f dto.ScheduleFilters) ([]domain.UtmComplianceReportSchedule, int64, error)
-	ListAll(ctx context.Context) ([]domain.UtmComplianceReportSchedule, error)
-	Delete(ctx context.Context, id int64) error
-	ClaimDue(ctx context.Context, id int64, expectedLast, newLast time.Time) (bool, error)
+	Create(ctx context.Context, s *domain.ReportSchedule) error
+	Update(ctx context.Context, s *domain.ReportSchedule) error
+	GetByID(ctx context.Context, id uuid.UUID) (*domain.ReportSchedule, error)
+	ListByUser(ctx context.Context, userID uuid.UUID, f dto.ScheduleFilters) ([]domain.ReportSchedule, int64, error)
+	ListDue(ctx context.Context, now time.Time) ([]domain.ReportSchedule, error)
+	Delete(ctx context.Context, id uuid.UUID) error
+	ClaimDue(ctx context.Context, id uuid.UUID, expectedNext, newLast, newNext time.Time) (bool, error)
+	ForFramework(ctx context.Context, frameworkKey string) (*domain.ReportSchedule, error)
 }
 
-type OpenSearchSQL interface {
-	RunCheck(ctx context.Context, sql string) (hits int64, err error)
+type CheckQuery struct {
+	Dataset  domain.Dataset
+	DataType string
+	Filters  []common_models.FilterType
+	From, To time.Time
 }
 
-type OpenSearchAlerts interface {
-	CountByRuleNames(ctx context.Context, ruleNames []string, sinceISO string) (int64, error)
+type EventCounter interface {
+	Count(ctx context.Context, q CheckQuery) (int64, error)
+	HasData(ctx context.Context, dataset domain.Dataset, dataType string, from, to time.Time) (bool, error)
+	CountByRuleNames(ctx context.Context, ruleNames []string, from, to time.Time) (map[string]int64, error)
 }
 
 type ReportStore interface {
-	Save(ctx context.Context, snap *domain.ReportSnapshot) error
-	List(ctx context.Context, frameworkKey string, limit int) ([]domain.ReportSnapshotMeta, error)
-	Get(ctx context.Context, id string) (*domain.ReportSnapshot, error)
-	Delete(ctx context.Context, id string) error
+	Get(ctx context.Context, frameworkKey string) (*domain.Report, error)
+	Save(ctx context.Context, r *domain.Report) error
+	List(ctx context.Context) ([]domain.Report, error)
+	Delete(ctx context.Context, frameworkKey string) error
 }
 
-type ControlStatusOverrideRepository interface {
-	Upsert(ctx context.Context, o *domain.UtmComplianceControlStatusOverride) error
-	Delete(ctx context.Context, frameworkKey, controlID string) error
-	ListByFramework(ctx context.Context, frameworkKey string) (map[string]string, error)
-}
-
-type ControlNoteRepository interface {
-	Upsert(ctx context.Context, n *domain.UtmComplianceControlNote) error
-	Delete(ctx context.Context, frameworkKey, controlID string) error
-	ListByFramework(ctx context.Context, frameworkKey string) (map[string]string, error)
-}
-
-type TenantFrameworkRepository interface {
-	List(ctx context.Context) ([]string, error)                           // framework keys the acting tenant possesses
-	ListForTenant(ctx context.Context, tenantID string) ([]string, error) // same, for a specific tenant
-	Enable(ctx context.Context, frameworkKey string) error                // upsert (tenant, framework)
-	Disable(ctx context.Context, frameworkKey string) error               // delete (tenant, framework)
-	Has(ctx context.Context, frameworkKey string) (bool, error)
-	ListTenants(ctx context.Context, frameworkKey string) ([]string, error) // tenants who possess this framework
+type ReportScoreStore interface {
+	Upsert(ctx context.Context, p *domain.ReportScore) error
+	History(ctx context.Context, frameworkKey string, from, to time.Time) ([]domain.ReportScore, error)
+	Body(ctx context.Context, frameworkKey string, day time.Time) ([]byte, error)
+	PruneBodies(ctx context.Context, before time.Time) (int64, error)
 }

backend/modules/compliance/connectors/usecase.go

@@ -2,6 +2,7 @@ package connectors
 
 import (
 	"context"
+	"time"
 
 	"github.com/google/uuid"
 
@@ -10,51 +11,55 @@ import (
 )
 
 type FrameworkUsecase interface {
-	ListControls(ctx context.Context) []domain.Control
-	GetControl(ctx context.Context, id string) (*domain.Control, error)
+	ListControls(ctx context.Context) []dto.ControlResponse
+	GetControl(ctx context.Context, id string) (*dto.ControlResponse, error)
 
-	ListFrameworks(ctx context.Context) []domain.Framework
-	GetFramework(ctx context.Context, key string) (*domain.Framework, error)
+	ListFrameworks(ctx context.Context) []dto.FrameworkResponse
+	GetFramework(ctx context.Context, key string) (*dto.FrameworkResponse, error)
 
 	CreateControl(ctx context.Context, c domain.Control) (*domain.Control, error)
 	UpdateControl(ctx context.Context, c domain.Control) (*domain.Control, error)
 	DeleteControl(ctx context.Context, id string) error
-	SetControlEnabled(ctx context.Context, id string, enabled bool) error
 
 	CreateFramework(ctx context.Context, f domain.Framework) (*domain.Framework, error)
 	UpdateFramework(ctx context.Context, f domain.Framework) (*domain.Framework, error)
 	DeleteFramework(ctx context.Context, key string) error
-	SetFrameworkEnabled(ctx context.Context, key string, enabled bool) error
 }
 
 type ReportBrand struct {
-	Name      string // product/company name (defaults to "UTMStack")
-	LogoPath  string // absolute path to a PNG/JPG report logo on disk ("" → none)
+	Name     string // product/company name (defaults to "UTMStack")
+	LogoPath string // absolute path to a PNG/JPG report logo on disk ("" → none)
+	// CoverPath is the full-bleed image behind the cover page, configured with
+	// the rest of the branding. Empty falls back to a plain typographic cover.
+	CoverPath string
 	AccentHex string // accent color, CSS hex (e.g. "#6366f1"); "" → default
+	// PreparedBy names whoever asked for the document. A report says who
+	// produced it; that is half of what makes it evidence.
+	PreparedBy string
 }
 
 type BrandingProvider interface {
 	ReportBrand(ctx context.Context) ReportBrand
 }
 
 type EvaluatorUsecase interface {
-	EvaluateFramework(ctx context.Context, frameworkKey string) (*domain.Report, error)
-	GenerateReport(ctx context.Context, frameworkKey string) (*domain.Report, error) // evaluate + store snapshot
-	ListReports(ctx context.Context, frameworkKey string, limit int) ([]domain.ReportSnapshotMeta, error)
-	GetReport(ctx context.Context, id string) (*domain.ReportSnapshot, error)
-	DeleteReport(ctx context.Context, id string) error
-	FrameworkReportPDF(ctx context.Context, frameworkKey string) ([]byte, string, error) // live eval → PDF + framework name
-	SnapshotPDF(ctx context.Context, id string) ([]byte, string, error)                  // stored snapshot → PDF + framework name
-	SetStatusOverride(ctx context.Context, frameworkKey, controlID, status, reason string) error
-	ClearStatusOverride(ctx context.Context, frameworkKey, controlID string) error
-	SetControlNote(ctx context.Context, frameworkKey, controlID, note string) error
-	ClearControlNote(ctx context.Context, frameworkKey, controlID string) error
+	Evaluate(ctx context.Context, frameworkKey string, windowDays int) (*dto.ReportResponse, error)
+	Get(ctx context.Context, frameworkKey string) (*dto.ReportResponse, error)
+	List(ctx context.Context) ([]dto.ReportMeta, error)
+	Delete(ctx context.Context, frameworkKey string) error
+	EditControl(ctx context.Context, editedBy, frameworkKey, controlID string, req dto.EditControlRequest) (*dto.ReportResponse, error)
+	// preparedBy names whoever asked for the document — a report says who
+	// produced it, and that is half of what makes it evidence. A scheduled run
+	// has no requester and passes "".
+	PDF(ctx context.Context, frameworkKey, preparedBy string) ([]byte, string, error)
+	History(ctx context.Context, frameworkKey string, from, to time.Time) ([]dto.ScorePoint, error)
+	HistoryPDF(ctx context.Context, frameworkKey, preparedBy string, day time.Time) ([]byte, string, error)
 }
 
 type ScheduleUsecase interface {
 	Create(ctx context.Context, userID uuid.UUID, req dto.CreateScheduleRequest) (*dto.ScheduleResponse, error)
 	Update(ctx context.Context, userID uuid.UUID, req dto.UpdateScheduleRequest) (*dto.ScheduleResponse, error)
-	GetByID(ctx context.Context, id int64) (*dto.ScheduleResponse, error)
+	GetByID(ctx context.Context, id uuid.UUID) (*dto.ScheduleResponse, error)
 	ListByUser(ctx context.Context, userID uuid.UUID, f dto.ScheduleFilters) ([]dto.ScheduleResponse, int64, error)
-	Delete(ctx context.Context, id int64) error
+	Delete(ctx context.Context, id uuid.UUID) error
 }