Add IaC Realtime scanning functionality (AST-102217, AST-102218) (#1238)

* Add IaC Realtime scanning functionality

* Rename command for IaC Realtime scan and update flag descriptions

* Implement IaC Realtime scan functionality and enhance error handling

* Refactor IaC Realtime scan to return structured results and improve error handling

* Refactor IaC Realtime file validation to use supported extension check

* Add SimilarityID to IaC Realtime results and enhance line index handling

* Refactor IaC Realtime service to improve file handling and container management

* Refactor Mapper methods to use receiver 'm' for consistency and clarity

* Fix casing of 'Locations' field in config struct for consistency

* Rename package from 'iac_realtime' to 'iacrealtime' for consistency across files

* Rename package from 'iac_realtime' to 'iacrealtime' for consistency across files

* Refactor GetLineIndices method signature for improved clarity

* Add unit tests for DockerManager and FileHandler, and implement integration tests for IacRealtimeService

* Refactor KICS results file tests for improved readability and maintainability

* Refactor file handler tests for improved structure and readability; add helper functions for test case management

* Refactor test helper functions for improved clarity and consistency in signatures

* Add integration tests for IacRealtimeScan functionality with various file types and validation checks

* Rename DockerManager to ContainerManager and update related references; refactor validation logic in IacRealtimeService

* Refactor ContainerManager to IContainerManager interface; update IacRealtimeService and tests to use mock container manager

* Add nil checks in mock container manager and scanner tests to prevent nil pointer dereference

Author: cx-ben-alvo

internal/commands/iac-realtime-engine.go

@@ -0,0 +1,39 @@
+package commands
+
+import (
+	"github.com/checkmarx/ast-cli/internal/commands/util/printer"
+	errorconstants "github.com/checkmarx/ast-cli/internal/constants/errors"
+	commonParams "github.com/checkmarx/ast-cli/internal/params"
+	"github.com/checkmarx/ast-cli/internal/services/realtimeengine/iacrealtime"
+	"github.com/checkmarx/ast-cli/internal/wrappers"
+	"github.com/spf13/cobra"
+)
+
+func RunScanIacRealtimeCommand(
+	jwtWrapper wrappers.JWTWrapper,
+	featureFlagWrapper wrappers.FeatureFlagsWrapper,
+) func(cmd *cobra.Command, args []string) error {
+	return func(cmd *cobra.Command, _ []string) error {
+		fileSourceFlag, _ := cmd.Flags().GetString(commonParams.SourcesFlag)
+		if fileSourceFlag == "" {
+			return errorconstants.NewRealtimeEngineError("file path is required").Error()
+		}
+
+		ignoredFilePathFlag, _ := cmd.Flags().GetString(commonParams.IgnoredFilePathFlag)
+		engine, _ := cmd.Flags().GetString(commonParams.EngineFlag)
+
+		iacRealtimeService := iacrealtime.NewIacRealtimeService(jwtWrapper, featureFlagWrapper, iacrealtime.NewContainerManager())
+
+		results, err := iacRealtimeService.RunIacRealtimeScan(fileSourceFlag, engine, ignoredFilePathFlag)
+		if err != nil {
+			return err
+		}
+
+		err = printer.Print(cmd.OutOrStdout(), results, printer.FormatJSON)
+		if err != nil {
+			return errorconstants.NewRealtimeEngineError("failed to return IaC Realtime vulnerabilities").Error()
+		}
+
+		return nil
+	}
+}

internal/commands/scan.go

@@ -225,6 +225,8 @@ func NewScanCommand(
 
 	secretsRealtimeCmd := scanSecretsRealtimeSubCommand(jwtWrapper, featureFlagsWrapper)
 
+	iacRealtimeCmd := scanIacRealtimeSubCommand(jwtWrapper, featureFlagsWrapper)
+
 	addFormatFlagToMultipleCommands(
 		[]*cobra.Command{listScansCmd, showScanCmd, workflowScanCmd},
 		printer.FormatTable, printer.FormatList, printer.FormatJSON,
@@ -247,6 +249,7 @@ func NewScanCommand(
 		ossRealtimeCmd,
 		containersRealtimeCmd,
 		secretsRealtimeCmd,
+		iacRealtimeCmd,
 	)
 	return scanCmd
 }
@@ -499,6 +502,52 @@ func scanOssRealtimeSubCommand(
 	return scanOssRealtimeCmd
 }
 
+func scanIacRealtimeSubCommand(
+	jwtWrapper wrappers.JWTWrapper,
+	featureFlagsWrapper wrappers.FeatureFlagsWrapper,
+) *cobra.Command {
+	scanIacRealtimeCmd := &cobra.Command{
+		Hidden: true,
+		Use:    "iac-realtime",
+		Short:  "Run a IaC-Realtime scan",
+		Long:   "Running a IaC-Realtime scan is a fast and efficient way to identify Infrustructure as Code vulnerabilities in a file.",
+		Example: heredoc.Doc(
+			`
+			$ cx scan iac-realtime -s <path to a manifest file> --ignored-file-path <path to ignored iac vulnerabilities JSON file>
+			`,
+		),
+		Annotations: map[string]string{
+			"command:doc": heredoc.Doc(
+				`
+				https://docs.checkmarx.com/en/34965-68625-checkmarx-one-cli-commands.html
+				`,
+			),
+		},
+		RunE: RunScanIacRealtimeCommand(jwtWrapper, featureFlagsWrapper),
+	}
+
+	scanIacRealtimeCmd.PersistentFlags().StringP(
+		commonParams.SourcesFlag,
+		commonParams.SourcesFlagSh,
+		"",
+		"The file source should be the path to a single file",
+	)
+
+	scanIacRealtimeCmd.Flags().String(
+		commonParams.IgnoredFilePathFlag,
+		"",
+		"Path to a JSON file listing ignored iac vulnerabilities",
+	)
+
+	scanIacRealtimeCmd.Flags().String(
+		commonParams.EngineFlag,
+		"docker",
+		"Name of the container engine to run IaC-Realtime. (ex. docker, podman)",
+	)
+
+	return scanIacRealtimeCmd
+}
+
 func scanContainersRealtimeSubCommand(realtimeScannerWrapper wrappers.RealtimeScannerWrapper, jwtWrapper wrappers.JWTWrapper, featureFlagsWrapper wrappers.FeatureFlagsWrapper) *cobra.Command {
 	scanContainersRealtimeCmd := &cobra.Command{
 		Hidden: true,

internal/commands/util/remediation.go

@@ -27,7 +27,7 @@ const (
 	filesContainerVolume      = ":/files"
 	resultsContainerLocation  = "/kics/"
 	containerRemove           = "--rm"
-	containerImage            = "checkmarx/kics:v2.1.11"
+	ContainerImage            = "checkmarx/kics:v2.1.11"
 	containerNameFlag         = "--name"
 	remediateCommand          = "remediate"
 	resultsFlag               = "--results"
@@ -247,7 +247,7 @@ func runKicsRemediation(cmd *cobra.Command, volumeMap, tempDir string) error {
 		kicsFilesPath + filesContainerVolume,
 		containerNameFlag,
 		containerName,
-		containerImage,
+		ContainerImage,
 		remediateCommand,
 		resultsFlag,
 		resultsContainerLocation + file,

internal/services/realtimeengine/iacrealtime/config.go

@@ -0,0 +1,12 @@
+package iacrealtime
+
+import "github.com/checkmarx/ast-cli/internal/services/realtimeengine"
+
+type IacRealtimeResult struct {
+	SimilarityID string                    `json:"SimilarityID"`
+	Title        string                    `json:"Title"`
+	Description  string                    `json:"Description"`
+	Severity     string                    `json:"Severity"`
+	FilePath     string                    `json:"FilePath"`
+	Locations    []realtimeengine.Location `json:"Locations"`
+}

internal/services/realtimeengine/iacrealtime/constants.go

@@ -0,0 +1,25 @@
+package iacrealtime
+
+const (
+	ContainerPath            = "/path"
+	ContainerFormat          = "json"
+	ContainerTempDirPattern  = "iac-realtime"
+	KicsContainerPrefix      = "cli-iac-realtime-"
+	ContainerResultsFileName = "results.json"
+)
+
+var KicsErrorCodes = []string{"60", "50", "40", "30", "20"}
+
+type LineIndex struct {
+	Start int
+	End   int
+}
+
+var Severities = map[string]string{
+	"critical": "Critical",
+	"high":     "High",
+	"medium":   "Medium",
+	"low":      "Low",
+	"info":     "Info",
+	"unknown":  "Unknown",
+}

internal/services/realtimeengine/iacrealtime/container-manager.go

@@ -0,0 +1,46 @@
+package iacrealtime
+
+import (
+	"os/exec"
+
+	"github.com/checkmarx/ast-cli/internal/commands/util"
+	commonParams "github.com/checkmarx/ast-cli/internal/params"
+	"github.com/google/uuid"
+	"github.com/spf13/viper"
+)
+
+// IContainerManager interface for container operations
+type IContainerManager interface {
+	GenerateContainerID() string
+	RunKicsContainer(engine, volumeMap string) error
+}
+
+// ContainerManager handles Docker container operations
+type ContainerManager struct{}
+
+func NewContainerManager() IContainerManager {
+	return &ContainerManager{}
+}
+
+func (dm *ContainerManager) GenerateContainerID() string {
+	containerID := uuid.New().String()
+	containerName := KicsContainerPrefix + containerID
+	viper.Set(commonParams.KicsContainerNameKey, containerName)
+	return containerName
+}
+
+func (dm *ContainerManager) RunKicsContainer(engine, volumeMap string) error {
+	args := []string{
+		"run", "--rm",
+		"-v", volumeMap,
+		"--name", viper.GetString(commonParams.KicsContainerNameKey),
+		util.ContainerImage,
+		"scan",
+		"-p", ContainerPath,
+		"-o", ContainerPath,
+		"--report-formats", ContainerFormat,
+	}
+
+	_, err := exec.Command(engine, args...).CombinedOutput()
+	return err
+}