Module Engine IAC
Overview
The engine_iac
module is responsible for orchestrating Infrastructure as Code (IaC) security scanning within the DevSecOps Engine Tools platform. It automates the execution of IaC security tools, processes scan configurations, manages exclusions, and integrates results for further risk analysis and reporting.
Configuration Structure
The module is configured through two main JSON files located in example_remote_config_local/engine_sast/engine_iac/
:
ConfigTool.json
Main configuration file that defines scanning behavior, tool versions, and security rules.
{
"SEARCH_PATTERN": ["ms_"],
"IGNORE_SEARCH_PATTERN": "(.*_test)",
"UPDATE_SERVICE_WITH_FILE_NAME_CFT": "True",
"REGEX_CLEAN_END_PIPELINE_NAME": "",
"MESSAGE_INFO_ENGINE_IAC": "engine_iac run successfully",
"THRESHOLD": {
"VULNERABILITY": {
"Critical": 1,
"High": 4,
"Medium": 10,
"Low": 15
},
"COMPLIANCE": {
"Critical": 1
}
},
"CHECKOV": {
"VERSION": "3.2.427",
"INSTALL_TYPE": "remote-binary",
"URL_FILE_LINUX": "https://github.com/bridgecrewio/checkov/releases/download/2.3.321/checkov_linux_X86_64_2.3.321.zip",
"URL_FILE_LINUX_ARM64": "https://github.com/bridgecrewio/checkov/releases/download/2.3.321/checkov_linux_arm64_2.3.321.zip",
"URL_FILE_DARWIN": "https://github.com/bridgecrewio/checkov/releases/download/2.3.321/checkov_darwin_X86_64_2.3.321.zip",
"URL_FILE_WINDOWS": "https://github.com/bridgecrewio/checkov/releases/download/2.3.321/checkov_windows_X86_64_2.3.321.zip",
"USE_EXTERNAL_CHECKS_GIT": false,
"EXTERNAL_CHECKS_GIT": "",
"EXTERNAL_GIT_SSH_HOST": "",
"EXTERNAL_GIT_PUBLIC_KEY_FINGERPRINT": "",
"USE_EXTERNAL_CHECKS_DIR": false,
"EXTERNAL_DIR_OWNER": "",
"EXTERNAL_DIR_REPOSITORY": "",
"APP_ID_GITHUB": "",
"INSTALLATION_ID_GITHUB": "",
"DEFAULT_SEVERITY": "Critical",
"DEFAULT_CATEGORY": "Compliance",
"REGEX_CLEAN_RESOURCE": "",
"RULES": {
"RULES_DOCKER" {
"CKV_DOCKER_1": {
"checkID": "IAC-CKV-DOCKER-1 Ensure port 22 is not exposed",
"environment": {
"dev": true,
"pdn": true,
"qa": true
},
"guideline": "https://bit.ly/3IrJFQx",
"severity": "Critical",
"cvss": "",
"category": "Vulnerability"
},...
},
"RULES_K8S" : {
"CKV_K8S_8": {
"checkID": "IAC-CKV_K8S_8 Liveness Probe Should be Configured",
"environment": {
"dev": true,
"pdn": true,
"qa": true
},
"guideline": "https://bit.ly/3IrJFQx",
"severity": "High",
"cvss": "",
"category": "Compliance"
},....
},
"RULES_CLOUDFORMATION": {
"CKV_AWS_26": {
"customID": "C-SNS-002",
"checkID": "C-SNS-002-AWS SNS is not encrypted",
"environment": {
"dev": true,
"pdn": true,
"qa": true
},
"guideline": "https://bit.ly/44frBRZ",
"severity": "High",
"cvss": "",
"category": "Vulnerability"
},...
},
"RULES_TERRAFORM" : {
"CKV_AWS_144": {
"checkID": "IAC-CKV-TERRAFORM-1 Ensure terraform",
"environment": {
"dev": true,
"pdn": true,
"qa": true
},
"guideline": "guideline",
"severity": "Medium",
"cvss": "",
"category": "Vulnerability"
},...
}
}
},
"KICS": {
"CLI_VERSION": "2.1.5",
"PATH_KICS": "kics/bin/kics",
"DOWNLOAD_KICS_ASSETS": false,
"EXCLUDE_PATHS": ["name_folder_to_exclude_1", "name_folder_to_exclude_2"],
"RULES":{
"RULES_OPENAPI":{
"CKV_OPENAPI_1":{
"checkID": "6998389e-66b2-473d-8d05-c8d71ac4d04d",
"overrideID": "6998389e-254as-473d-1234-c8d71ac4dabc",
"environment": {
"dev": true,
"pdn": true,
"qa": true
},
"guideline": "guideline",
"severity": "Medium",
"cvss": "",
"category": "Vulnerability"
},...
}
}
},
"KUBESCAPE": {
"VERSION": "3.0.11"
}
}
Configuration Parameters
Search and Pattern Configuration
- SEARCH_PATTERN: Array of patterns to search for in repository files/folders (e.g.,
["ms_"]
for microservices) - IGNORE_SEARCH_PATTERN: Regex pattern to exclude files/folders from scanning (e.g.,
"(.*_test)"
ignores test files) - UPDATE_SERVICE_WITH_FILE_NAME_CFT: Boolean flag to update service name with CloudFormation file name
- REGEX_CLEAN_END_PIPELINE_NAME: Regex pattern to clean pipeline names
- MESSAGE_INFO_ENGINE_IAC: Success message displayed when engine completes successfully
Threshold Configuration
- THRESHOLD.VULNERABILITY: Maximum allowed vulnerabilities by severity level:
Critical
: Maximum 1 critical vulnerability allowedHigh
: Maximum 4 high severity vulnerabilitiesMedium
: Maximum 10 medium severity vulnerabilitiesLow
: Maximum 15 low severity vulnerabilities
- THRESHOLD.COMPLIANCE: Maximum allowed compliance issues:
Critical
: Maximum 1 critical compliance issue
Checkov Tool Configuration
- VERSION: Checkov version to use (e.g.,
"3.2.427"
) - INSTALL_TYPE: Installation method (
"remote-binary"
for downloading binaries) - URL_FILE_*: Download URLs for different platforms:
URL_FILE_LINUX
: Linux x86_64 binary URLURL_FILE_LINUX_ARM64
: Linux ARM64 binary URLURL_FILE_DARWIN
: macOS binary URLURL_FILE_WINDOWS
: Windows binary URL
- External Checks Configuration:
USE_EXTERNAL_CHECKS_GIT
: Enable external checks from Git repositoryEXTERNAL_CHECKS_GIT
: Git repository URL for external checksEXTERNAL_GIT_SSH_HOST
: SSH host for Git accessEXTERNAL_GIT_PUBLIC_KEY_FINGERPRINT
: SSH public key fingerprintUSE_EXTERNAL_CHECKS_DIR
: Enable external checks from directoryEXTERNAL_DIR_OWNER
: Directory owner for external checksEXTERNAL_DIR_REPOSITORY
: Repository for external checks directory
- GitHub Integration:
APP_ID_GITHUB
: GitHub App ID for authenticationINSTALLATION_ID_GITHUB
: GitHub App installation ID
- Default Values:
DEFAULT_SEVERITY
: Default severity level for new rules ("Critical"
)DEFAULT_CATEGORY
: Default category for new rules ("Compliance"
)REGEX_CLEAN_RESOURCE
: Regex pattern to clean resource names
KICS Tool Configuration
- CLI_VERSION: KICS CLI version (e.g.,
"2.1.5"
) - PATH_KICS: Relative path to KICS binary (
"kics/bin/kics"
) - DOWNLOAD_KICS_ASSETS: Boolean flag to download KICS assets
- EXCLUDE_PATHS: Array of folder names to exclude from scanning
Kubescape Tool Configuration
- VERSION: Kubescape version to use (e.g.,
"3.0.11"
)
Security Rules Configuration
Each tool contains rule sets organized by technology:
Rule Structure: Each security rule contains:
checkID
: Unique identifier and description of the security checkcustomID
: Custom internal identifier (CloudFormation rules only)overrideID
: Override identifier for rule customization (KICS rules only)environment
: Environment-specific enablement:dev
: Enable in development environmentpdn
: Enable in production environmentqa
: Enable in QA environment
guideline
: URL to security guideline documentationseverity
: Risk level ("Critical"
,"High"
,"Medium"
,"Low"
)cvss
: CVSS score (if applicable)category
: Rule category ("Vulnerability"
,"Compliance"
)
Rule Categories:
- RULES_DOCKER: Container security rules (port exposure, user configuration, file operations)
- RULES_K8S: Kubernetes security rules (resource limits, security contexts, RBAC)
- RULES_CLOUDFORMATION: AWS CloudFormation security rules (encryption, access controls, logging)
- RULES_TERRAFORM: Terraform-specific infrastructure security rules
- RULES_OPENAPI: API security rules for OpenAPI specifications
In the RULES section of each platform (RULES_DOCKER, RULES_K8S, RULES_CLOUDFORMATION, etc.), the body is empty. Example “RULES_DOCKER” , the tool executes all rules associated with it.
Exclusions.json
Defines exclusion rules for repositories and specific security checks.
Structure
{
"All": {
"CHECKOV": [
{
"id": "CKV_K8S_24",
"where": "all",
"create_date": "18112023",
"expired_date": "18032024",
"severity": "HIGH",
"hu": "4338704"
}
]
},
"Repository_Test": {
"SKIP_TOOL": {
"create_date": "24012024",
"expired_date": "30012024",
"hu": "3423213"
},
"CHECKOV": [
{
"id": "CKV_K8S_8",
"where": "deployment-configmap.yaml",
"create_date": "18112023",
"expired_date": "18032024",
"severity": "HIGH",
"hu": "4338704"
}
]
}
}
Exclusion Types
- All: Global exclusions applied to all repositories
- Repository-specific: Exclusions for specific repositories
- SKIP_TOOL: Complete tool bypass for a repository
- Rule-specific: Exclusions for specific security rules with:
id
: Security rule identifierwhere
: File or location scope ("all" for global)create_date
: Exclusion creation dateexpired_date
: Exclusion expiration dateseverity
: Rule severity levelhu
: Human user identifier for audit trail
Main Responsibilities
- IaC Security Orchestration: Executes IaC security tools (Checkov, KICS, Kubescape) on infrastructure code
- Configuration Management: Loads and processes scan configurations and exclusions from remote repositories
- Folder and File Discovery: Identifies relevant folders/files for scanning based on patterns and configuration
- Exclusions Management: Applies exclusion rules based on configuration and DevSecOps policy
- Result Processing: Aggregates and normalizes findings for risk evaluation and reporting
- Threshold Enforcement: Validates findings against configured vulnerability and compliance thresholds
Key Components
runner_iac_scan.py
: Main entry point for IaC scan orchestrationentry_point_tool.py
: Initializes the IaC engine and triggers the scan processiac_scan.py
: Core use case for executing the scan, handling configuration, exclusions, and result aggregation- Adapters: Integrations for IaC security tools (Checkov, KICS, Kubescape)
Supported Tools and Features
- Checkov: Scans Terraform, CloudFormation, Kubernetes, Docker, and more for security misconfigurations
- KICS: Scans IaC files for vulnerabilities and compliance issues with OpenAPI support
- Kubescape: Focused on Kubernetes security scanning with RBAC analysis
- Configurable Exclusions: Supports exclusion of files/folders and custom ignore patterns with expiration dates
- Thresholds and Policies: Handles custom thresholds and build-breaking policies for vulnerabilities and compliance
- Multi-platform Support: Cross-platform binary distribution for Linux, macOS, and Windows
Example Usage
The IaC engine is typically invoked as part of the overall DevSecOps pipeline, after infrastructure code changes are detected:
devsecops-engine-tools \
--platform_devops github \
--remote_config_source github \
--remote_config_repo devsecops-config \
--module engine_iac \
--tool checkov \
--folder_path path/to/iac
Configuration Guidelines
Configure Rules
- Define the rule in the appropriate
RULES_*
section based on technology (Docker, K8S, CloudFormation, etc.) - Include all required fields:
checkID
,environment
,guideline
,severity
,category
- Set environment-specific enablement flags (
dev
,pdn
,qa
) - Provide documentation guidelines URL
Managing Exclusions
- Add exclusions to
Exclusions.json
with proper expiration dates - Use specific file paths in
where
field when possible (avoid "all" for security) - Include audit trail information (
hu
field) for compliance tracking - Review and clean expired exclusions regularly
Tool Version Management
Update tool versions in the configuration and ensure corresponding binary URLs are available for all supported platforms.
Extensibility
- New IaC security tools can be added by extending the adapters and use cases
- Custom rules can be defined in the configuration without code changes
- Supports integration with various version control and CI/CD platforms
- Exclusion logic can be extended for additional use cases and audit requirements
Testing
- Unit tests are provided in the
test/
directory, covering orchestration logic, configuration parsing, and exclusion handling - Integration tests validate tool execution and result processing workflows