b1_01_application_snapshot_

Chapter 1: Application Snapshot

Welcome to the ec-cli tutorial! We're excited to help you learn how to ensure your software supply chain is secure and compliant.

Imagine you've just built a new version of your amazing application. It's composed of several parts, specifically different container images (think of these like packaged-up pieces of your software). Before you release it, you want to make sure every single one of these images meets your organization's security and quality standards.

But how does ec-cli know which specific images belong to this new release? You might have hundreds of images in your registry! This is where the Application Snapshot comes in.

What is an Application Snapshot?

Think of an Application Snapshot like a recipe or a bill of materials (BOM) for your software release. It's a simple list that tells ec-cli exactly which container images are part of the application version you want to check.

Its main job is to be the primary input for ec-cli, clearly defining the scope of what needs to be validated. Without it, ec-cli wouldn't know where to start.

This "list" is usually written in a structured format that computers can easily read, like JSON or YAML.

Here's a very basic example of what an Application Snapshot might look like in YAML format:

# snapshot.yaml
components:
  - name: backend-service
    containerImage: quay.io/my-org/backend:v1.2.0
    source:
      git:
        url: https://github.com/my-org/backend
        revision: main
  - name: frontend-app
    containerImage: quay.io/my-org/frontend:v1.2.0

Explanation:

• components: This is the main list. Each item under it represents a piece of your application.
• containerImage: This is the most important part! It's the exact address (URL and tag/digest) of the container image we want ec-cli to check.
• name: (Optional) A friendly name for the component.
• source: (Optional) Information about where the source code for this image came from (like a Git repository). This can be useful for more advanced checks later.

How ec-cli Uses the Snapshot

When you run the ec validate image command, you tell ec-cli where to find this list using the --images flag. You can either point it to a file (like snapshot.yaml above) or even provide the list directly as a JSON string.

Example 1: Using a file

ec validate image --images snapshot.yaml --policy my-policy

In this case, ec-cli will:

1. Open and read the snapshot.yaml file.
2. Parse the YAML content.
3. Identify the containerImage URLs: quay.io/my-org/backend:v1.2.0 and quay.io/my-org/frontend:v1.2.0.
4. Proceed to validate each of these images against the rules defined in my-policy. (We'll cover policies in the next chapter!)

Example 2: Using inline JSON

ec validate image --images '{"components":[{"containerImage":"quay.io/my-org/backend:v1.2.0"}]}' --policy my-policy

Here, ec-cli does the same thing, but reads the snapshot definition directly from the command line argument. It finds the image quay.io/my-org/backend:v1.2.0 and validates it.

Under the Hood: Parsing the Snapshot

So, how does ec-cli actually process this input? Let's look at a simplified flow.

sequenceDiagram
    participant User
    participant ec_cli as ec validate image
    participant InputParser as Snapshot Parser
    participant Validator as Image Validator

    User->>ec_cli: Runs `ec validate image --images snapshot.yaml ...`
    Note over ec_cli: Command starts execution
    ec_cli->>InputParser: Give me the list of images from `snapshot.yaml`
    InputParser->>InputParser: Reads snapshot.yaml file
    InputParser->>InputParser: Parses YAML content
    InputParser-->>ec_cli: Returns list: ["image1_url", "image2_url"]
    Note over ec_cli: Now knows which images to check
    ec_cli->>Validator: Validate "image1_url"
    Validator-->>ec_cli: Validation results for "image1_url"
    ec_cli->>Validator: Validate "image2_url"
    Validator-->>ec_cli: Validation results for "image2_url"
    Note over ec_cli: Collects all results
    ec_cli-->>User: Shows final report

Loading

The key step here is the "Snapshot Parser". Internally, ec-cli uses code to handle the reading and parsing of the Application Snapshot, whether it comes from a file or a command-line string.

Let's peek at a relevant piece of code (simplified for clarity):

File: internal/applicationsnapshot/input.go

// Simplified view of reading snapshot data (could be YAML or JSON)
func readSnapshotSource(input []byte) (app.SnapshotSpec, error) {
	// This is the Go structure that holds the snapshot data
	var snapshotSpec app.SnapshotSpec

	// Tries to understand the input bytes as YAML/JSON
	// 'yaml.Unmarshal' can often handle JSON too!
	err := yaml.Unmarshal(input, &snapshotSpec)
	if err != nil {
		// Handle errors if the format is wrong...
		log.Debugf("Problem parsing application snapshot from input")
		return app.SnapshotSpec{}, fmt.Errorf("unable to parse Snapshot spec: %w", err)
	}

	// If successful, returns the parsed list of components inside snapshotSpec
	log.Debugf("Read application snapshot successfully")
	return snapshotSpec, nil
}

Explanation:

• This Go function readSnapshotSource takes the raw bytes of the snapshot (from a file or string).
• It uses a library (sigs.k8s.io/yaml) to convert those bytes into a structured Go object called app.SnapshotSpec. This object contains the Components list we saw earlier.
• The ec validate image command calls functions like this (specifically DetermineInputSpec in the same file) during its setup phase (PreRunE in cmd/validate/image.go) to figure out the list of images defined by the user.

Once ec-cli has this structured list (app.SnapshotSpec), it iterates through each Component and uses the ContainerImage URL as the target for the validation checks defined by the Policy Definition & Sources.

Conclusion

You've learned about the Application Snapshot – the crucial input that tells ec-cli which container images to validate for a specific application release. It acts like a recipe, listing all the image "ingredients". You saw how to define it using YAML or JSON and how ec-cli parses this information using the --images flag.

Now that we know what we need to check, the next logical step is to understand how ec-cli performs the checks. What rules does it follow? That's where Policies come in.

Let's move on to the next chapter: Policy Definition & Sources.

---

Generated by AI Codebase Knowledge Builder