Documentation
¶
Overview ¶
Package shadow_ai implements the Sentinel Shadow AI Control Module.
Five levels of shadow AI management:
L1 — Universal Integration Layer: plugin-based enforcement (firewall, EDR, proxy) L2 — Detection Engine: network signatures, endpoint, API keys, behavioral L3 — Document Review Bridge: controlled LLM access with PII/secret scanning L4 — Approval Workflow: tiered data classification and manager/SOC approval L5 — SOC Integration: dashboard, correlation rules, playbooks, compliance
Index ¶
- Constants
- func RegisterDefaultPlugins(registry *PluginRegistry)
- func ServicesByCategory() map[string][]AIServiceInfo
- func ShadowAICorrelationRules() []domsoc.SOCCorrelationRule
- type AIServiceInfo
- type AISignatureDB
- func (db *AISignatureDB) AddService(svc AIServiceInfo)
- func (db *AISignatureDB) DomainPatternCount() int
- func (db *AISignatureDB) MatchDomain(domain string) string
- func (db *AISignatureDB) MatchHTTPHeaders(headers map[string]string) string
- func (db *AISignatureDB) ScanForAPIKeys(content string) string
- func (db *AISignatureDB) ServiceCount() int
- type APIKeyPattern
- type ApprovalEngine
- func (ae *ApprovalEngine) Approve(requestID, approvedBy string) error
- func (ae *ApprovalEngine) Deny(requestID, deniedBy, reason string) error
- func (ae *ApprovalEngine) ExpireOverdue() int
- func (ae *ApprovalEngine) GetRequest(requestID string) (*ApprovalRequest, bool)
- func (ae *ApprovalEngine) PendingRequests() []ApprovalRequest
- func (ae *ApprovalEngine) Stats() map[string]int
- func (ae *ApprovalEngine) SubmitRequest(userID, docID string, dataClass DataClassification) *ApprovalRequest
- func (ae *ApprovalEngine) Tiers() []ApprovalTier
- type ApprovalRequest
- type ApprovalStatus
- type ApprovalTier
- type BehavioralAlert
- type BehavioralDetector
- func (bd *BehavioralDetector) Alerts() <-chan BehavioralAlert
- func (bd *BehavioralDetector) DetectAnomalies() []BehavioralAlert
- func (bd *BehavioralDetector) RecordAccess(userID, destination string, dataSize int64)
- func (bd *BehavioralDetector) ResetCurrent()
- func (bd *BehavioralDetector) SetBaseline(userID string, profile *UserBehaviorProfile)
- type BlockRequest
- type CheckPointEnforcer
- func (c *CheckPointEnforcer) BlockDomain(_ context.Context, domain string, reason string) error
- func (c *CheckPointEnforcer) BlockIP(_ context.Context, ip string, duration time.Duration, reason string) error
- func (c *CheckPointEnforcer) HealthCheck(ctx context.Context) error
- func (c *CheckPointEnforcer) Initialize(config map[string]interface{}) error
- func (c *CheckPointEnforcer) UnblockDomain(_ context.Context, domain string) error
- func (c *CheckPointEnforcer) UnblockIP(_ context.Context, ip string) error
- func (c *CheckPointEnforcer) Vendor() string
- type ComplianceReport
- type CrowdStrikeController
- func (cs *CrowdStrikeController) HealthCheck(ctx context.Context) error
- func (cs *CrowdStrikeController) Initialize(config map[string]interface{}) error
- func (cs *CrowdStrikeController) IsolateHost(_ context.Context, hostname string) error
- func (cs *CrowdStrikeController) KillProcess(_ context.Context, hostname string, pid int) error
- func (cs *CrowdStrikeController) QuarantineFile(_ context.Context, hostname, path string) error
- func (cs *CrowdStrikeController) ReleaseHost(_ context.Context, hostname string) error
- func (cs *CrowdStrikeController) Vendor() string
- type DataClassification
- type DetectionMethod
- type DocBridge
- func (db *DocBridge) GetReview(docID string) (*ScanResult, bool)
- func (db *DocBridge) RecentReviews(limit int) []ScanResult
- func (db *DocBridge) RedactContent(content string) string
- func (db *DocBridge) ScanDocument(docID, content, userID string) *ScanResult
- func (db *DocBridge) Stats() map[string]int
- type DocReviewStatus
- type EndpointController
- type FallbackManager
- func (fm *FallbackManager) BlockDomain(ctx context.Context, domain, reason string) (enforcedBy string, err error)
- func (fm *FallbackManager) BlockIP(ctx context.Context, ip string, duration time.Duration, reason string) (enforcedBy string, err error)
- func (fm *FallbackManager) IsolateHost(ctx context.Context, hostname string) (enforcedBy string, err error)
- func (fm *FallbackManager) SetEventLogger(fn func(ShadowAIEvent))
- func (fm *FallbackManager) Strategy() string
- type HealthChecker
- type Initializer
- type IntegrationConfig
- type NetworkDetector
- type NetworkEnforcer
- type NetworkEvent
- type PIIMatch
- type PluginConfig
- type PluginFactory
- type PluginHealth
- type PluginRegistry
- func (r *PluginRegistry) AllHealth() []PluginHealth
- func (r *PluginRegistry) Get(vendor string) (interface{}, bool)
- func (r *PluginRegistry) GetByType(pluginType PluginType) []interface{}
- func (r *PluginRegistry) GetEndpointControllers() []EndpointController
- func (r *PluginRegistry) GetHealth(vendor string) (*PluginHealth, bool)
- func (r *PluginRegistry) GetNetworkEnforcers() []NetworkEnforcer
- func (r *PluginRegistry) GetWebGateways() []WebGateway
- func (r *PluginRegistry) IsHealthy(vendor string) bool
- func (r *PluginRegistry) LoadPlugins(config *IntegrationConfig) error
- func (r *PluginRegistry) PluginCount() int
- func (r *PluginRegistry) RegisterFactory(pluginType PluginType, vendor string, factory PluginFactory)
- func (r *PluginRegistry) SetHealth(vendor string, health *PluginHealth)
- func (r *PluginRegistry) Vendors() []string
- type PluginStatus
- type PluginType
- type ScanResult
- type SecretMatch
- type ShadowAIController
- func (c *ShadowAIController) ApprovalEngine() *ApprovalEngine
- func (c *ShadowAIController) BehavioralDetector() *BehavioralDetector
- func (c *ShadowAIController) Configure(config *IntegrationConfig) error
- func (c *ShadowAIController) DocBridge() *DocBridge
- func (c *ShadowAIController) GenerateComplianceReport(period string) ComplianceReport
- func (c *ShadowAIController) GetEvent(id string) (*ShadowAIEvent, bool)
- func (c *ShadowAIController) GetEvents(limit int) []ShadowAIEvent
- func (c *ShadowAIController) GetStats(timeRange string) ShadowAIStats
- func (c *ShadowAIController) IntegrationHealth() []PluginHealth
- func (c *ShadowAIController) ManualBlock(ctx context.Context, req BlockRequest) error
- func (c *ShadowAIController) NetworkDetector() *NetworkDetector
- func (c *ShadowAIController) ProcessNetworkEvent(ctx context.Context, event NetworkEvent) *ShadowAIEvent
- func (c *ShadowAIController) Registry() *PluginRegistry
- func (c *ShadowAIController) ReviewDocument(docID, content, userID string) (*ScanResult, *ApprovalRequest)
- func (c *ShadowAIController) ScanContent(content string) string
- func (c *ShadowAIController) SetSOCEventEmitter(...)
- func (c *ShadowAIController) StartHealthChecker(ctx context.Context)
- func (c *ShadowAIController) VendorHealth(vendor string) (*PluginHealth, bool)
- type ShadowAIEvent
- type ShadowAIStats
- type UserBehaviorProfile
- type Violator
- type WebGateway
- type ZscalerGateway
- func (z *ZscalerGateway) BlockCategory(_ context.Context, category string) error
- func (z *ZscalerGateway) BlockURL(_ context.Context, url, reason string) error
- func (z *ZscalerGateway) HealthCheck(ctx context.Context) error
- func (z *ZscalerGateway) Initialize(config map[string]interface{}) error
- func (z *ZscalerGateway) UnblockURL(_ context.Context, url string) error
- func (z *ZscalerGateway) Vendor() string
Constants ¶
const MaxConsecutivePluginFailures = 3
MaxConsecutivePluginFailures before marking offline.
Variables ¶
This section is empty.
Functions ¶
func RegisterDefaultPlugins ¶
func RegisterDefaultPlugins(registry *PluginRegistry)
RegisterDefaultPlugins registers all built-in vendor plugin factories.
func ServicesByCategory ¶
func ServicesByCategory() map[string][]AIServiceInfo
ServicesByCategory returns AI services grouped by category.
func ShadowAICorrelationRules ¶
func ShadowAICorrelationRules() []domsoc.SOCCorrelationRule
ShadowAICorrelationRules returns SOC correlation rules specific to Shadow AI detection. These integrate into the existing SOC correlation engine.
Types ¶
type AIServiceInfo ¶
type AIServiceInfo struct {
Name string `json:"name"` // "ChatGPT", "Claude", "Gemini"
Vendor string `json:"vendor"` // "OpenAI", "Anthropic", "Google"
Domains []string `json:"domains"` // ["*.openai.com", "chat.openai.com"]
Category string `json:"category"` // "llm", "image_gen", "code_assist"
}
AIServiceInfo describes a known AI service for signature matching.
type AISignatureDB ¶
type AISignatureDB struct {
// contains filtered or unexported fields
}
AISignatureDB contains known AI service signatures for detection.
func NewAISignatureDB ¶
func NewAISignatureDB() *AISignatureDB
NewAISignatureDB creates a signature database pre-loaded with known AI services.
func (*AISignatureDB) AddService ¶
func (db *AISignatureDB) AddService(svc AIServiceInfo)
AddService adds a custom AI service to the database.
func (*AISignatureDB) DomainPatternCount ¶
func (db *AISignatureDB) DomainPatternCount() int
DomainPatternCount returns the number of compiled domain patterns.
func (*AISignatureDB) MatchDomain ¶
func (db *AISignatureDB) MatchDomain(domain string) string
MatchDomain checks if a domain matches any known AI service. Returns the service name or empty string.
func (*AISignatureDB) MatchHTTPHeaders ¶
func (db *AISignatureDB) MatchHTTPHeaders(headers map[string]string) string
MatchHTTPHeaders checks if HTTP headers contain known AI service signatures.
func (*AISignatureDB) ScanForAPIKeys ¶
func (db *AISignatureDB) ScanForAPIKeys(content string) string
ScanForAPIKeys scans content for AI API keys. Returns the matched pattern name or empty string.
func (*AISignatureDB) ServiceCount ¶
func (db *AISignatureDB) ServiceCount() int
ServiceCount returns the number of known AI services.
type APIKeyPattern ¶
type APIKeyPattern struct {
Name string `json:"name"`
Pattern *regexp.Regexp `json:"-"`
Entropy float64 `json:"min_entropy"`
}
APIKeyPattern defines a regex pattern for detecting AI API keys.
type ApprovalEngine ¶
type ApprovalEngine struct {
// contains filtered or unexported fields
}
ApprovalEngine manages the tiered approval workflow.
func NewApprovalEngine ¶
func NewApprovalEngine() *ApprovalEngine
NewApprovalEngine creates an engine with default tiers.
func (*ApprovalEngine) Approve ¶
func (ae *ApprovalEngine) Approve(requestID, approvedBy string) error
Approve approves a pending request.
func (*ApprovalEngine) Deny ¶
func (ae *ApprovalEngine) Deny(requestID, deniedBy, reason string) error
Deny denies a pending request.
func (*ApprovalEngine) ExpireOverdue ¶
func (ae *ApprovalEngine) ExpireOverdue() int
ExpireOverdue marks overdue pending requests as expired. Returns the number of expired requests.
func (*ApprovalEngine) GetRequest ¶
func (ae *ApprovalEngine) GetRequest(requestID string) (*ApprovalRequest, bool)
GetRequest returns an approval request by ID.
func (*ApprovalEngine) PendingRequests ¶
func (ae *ApprovalEngine) PendingRequests() []ApprovalRequest
PendingRequests returns all pending approval requests.
func (*ApprovalEngine) Stats ¶
func (ae *ApprovalEngine) Stats() map[string]int
Stats returns approval workflow statistics.
func (*ApprovalEngine) SubmitRequest ¶
func (ae *ApprovalEngine) SubmitRequest(userID, docID string, dataClass DataClassification) *ApprovalRequest
SubmitRequest creates a new approval request based on data classification. Returns the request or auto-approves if the tier allows it.
func (*ApprovalEngine) Tiers ¶
func (ae *ApprovalEngine) Tiers() []ApprovalTier
Tiers returns the approval tier configuration.
type ApprovalRequest ¶
type ApprovalRequest struct {
ID string `json:"id"`
DocID string `json:"doc_id"`
UserID string `json:"user_id"`
Tier string `json:"tier"`
DataClass DataClassification `json:"data_class"`
Status string `json:"status"` // "pending", "approved", "denied", "expired"
ApprovedBy string `json:"approved_by,omitempty"`
DeniedBy string `json:"denied_by,omitempty"`
Reason string `json:"reason,omitempty"`
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
ResolvedAt time.Time `json:"resolved_at,omitempty"`
}
ApprovalRequest tracks a pending approval for AI access.
type ApprovalStatus ¶
type ApprovalStatus string
ApprovalStatus tracks the state of an approval request.
const ( ApprovalPending ApprovalStatus = "pending" ApprovalApproved ApprovalStatus = "approved" ApprovalDenied ApprovalStatus = "denied" ApprovalExpired ApprovalStatus = "expired" ApprovalAutoApproved ApprovalStatus = "auto_approved" )
type ApprovalTier ¶
type ApprovalTier struct {
Name string `yaml:"name" json:"name"`
DataClass DataClassification `yaml:"data_class" json:"data_class"`
ApprovalNeeded []string `yaml:"approval_needed" json:"approval_needed"` // ["manager"], ["manager", "soc"], ["ciso"]
SLA time.Duration `yaml:"sla" json:"sla"`
AutoApprove bool `yaml:"auto_approve" json:"auto_approve"`
}
ApprovalTier defines the approval requirements for a data classification level.
func DefaultApprovalTiers ¶
func DefaultApprovalTiers() []ApprovalTier
DefaultApprovalTiers defines the approval requirements per data classification.
type BehavioralAlert ¶
type BehavioralAlert struct {
UserID string `json:"user_id"`
AnomalyType string `json:"anomaly_type"` // "access_spike", "new_destination", "data_volume_spike"
Current float64 `json:"current"`
Baseline float64 `json:"baseline"`
ZScore float64 `json:"z_score"`
Destination string `json:"destination,omitempty"`
Severity string `json:"severity"`
}
BehavioralAlert is emitted when anomalous AI access is detected.
type BehavioralDetector ¶
type BehavioralDetector struct {
// contains filtered or unexported fields
}
BehavioralDetector detects anomalous AI usage patterns per user.
func NewBehavioralDetector ¶
func NewBehavioralDetector(alertBufSize int) *BehavioralDetector
NewBehavioralDetector creates a behavioral detector with a buffered alert bus.
func (*BehavioralDetector) Alerts ¶
func (bd *BehavioralDetector) Alerts() <-chan BehavioralAlert
Alerts returns the alert channel for consuming behavioral alerts.
func (*BehavioralDetector) DetectAnomalies ¶
func (bd *BehavioralDetector) DetectAnomalies() []BehavioralAlert
DetectAnomalies compares current behavior to baselines and emits alerts.
func (*BehavioralDetector) RecordAccess ¶
func (bd *BehavioralDetector) RecordAccess(userID, destination string, dataSize int64)
RecordAccess records a single AI access attempt for behavioral tracking.
func (*BehavioralDetector) ResetCurrent ¶
func (bd *BehavioralDetector) ResetCurrent()
ResetCurrent clears the current period data (call after each analysis window).
func (*BehavioralDetector) SetBaseline ¶
func (bd *BehavioralDetector) SetBaseline(userID string, profile *UserBehaviorProfile)
SetBaseline sets the known baseline behavior for a user.
type BlockRequest ¶
type BlockRequest struct {
TargetType string `json:"target_type"` // "ip", "domain", "user"
Target string `json:"target"`
Duration time.Duration `json:"duration"`
Reason string `json:"reason"`
BlockedBy string `json:"blocked_by"` // RBAC user
}
BlockRequest is an API request to manually block a target.
type CheckPointEnforcer ¶
type CheckPointEnforcer struct {
// contains filtered or unexported fields
}
CheckPointEnforcer is a stub implementation for Check Point firewalls.
func NewCheckPointEnforcer ¶
func NewCheckPointEnforcer() *CheckPointEnforcer
func (*CheckPointEnforcer) BlockDomain ¶
func (*CheckPointEnforcer) HealthCheck ¶
func (c *CheckPointEnforcer) HealthCheck(ctx context.Context) error
func (*CheckPointEnforcer) Initialize ¶
func (c *CheckPointEnforcer) Initialize(config map[string]interface{}) error
func (*CheckPointEnforcer) UnblockDomain ¶
func (c *CheckPointEnforcer) UnblockDomain(_ context.Context, domain string) error
func (*CheckPointEnforcer) UnblockIP ¶
func (c *CheckPointEnforcer) UnblockIP(_ context.Context, ip string) error
func (*CheckPointEnforcer) Vendor ¶
func (c *CheckPointEnforcer) Vendor() string
type ComplianceReport ¶
type ComplianceReport struct {
GeneratedAt time.Time `json:"generated_at"`
Period string `json:"period"` // "monthly", "quarterly"
TotalInteractions int `json:"total_interactions"`
BlockedAttempts int `json:"blocked_attempts"`
ApprovedReviews int `json:"approved_reviews"`
PIIDetected int `json:"pii_detected"`
SecretsDetected int `json:"secrets_detected"`
AuditComplete bool `json:"audit_complete"`
Regulations []string `json:"regulations"` // ["GDPR", "SOC2", "EU AI Act"]
}
ComplianceReport is the Shadow AI compliance report for GDPR/SOC2/EU AI Act.
type CrowdStrikeController ¶
type CrowdStrikeController struct {
// contains filtered or unexported fields
}
CrowdStrikeController is a stub implementation for CrowdStrike Falcon EDR.
func NewCrowdStrikeController ¶
func NewCrowdStrikeController() *CrowdStrikeController
func (*CrowdStrikeController) HealthCheck ¶
func (cs *CrowdStrikeController) HealthCheck(ctx context.Context) error
func (*CrowdStrikeController) Initialize ¶
func (cs *CrowdStrikeController) Initialize(config map[string]interface{}) error
func (*CrowdStrikeController) IsolateHost ¶
func (cs *CrowdStrikeController) IsolateHost(_ context.Context, hostname string) error
func (*CrowdStrikeController) KillProcess ¶
func (*CrowdStrikeController) QuarantineFile ¶
func (cs *CrowdStrikeController) QuarantineFile(_ context.Context, hostname, path string) error
func (*CrowdStrikeController) ReleaseHost ¶
func (cs *CrowdStrikeController) ReleaseHost(_ context.Context, hostname string) error
func (*CrowdStrikeController) Vendor ¶
func (cs *CrowdStrikeController) Vendor() string
type DataClassification ¶
type DataClassification string
DataClassification determines the approval tier required.
const ( DataPublic DataClassification = "PUBLIC" DataInternal DataClassification = "INTERNAL" DataConfidential DataClassification = "CONFIDENTIAL" DataCritical DataClassification = "CRITICAL" )
type DetectionMethod ¶
type DetectionMethod string
DetectionMethod identifies how a shadow AI usage was detected.
const ( DetectNetwork DetectionMethod = "network" // Domain/IP match DetectHTTP DetectionMethod = "http" // HTTP header signature DetectTLS DetectionMethod = "tls" // TLS/JA3 fingerprint DetectProcess DetectionMethod = "process" // AI tool process execution DetectAPIKey DetectionMethod = "api_key" // AI API key in payload DetectBehavioral DetectionMethod = "behavioral" // Anomalous AI access pattern DetectClipboard DetectionMethod = "clipboard" // Large clipboard → AI browser pattern )
type DocBridge ¶
type DocBridge struct {
// contains filtered or unexported fields
}
DocBridge manages document scanning, redaction, and review workflow.
func NewDocBridge ¶
func NewDocBridge() *DocBridge
NewDocBridge creates a new Document Review Bridge.
func (*DocBridge) GetReview ¶
func (db *DocBridge) GetReview(docID string) (*ScanResult, bool)
GetReview returns a scan result by document ID.
func (*DocBridge) RecentReviews ¶
func (db *DocBridge) RecentReviews(limit int) []ScanResult
RecentReviews returns the N most recent reviews.
func (*DocBridge) RedactContent ¶
RedactContent replaces PII and secrets in content with masked values.
func (*DocBridge) ScanDocument ¶
func (db *DocBridge) ScanDocument(docID, content, userID string) *ScanResult
ScanDocument scans content for PII and secrets, classifies data, returns result.
type DocReviewStatus ¶
type DocReviewStatus string
DocReviewStatus tracks the lifecycle of a document review.
const ( DocReviewPending DocReviewStatus = "pending" DocReviewScanning DocReviewStatus = "scanning" DocReviewClean DocReviewStatus = "clean" DocReviewRedacted DocReviewStatus = "redacted" DocReviewBlocked DocReviewStatus = "blocked" DocReviewApproved DocReviewStatus = "approved" )
type EndpointController ¶
type EndpointController interface {
// IsolateHost quarantines a host from the network.
IsolateHost(ctx context.Context, hostname string) error
// ReleaseHost removes host isolation.
ReleaseHost(ctx context.Context, hostname string) error
// KillProcess terminates a process on a remote host.
KillProcess(ctx context.Context, hostname string, pid int) error
// QuarantineFile moves a file to quarantine on a remote host.
QuarantineFile(ctx context.Context, hostname string, path string) error
// HealthCheck verifies the EDR API is reachable.
HealthCheck(ctx context.Context) error
// Vendor returns the vendor identifier (e.g., "crowdstrike", "sentinelone", "defender").
Vendor() string
}
EndpointController is the universal interface for ALL EDR systems. Implementations: CrowdStrike, SentinelOne, Microsoft Defender.
type FallbackManager ¶
type FallbackManager struct {
// contains filtered or unexported fields
}
FallbackManager provides priority-based enforcement with graceful degradation. Tries enforcement points in priority order; falls back to detect_only if all are offline.
func NewFallbackManager ¶
func NewFallbackManager(registry *PluginRegistry, strategy string) *FallbackManager
NewFallbackManager creates a new fallback manager with the given enforcement priority.
func (*FallbackManager) BlockDomain ¶
func (fm *FallbackManager) BlockDomain(ctx context.Context, domain, reason string) (enforcedBy string, err error)
BlockDomain attempts to block a domain using the highest-priority healthy plugin. Returns the vendor that enforced, or falls back to detect_only mode.
func (*FallbackManager) BlockIP ¶
func (fm *FallbackManager) BlockIP(ctx context.Context, ip string, duration time.Duration, reason string) (enforcedBy string, err error)
BlockIP attempts to block an IP using the highest-priority healthy firewall.
func (*FallbackManager) IsolateHost ¶
func (fm *FallbackManager) IsolateHost(ctx context.Context, hostname string) (enforcedBy string, err error)
IsolateHost attempts to isolate a host using the highest-priority healthy EDR.
func (*FallbackManager) SetEventLogger ¶
func (fm *FallbackManager) SetEventLogger(fn func(ShadowAIEvent))
SetEventLogger sets the callback for logging detection-only events.
func (*FallbackManager) Strategy ¶
func (fm *FallbackManager) Strategy() string
Strategy returns the configured fallback strategy.
type HealthChecker ¶
type HealthChecker struct {
// contains filtered or unexported fields
}
HealthChecker performs continuous health monitoring of all registered plugins.
func NewHealthChecker ¶
func NewHealthChecker(registry *PluginRegistry, interval time.Duration, alertFn func(string, PluginStatus, string)) *HealthChecker
NewHealthChecker creates a health checker that monitors plugin health.
func (*HealthChecker) CheckNow ¶
func (hc *HealthChecker) CheckNow(ctx context.Context)
CheckNow runs an immediate health check on all plugins (non-blocking).
func (*HealthChecker) Start ¶
func (hc *HealthChecker) Start(ctx context.Context)
Start begins continuous health monitoring. Blocks until ctx is cancelled.
type Initializer ¶
Initializer is implemented by plugins that need configuration before use.
type IntegrationConfig ¶
type IntegrationConfig struct {
Plugins []PluginConfig `yaml:"plugins" json:"plugins"`
FallbackStrategy string `yaml:"fallback_strategy" json:"fallback_strategy"` // "detect_only" | "alert_only"
HealthCheckInterval time.Duration `yaml:"health_check_interval" json:"health_check_interval"` // default: 30s
}
IntegrationConfig is the top-level Shadow AI configuration.
type NetworkDetector ¶
type NetworkDetector struct {
// contains filtered or unexported fields
}
NetworkDetector analyzes network events for AI service access.
func NewNetworkDetector ¶
func NewNetworkDetector() *NetworkDetector
NewNetworkDetector creates a new network detector with the default signature DB.
func NewNetworkDetectorWithDB ¶
func NewNetworkDetectorWithDB(db *AISignatureDB) *NetworkDetector
NewNetworkDetectorWithDB creates a detector with a custom signature database.
func (*NetworkDetector) Analyze ¶
func (nd *NetworkDetector) Analyze(event NetworkEvent) *ShadowAIEvent
Analyze checks a network event for AI service access. Returns a ShadowAIEvent if detected, nil otherwise.
func (*NetworkDetector) SignatureDB ¶
func (nd *NetworkDetector) SignatureDB() *AISignatureDB
SignatureDB returns the underlying signature database for extension.
type NetworkEnforcer ¶
type NetworkEnforcer interface {
// BlockIP blocks an IP address for the given duration.
BlockIP(ctx context.Context, ip string, duration time.Duration, reason string) error
// BlockDomain blocks a domain name.
BlockDomain(ctx context.Context, domain string, reason string) error
// UnblockIP removes an IP block.
UnblockIP(ctx context.Context, ip string) error
// UnblockDomain removes a domain block.
UnblockDomain(ctx context.Context, domain string) error
// HealthCheck verifies the firewall API is reachable.
HealthCheck(ctx context.Context) error
// Vendor returns the vendor identifier (e.g., "checkpoint", "cisco", "paloalto").
Vendor() string
}
NetworkEnforcer is the universal interface for ALL firewalls. Implementations: Check Point, Cisco ASA/FMC, Palo Alto, Fortinet.
type NetworkEvent ¶
type NetworkEvent struct {
User string `json:"user"`
Hostname string `json:"hostname"`
Destination string `json:"destination"` // Domain or IP
Port int `json:"port"`
HTTPHeaders map[string]string `json:"http_headers,omitempty"`
TLSJA3 string `json:"tls_ja3,omitempty"`
DataSize int64 `json:"data_size"`
Timestamp time.Time `json:"timestamp"`
}
NetworkEvent represents a network connection event for analysis.
type PIIMatch ¶
type PIIMatch struct {
Type string `json:"type"` // "email", "phone", "ssn", "credit_card", "passport"
Location int `json:"location"` // Character offset
Length int `json:"length"`
Masked string `json:"masked"` // Redacted value, e.g., "j***@example.com"
}
PIIMatch represents a detected PII pattern in content.
type PluginConfig ¶
type PluginConfig struct {
Type PluginType `yaml:"type" json:"type"`
Vendor string `yaml:"vendor" json:"vendor"`
Enabled bool `yaml:"enabled" json:"enabled"`
Config map[string]interface{} `yaml:"config" json:"config"`
}
PluginConfig defines a vendor plugin configuration loaded from YAML.
type PluginFactory ¶
type PluginFactory func() interface{}
PluginFactory creates a new plugin instance.
type PluginHealth ¶
type PluginHealth struct {
Vendor string `json:"vendor"`
Type PluginType `json:"type"`
Status PluginStatus `json:"status"`
LastCheck time.Time `json:"last_check"`
Consecutive int `json:"consecutive_failures"`
Latency time.Duration `json:"latency"`
LastError string `json:"last_error,omitempty"`
}
PluginHealth tracks the health state of a single plugin.
type PluginRegistry ¶
type PluginRegistry struct {
// contains filtered or unexported fields
}
PluginRegistry manages vendor plugin registration, loading, and lifecycle. Thread-safe via sync.RWMutex.
func NewPluginRegistry ¶
func NewPluginRegistry() *PluginRegistry
NewPluginRegistry creates a new plugin registry.
func (*PluginRegistry) AllHealth ¶
func (r *PluginRegistry) AllHealth() []PluginHealth
AllHealth returns health snapshots for all plugins.
func (*PluginRegistry) Get ¶
func (r *PluginRegistry) Get(vendor string) (interface{}, bool)
Get returns a plugin by vendor name.
func (*PluginRegistry) GetByType ¶
func (r *PluginRegistry) GetByType(pluginType PluginType) []interface{}
GetByType returns all plugins of a given type.
func (*PluginRegistry) GetEndpointControllers ¶
func (r *PluginRegistry) GetEndpointControllers() []EndpointController
GetEndpointControllers returns all loaded EndpointController plugins.
func (*PluginRegistry) GetHealth ¶
func (r *PluginRegistry) GetHealth(vendor string) (*PluginHealth, bool)
GetHealth returns the health status snapshot for a plugin.
func (*PluginRegistry) GetNetworkEnforcers ¶
func (r *PluginRegistry) GetNetworkEnforcers() []NetworkEnforcer
GetNetworkEnforcers returns all loaded NetworkEnforcer plugins.
func (*PluginRegistry) GetWebGateways ¶
func (r *PluginRegistry) GetWebGateways() []WebGateway
GetWebGateways returns all loaded WebGateway plugins.
func (*PluginRegistry) IsHealthy ¶
func (r *PluginRegistry) IsHealthy(vendor string) bool
IsHealthy returns true if a plugin is currently healthy.
func (*PluginRegistry) LoadPlugins ¶
func (r *PluginRegistry) LoadPlugins(config *IntegrationConfig) error
LoadPlugins creates and initializes plugins from configuration. Plugins that fail to initialize are logged but do not block other plugins.
func (*PluginRegistry) PluginCount ¶
func (r *PluginRegistry) PluginCount() int
PluginCount returns the number of loaded plugins.
func (*PluginRegistry) RegisterFactory ¶
func (r *PluginRegistry) RegisterFactory(pluginType PluginType, vendor string, factory PluginFactory)
RegisterFactory registers a plugin factory for a given type+vendor combination. Example: RegisterFactory("firewall", "checkpoint", func() interface{} { return &CheckPointEnforcer{} })
func (*PluginRegistry) SetHealth ¶
func (r *PluginRegistry) SetHealth(vendor string, health *PluginHealth)
SetHealth updates the health status for a plugin.
func (*PluginRegistry) Vendors ¶
func (r *PluginRegistry) Vendors() []string
Vendors returns all loaded vendor names.
type PluginStatus ¶
type PluginStatus string
PluginStatus represents a plugin's operational state.
const ( PluginStatusHealthy PluginStatus = "healthy" PluginStatusDegraded PluginStatus = "degraded" PluginStatusOffline PluginStatus = "offline" )
type PluginType ¶
type PluginType string
PluginType categorizes enforcement points.
const ( PluginTypeFirewall PluginType = "firewall" PluginTypeEDR PluginType = "edr" PluginTypeProxy PluginType = "proxy" PluginTypeDNS PluginType = "dns" )
type ScanResult ¶
type ScanResult struct {
DocumentID string `json:"document_id"`
Status DocReviewStatus `json:"status"`
PIIFound []PIIMatch `json:"pii_found,omitempty"`
SecretsFound []SecretMatch `json:"secrets_found,omitempty"`
DataClass DataClassification `json:"data_classification"`
ContentHash string `json:"content_hash"`
ScannedAt time.Time `json:"scanned_at"`
SizeBytes int `json:"size_bytes"`
}
ScanResult contains the results of scanning a document.
type SecretMatch ¶
type SecretMatch struct {
Type string `json:"type"` // "api_key", "password", "token", "private_key"
Location int `json:"location"`
Length int `json:"length"`
Provider string `json:"provider"` // "OpenAI", "AWS", "GitHub", etc.
}
SecretMatch represents a detected secret/API key in content.
type ShadowAIController ¶
type ShadowAIController struct {
// contains filtered or unexported fields
}
ShadowAIController is the main orchestrator that ties together detection, enforcement, SOC event emission, and statistics.
func NewShadowAIController ¶
func NewShadowAIController() *ShadowAIController
NewShadowAIController creates the main Shadow AI Control orchestrator.
func (*ShadowAIController) ApprovalEngine ¶
func (c *ShadowAIController) ApprovalEngine() *ApprovalEngine
ApprovalEngine returns the approval workflow engine.
func (*ShadowAIController) BehavioralDetector ¶
func (c *ShadowAIController) BehavioralDetector() *BehavioralDetector
BehavioralDetector returns the behavioral detector.
func (*ShadowAIController) Configure ¶
func (c *ShadowAIController) Configure(config *IntegrationConfig) error
Configure loads plugin configuration and initializes the integration layer.
func (*ShadowAIController) DocBridge ¶
func (c *ShadowAIController) DocBridge() *DocBridge
DocBridge returns the document review bridge.
func (*ShadowAIController) GenerateComplianceReport ¶
func (c *ShadowAIController) GenerateComplianceReport(period string) ComplianceReport
GenerateComplianceReport generates a compliance report for the given period.
func (*ShadowAIController) GetEvent ¶
func (c *ShadowAIController) GetEvent(id string) (*ShadowAIEvent, bool)
GetEvent returns a single event by ID.
func (*ShadowAIController) GetEvents ¶
func (c *ShadowAIController) GetEvents(limit int) []ShadowAIEvent
GetEvents returns recent shadow AI events (newest first).
func (*ShadowAIController) GetStats ¶
func (c *ShadowAIController) GetStats(timeRange string) ShadowAIStats
GetStats returns aggregate shadow AI statistics.
func (*ShadowAIController) IntegrationHealth ¶
func (c *ShadowAIController) IntegrationHealth() []PluginHealth
IntegrationHealth returns health status of all plugins.
func (*ShadowAIController) ManualBlock ¶
func (c *ShadowAIController) ManualBlock(ctx context.Context, req BlockRequest) error
ManualBlock manually blocks a domain or IP.
func (*ShadowAIController) NetworkDetector ¶
func (c *ShadowAIController) NetworkDetector() *NetworkDetector
NetworkDetector returns the network detector for configuration.
func (*ShadowAIController) ProcessNetworkEvent ¶
func (c *ShadowAIController) ProcessNetworkEvent(ctx context.Context, event NetworkEvent) *ShadowAIEvent
ProcessNetworkEvent analyzes a network event and enforces policy.
func (*ShadowAIController) Registry ¶
func (c *ShadowAIController) Registry() *PluginRegistry
Registry returns the plugin registry for direct access.
func (*ShadowAIController) ReviewDocument ¶
func (c *ShadowAIController) ReviewDocument(docID, content, userID string) (*ScanResult, *ApprovalRequest)
ReviewDocument scans a document and creates an approval request if needed.
func (*ShadowAIController) ScanContent ¶
func (c *ShadowAIController) ScanContent(content string) string
ScanContent scans text content for AI API keys.
func (*ShadowAIController) SetSOCEventEmitter ¶
func (c *ShadowAIController) SetSOCEventEmitter(fn func(source, severity, category, description string, meta map[string]string))
SetSOCEventEmitter sets the function used to emit events into the SOC pipeline.
func (*ShadowAIController) StartHealthChecker ¶
func (c *ShadowAIController) StartHealthChecker(ctx context.Context)
StartHealthChecker starts continuous plugin health monitoring.
func (*ShadowAIController) VendorHealth ¶
func (c *ShadowAIController) VendorHealth(vendor string) (*PluginHealth, bool)
VendorHealth returns health for a specific vendor.
type ShadowAIEvent ¶
type ShadowAIEvent struct {
ID string `json:"id"`
UserID string `json:"user_id"`
Hostname string `json:"hostname"`
Destination string `json:"destination"` // Target AI service domain/IP
AIService string `json:"ai_service"` // "chatgpt", "claude", "gemini", etc.
DetectionMethod DetectionMethod `json:"detection_method"`
Action string `json:"action"` // "blocked", "allowed", "pending"
EnforcedBy string `json:"enforced_by"` // Plugin vendor that enforced
DataSize int64 `json:"data_size"` // Bytes sent to AI
Timestamp time.Time `json:"timestamp"`
Metadata map[string]string `json:"metadata,omitempty"`
}
ShadowAIEvent is a detected shadow AI usage attempt.
type ShadowAIStats ¶
type ShadowAIStats struct {
TimeRange string `json:"time_range"` // "24h", "7d", "30d"
Total int `json:"total_attempts"`
Blocked int `json:"blocked"`
Approved int `json:"approved"`
Pending int `json:"pending"`
ByService map[string]int `json:"by_service"`
ByDepartment map[string]int `json:"by_department"`
TopViolators []Violator `json:"top_violators"`
}
ShadowAIStats provides aggregate statistics for the dashboard.
type UserBehaviorProfile ¶
type UserBehaviorProfile struct {
UserID string `json:"user_id"`
AccessFrequency float64 `json:"access_frequency"` // Requests per hour
DataVolumePerHour float64 `json:"data_volume_per_hour"` // Bytes per hour
KnownDestinations []string `json:"known_destinations"`
UpdatedAt time.Time `json:"updated_at"`
}
UserBehaviorProfile tracks a user's AI access behavior for anomaly detection.
type WebGateway ¶
type WebGateway interface {
// BlockURL adds a URL to the blocklist.
BlockURL(ctx context.Context, url string, reason string) error
// UnblockURL removes a URL from the blocklist.
UnblockURL(ctx context.Context, url string) error
// BlockCategory blocks an entire URL category (e.g., "Artificial Intelligence").
BlockCategory(ctx context.Context, category string) error
// HealthCheck verifies the gateway API is reachable.
HealthCheck(ctx context.Context) error
// Vendor returns the vendor identifier (e.g., "zscaler", "netskope", "squid").
Vendor() string
}
WebGateway is the universal interface for ALL proxy/CASB systems. Implementations: Zscaler, Netskope, Squid, BlueCoat.
type ZscalerGateway ¶
type ZscalerGateway struct {
// contains filtered or unexported fields
}
ZscalerGateway is a stub implementation for Zscaler Internet Access.
func NewZscalerGateway ¶
func NewZscalerGateway() *ZscalerGateway
func (*ZscalerGateway) BlockCategory ¶
func (z *ZscalerGateway) BlockCategory(_ context.Context, category string) error
func (*ZscalerGateway) BlockURL ¶
func (z *ZscalerGateway) BlockURL(_ context.Context, url, reason string) error
func (*ZscalerGateway) HealthCheck ¶
func (z *ZscalerGateway) HealthCheck(ctx context.Context) error
func (*ZscalerGateway) Initialize ¶
func (z *ZscalerGateway) Initialize(config map[string]interface{}) error
func (*ZscalerGateway) UnblockURL ¶
func (z *ZscalerGateway) UnblockURL(_ context.Context, url string) error
func (*ZscalerGateway) Vendor ¶
func (z *ZscalerGateway) Vendor() string