Skip to content

Distroless Container Workflow

This document details the workflow for scanning distroless containers, which are minimal containers without a shell or common utilities.

Workflow Overview

The distroless container workflow uses a debug container approach to access containers that lack a shell or common utilities. It employs ephemeral debug containers with chroot to scan the target container's filesystem.

Detailed Workflow Steps

1. Setup Phase

flowchart TD
    A[Start Setup] --> B[Identify Distroless Target Container]
    B --> C[Create Service Account]
    C --> D[Apply Extended RBAC]
    D --> E[Generate Short-lived Token]
    E --> F[Create Restricted Kubeconfig]
    F --> G[Setup Complete]

    style A fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style G fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

Setup Tasks

  1. Identify Target Container:
  2. Namespace, pod name, and container name are identified
  3. Container status verified to ensure it's running

  4. Container verified as distroless or minimal

  5. Create Service Account:

  6. Temporary service account created in target namespace

  7. Account is marked for cleanup after scan completion

  8. Apply Extended RBAC:

  9. Role created with permissions for:
    • pods/exec permission for target pod
    • pods/ephemeralcontainers permission for debug container
    • pods GET permission for target pod

  10. RoleBinding created to link service account to role

  11. Generate Token:

  12. Short-lived token generated for service account

  13. Token expiration set to minimal required time

  14. Create Kubeconfig:

  15. Restricted kubeconfig file created with token
  16. File permissions set to restrict access

2. Debug Container Deployment Phase

flowchart TD
    A[Start Debug Deployment] --> B[Create Debug Container Spec]
    B --> C[Apply Debug Container to Target Pod]
    C --> D[Wait for Debug Container Ready]
    D --> E[Verify Debug Container Access]
    E --> F[Debug Container Ready]

    style A fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style F fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

Debug Container Tasks

  1. Create Debug Container:

  2. Debug container specification created with:

    • CINC Auditor image
    • Target process namespace sharing
    • Required security context

  3. Apply Debug Container:

  4. Debug container added to target pod

  5. Container configured to access target filesystem

  6. Wait for Readiness:

  7. Debug container availability checked
  8. Connection tested

3. Scanning Phase

flowchart TD
    A[Start Scanning] --> B[Initialize CINC Auditor in Debug Container]
    B --> C[Chroot to Target Container Filesystem]
    C --> D[Execute Compliance Profile]
    D --> E[Collect Scan Results]
    E --> F[Export Results from Debug Container]
    F --> G[Scanning Complete]

    style A fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style D fill:#217645,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style G fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

Scanning Tasks

  1. Initialize CINC Auditor:
  2. CINC Auditor (InSpec) initialized in debug container

  3. Scanner configured with appropriate profile

  4. Chroot to Target:

  5. Target container filesystem accessed via:

    • Process filesystem (/proc/<pid>/root)
    • Or bind-mounted directory

  6. Execute Profile:

  7. Compliance profile run against target filesystem

  8. Profile execution constrained to target context

  9. Collect Results:

  10. Scan results collected in structured JSON format

  11. Results stored in debug container

  12. Export Results:

  13. Results exported from debug container
  14. Results saved for processing

4. Results Processing Phase

flowchart TD
    A[Start Processing] --> B[Format Raw Results]
    B --> C[Generate JSON Report]
    C --> D[Process with SAF CLI]
    D --> E[Apply Threshold Validation]
    E --> F{Thresholds Met?}
    F -->|Yes| G[Mark as Passed]
    F -->|No| H[Mark as Failed]
    G --> I[Processing Complete]
    H --> I

    style A fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style D fill:#217645,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style E fill:#217645,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style F fill:#DD6100,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style G fill:#217645,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style H fill:#DD6100,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style I fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

Processing Tasks

  1. Format Results:
  2. Raw scan results formatted for readability

  3. Results organized by control

  4. Generate Reports:

  5. JSON report generated with full scan details

  6. Additional report formats created as needed

  7. Process with SAF CLI:

  8. MITRE SAF CLI processes scan results

  9. Results evaluated against compliance standards

  10. Threshold Validation:

  11. Results compared to configured thresholds
  12. Pass/fail status determined

5. Cleanup Phase

flowchart TD
    A[Start Cleanup] --> B[Remove Debug Container]
    B --> C[Delete Kubeconfig]
    C --> D[Delete Service Account]
    D --> E[Delete Role and RoleBinding]
    E --> F[Verify Resource Removal]
    F --> G[Cleanup Complete]

    style A fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    style G fill:#505050,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

Cleanup Tasks

  1. Remove Debug Container:
  2. Debug container removed from target pod

  3. Removal verified

  4. Delete Kubeconfig:

  5. Temporary kubeconfig file securely deleted

  6. File permissions verified during deletion

  7. Delete Kubernetes Resources:

  8. Service account removed
  9. Role and RoleBinding removed

  10. Any other temporary resources removed

  11. Verify Cleanup:

  12. Resource deletion confirmed
  13. No leftover resources remain

Implementation Details

The distroless container workflow is implemented in the scan-distroless-container.sh script with the following parameters:

1
./kubernetes-scripts/scan-distroless-container.sh <namespace> <pod-name> <container-name> <profile-path> [threshold_file]

Required Parameters

  • namespace: Kubernetes namespace containing the target container
  • pod-name: Name of the pod containing the target container
  • container-name: Name of the target container
  • profile-path: Path to the InSpec profile to run

Optional Parameters

  • threshold_file: Path to threshold configuration file for validation

Kubernetes Version Requirements

This workflow requires:

  • Kubernetes v1.16+ for ephemeral container support
  • Feature gate EphemeralContainers=true enabled in the cluster

Error Handling

The workflow includes specialized error handling for distroless containers:

  1. Feature Detection: Checks for ephemeral container support
  2. Alternative Fallbacks: Can use other methods if ephemeral containers unavailable
  3. Filesystem Access: Validates access to target filesystem
  4. Resource Cleanup: Ensures debug containers are removed even after failures

Integration with CI/CD

For CI/CD integration, the workflow can be adapted to run as part of:

  • GitHub Actions workflows with special ephemeral container permissions
  • GitLab CI pipelines with extended RBAC
  • Other CI/CD systems with appropriate configuration

See CI/CD Integration for Distroless Containers for specific integration examples.