✨ Now with dockerfiles

DEV_GUIDE_ACTIONS.md

@@ -0,0 +1,28 @@
+## PKG/ACTIONS Directory Run Down
+
+The `pkg/actions` directory focuses on core actions and functionalities of the audit tool.
+
+### run_validators.go
+
+- **RunValidators**: Main function to run various validators.
+- **checkBundleAgainstCommonCriteria**: Checks bundles against common criteria.
+- **fromOCPValidator**: Related to OCP validation.
+- **fromAuditValidatorsBundleSize**: Checks bundle sizes as part of the validation.
+
+### run_scorecard.go
+
+- **RunScorecard**: Main function to run the scorecard functionality.
+- **writeScorecardConfig**: Writes or updates the configuration for the scorecard.
+
+### get_bundle.go
+
+- **GetDataFromBundleImage**: Fetches data from a bundle image.
+- **createBundleDir**: Creates a directory for the bundle.
+- **extractBundleFromImage**: Extracts bundle data from an image.
+- **cleanupBundleDir**: Cleans up the bundle directory after processing.
+- **DownloadImage**: Downloads an image for further processing or analysis.
+
+### extract_index.go
+
+- **ExtractIndexDBorCatalogs**: Extracts database or catalogs from an index.
+- **GetVersionTagFromImage**: Retrieves the version tag from an image.

DEV_GUIDE_ADDING_CMDS.md

@@ -0,0 +1,115 @@
+# Commands and Sub-Commands Development Guide
+
+This section of the development guide focuses on understanding, adding, and modifying commands and sub-commands within
+the audit tool. By following the described patterns, developers can seamlessly introduce new functionalities.
+
+## Adding a New Primary Command
+
+1. **Define Your Command**:
+   Begin by defining your command structure using the `cobra.Command` type, including:
+   - `Use`: Command's name.
+   - `Short`: A brief description.
+   - `Long`: An extended description.
+
+   Example from the `audit-tool`:
+   ```go
+   rootCmd := &cobra.Command{
+       Use:   "audit-tool",
+       Short: "An analytic tool to audit operator bundles and index catalogs",
+       Long:  "The audit is an analytic tool which uses the Operator Framework solutions ...",
+   }
+   ```
+
+2. **Add Sub-Commands (if necessary)**:
+   For embedding sub-commands to your main command, employ the `AddCommand` method. As observed in the `audit-tool`,
+   sub-commands like `index` and `custom` are integrated as:
+   ```go
+   rootCmd.AddCommand(index.NewCmd())
+   rootCmd.AddCommand(custom.NewCmd())
+   ```
+
+3. **Execute the Command**:
+   Ensure the primary command's execution in the `main` function:
+   ```go
+   if err := rootCmd.Execute(); err != nil {
+       log.Fatal(err)
+   }
+   ```
+
+## Tutorial: Add a Sub-Command to the `index` Command
+
+The `index` command has sub-commands like `bundles` and `eus`. To introduce a new sub-command:
+
+1. **Create a Sub-directory**:
+   Organize by creating a sub-directory within `index`. Name it as per your sub-command. E.g., for a sub-command
+   named `sample`, formulate a `sample` directory.
+
+2. **Define Your Sub-Command**:
+   In this directory, create a `command.go` file and define your sub-command structure:
+   ```go
+   package sample
+
+   import (
+       "github.com/spf13/cobra"
+   )
+
+   func NewCmd() *cobra.Command {
+       cmd := &cobra.Command{
+           Use:   "sample",
+           Short: "Short description of sample",
+           Long:  "Detailed description of sample...",
+       }
+       return cmd
+   }
+   ```
+
+3. **Add Flags (optional)**:
+   For flag additions to your sub-command, utilize the `Flags` method. For instance, to integrate a `--test` flag:
+   ```go
+   cmd.Flags().BoolP("test", "t", false, "Description of test flag")
+   ```
+
+4. **Integrate Sub-Command**:
+   Navigate back to the `main.go` of `index` and add your new sub-command:
+   ```go
+   indexCmd.AddCommand(sample.NewCmd())
+   ```
+
+---
+
+## Adding Flags with parameters to the `sample` Sub-Command
+
+Flags offer flexibility to commands by allowing users to specify options or provide additional input. Here, we'll delve
+into adding both boolean flags and flags that accept parameters to the `sample` sub-command.
+
+1. **Boolean Flag**:
+   A flag that signifies a simple `true` or `false` option.
+
+   Example: Adding a `--test` flag to the `sample` sub-command:
+   ```go
+   cmd.Flags().BoolP("test", "t", false, "Description of test flag")
+   ```
+   Use: `audit-tool index sample --test`
+
+2. **Flag with Parameter**:
+   A flag that necessitates an accompanying value.
+
+   Example: Introducing a `--input` flag which requires a string parameter:
+   ```go
+   cmd.Flags().StringP("input", "i", "", "Provide input data for the sample command")
+   ```
+   Use: `audit-tool index sample --input "This is sample input"`
+
+3. **Utilize Flag Parameters in Command Logic**:
+   To harness the values provided through flags, use the `cmd.Flag("flag-name").Value.String()` method.
+
+   Example: Using the `--input` flag's value within the `sample` sub-command:
+   ```go
+   var input string = cmd.Flag("input").Value.String()
+   if input != "" {
+       fmt.Println("Received input:", input)
+   } else {
+       fmt.Println("No input provided.")
+   }
+   ```
+   This code snippet checks if the `--input` flag has been provided a value, and if so, it prints the received input.

DEV_GUIDE_CUSTOM.md

@@ -0,0 +1,47 @@
+## CUSTOM Directory Run Down
+
+The `custom` directory focuses on providing specific functionalities that are tailored to the unique requirements of the
+audit tool. These functionalities are organized as sub-commands, each having its own directory.
+
+### NewCmd
+
+This function initializes the overarching command for the 'custom' functionalities. It sets up the primary CLI structure
+for the custom operations, guiding users to its specific sub-commands.
+
+### Subdirectories:
+
+Each subdirectory represents a specific custom functionality or operation. Here are the details:
+
+#### validator
+
+- **NewCmd**: This function sets up the command structure for the 'validator' functionality. It provides a brief
+  description to the user about its purpose and defines available flags and options.
+- **validation**: This function validates the provided flags and arguments specific to the 'validator' operation. It
+  ensures that necessary inputs are present and correctly formatted.
+- **run**: This function drives the core logic of the 'validator' functionality, making necessary calls to validate the
+  data as per the defined criteria.
+
+#### deprecate
+
+- **NewCmd**: This function initializes the command for the 'deprecate' functionality, defining its purpose and
+  available flags.
+- **validation**: This function checks the provided flags and arguments to ensure they align with the 'deprecate'
+  operation requirements.
+- **run**: This function manages the 'deprecate' operation, handling the necessary steps to mark certain data as
+  deprecated.
+
+#### qa
+
+- **NewCmd**: This function sets up the command for the 'qa' functionality, providing a brief description and defining
+  the available flags.
+- **validation**: This function validates user input, ensuring it matches the criteria set for the 'qa' operation.
+- **run**: This function handles the 'qa' operation, performing quality assurance checks on the provided data.
+
+#### multiarch
+
+- **NewCmd**: This function initializes the command for the 'multiarch' functionality. It provides a description and
+  lists available flags for the user.
+- **validation**: This function checks the flags and arguments to ensure they fit the 'multiarch' operation's
+  requirements.
+- **run**: This function manages the 'multiarch' functionality, handling operations and checks related to multiple
+  architectures.

DEV_GUIDE_EXT_TOOLS.md

@@ -0,0 +1,40 @@
+# External Tool Integration in the Audit Tool
+
+This document showcases how external tools have been integrated into the Audit Tool. By examining these specific
+implementations, developers can gain insights into adding similar integrations in the future.
+
+## `operator-sdk` Integration
+
+1. **Tool Purpose**: The `operator-sdk` tool assists in building, testing, and deploying Operator projects.
+2. **Invocation in the Audit Tool**: The binary is invoked in the audit tool via system command calls. For instance:
+   ```go
+   cmd := exec.Command("operator-sdk", "bundle", "validate", "--select-optional", "suite=operatorframework")
+   ```
+3. **Handling Results**: Output and errors from the tool are captured and processed. For example:
+   ```go
+   output, err := cmd.CombinedOutput()
+   if err != nil {
+       log.Errorf("operator-sdk validation failed: %s", output)
+   }
+   ```
+
+## `check-payload` Integration
+
+1. **Tool Purpose**: The `check-payload` tool scans operator images to ensure compliance with specific standards.
+2. **Invocation in the Audit Tool**: The binary is invoked similarly to the `operator-sdk`, but with different
+   arguments:
+   ```go
+   cmd := exec.Command("/path/to/check-payload", "scan", "operator", "--spec", imageRef)
+   ```
+3. **Handling Results**: Output, warnings, and errors from this tool are captured and processed. Here's an example of
+   how these results can be processed and incorporated into the audit tool's report:
+   ```go
+   output, err := cmd.CombinedOutput()
+   if err != nil {
+       // Handle error, potentially adding it to the report
+   } else {
+       // Process the output and distinguish between warnings and errors
+       // Add warnings and errors to the report as appropriate
+   }
+   ```
+

DEV_GUIDE_MODELS.md

@@ -0,0 +1,8 @@
+## PKG/MODELS Directory Run Down
+
+The `pkg/models` directory contains data structures or models that provide a representation of the core entities within
+the system.
+
+### bundle.go
+
+- **AuditBundle**: Represents the model for an audit bundle.

DEV_GUIDE_VALIDATION.md

@@ -0,0 +1,10 @@
+## PKG/VALIDATION Directory Run Down
+
+The `pkg/validation` directory contains code related to validation checks and functionalities within the application.
+
+### bundle_size.go
+
+- **validateBundleSizeValidator**: A function related to validating the size of a bundle.
+- **validateBundleSize**: Function focused on bundle size validation.
+- **checkBundleSize**: Checks the size of a bundle.
+- **formatBytesInUnit**: Utility function to format bytes into a specific unit (e.g., KB, MB).

README.md

@@ -16,6 +16,7 @@ For further information about its motivation see the [EP Audit command operation
 
 - go 1.19 
 - docker or podman
+- tar and skopeo (to scrape Dockerfile from image layer oci dirs -- common to all Red Hat built operators)
 - access to the registry where the index catalog and operator bundle images are distributed
 - access to a Kubernetes cluster
 - [operator-sdk][operator-sdk] installed >= `1.5.0

pkg/actions/get_bundle.go

@@ -21,6 +21,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 
 	// "strings"
 
@@ -79,7 +80,21 @@ func GetDataFromBundleImage(auditBundle *models.AuditBundle,
 			}
 		}
 		auditBundle.BundleImageLabels = inspectManifest.DockerConfig.Labels
+	}
+
+	// Ensure the image path has the 'docker://' prefix
+	formattedImagePath := auditBundle.OperatorBundleImagePath
+	if !strings.HasPrefix(formattedImagePath, "docker://") {
+		formattedImagePath = "docker://" + formattedImagePath
+	}
 
+	dockerfiles, err := pkg.RunSkopeoLayerExtract(formattedImagePath)
+	if err != nil {
+		log.Printf("Error extracting Dockerfiles: %s", err)
+		// Handle the error, e.g., by returning or continuing with other logic
+	} else {
+		// Store the extracted Dockerfiles in the auditBundle
+		auditBundle.BundleDockerfiles = dockerfiles
 	}
 
 	// Read the bundle