Fix container-images flag to support prefix syntax advanced parsing (AST-108903)

[cx-shaked-karta]

Summary

This PR fixes the container-images flag to support Syft-compatible prefix syntax while restricting scanning to single images only.

Changes Made

✅ Added Prefix Syntax Support

• docker:image:tag - Docker daemon images
• podman:image:tag - Podman daemon images
• containerd:image:tag - Containerd daemon images
• registry:image:tag - Registry images (restricted to single images)
• docker-archive:file.tar - Docker archive files
• oci-archive:file.tar - OCI archive files
• oci-dir:/path/to/dir - OCI directory layout (supports files and directories)
• file:/path/to/file - Single files

🚫 Added Restrictions

• Blocked dir: prefix - Prevents scanning entire directories
• Registry validation - Prevents scanning entire registries without specific images
• Single image enforcement - Each comma-separated entry must be a single image

🗑️ Removed Features

• Removed singularity support - No longer supported

🧪 Testing

• Added 30+ comprehensive test cases covering all scenarios
• Validates both positive and negative cases
• Tests comma-separated image lists with mixed valid/invalid entries

Backward Compatibility

• ✅ Traditional image:tag format still works
• ✅ Legacy .tar files still supported
• ✅ Comma-separated lists still work (each entry validated individually)

Example Usage

# ✅ Multiple single images (allowed)
--container-images "docker:nginx:latest,podman:test:latest,registry:ubuntu:20.04"

# 🚫 Bulk scanning (blocked)
--container-images "dir:/path/to/directory"  # Blocked
--container-images "registry:myregistry.com"  # Blocked

Fixes: https://checkmarx.atlassian.net/browse/AST-108903

[github-actions]

Checkmarx One – Scan Summary & Details – b3c00b05-b1d1-46af-b09c-6e2d4d9543f6

Great job! No new security vulnerabilities introduced in this pull request

[cx-anurag-dalke]

ok

[cx-shaked-karta]

🔄 Update: Automatic Local Resolution for Tar Files

Added automatic enforcement of --containers-local-resolution when tar files are detected in --container-images flag.

New Behavior

When using --container-images with tar file(s):

• ✅ If --containers-local-resolution is already set → No action taken
• ⚠️ If --containers-local-resolution is not set → Automatically enabled with warning message

Implementation Details

New Functions:

• isTarFileReference() - Detects tar file references with support for:

  • Simple tar files: image.tar
  • Prefixed tar files: docker-archive:alpine.tar, oci-archive:image.tar, file:myimage.tar
  • Quoted paths: 'alpine.tar', "image.tar"
  • Case-insensitive detection: image.TAR
  • ✅ Validates that tar files don't have invalid tag suffixes (e.g., file.tar:latest is rejected)

• enforceLocalResolutionForTarFiles() - Automatically enables local resolution when tar files are detected

Warning Message:

Warning: Tar file(s) detected in --container-images. Automatically enabling --containers-local-resolution flag.

Examples

# Tar file without --containers-local-resolution
# → Warning printed, flag auto-enabled
cx scan create --container-images "alpine.tar" -s . --project-name test

# Tar file with --containers-local-resolution already set
# → No warning, proceeds normally
cx scan create --container-images "alpine.tar" --containers-local-resolution -s . --project-name test

# Mixed tar + regular images
# → Warning printed, flag auto-enabled for all
cx scan create --container-images "nginx:latest,alpine.tar,ubuntu:20.04" -s . --project-name test

Test Coverage

Added comprehensive test coverage:

• ✅ 17 test cases in TestIsTarFileReference covering all tar file detection scenarios
• ✅ 11 test cases in TestEnforceLocalResolutionForTarFiles validating flag enforcement
• ✅ 4 integration test cases in TestEnforceLocalResolutionForTarFiles_Integration verifying end-to-end behavior

All tests passing ✅

[cx-shaked-karta]

🚀 Latest Updates - Complete OCI Directory Support & Advanced Image Processing

✨ Major New Features

1. Full OCI Directory Support (Skopeo Integration)

• ✅ Tag extraction from index.json - Automatically reads org.opencontainers.image.ref.name annotation
• ✅ Nested path support - Handles paths like docker.io/library/alpine
• ✅ No explicit tag required - Tags embedded in OCI metadata, not CLI input
• ✅ Multiple manifest handling - Uses first manifest's tag annotation
• ✅ Comprehensive error handling - Skips images missing tag annotations with clear warnings

Example Usage:

# Create OCI directory with Skopeo
skopeo copy --override-arch amd64 docker://alpine:latest oci:docker.io/library/alpine:latest

# Scan with CxOne CLI (no tag in CLI command)
cx scan create --container-images "oci-dir:docker.io/library/alpine" --containers-local-resolution

2. Zero-Package Image Filtering

• ✅ Automatic exclusion - Images with 0 packages automatically skipped
• ✅ Clear warnings - Logs: "Image X has 0 packages, skipping from containers-resolution.json"
• ✅ Corruption detection - Failed tar extractions excluded from results
• 🎯 Benefit: Only images with analyzable content included in scan results

3. Enhanced Tar File Handling

• ✅ Prefix stripping - Correctly strips file:, docker-archive:, oci-archive: before file operations
• ✅ Metadata extraction - Reads manifest.json from tar files for accurate image name/tag
• ✅ Improved logging - Better visibility into tar file processing
• ✅ Error resilience - Graceful handling of corrupted or invalid tar files

4. Automatic Local Resolution for Tar Files

• ✅ Smart detection - Automatically identifies tar files in --container-images
• ✅ Auto-enable flag - Sets --containers-local-resolution when tar files detected
• ✅ User warning - Clear message: "Warning: Tar file(s) detected in --container-images. Automatically enabling --containers-local-resolution flag."
• ✅ No duplicate warnings - Silent if flag already set

---

🏗️ Architecture Improvements

Cross-Project Changes

ast-cli (internal/commands/scan.go):

• Prefix validation with consistent constants
• OCI directory path validation
• Tar file auto-detection
• Passes prefixed images directly to Syft (no stripping)

containers-resolver (pkg/containerResolver/containerScanner.go):

• Orchestrates image analysis across projects
• Platform-specific analysis (linux/amd64)
• Result aggregation and filtering

containers-syft-packages-extractor (pkg/syftPackagesExtractor/utils.go):

• Scheme source extraction for stereoscope compatibility
• OCI directory metadata extraction
• Tar file metadata extraction
• Zero-package filtering
• Conditional platform logging

---

🧪 Comprehensive Test Coverage

New Tests Added

containers-syft-packages-extractor:

• ✅ TestExtractImageNameAndTagFromOCIDir (6 test cases)

  • Valid OCI dir with tag annotation
  • Multiple manifests handling
  • Nested path extraction
  • Missing annotation error handling
  • Empty manifests error handling
  • Invalid JSON error handling

• ✅ TestIsTaggedImageFormat (11 test cases)

  • Standard images with tags
  • Daemon prefixes (docker, podman, containerd, registry)
  • Archive prefixes (oci-dir, oci-archive, docker-archive, file)
  • Tar files and images without tags

ast-cli:

• ✅ 5 OCI-dir validation test cases in TestValidateContainerImageFormat_Comprehensive
• ✅ 17 test cases in TestIsTarFileReference
• ✅ 11 test cases in TestEnforceLocalResolutionForTarFiles
• ✅ 4 integration test cases in TestEnforceLocalResolutionForTarFiles_Integration

All tests passing: ✅ 100% pass rate

---

📊 Processing Flow

User Input → CLI Validation → Normalization → Resolver → Syft Analysis → SBOM → Transform → Filter (0-pkg) → Save
   (CLI)      (scan.go)        (scan.go)      (resolver)  (syft-extractor)  (SBOM)  (utils.go)    (skip)      (JSON)

---

📝 Documentation Updates

• ✅ Confluence page updated - Complete technical documentation with flow diagrams
• ✅ Docker Save vs Skopeo OCI comparison table - Feature-by-feature comparison
• ✅ Skopeo best practices - Step-by-step guides for all scenarios
• ✅ Troubleshooting section - Common issues and solutions

📖 Documentation: Container Images Flag Validation Logic

---

🔧 Bug Fixes

1. ✅ Fixed magic number linting - Replaced hardcoded 2 with minPartsForTaggedImage constant
2. ✅ Fixed OCI-dir validation - Now allows directories without explicit tags
3. ✅ Fixed prefix stripping - Correct handling across all image formats
4. ✅ Fixed tar file paths - Proper prefix removal for file operations
5. ✅ Fixed zero-package handling - Empty images no longer included in results

---

✅ Validation Examples

Valid Inputs:

# Standard images
--container-images "nginx:latest,alpine:3.18"

# OCI directories (tag from index.json)
--container-images "oci-dir:docker.io/library/alpine"
--container-images "oci-dir:./my-alpine-image"

# Tar files (with auto local-resolution)
--container-images "alpine.tar"
--container-images "file:./images/nginx.tar"
--container-images "docker-archive:saved-image.tar"

# Daemon sources
--container-images "docker:nginx:latest,podman:alpine:3.18"

# Mixed formats
--container-images "nginx:latest,oci-dir:./alpine,file:ubuntu.tar"

Invalid Inputs (with helpful errors):

# Missing tag
--container-images "nginx"
# ❌ Error: image does not have a tag

# OCI dir without tag annotation
--container-images "oci-dir:path/to/oci-dir"
# ⚠️ Warning: no image tag found in OCI index.json annotations (image skipped)

# Compressed tar
--container-images "image.tar.gz"
# ❌ Error: file is compressed, use non-compressed format (tar)

# OCI dir with explicit tag (NOT SUPPORTED)
--container-images "oci-dir:./my-image:latest"
# ❌ Will fail - tags must be in index.json, not CLI command

---

📈 Stats

• +1,007 lines added
• -51 lines removed
• 5 files changed
• 22 commits (latest: 0419c02)
• 40+ test cases covering all scenarios
• 0 linting errors

---

🔗 Related Links

• Jira: AST-108903
• Documentation: Container Images Flag Validation Logic
• Dependency: containers-syft-packages-extractor v1.0.19
• Dependency: containers-resolver v1.0.23

---

Ready for review! ✅ All tests passing, documentation complete, zero linting issues.

[cx-anurag-dalke]

ok

[cx-anurag-dalke]

ok

[cx-anurag-dalke]

ok