Initial commit: breakpilot-compliance - Compliance SDK Platform
Services: Admin-Compliance, Backend-Compliance, AI-Compliance-SDK, Consent-SDK, Developer-Portal, PCA-Platform, DSMS Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
381
ai-compliance-sdk/internal/ucca/obligations_framework.go
Normal file
381
ai-compliance-sdk/internal/ucca/obligations_framework.go
Normal file
@@ -0,0 +1,381 @@
|
||||
package ucca
|
||||
|
||||
import (
|
||||
"time"
|
||||
|
||||
"github.com/google/uuid"
|
||||
)
|
||||
|
||||
// ============================================================================
|
||||
// Generic Obligations Framework
|
||||
// ============================================================================
|
||||
//
|
||||
// This framework provides a regulation-agnostic way to derive and manage
|
||||
// compliance obligations. Each regulation (DSGVO, NIS2, AI Act, etc.) is
|
||||
// implemented as a separate module that conforms to the RegulationModule
|
||||
// interface.
|
||||
//
|
||||
// Key principles:
|
||||
// - Deterministic: No LLM involvement in obligation derivation
|
||||
// - Transparent: Obligations are traceable to legal basis
|
||||
// - Composable: Regulations can be combined
|
||||
// - Auditable: Full traceability for compliance evidence
|
||||
//
|
||||
// ============================================================================
|
||||
|
||||
// ============================================================================
|
||||
// Enums and Constants
|
||||
// ============================================================================
|
||||
|
||||
// ObligationPriority represents the urgency of an obligation
|
||||
type ObligationPriority string
|
||||
|
||||
const (
|
||||
PriorityCritical ObligationPriority = "critical"
|
||||
PriorityHigh ObligationPriority = "high"
|
||||
PriorityMedium ObligationPriority = "medium"
|
||||
PriorityLow ObligationPriority = "low"
|
||||
)
|
||||
|
||||
// ObligationCategory represents the type of obligation
|
||||
type ObligationCategory string
|
||||
|
||||
const (
|
||||
CategoryMeldepflicht ObligationCategory = "Meldepflicht"
|
||||
CategoryGovernance ObligationCategory = "Governance"
|
||||
CategoryTechnical ObligationCategory = "Technisch"
|
||||
CategoryOrganizational ObligationCategory = "Organisatorisch"
|
||||
CategoryDocumentation ObligationCategory = "Dokumentation"
|
||||
CategoryTraining ObligationCategory = "Schulung"
|
||||
CategoryAudit ObligationCategory = "Audit"
|
||||
CategoryCompliance ObligationCategory = "Compliance"
|
||||
)
|
||||
|
||||
// ResponsibleRole represents who is responsible for an obligation
|
||||
type ResponsibleRole string
|
||||
|
||||
const (
|
||||
RoleManagement ResponsibleRole = "Geschäftsführung"
|
||||
RoleDSB ResponsibleRole = "Datenschutzbeauftragter"
|
||||
RoleCISO ResponsibleRole = "CISO"
|
||||
RoleITLeitung ResponsibleRole = "IT-Leitung"
|
||||
RoleCompliance ResponsibleRole = "Compliance-Officer"
|
||||
RoleAIBeauftragter ResponsibleRole = "KI-Beauftragter"
|
||||
RoleKIVerantwortlicher ResponsibleRole = "KI-Verantwortlicher"
|
||||
RoleRiskManager ResponsibleRole = "Risikomanager"
|
||||
RoleFachbereich ResponsibleRole = "Fachbereichsleitung"
|
||||
)
|
||||
|
||||
// DeadlineType represents the type of deadline
|
||||
type DeadlineType string
|
||||
|
||||
const (
|
||||
DeadlineAbsolute DeadlineType = "absolute"
|
||||
DeadlineRelative DeadlineType = "relative"
|
||||
DeadlineRecurring DeadlineType = "recurring"
|
||||
DeadlineOnEvent DeadlineType = "on_event"
|
||||
)
|
||||
|
||||
// NIS2Classification represents NIS2 entity classification
|
||||
type NIS2Classification string
|
||||
|
||||
const (
|
||||
NIS2NotAffected NIS2Classification = "nicht_betroffen"
|
||||
NIS2ImportantEntity NIS2Classification = "wichtige_einrichtung"
|
||||
NIS2EssentialEntity NIS2Classification = "besonders_wichtige_einrichtung"
|
||||
)
|
||||
|
||||
// ============================================================================
|
||||
// Core Interfaces
|
||||
// ============================================================================
|
||||
|
||||
// RegulationModule is the interface that all regulation modules must implement
|
||||
type RegulationModule interface {
|
||||
// ID returns the unique identifier for this regulation (e.g., "nis2", "dsgvo")
|
||||
ID() string
|
||||
|
||||
// Name returns the human-readable name (e.g., "NIS2-Richtlinie")
|
||||
Name() string
|
||||
|
||||
// Description returns a brief description of the regulation
|
||||
Description() string
|
||||
|
||||
// IsApplicable checks if this regulation applies to the given organization
|
||||
IsApplicable(facts *UnifiedFacts) bool
|
||||
|
||||
// DeriveObligations derives all obligations based on the facts
|
||||
DeriveObligations(facts *UnifiedFacts) []Obligation
|
||||
|
||||
// DeriveControls derives required controls based on the facts
|
||||
DeriveControls(facts *UnifiedFacts) []ObligationControl
|
||||
|
||||
// GetDecisionTree returns the decision tree for this regulation (optional)
|
||||
GetDecisionTree() *DecisionTree
|
||||
|
||||
// GetIncidentDeadlines returns incident reporting deadlines (optional)
|
||||
GetIncidentDeadlines(facts *UnifiedFacts) []IncidentDeadline
|
||||
|
||||
// GetClassification returns the specific classification within this regulation
|
||||
GetClassification(facts *UnifiedFacts) string
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Core Data Structures
|
||||
// ============================================================================
|
||||
|
||||
// LegalReference represents a reference to a specific legal provision
|
||||
type LegalReference struct {
|
||||
Norm string `json:"norm" yaml:"norm"` // e.g., "Art. 28 DSGVO", "§ 33 BSIG-E"
|
||||
Article string `json:"article,omitempty" yaml:"article,omitempty"` // Article/paragraph number
|
||||
Title string `json:"title,omitempty" yaml:"title,omitempty"` // Title of the provision
|
||||
Description string `json:"description,omitempty" yaml:"description,omitempty"` // Brief description
|
||||
URL string `json:"url,omitempty" yaml:"url,omitempty"` // Link to full text
|
||||
}
|
||||
|
||||
// Deadline represents when an obligation must be fulfilled
|
||||
type Deadline struct {
|
||||
Type DeadlineType `json:"type" yaml:"type"` // absolute, relative, recurring, on_event
|
||||
Date *time.Time `json:"date,omitempty" yaml:"date,omitempty"` // For absolute deadlines
|
||||
Duration string `json:"duration,omitempty" yaml:"duration,omitempty"` // For relative: "18 Monate nach Inkrafttreten"
|
||||
Event string `json:"event,omitempty" yaml:"event,omitempty"` // For on_event: "Bei Sicherheitsvorfall"
|
||||
Interval string `json:"interval,omitempty" yaml:"interval,omitempty"` // For recurring: "jährlich", "quartalsweise"
|
||||
}
|
||||
|
||||
// SanctionInfo represents potential sanctions for non-compliance
|
||||
type SanctionInfo struct {
|
||||
MaxFine string `json:"max_fine,omitempty" yaml:"max_fine,omitempty"` // e.g., "10 Mio. EUR oder 2% Jahresumsatz"
|
||||
MinFine string `json:"min_fine,omitempty" yaml:"min_fine,omitempty"` // Minimum fine if applicable
|
||||
PersonalLiability bool `json:"personal_liability" yaml:"personal_liability"` // Can management be held personally liable?
|
||||
CriminalLiability bool `json:"criminal_liability" yaml:"criminal_liability"` // Can lead to criminal charges?
|
||||
Description string `json:"description,omitempty" yaml:"description,omitempty"` // Additional description
|
||||
}
|
||||
|
||||
// EvidenceItem represents what constitutes evidence of compliance
|
||||
type EvidenceItem struct {
|
||||
ID string `json:"id,omitempty" yaml:"id,omitempty"`
|
||||
Name string `json:"name" yaml:"name"` // e.g., "Registrierungsbestätigung BSI"
|
||||
Description string `json:"description,omitempty" yaml:"description,omitempty"` // What this evidence should contain
|
||||
Format string `json:"format,omitempty" yaml:"format,omitempty"` // e.g., "PDF", "Screenshot", "Protokoll"
|
||||
Required bool `json:"required" yaml:"required"` // Is this evidence mandatory?
|
||||
}
|
||||
|
||||
// Obligation represents a single regulatory obligation
|
||||
type Obligation struct {
|
||||
ID string `json:"id" yaml:"id"` // e.g., "NIS2-OBL-001"
|
||||
RegulationID string `json:"regulation_id" yaml:"regulation_id"` // e.g., "nis2"
|
||||
Title string `json:"title" yaml:"title"` // e.g., "BSI-Registrierung"
|
||||
Description string `json:"description" yaml:"description"` // Detailed description
|
||||
LegalBasis []LegalReference `json:"legal_basis" yaml:"legal_basis"` // Legal references
|
||||
Category ObligationCategory `json:"category" yaml:"category"` // Type of obligation
|
||||
Responsible ResponsibleRole `json:"responsible" yaml:"responsible"` // Who is responsible
|
||||
Deadline *Deadline `json:"deadline,omitempty" yaml:"deadline,omitempty"`
|
||||
Sanctions *SanctionInfo `json:"sanctions,omitempty" yaml:"sanctions,omitempty"`
|
||||
Evidence []EvidenceItem `json:"evidence,omitempty" yaml:"evidence,omitempty"`
|
||||
Priority ObligationPriority `json:"priority" yaml:"priority"`
|
||||
Dependencies []string `json:"dependencies,omitempty" yaml:"dependencies,omitempty"` // IDs of prerequisite obligations
|
||||
ISO27001Mapping []string `json:"iso27001_mapping,omitempty" yaml:"iso27001_mapping,omitempty"`
|
||||
SOC2Mapping []string `json:"soc2_mapping,omitempty" yaml:"soc2_mapping,omitempty"`
|
||||
AppliesWhen string `json:"applies_when,omitempty" yaml:"applies_when,omitempty"` // Condition expression
|
||||
|
||||
// Implementation guidance
|
||||
HowToImplement string `json:"how_to_implement,omitempty" yaml:"how_to_implement,omitempty"`
|
||||
BreakpilotFeature string `json:"breakpilot_feature,omitempty" yaml:"breakpilot_feature,omitempty"`
|
||||
ExternalResources []string `json:"external_resources,omitempty" yaml:"external_resources,omitempty"`
|
||||
}
|
||||
|
||||
// ObligationControl represents a required control/measure
|
||||
type ObligationControl struct {
|
||||
ID string `json:"id" yaml:"id"`
|
||||
RegulationID string `json:"regulation_id" yaml:"regulation_id"`
|
||||
Name string `json:"name" yaml:"name"`
|
||||
Description string `json:"description" yaml:"description"`
|
||||
Category string `json:"category" yaml:"category"`
|
||||
WhenApplicable string `json:"when_applicable,omitempty" yaml:"when_applicable,omitempty"`
|
||||
WhatToDo string `json:"what_to_do" yaml:"what_to_do"`
|
||||
HowToImplement string `json:"how_to_implement,omitempty" yaml:"how_to_implement,omitempty"`
|
||||
EvidenceNeeded []EvidenceItem `json:"evidence_needed,omitempty" yaml:"evidence_needed,omitempty"`
|
||||
ISO27001Mapping []string `json:"iso27001_mapping,omitempty" yaml:"iso27001_mapping,omitempty"`
|
||||
BreakpilotFeature string `json:"breakpilot_feature,omitempty" yaml:"breakpilot_feature,omitempty"`
|
||||
Priority ObligationPriority `json:"priority" yaml:"priority"`
|
||||
}
|
||||
|
||||
// IncidentDeadline represents a deadline for incident reporting
|
||||
type IncidentDeadline struct {
|
||||
RegulationID string `json:"regulation_id" yaml:"regulation_id"`
|
||||
Phase string `json:"phase" yaml:"phase"` // e.g., "Erstmeldung", "Zwischenbericht"
|
||||
Deadline string `json:"deadline" yaml:"deadline"` // e.g., "24 Stunden", "72 Stunden"
|
||||
Content string `json:"content" yaml:"content"` // What must be reported
|
||||
Recipient string `json:"recipient" yaml:"recipient"` // e.g., "BSI", "Aufsichtsbehörde"
|
||||
LegalBasis []LegalReference `json:"legal_basis" yaml:"legal_basis"`
|
||||
AppliesWhen string `json:"applies_when,omitempty" yaml:"applies_when,omitempty"`
|
||||
}
|
||||
|
||||
// DecisionTree represents a decision tree for determining applicability
|
||||
type DecisionTree struct {
|
||||
ID string `json:"id" yaml:"id"`
|
||||
Name string `json:"name" yaml:"name"`
|
||||
RootNode *DecisionNode `json:"root_node" yaml:"root_node"`
|
||||
Metadata map[string]interface{} `json:"metadata,omitempty" yaml:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// DecisionNode represents a node in a decision tree
|
||||
type DecisionNode struct {
|
||||
ID string `json:"id" yaml:"id"`
|
||||
Question string `json:"question,omitempty" yaml:"question,omitempty"`
|
||||
Condition *ConditionDef `json:"condition,omitempty" yaml:"condition,omitempty"`
|
||||
YesNode *DecisionNode `json:"yes_node,omitempty" yaml:"yes_node,omitempty"`
|
||||
NoNode *DecisionNode `json:"no_node,omitempty" yaml:"no_node,omitempty"`
|
||||
Result string `json:"result,omitempty" yaml:"result,omitempty"` // Terminal node result
|
||||
Explanation string `json:"explanation,omitempty" yaml:"explanation,omitempty"`
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Output Structures
|
||||
// ============================================================================
|
||||
|
||||
// ApplicableRegulation represents a regulation that applies to the organization
|
||||
type ApplicableRegulation struct {
|
||||
ID string `json:"id"` // e.g., "nis2"
|
||||
Name string `json:"name"` // e.g., "NIS2-Richtlinie"
|
||||
Classification string `json:"classification"` // e.g., "wichtige_einrichtung"
|
||||
Reason string `json:"reason"` // Why this regulation applies
|
||||
ObligationCount int `json:"obligation_count"` // Number of derived obligations
|
||||
ControlCount int `json:"control_count"` // Number of required controls
|
||||
}
|
||||
|
||||
// SanctionsSummary aggregates sanction risks across all applicable regulations
|
||||
type SanctionsSummary struct {
|
||||
MaxFinancialRisk string `json:"max_financial_risk"` // Highest potential fine
|
||||
PersonalLiabilityRisk bool `json:"personal_liability_risk"` // Any personal liability?
|
||||
CriminalLiabilityRisk bool `json:"criminal_liability_risk"` // Any criminal liability?
|
||||
AffectedRegulations []string `json:"affected_regulations"` // Which regulations have sanctions
|
||||
Summary string `json:"summary"` // Human-readable summary
|
||||
}
|
||||
|
||||
// ExecutiveSummary provides a C-level overview
|
||||
type ExecutiveSummary struct {
|
||||
TotalRegulations int `json:"total_regulations"`
|
||||
TotalObligations int `json:"total_obligations"`
|
||||
CriticalObligations int `json:"critical_obligations"`
|
||||
UpcomingDeadlines int `json:"upcoming_deadlines"` // Deadlines within 30 days
|
||||
OverdueObligations int `json:"overdue_obligations"` // Past deadline
|
||||
KeyRisks []string `json:"key_risks"`
|
||||
RecommendedActions []string `json:"recommended_actions"`
|
||||
ComplianceScore int `json:"compliance_score"` // 0-100
|
||||
NextReviewDate *time.Time `json:"next_review_date,omitempty"`
|
||||
}
|
||||
|
||||
// ManagementObligationsOverview is the main output structure for C-Level
|
||||
type ManagementObligationsOverview struct {
|
||||
// Metadata
|
||||
ID uuid.UUID `json:"id"`
|
||||
TenantID uuid.UUID `json:"tenant_id"`
|
||||
OrganizationName string `json:"organization_name"`
|
||||
AssessmentID string `json:"assessment_id,omitempty"`
|
||||
AssessmentDate time.Time `json:"assessment_date"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
|
||||
// Input facts summary
|
||||
FactsSummary map[string]interface{} `json:"facts_summary,omitempty"`
|
||||
|
||||
// Which regulations apply
|
||||
ApplicableRegulations []ApplicableRegulation `json:"applicable_regulations"`
|
||||
|
||||
// All derived obligations (aggregated from all regulations)
|
||||
Obligations []Obligation `json:"obligations"`
|
||||
|
||||
// All required controls
|
||||
RequiredControls []ObligationControl `json:"required_controls"`
|
||||
|
||||
// Incident reporting deadlines
|
||||
IncidentDeadlines []IncidentDeadline `json:"incident_deadlines,omitempty"`
|
||||
|
||||
// Aggregated sanction risks
|
||||
SanctionsSummary SanctionsSummary `json:"sanctions_summary"`
|
||||
|
||||
// Executive summary for C-Level
|
||||
ExecutiveSummary ExecutiveSummary `json:"executive_summary"`
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// API Request/Response Types
|
||||
// ============================================================================
|
||||
|
||||
// ObligationsAssessRequest is the API request for assessing obligations
|
||||
type ObligationsAssessRequest struct {
|
||||
Facts *UnifiedFacts `json:"facts"`
|
||||
OrganizationName string `json:"organization_name,omitempty"`
|
||||
}
|
||||
|
||||
// ObligationsAssessResponse is the API response for obligations assessment
|
||||
type ObligationsAssessResponse struct {
|
||||
Overview *ManagementObligationsOverview `json:"overview"`
|
||||
Warnings []string `json:"warnings,omitempty"`
|
||||
}
|
||||
|
||||
// ObligationsByRegulationResponse groups obligations by regulation
|
||||
type ObligationsByRegulationResponse struct {
|
||||
Regulations map[string][]Obligation `json:"regulations"` // regulation_id -> obligations
|
||||
}
|
||||
|
||||
// ObligationsByDeadlineResponse sorts obligations by deadline
|
||||
type ObligationsByDeadlineResponse struct {
|
||||
Overdue []Obligation `json:"overdue"`
|
||||
ThisWeek []Obligation `json:"this_week"`
|
||||
ThisMonth []Obligation `json:"this_month"`
|
||||
NextQuarter []Obligation `json:"next_quarter"`
|
||||
Later []Obligation `json:"later"`
|
||||
NoDeadline []Obligation `json:"no_deadline"`
|
||||
}
|
||||
|
||||
// ObligationsByResponsibleResponse groups obligations by responsible role
|
||||
type ObligationsByResponsibleResponse struct {
|
||||
ByRole map[ResponsibleRole][]Obligation `json:"by_role"`
|
||||
}
|
||||
|
||||
// AvailableRegulationsResponse lists all available regulation modules
|
||||
type AvailableRegulationsResponse struct {
|
||||
Regulations []RegulationInfo `json:"regulations"`
|
||||
}
|
||||
|
||||
// RegulationInfo provides info about a regulation module
|
||||
type RegulationInfo struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
Country string `json:"country,omitempty"` // e.g., "DE", "EU"
|
||||
EffectiveDate string `json:"effective_date,omitempty"`
|
||||
}
|
||||
|
||||
// ExportMemoRequest is the request for exporting a C-Level memo
|
||||
type ExportMemoRequest struct {
|
||||
AssessmentID string `json:"assessment_id"`
|
||||
Format string `json:"format"` // "markdown" or "pdf"
|
||||
Language string `json:"language,omitempty"` // "de" or "en", default "de"
|
||||
}
|
||||
|
||||
// ExportMemoResponse contains the exported memo
|
||||
type ExportMemoResponse struct {
|
||||
Content string `json:"content"` // Markdown or base64-encoded PDF
|
||||
ContentType string `json:"content_type"` // "text/markdown" or "application/pdf"
|
||||
Filename string `json:"filename"`
|
||||
GeneratedAt time.Time `json:"generated_at"`
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Database Entity for Persistence
|
||||
// ============================================================================
|
||||
|
||||
// ObligationsAssessment represents a stored obligations assessment
|
||||
type ObligationsAssessment struct {
|
||||
ID uuid.UUID `json:"id"`
|
||||
TenantID uuid.UUID `json:"tenant_id"`
|
||||
OrganizationName string `json:"organization_name"`
|
||||
Facts *UnifiedFacts `json:"facts"`
|
||||
Overview *ManagementObligationsOverview `json:"overview"`
|
||||
Status string `json:"status"` // "draft", "completed"
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
CreatedBy uuid.UUID `json:"created_by"`
|
||||
}
|
||||
Reference in New Issue
Block a user