Home

Relevant source files

The following files were used as context for generating this wiki page:

• iac-recert-engine/cmd/ice/root.go
• iac-recert-engine/cmd/ice/run.go
• iac-recert-engine/example.config.yaml
• iac-recert-engine/internal/config/types.go
• iac-recert-engine/internal/engine/engine.go
• iac-recert-engine/internal/pr/generator.go
• iac-recert-engine/internal/provider/github.go
• iac-recert-engine/internal/scan/file_scanner.go
• iac-recert-engine/internal/scan/git_history.go
• iac-recert-engine/internal/scan/recert_checker.go
• iac-recert-engine/internal/strategy/strategy_test.go
• iac-recert-engine/internal/types/types.go

The Infrastructure as Code Recertification Engine (ICE) is a command-line tool designed to automate the recertification process for IaC repositories. It operates by scanning a repository for files matching user-defined patterns, checking their last modification dates against configured time thresholds, and automatically generating pull requests for files that require review and recertification.

The primary goal of ICE is to ensure that infrastructure configurations do not become stale or un-reviewed for extended periods, thereby improving security and compliance posture. The engine is highly configurable, allowing users to define specific file patterns, recertification periods, pull request grouping strategies, and assignee resolution logic.

Sources: cmd/ice/root.go:11-14, internal/engine/engine.go

High-Level Architecture

The core of the application is the Engine, which orchestrates the entire recertification process. The process is executed via the run command and follows a sequential pipeline of scanning, analysis, checking, grouping, and actioning.

Sources: cmd/ice/run.go:17-41, internal/engine/engine.go:23-28

Execution Flow

The following diagram illustrates the main stages of the Engine.Run method.

Sources: internal/engine/engine.go:90-146

Engine Components

The Engine struct is composed of several specialized components, each responsible for a specific stage of the workflow.

Sources: internal/engine/engine.go:23-35

Configuration

The engine's behavior is controlled by a central YAML configuration file. The structure is defined in internal/config/types.go and an example is provided in example.config.yaml.

Sources: internal/config/types.go, example.config.yaml

Main Configuration Blocks

Block	Description
repository	Specifies the target repository URL and its provider (github, azure, gitlab).
auth	Defines the authentication method, typically an environment variable containing a personal access token.
global	Contains global settings like dry_run mode, verbose_logging, and the default_base_branch for PRs.
patterns	An array defining which files to scan, their recertification period, and other metadata.
pr_strategy	Determines how files needing recertification are grouped into pull requests.
assignment	Defines the strategy for assigning pull requests to users or teams.
pr_template	Configures the title and body of the generated pull requests.
audit	Configures audit logging for the engine's operations.

Sources: internal/config/types.go:8-25, example.config.yaml

File Patterns (patterns)

This is a critical section that defines the scope of the scan. Each entry in the patterns list is an object with the following key properties:

Key	Description	Example
name	A unique identifier for the pattern.	terraform-prod
paths	An array of glob patterns to include files.	["terraform/prod/**/*.tf"]
exclude	An array of glob patterns to exclude files from the match.	["**/*.test.tf"]
recertification_days	The number of days after which a file is considered due for recertification.	180
enabled	A boolean to enable or disable this pattern.	true
decorator	A string to prepend to the file content upon recertification. {timestamp} is replaced with the current time.	// Last Recertification: {timestamp}\n

Sources: internal/config/types.go:43-51, example.config.yaml:26-40

PR Grouping Strategy (pr_strategy)

This setting controls how multiple files are bundled into pull requests.

Type	Description
per_file	Creates one pull request for each file that needs recertification.
per_pattern	Groups all files matching the same pattern into a single pull request.
per_committer	Groups all files last modified by the same author into a single pull request.
single_pr	Groups all files needing recertification across all patterns into one large pull request.
plugin	Uses a custom plugin to determine the grouping logic.

Sources: internal/config/types.go:53-57, internal/strategy/strategy_test.go

Assignment Strategy (assignment)

This setting determines who is assigned to the generated pull requests.

Strategy	Description
static	Assigns a predefined list of users from fallback_assignees.
last_committer	Assigns the author of the most recent commit within the file group.
composite	Uses a set of rules to apply different strategies based on file paths.
plugin	Uses a custom plugin to resolve assignees.

Sources: internal/config/types.go:59-64, example.config.yaml:65-76

Detailed Workflow

The Engine.Run method executes a series of steps to perform the recertification task.

Sources: internal/engine/engine.go:90-146

1. Scanning

The Scanner component is responsible for finding all relevant files.

1. It first clones the target repository into a temporary local directory.
2. It then iterates through all enabled patterns from the configuration.
3. For each pattern, it uses doublestar.FilepathGlob to find all files matching the paths and exclude glob expressions.
4. A de-duplicated list of types.FileInfo objects is returned.

Sources: internal/scan/file_scanner.go:23-102

2. History Analysis (Enrichment)

The HistoryAnalyzer enriches the file information with Git history.

1. For each file found by the scanner, it calculates the file's path relative to the repository root.
2. It calls the GitProvider.GetLastModificationDate method for that file path.
3. The provider implementation (e.g., GitHubProvider) queries the Git service's API to find the last commit that touched the file.
4. The FileInfo struct is updated with the LastModified date, CommitHash, and CommitAuthor.

Sources: internal/scan/git_history.go:23-58, internal/provider/github.go:76-101

3. Recertification Check

The Checker determines which files need recertification.

1. It iterates through the enriched FileInfo objects.
2. For each file, it calculates the number of days since it was last modified (DaysSince).
3. It compares DaysSince to the RecertificationDays threshold defined in the matching pattern. If DaysSince >= RecertificationDays, the file NeedsRecert.
4. A Priority is calculated based on how far past the due date the file is. The ratios are: >1.5 -> "Critical", >=1.0 -> "High", >=0.8 -> "Medium".

Sources: internal/scan/recert_checker.go:49-97

4. Grouping and Processing

The final stage involves grouping files and creating pull requests. The following sequence diagram shows the interactions during this phase for a single group.

Sources: internal/engine/engine.go:121-251, internal/pr/generator.go, internal/assign/resolver.go

Core Data Structures

The engine relies on several key data structures to pass information between its components.

Struct	File	Description
FileInfo	internal/types/types.go	Represents a single file, including its path, size, and commit history details.
RecertCheckResult	internal/types/types.go	Contains the outcome of a recertification check for a file, including priority and due date.
FileGroup	internal/types/types.go	A collection of files grouped together by a Strategy to be included in a single pull request.
PRConfig	internal/types/types.go	Holds all the necessary information to create a pull request, such as title, description, branch, and assignees.

Sources: internal/types/types.go:8-48