security

package
v1.215.0-rc.8 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxFindingsForLookup = 500

MaxFindingsForLookup is the default max findings when looking up a specific finding by ID.

Variables

This section is empty.

Functions

func NewFindingsCache 

func NewFindingsCache(opts ...FindingsCacheOption) *findingsCache

NewFindingsCache creates a new findings cache with the given options.

Types

type AWSSecurityTagMapping 

type AWSSecurityTagMapping = schema.AWSSecurityTagMapping

AWSSecurityTagMapping is re-exported from schema for use in reports.

type CodeChange 

type CodeChange struct {
	FilePath string `json:"file_path" yaml:"file_path"`
	Line     int    `json:"line,omitempty" yaml:"line,omitempty"`
	Before   string `json:"before" yaml:"before"`
	After    string `json:"after" yaml:"after"`
}

CodeChange represents a specific code change in a Terraform file.

type ComplianceControl 

type ComplianceControl struct {
	ControlID   string       `json:"control_id" yaml:"control_id"`
	Title       string       `json:"title" yaml:"title"`
	Severity    Severity     `json:"severity" yaml:"severity"`
	Component   string       `json:"component,omitempty" yaml:"component,omitempty"`
	Stack       string       `json:"stack,omitempty" yaml:"stack,omitempty"`
	Remediation *Remediation `json:"remediation,omitempty" yaml:"remediation,omitempty"`
}

ComplianceControl represents a single compliance control and its status.

type ComplianceReport 

type ComplianceReport struct {
	GeneratedAt     time.Time           `json:"generated_at" yaml:"generated_at"`
	Stack           string              `json:"stack,omitempty" yaml:"stack,omitempty"`
	Framework       string              `json:"framework" yaml:"framework"`
	FrameworkTitle  string              `json:"framework_title" yaml:"framework_title"`
	TotalControls   int                 `json:"total_controls" yaml:"total_controls"`
	PassingControls int                 `json:"passing_controls" yaml:"passing_controls"`
	FailingControls int                 `json:"failing_controls" yaml:"failing_controls"`
	ScorePercent    float64             `json:"score_percent" yaml:"score_percent"`
	FailingDetails  []ComplianceControl `json:"failing_details" yaml:"failing_details"`
}

ComplianceReport represents a compliance posture report for a specific framework.

type ComponentMapper 

type ComponentMapper interface {
	// MapFinding attempts to map a finding's resource to an Atmos component/stack.
	// It tries Path A (tag-based) first, then falls back to Path B (heuristic pipeline).
	MapFinding(ctx context.Context, finding *Finding) (*ComponentMapping, error)

	// MapFindings maps multiple findings in batch, optimizing for shared lookups.
	MapFindings(ctx context.Context, findings []Finding) ([]Finding, error)
}

ComponentMapper maps AWS resources from security findings to Atmos components and stacks.

func NewComponentMapper 

func NewComponentMapper(atmosConfig *schema.AtmosConfiguration, authCtx *schema.AWSAuthContext) ComponentMapper

NewComponentMapper creates a ComponentMapper that uses both tag-based and heuristic strategies. If authCtx is non-nil, AWS clients will use Atmos Auth credentials.

type ComponentMapping 

type ComponentMapping struct {
	Stack         string            `json:"stack" yaml:"stack"`
	Component     string            `json:"component" yaml:"component"`
	ComponentPath string            `json:"component_path" yaml:"component_path"`
	Workspace     string            `json:"workspace,omitempty" yaml:"workspace,omitempty"`
	Mapped        bool              `json:"mapped" yaml:"mapped"`
	Confidence    MappingConfidence `json:"confidence" yaml:"confidence"`
	Method        string            `json:"method" yaml:"method"` // How the mapping was determined (e.g., "tag", "state", "naming", "ai").
}

ComponentMapping represents the resolved mapping from a finding to an Atmos component/stack.

type Finding 

type Finding struct {
	ID                 string            `json:"id" yaml:"id"`
	Title              string            `json:"title" yaml:"title"`
	Description        string            `json:"description" yaml:"description"`
	Severity           Severity          `json:"severity" yaml:"severity"`
	Source             Source            `json:"source" yaml:"source"`
	ComplianceStandard string            `json:"compliance_standard,omitempty" yaml:"compliance_standard,omitempty"`
	SecurityControlID  string            `json:"security_control_id,omitempty" yaml:"security_control_id,omitempty"` // Per-control ID (e.g., "EC2.18") for compliance deduplication.
	ResourceARN        string            `json:"resource_arn" yaml:"resource_arn"`
	ResourceType       string            `json:"resource_type" yaml:"resource_type"`
	ResourceTags       map[string]string `json:"resource_tags,omitempty" yaml:"resource_tags,omitempty"` // Tags from the Security Hub finding (no extra API call needed).
	AccountID          string            `json:"account_id" yaml:"account_id"`
	Region             string            `json:"region" yaml:"region"`
	CreatedAt          time.Time         `json:"created_at" yaml:"created_at"`
	UpdatedAt          time.Time         `json:"updated_at" yaml:"updated_at"`
	Mapping            *ComponentMapping `json:"mapping,omitempty" yaml:"mapping,omitempty"`
	Remediation        *Remediation      `json:"remediation,omitempty" yaml:"remediation,omitempty"`
}

Finding represents a normalized security finding from any AWS security service.

type FindingAnalyzer 

type FindingAnalyzer interface {
	// AnalyzeFinding analyzes a single finding with component context.
	AnalyzeFinding(ctx context.Context, finding *Finding, componentSource string, stackConfig string) (*Remediation, error)

	// AnalyzeFindings analyzes multiple findings in batch, grouping by component.
	AnalyzeFindings(ctx context.Context, findings []Finding) ([]Finding, error)
}

FindingAnalyzer provides AI-powered analysis of security findings.

func NewFindingAnalyzer 

func NewFindingAnalyzer(ctx context.Context, atmosConfig *schema.AtmosConfiguration, toolRegistry *tools.Registry, toolExecutor *tools.Executor) (FindingAnalyzer, error)

NewFindingAnalyzer creates a FindingAnalyzer backed by the configured AI provider. If toolRegistry and toolExecutor are provided, API providers use multi-turn tool analysis. CLI providers always fall back to single-prompt mode with pre-fetched context.

type FindingFetcher 

type FindingFetcher interface {
	// FetchFindings retrieves findings matching the given options.
	FetchFindings(ctx context.Context, opts *QueryOptions) ([]Finding, error)

	// FetchComplianceStatus retrieves compliance status for a specific framework.
	FetchComplianceStatus(ctx context.Context, framework string, stack string) (*ComplianceReport, error)
}

FindingFetcher retrieves security findings from AWS security services.

func NewFindingFetcher 

func NewFindingFetcher(atmosConfig *schema.AtmosConfiguration, authCtx *schema.AWSAuthContext) FindingFetcher

NewFindingFetcher creates a FindingFetcher based on the configured security sources. If authCtx is non-nil, AWS clients will use Atmos Auth credentials.

type FindingsCacheOption 

type FindingsCacheOption func(*findingsCache)

FindingsCacheOption is a functional option for configuring the findings cache.

func WithCacheTTL 

func WithCacheTTL(ttl time.Duration) FindingsCacheOption

WithCacheTTL sets a custom TTL for cache entries.

type MappingConfidence 

type MappingConfidence string

MappingConfidence represents how confident the finding-to-code mapping is. 

const (
	ConfidenceExact  MappingConfidence = "exact"  // Tag-based (Path A).
	ConfidenceHigh   MappingConfidence = "high"   // Terraform state match.
	ConfidenceMedium MappingConfidence = "medium" // Naming convention match.
	ConfidenceLow    MappingConfidence = "low"    // Resource type + AI inference.
	ConfidenceNone   MappingConfidence = "none"   // No match found.
)

type OrganizationsAPI 

type OrganizationsAPI interface {
	DescribeAccount(ctx context.Context, params *organizations.DescribeAccountInput, optFns ...func(*organizations.Options)) (*organizations.DescribeAccountOutput, error)
}

OrganizationsAPI defines the subset of AWS Organizations API used for account name lookup.

type OutputFormat 

type OutputFormat string

OutputFormat represents the desired output format. 

const (
	FormatMarkdown OutputFormat = "markdown"
	FormatJSON     OutputFormat = "json"
	FormatYAML     OutputFormat = "yaml"
	FormatCSV      OutputFormat = "csv"
)

func ParseOutputFormat 

func ParseOutputFormat(format string) (OutputFormat, error)

ParseOutputFormat validates a format string and returns the corresponding OutputFormat.

type QueryOptions 

type QueryOptions struct {
	Stack       string
	Component   string
	Severity    []Severity
	Source      Source
	Framework   string
	MaxFindings int
	Region      string
	NoAI        bool
}

QueryOptions contains the filter options for fetching security findings.

type Remediation 

type Remediation struct {
	Description   string       `json:"description" yaml:"description"`                           // Brief summary of the remediation.
	RootCause     string       `json:"root_cause,omitempty" yaml:"root_cause,omitempty"`         // Why this finding exists in the infrastructure.
	Steps         []string     `json:"steps,omitempty" yaml:"steps,omitempty"`                   // Ordered remediation steps.
	CodeChanges   []CodeChange `json:"code_changes,omitempty" yaml:"code_changes,omitempty"`     // Specific Terraform/HCL changes.
	StackChanges  string       `json:"stack_changes,omitempty" yaml:"stack_changes,omitempty"`   // Specific stack YAML changes.
	DeployCommand string       `json:"deploy_command,omitempty" yaml:"deploy_command,omitempty"` // atmos terraform apply <component> -s <stack>.
	RiskLevel     string       `json:"risk_level,omitempty" yaml:"risk_level,omitempty"`         // low, medium, high.
	References    []string     `json:"references,omitempty" yaml:"references,omitempty"`         // AWS docs, CIS benchmarks, etc.
}

Remediation contains AI-generated remediation details for a finding. This is the output contract — every AI provider must populate these fields following the same structure, ensuring consistent and reproducible output.

type Report 

type Report struct {
	GeneratedAt    time.Time              `json:"generated_at" yaml:"generated_at"`
	Stack          string                 `json:"stack,omitempty" yaml:"stack,omitempty"`
	Component      string                 `json:"component,omitempty" yaml:"component,omitempty"`
	TotalFindings  int                    `json:"total_findings" yaml:"total_findings"`
	SeverityCounts map[Severity]int       `json:"severity_counts" yaml:"severity_counts"`
	Findings       []Finding              `json:"findings" yaml:"findings"`
	MappedCount    int                    `json:"mapped_count" yaml:"mapped_count"`
	UnmappedCount  int                    `json:"unmapped_count" yaml:"unmapped_count"`
	TagMapping     *AWSSecurityTagMapping `json:"-" yaml:"-"` // Display-only: configured tag keys for unmapped findings message.
	GroupFindings  bool                   `json:"-" yaml:"-"` // Display-only: group duplicate findings in Markdown output.
}

Report represents a complete security or compliance analysis report.

type ReportRenderer 

type ReportRenderer interface {
	// RenderSecurityReport renders a security findings report.
	RenderSecurityReport(w io.Writer, report *Report) error

	// RenderComplianceReport renders a compliance posture report.
	RenderComplianceReport(w io.Writer, report *ComplianceReport) error
}

ReportRenderer renders security and compliance reports in various formats.

func NewReportRenderer 

func NewReportRenderer(format OutputFormat) ReportRenderer

NewReportRenderer creates a renderer for the given output format.

type SecurityHubAPI 

type SecurityHubAPI interface {
	GetFindings(ctx context.Context, params *securityhub.GetFindingsInput, optFns ...func(*securityhub.Options)) (*securityhub.GetFindingsOutput, error)
	GetEnabledStandards(ctx context.Context, params *securityhub.GetEnabledStandardsInput, optFns ...func(*securityhub.Options)) (*securityhub.GetEnabledStandardsOutput, error)
	ListSecurityControlDefinitions(ctx context.Context, params *securityhub.ListSecurityControlDefinitionsInput, optFns ...func(*securityhub.Options)) (*securityhub.ListSecurityControlDefinitionsOutput, error)
}

SecurityHubAPI defines the subset of AWS Security Hub API used by this package.

type Severity 

type Severity string

Severity represents a security finding severity level. 

const (
	SeverityCritical      Severity = "CRITICAL"
	SeverityHigh          Severity = "HIGH"
	SeverityMedium        Severity = "MEDIUM"
	SeverityLow           Severity = "LOW"
	SeverityInformational Severity = "INFORMATIONAL"
)

type Source 

type Source string

Source represents the AWS security service that generated a finding. 

const (
	SourceSecurityHub    Source = "security-hub"
	SourceConfig         Source = "config"
	SourceInspector      Source = "inspector"
	SourceGuardDuty      Source = "guardduty"
	SourceMacie          Source = "macie"
	SourceAccessAnalyzer Source = "access-analyzer"
	SourceAll            Source = "all"
)

type TaggingAPI 

type TaggingAPI interface {
	GetResources(ctx context.Context, params *resourcegroupstaggingapi.GetResourcesInput, optFns ...func(*resourcegroupstaggingapi.Options)) (*resourcegroupstaggingapi.GetResourcesOutput, error)
}

TaggingAPI defines the subset of AWS Resource Groups Tagging API used by this package.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.