rules

package
v2.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const SecretsExposure = SecretExposure

SecretsExposure is a deprecated alias for SecretExposure.

The engine previously emitted two distinct category values for the same concept, "SECRET_EXPOSURE" and "SECRETS_EXPOSURE". Consumers filtering findings by category had to match both spellings, and code that matched only the singular form silently skipped findings carrying the plural one. Both now resolve to "SECRET_EXPOSURE".

Deprecated: use SecretExposure. This alias is retained so that existing importers continue to compile, and will be removed in a future major version.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdvancedSupplyChainAnalyzer 

type AdvancedSupplyChainAnalyzer struct {
	// contains filtered or unexported fields
}

AdvancedSupplyChainAnalyzer provides comprehensive supply chain security analysis

func NewAdvancedSupplyChainAnalyzer 

func NewAdvancedSupplyChainAnalyzer() *AdvancedSupplyChainAnalyzer

NewAdvancedSupplyChainAnalyzer creates a new advanced analyzer

type Category 

type Category string

Category represents the category of a security rule 

const (
	MaliciousPattern    Category = "MALICIOUS_PATTERN"
	Misconfiguration    Category = "MISCONFIGURATION"
	SecretExposure      Category = "SECRET_EXPOSURE"
	ShellObfuscation    Category = "SHELL_OBFUSCATION"
	PolicyViolation     Category = "POLICY_VIOLATION"
	SupplyChain         Category = "SUPPLY_CHAIN"
	InjectionAttack     Category = "INJECTION_ATTACK"
	AccessControl       Category = "ACCESS_CONTROL"
	PrivilegeEscalation Category = "PRIVILEGE_ESCALATION"
	DataExposure        Category = "DATA_EXPOSURE"
)

type ConfigInterface 

type ConfigInterface interface {
	IsRuleEnabled(ruleID string) bool
	ShouldIgnoreForRule(ruleID, text, filePath string) bool
	ShouldIgnoreSecret(text, context string) bool
}

ConfigInterface defines the interface for configuration

type Finding 

type Finding struct {
	RuleID      string
	RuleName    string
	Description string
	Severity    Severity
	Category    Category
	FilePath    string
	JobName     string
	StepName    string
	Evidence    string
	Remediation string
	LineNumber  int    // Line number where the issue was found
	GitHubURL   string // Direct GitHub URL to the line (for remote repositories)
	GitLabURL   string // Direct GitLab URL to the line (for remote repositories)

	// Context fields for better AI analysis
	Trigger     string `json:"trigger,omitempty"`      // Workflow trigger (e.g., "push", "pull_request", "workflow_dispatch")
	RunnerType  string `json:"runner_type,omitempty"`  // Runner type (e.g., "ubuntu-latest", "self-hosted", "windows-latest")
	FileContext string `json:"file_context,omitempty"` // File context (e.g., "production", "test", "example", "template")

	// AI verification fields
	AIVerified            bool    `json:"ai_verified,omitempty"`              // Whether AI analysis was performed
	AILikelyFalsePositive *bool   `json:"ai_likely_false_positive,omitempty"` // AI assessment (nil if not analyzed)
	AIConfidence          float64 `json:"ai_confidence,omitempty"`            // AI confidence level (0.0 to 1.0)
	AIReasoning           string  `json:"ai_reasoning,omitempty"`             // AI explanation
	AISuggestedSeverity   string  `json:"ai_suggested_severity,omitempty"`    // AI suggested severity if different
	AIError               string  `json:"ai_error,omitempty"`                 // AI analysis error if any
	AISkipped             bool    `json:"ai_skipped,omitempty"`               // Whether AI analysis was skipped
	AISkipReason          string  `json:"ai_skip_reason,omitempty"`           // Reason AI analysis was skipped
	AIRemediation         string  `json:"ai_remediation,omitempty"`           // AI-suggested remediation steps
}

Finding represents a detected security issue

func CheckAIAgentCommentTriggered 

func CheckAIAgentCommentTriggered(workflow parser.WorkflowFile) []Finding

CheckAIAgentCommentTriggered detects AI agent workflows triggered by issue_comment or pull_request_review_comment that process attacker-controlled input (comment body) with secrets available. This enables prompt injection attacks where any external user can @mention the agent and craft payloads to exfiltrate secrets or abuse write permissions.

func CheckAdvancedExfiltration added in v2.1.0 

func CheckAdvancedExfiltration(workflow parser.WorkflowFile) []Finding

CheckAdvancedExfiltration detects covert data exfiltration channels in `run:` steps.

func CheckAdvancedInjection added in v2.1.0 

func CheckAdvancedInjection(workflow parser.WorkflowFile) []Finding

CheckAdvancedInjection detects indirect command injection in `run:` steps.

func CheckAdvancedPrivilegeAnalysis 

func CheckAdvancedPrivilegeAnalysis(workflow parser.WorkflowFile) []Finding

CheckAdvancedPrivilegeAnalysis performs advanced workflow privilege analysis

func CheckAllRules 

func CheckAllRules(workflow parser.WorkflowFile) []Finding

CheckAllRules runs all security rule checks

func CheckArchivedActionSource added in v2.1.0 

func CheckArchivedActionSource(workflow parser.WorkflowFile) []Finding

CheckArchivedActionSource is the public entry point for the ARCHIVED_ACTION_SOURCE rule.

func CheckCachePoisoning 

func CheckCachePoisoning(workflow parser.WorkflowFile) []Finding

CheckCachePoisoning is the public entry point that detects cache poisoning attack vectors (CP-001 and CP-002).

func CheckConcurrencyLimits added in v2.1.0 

func CheckConcurrencyLimits(workflow parser.WorkflowFile) []Finding

CheckConcurrencyLimits is the public entry point for the CONCURRENCY_LIMITS_MISSING rule.

func CheckContainerSecurity added in v2.1.0 

func CheckContainerSecurity(workflow parser.WorkflowFile) []Finding

CheckContainerSecurity is the public entry point that runs both container image pinning and container registry credential checks.

func CheckCrossFileTaint added in v2.1.0 

func CheckCrossFileTaint(workflow parser.WorkflowFile) []Finding

CheckCrossFileTaint is the public entry point for the CROSS_FILE_TAINT rule.

func CheckCrossJobTaint added in v2.1.0 

func CheckCrossJobTaint(workflow parser.WorkflowFile) []Finding

CheckCrossJobTaint is the public entry point for the CROSS_JOB_TAINT rule.

func CheckDefinitionHygiene added in v2.1.0 

func CheckDefinitionHygiene(workflow parser.WorkflowFile) []Finding

CheckDefinitionHygiene runs the workflow-readability checks.

func CheckDockerAgentExposure 

func CheckDockerAgentExposure(workflow parser.WorkflowFile) []Finding

CheckDockerAgentExposure detects pull_request_target workflows that run Docker containers or reusable agent workflows with secrets on fork code.

func CheckGitHubAppTokenMisuse added in v2.1.0 

func CheckGitHubAppTokenMisuse(workflow parser.WorkflowFile) []Finding

CheckGitHubAppTokenMisuse is the public entry point for the GITHUB_APP_TOKEN_MISUSE rule.

func CheckInjectionVulnerabilities 

func CheckInjectionVulnerabilities(workflow parser.WorkflowFile) []Finding

CheckInjectionVulnerabilities is the main entry point for injection vulnerability checks

func CheckInsecureURLScheme added in v2.1.0 

func CheckInsecureURLScheme(workflow parser.WorkflowFile) []Finding

CheckInsecureURLScheme is the public entry point for the INSECURE_URL_SCHEME rule.

func CheckMisfeatures added in v2.1.0 

func CheckMisfeatures(workflow parser.WorkflowFile) []Finding

CheckMisfeatures is the public entry point for the MISFEATURE rule.

func CheckOIDCAbuse 

func CheckOIDCAbuse(workflow parser.WorkflowFile) []Finding

CheckOIDCAbuse is the entry point for OIDC token abuse detection. It checks for OA-001 (workflow-level id-token:write) and OA-002 (id-token:write without environment scope).

func CheckPackageInstallHygiene added in v2.1.0 

func CheckPackageInstallHygiene(workflow parser.WorkflowFile) []Finding

CheckPackageInstallHygiene runs both install-related supply chain checks.

func CheckRefVersionMismatch added in v2.1.0 

func CheckRefVersionMismatch(workflow parser.WorkflowFile) []Finding

CheckRefVersionMismatch is the public entry point for the REF_VERSION_MISMATCH rule.

func CheckSecretsOutsideEnv added in v2.1.0 

func CheckSecretsOutsideEnv(workflow parser.WorkflowFile) []Finding

CheckSecretsOutsideEnv is the public entry point for the SECRETS_OUTSIDE_ENV rule.

func CheckSelfHostedRunnerSecurity 

func CheckSelfHostedRunnerSecurity(workflow parser.WorkflowFile) []Finding

CheckSelfHostedRunnerSecurity performs comprehensive self-hosted runner security analysis

func CheckShellInjectionVulnerabilities 

func CheckShellInjectionVulnerabilities(workflow parser.WorkflowFile) []Finding

CheckShellInjectionVulnerabilities is the main entry point for shell injection checks

func CheckSupplyChainVulnerabilities 

func CheckSupplyChainVulnerabilities(workflow parser.WorkflowFile) []Finding

CheckSupplyChainVulnerabilities checks for supply chain security issues

func CheckWorkflowRunTrust 

func CheckWorkflowRunTrust(workflow parser.WorkflowFile) []Finding

CheckWorkflowRunTrust is the main entry point for WRT-001, WRT-002, and WRT-003. It returns findings for all three rules covering the CVE-2025-30066 (tj-actions/reviewdog) supply chain attack pattern where workflow_run triggers allow untrusted artifact injection.

type InjectionPatterns 

type InjectionPatterns struct {
	GitHub []string
	GitLab []string
	Azure  []string
	Tekton []string
}

InjectionPatterns contains regex patterns for detecting injection vulnerabilities

func GetInjectionPatterns 

func GetInjectionPatterns() InjectionPatterns

GetInjectionPatterns returns patterns for detecting user-controlled input injection

type Platform 

type Platform string

Platform represents the CI/CD platform a rule applies to 

const (
	PlatformAll    Platform = "ALL"    // Rule applies to all platforms
	PlatformGitHub Platform = "GITHUB" // Rule applies only to GitHub Actions
	PlatformGitLab Platform = "GITLAB" // Rule applies only to GitLab CI
)

func StringToPlatform 

func StringToPlatform(platformStr string) Platform

StringToPlatform converts platform string constants to Platform enum

type Rule 

type Rule struct {
	ID          string
	Name        string
	Description string
	Severity    Severity
	Category    Category
	Platform    Platform // Platform compatibility for this rule
	Check       func(workflow parser.WorkflowFile) []Finding
}

Rule represents a security rule to check in a workflow

func FilterRulesByPlatform 

func FilterRulesByPlatform(rules []Rule, targetPlatform Platform) []Rule

FilterRulesByPlatform filters rules based on target platform compatibility

func NewForbiddenUsesRule added in v2.1.0 

func NewForbiddenUsesRule(allow, deny []string) *Rule

NewForbiddenUsesRule builds the opt-in FORBIDDEN_USES rule from an allowlist and a denylist.

The rule is policy enforcement rather than vulnerability detection: it lets an organization mechanically enforce which third-party actions may appear in its workflows. Because there is no universally correct policy, the rule does nothing until configured, and returns nil when both lists are empty so it is never registered as a no-op.

Allow and Deny are mutually exclusive; if both are supplied, Allow wins, since an allowlist is the strictly stronger control.

Note that this inspects `uses:` clauses as written. It cannot see actions pulled in indirectly — via a `git clone` in a `run:` step, or by a permitted action that itself calls a forbidden one — so it complements rather than replaces the other supply chain rules.

func StandardRules 

func StandardRules() []Rule

StandardRules returns the list of built-in security rules

type RuleEngine 

type RuleEngine struct {
	// contains filtered or unexported fields
}

RuleEngine handles rule execution with configuration support

func NewRuleEngine 

func NewRuleEngine(config ConfigInterface) *RuleEngine

NewRuleEngine creates a new rule engine with configuration

func (*RuleEngine) ExecuteRules 

func (re *RuleEngine) ExecuteRules(workflow parser.WorkflowFile, rules []Rule) []Finding

ExecuteRules runs rules against a workflow with configuration filtering.

Rules are independent pure functions of the workflow, so they are evaluated in parallel. This matters most for scans of a single workflow: the workflow processor only parallelises across files, so without this a one-workflow scan would leave every core but one idle.

Results are collected into a slice indexed by rule position and flattened in order, so the output is identical to sequential execution regardless of the order in which rules happen to finish.

func (*RuleEngine) SetContextAware 

func (re *RuleEngine) SetContextAware(enabled bool)

SetContextAware enables or disables context-aware analysis

type Severity 

type Severity string

Severity represents the severity level of a finding 

const (
	Critical Severity = "CRITICAL"
	High     Severity = "HIGH"
	Medium   Severity = "MEDIUM"
	Low      Severity = "LOW"
	Info     Severity = "INFO"
)

type VersionPinningAnalysis 

type VersionPinningAnalysis struct {
	Risk        string
	Description string
	Remediation string
	Version     string
	VersionType string
}

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.