shadow_ai

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 31, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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

View Source
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 (c *CheckPointEnforcer) BlockDomain(_ context.Context, domain string, reason string) error

func (*CheckPointEnforcer) BlockIP

func (c *CheckPointEnforcer) BlockIP(_ context.Context, ip string, duration time.Duration, reason string) error

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 (cs *CrowdStrikeController) KillProcess(_ context.Context, hostname string, pid int) error

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

func (db *DocBridge) RedactContent(content string) string

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.

func (*DocBridge) Stats

func (db *DocBridge) Stats() map[string]int

Stats returns aggregate document review statistics.

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

type Initializer interface {
	Initialize(config map[string]interface{}) error
}

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 Violator

type Violator struct {
	UserID   string `json:"user_id"`
	Attempts int    `json:"attempts"`
}

Violator tracks a user's shadow AI violation count.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL