Documentation
¶
Index ¶
- Constants
- func ColorLevel(score int) string
- func FormatAlertMessage(insights []Insight) string
- func HighestSeverity(insights []Insight) string
- func InsightFindingKey(i Insight) string
- func Now() time.Time
- type AcknowledgmentStore
- type AlertCallback
- type CVEInfo
- type CVEReader
- type CategoryScore
- type CategorySummary
- type CertificateInfo
- type CertificateReader
- type ContainerInfo
- type ContainerInsights
- type ContainerRisk
- type Deps
- type DockerSecurityConfig
- type EventCallback
- type InfrastructurePosture
- type Insight
- type InsightType
- type PortBinding
- type PostureAlertCallback
- type PostureEventCallback
- type RiskAcknowledgment
- type Scorer
- func (s *Scorer) CheckPostureThreshold(score int, color string)
- func (s *Scorer) InvalidateCache(containerID int64)
- func (s *Scorer) ScoreContainer(ctx context.Context, containerID int64, containerExternalID string, ...) (*SecurityScore, error)
- func (s *Scorer) ScoreInfrastructure(ctx context.Context, containers []ContainerInfo) (*InfrastructurePosture, error)
- func (s *Scorer) SetPostureAlertCallback(cb PostureAlertCallback)
- func (s *Scorer) SetPostureEventCallback(cb PostureEventCallback)
- func (s *Scorer) SetThreshold(threshold int)
- func (s *Scorer) Threshold() int
- type ScorerDeps
- type SecurityScore
- type Service
- func (s *Service) GetAllInsights() []ContainerInsights
- func (s *Service) GetContainerInsights(containerID int64) *ContainerInsights
- func (s *Service) GetSummary(totalContainers int) Summary
- func (s *Service) InsightCount(containerID int64) (int, string)
- func (s *Service) RemoveContainer(containerID int64)
- func (s *Service) SetAlertCallback(cb AlertCallback)
- func (s *Service) SetEventCallback(cb EventCallback)
- func (s *Service) UpdateContainer(containerID int64, containerName string, newInsights []Insight)
- type Summary
- type UpdateInfo
- type UpdateReader
Constants ¶
const ( SeverityCritical = "critical" SeverityHigh = "high" SeverityMedium = "medium" )
Severity levels for security insights.
const ( CategoryTLS = "tls" CategoryCVEs = "cves" CategoryUpdates = "updates" CategoryNetworkExposure = "network_exposure" CategoryImageAge = "image_age" )
Category names.
const ( WeightCVEs = 30 WeightNetworkExposure = 25 WeightTLS = 20 WeightUpdates = 15 WeightImageAge = 10 )
Category weights (must sum to 100).
Variables ¶
This section is empty.
Functions ¶
func ColorLevel ¶
ColorLevel returns the color indicator for a given score.
func FormatAlertMessage ¶
FormatAlertMessage builds a human-readable alert message for a container's insights.
func HighestSeverity ¶
HighestSeverity returns the most severe level from a list of insights.
func InsightFindingKey ¶ added in v1.2.2
InsightFindingKey returns the dedup key for an insight's finding.
Types ¶
type AcknowledgmentStore ¶
type AcknowledgmentStore interface {
InsertAcknowledgment(ctx context.Context, ack *RiskAcknowledgment) (int64, error)
DeleteAcknowledgment(ctx context.Context, id int64) error
ListAcknowledgments(ctx context.Context, containerExternalID string) ([]*RiskAcknowledgment, error)
GetAcknowledgment(ctx context.Context, id int64) (*RiskAcknowledgment, error)
IsAcknowledged(ctx context.Context, containerExternalID, findingType, findingKey string) (bool, error)
}
AcknowledgmentStore persists risk acknowledgments.
type AlertCallback ¶
type AlertCallback func(containerID int64, containerName string, insights []Insight, isRecover bool)
AlertCallback is called when security insights change and an alert should be fired.
type CVEReader ¶
type CVEReader interface {
ListCVEsForContainer(ctx context.Context, containerExternalID string) ([]CVEInfo, error)
}
CVEReader provides CVE data for a container.
type CategoryScore ¶
type CategoryScore struct {
Name string `json:"name"`
Weight int `json:"weight"`
SubScore int `json:"sub_score"`
Applicable bool `json:"applicable"`
IssueCount int `json:"issue_count"`
Summary string `json:"summary"`
}
CategoryScore represents one dimension of the security score.
type CategorySummary ¶
type CategorySummary struct {
Name string `json:"name"`
TotalIssues int `json:"total_issues"`
Summary string `json:"summary"`
}
CategorySummary holds aggregated category data across all containers.
type CertificateInfo ¶
type CertificateInfo struct {
Status string // "valid", "expiring", "expired", "error"
DaysRemaining int
}
CertificateInfo holds certificate monitor status for scoring.
type CertificateReader ¶
type CertificateReader interface {
ListCertificatesForContainer(ctx context.Context, containerExternalID string) ([]CertificateInfo, error)
}
CertificateReader provides certificate data for a container.
type ContainerInfo ¶
ContainerInfo holds minimal container data for infrastructure scoring.
type ContainerInsights ¶
type ContainerInsights struct {
ContainerID int64 `json:"container_id"`
ContainerName string `json:"container_name"`
HighestSeverity *string `json:"highest_severity"`
Count int `json:"count"`
Insights []Insight `json:"insights"`
}
ContainerInsights holds all active insights for a single container.
type ContainerRisk ¶
type ContainerRisk struct {
ContainerID int64 `json:"container_id"`
ContainerName string `json:"container_name"`
Score int `json:"score"`
ColorLevel string `json:"color"`
TopIssue string `json:"top_issue"`
}
ContainerRisk is a container's score entry for ranking purposes.
type Deps ¶
type Deps struct {
Logger *slog.Logger // required
AlertCallback AlertCallback // optional — nil-safe
EventCallback EventCallback // optional — nil-safe
}
Deps holds all dependencies for the security Service.
type DockerSecurityConfig ¶
type DockerSecurityConfig struct {
Privileged bool
NetworkMode string
Bindings []PortBinding
}
DockerSecurityConfig holds the security-relevant fields extracted from Docker's ContainerInspect.
type EventCallback ¶
EventCallback is called to broadcast SSE events.
type InfrastructurePosture ¶
type InfrastructurePosture struct {
Score int `json:"score"`
ColorLevel string `json:"color"`
ContainerCount int `json:"container_count"`
ScoredCount int `json:"scored_count"`
IsPartial bool `json:"is_partial"`
Categories []CategorySummary `json:"categories"`
TopRisks []ContainerRisk `json:"top_risks"`
ComputedAt time.Time `json:"computed_at"`
}
InfrastructurePosture is the top-level aggregation across all containers.
type Insight ¶
type Insight struct {
Type InsightType `json:"type"`
Severity string `json:"severity"`
ContainerID int64 `json:"container_id"`
ContainerName string `json:"container_name"`
Title string `json:"title"`
Description string `json:"description"`
Details map[string]any `json:"details"`
DetectedAt time.Time `json:"detected_at"`
}
Insight represents a single detected dangerous configuration.
func AnalyzeDocker ¶
func AnalyzeDocker(containerID int64, containerName string, cfg DockerSecurityConfig, now time.Time) []Insight
AnalyzeDocker inspects a Docker container's security configuration and returns all detected insights.
type InsightType ¶
type InsightType string
InsightType enumerates the categories of dangerous configurations.
const ( PortExposedAllInterfaces InsightType = "port_exposed_all_interfaces" DatabasePortExposed InsightType = "database_port_exposed" PrivilegedContainer InsightType = "privileged_container" HostNetworkMode InsightType = "host_network_mode" ServiceLoadBalancer InsightType = "service_load_balancer" ServiceNodePort InsightType = "service_node_port" MissingNetworkPolicy InsightType = "missing_network_policy" )
type PortBinding ¶
PortBinding represents a single host port binding from Docker HostConfig.
type PostureAlertCallback ¶
PostureAlertCallback is called when the infrastructure score crosses a threshold.
type PostureEventCallback ¶
PostureEventCallback is called to emit SSE events for posture changes.
type RiskAcknowledgment ¶
type RiskAcknowledgment struct {
ID int64 `json:"id"`
ContainerExternalID string `json:"container_external_id"`
FindingType string `json:"finding_type"`
FindingKey string `json:"finding_key"`
AcknowledgedBy string `json:"acknowledged_by"`
Reason string `json:"reason"`
AcknowledgedAt time.Time `json:"acknowledged_at"`
}
RiskAcknowledgment is a user-created marker indicating a specific risk finding is accepted.
type Scorer ¶
type Scorer struct {
// contains filtered or unexported fields
}
Scorer computes security posture scores for containers and infrastructure.
func NewScorer ¶
func NewScorer(d ScorerDeps) *Scorer
NewScorer creates a new Scorer with the given data source readers. All readers are optional — categories with nil readers are skipped during scoring.
func (*Scorer) CheckPostureThreshold ¶
CheckPostureThreshold compares the current score against the threshold and fires alerts.
func (*Scorer) InvalidateCache ¶
InvalidateCache removes a container's cached score.
func (*Scorer) ScoreContainer ¶
func (s *Scorer) ScoreContainer(ctx context.Context, containerID int64, containerExternalID string, containerName string) (*SecurityScore, error)
ScoreContainer computes the security score for a single container.
func (*Scorer) ScoreInfrastructure ¶
func (s *Scorer) ScoreInfrastructure(ctx context.Context, containers []ContainerInfo) (*InfrastructurePosture, error)
ScoreInfrastructure computes the infrastructure-wide security posture.
func (*Scorer) SetPostureAlertCallback ¶
func (s *Scorer) SetPostureAlertCallback(cb PostureAlertCallback)
SetPostureAlertCallback sets the callback for posture threshold alerts.
func (*Scorer) SetPostureEventCallback ¶
func (s *Scorer) SetPostureEventCallback(cb PostureEventCallback)
SetPostureEventCallback sets the callback for posture SSE events.
func (*Scorer) SetThreshold ¶
SetThreshold configures the score threshold for alerts. 0 disables alerts.
type ScorerDeps ¶
type ScorerDeps struct {
Certs CertificateReader // optional — nil skips TLS scoring
CVEs CVEReader // optional — nil skips CVE scoring
Updates UpdateReader // optional — nil skips update scoring
Security *Service // optional — nil skips network exposure scoring
Acks AcknowledgmentStore // required
Threshold int // optional — 0 disables alerts
PostureAlertCallback PostureAlertCallback // optional — nil-safe
PostureEventCallback PostureEventCallback // optional — nil-safe
}
ScorerDeps holds all dependencies for the security Scorer.
type SecurityScore ¶
type SecurityScore struct {
ContainerID int64 `json:"container_id"`
ContainerName string `json:"container_name"`
TotalScore int `json:"score"`
ColorLevel string `json:"color"`
Categories []CategoryScore `json:"categories"`
ApplicableCount int `json:"applicable_count"`
ComputedAt time.Time `json:"computed_at"`
IsPartial bool `json:"is_partial"`
}
SecurityScore represents the computed security health score for a single container.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service manages in-memory security insight state and emits alerts/events on changes.
func NewService ¶
NewService creates a new security insight service.
func (*Service) GetAllInsights ¶
func (s *Service) GetAllInsights() []ContainerInsights
GetAllInsights returns insights grouped by container.
func (*Service) GetContainerInsights ¶
func (s *Service) GetContainerInsights(containerID int64) *ContainerInsights
GetContainerInsights returns the current insights for a container.
func (*Service) GetSummary ¶
GetSummary returns aggregated counts across all containers.
func (*Service) InsightCount ¶
InsightCount returns the count and highest severity for a container (used by container list API).
func (*Service) RemoveContainer ¶
RemoveContainer cleans up state for a container that no longer exists.
func (*Service) SetAlertCallback ¶
func (s *Service) SetAlertCallback(cb AlertCallback)
SetAlertCallback sets the callback for alert events.
func (*Service) SetEventCallback ¶
func (s *Service) SetEventCallback(cb EventCallback)
SetEventCallback sets the callback for SSE broadcasting.
type Summary ¶
type Summary struct {
TotalContainersMonitored int `json:"total_containers_monitored"`
TotalContainersAffected int `json:"total_containers_affected"`
TotalInsights int `json:"total_insights"`
BySeverity map[string]int `json:"by_severity"`
ByType map[string]int `json:"by_type"`
}
Summary provides aggregated counts across all containers.
type UpdateInfo ¶
type UpdateInfo struct {
UpdateType string // "major", "minor", "patch", "digest_only"
PublishedAt *time.Time
}
UpdateInfo holds update availability for scoring.
type UpdateReader ¶
type UpdateReader interface {
ListUpdatesForContainer(ctx context.Context, containerExternalID string) ([]UpdateInfo, error)
}
UpdateReader provides update and image age data for a container.