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

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

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

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

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

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:

./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.