Add Platform Support for Docker Image Downloads #191

stescobedo92 · 2026-01-08T16:42:57Z

Description

This PR implements the ability to specify a target platform when downloading Docker images. Previously, images were downloaded for ARM64 architecture by default based on the server's architecture. Now users can explicitly request images for specific platforms like linux/amd64, linux/arm64, etc.

Usage

# Download for linux/amd64
curl "https://dockerimagesave.akiel.dev/image?name=alpine:latest&platform=linux/amd64"

# URL-encoded format also supported
curl "https://dockerimagesave.akiel.dev/image?name=alpine:latest&platform=linux%2Famd64"

# Download for ARM64
curl "https://dockerimagesave.akiel.dev/image?name=alpine:latest&platform=linux/arm64"

Changes by File

`registry.go`

Added new types and functions for platform support:

// New Platform struct
type Platform struct {
    OS           string
    Architecture string
}

// Helper functions
func DefaultPlatform() Platform           // Returns linux/amd64
func ParsePlatform(platform string) Platform
func (p Platform) String() string         // Returns "os/architecture"

Modified ImageReference struct:

type ImageReference struct {
    Registry   string
    Repository string
    Tag        string
    Platform   Platform  // NEW FIELD
}

Modified ParseImageReference():

Now initializes Platform field with default value (linux/amd64)

Modified selectManifestDigest():

Changed from hardcoded linux/amd64 preference to using ref.Platform
Improved error messages showing available platforms when requested platform is not found

`image.go`

Modified DownloadImage() signature:

// Before
func DownloadImage(imageRef string, outputDir string) (string, error)

// After
func DownloadImage(imageRef string, outputDir string, platform string) (string, error)

Modified createOutputTar():

Filename now includes platform: {image}_{tag}_{os}_{arch}.tar.gz
Example: library_alpine_latest_linux_amd64.tar.gz

`server.go`

Modified imageHandler():

Added parsing of platform query parameter
Added platform validation with validatePlatform()
Normalizes empty platform to linux/amd64 to ensure consistent cache keys and proper deduplication of concurrent requests
Updated cache key to include platform (prevents cache conflicts between platforms)
Improved logging to show platform being downloaded

Added validatePlatform() function:

Validates OS: linux, windows, darwin
Validates architectures: amd64, arm64, arm, 386, ppc64le, s390x, riscv64
Returns descriptive error messages

Added security functions to prevent path traversal (CodeQL fix):

sanitizePathComponent() - Removes dangerous characters (/, \, ..) from path components
validatePathContainment() - Ensures generated paths stay within the expected directory
sanitizePlatform() - Returns sanitized platform reconstructed from validated whitelist values

Modified getCacheFilename():

// Before
func (s *Server) getCacheFilename(imageName string) string

// After  
func (s *Server) getCacheFilename(imageName string, platform string) string

Modified serveImageFile():

Added platform parameter to generate correct filename

`main.go`

Fixed config file handling:

Config file is now optional (no longer crashes if config.yaml doesn't exist)
Falls back to defaults (port 8080) when no config is provided
Auto-detects config.yaml if present in current directory

New Unit Tests

`registry_test.go`

Test	Description
`TestParsePlatform`	Tests parsing of platform strings (valid, empty, invalid)
`TestPlatformString`	Tests `Platform.String()` serialization
`TestDefaultPlatform`	Verifies default platform is `linux/amd64`
`TestParseImageReference_IncludesPlatform`	Verifies ImageReference includes platform

`server_test.go`

Test	Description
`TestImageHandler_WithPlatform`	Integration test with platform parameter
`TestImageHandler_WithURLEncodedPlatform`	Tests URL-encoded platform (`linux%2Famd64`)
`TestImageHandler_InvalidPlatform`	Tests error handling for invalid platforms
`TestValidatePlatform`	Exhaustive validation tests (16 cases)
`TestGetCacheFilename_WithPlatform`	Tests filename generation with platform
`TestImageHandler_PlatformNormalization`	Verifies empty platform normalizes to linux/amd64
`TestSanitizePathComponent`	Tests path component sanitization (8 cases)
`TestValidatePathContainment`	Tests path containment validation (5 cases)
`TestSanitizePlatform`	Tests platform sanitization whitelist (18 cases)

`image_test.go`

Test	Description
`TestDownloadImage_WithPlatform`	Integration test downloading with platform
`TestDownloadImage_UnsupportedPlatform`	Tests error for unavailable platform
`TestCreateOutputTar_IncludesPlatformInFilename`	Verifies filename format

Testing

# Run all unit tests
go test -short -v ./...

# Run integration tests (requires network)
go test -v ./...

All 59 tests pass ✅

Security Enhancements

This PR includes security hardening to address CodeQL's "Uncontrolled data used in path expression" warning:

Path Traversal Protection

sanitizePathComponent(component string) - Removes dangerous characters:
- Path separators (/, \)
- Parent directory sequences (..)
- Leading dots (.hidden)
sanitizeForPath(s string) - Cleans strings for safe path usage:
- Replaces : with -
- Replaces / with _
- Removes \ and other unsafe characters
validatePathContainment(basePath, targetPath string) - Ensures paths stay within bounds:
- Resolves both paths to absolute form
- Verifies target is under base directory
- Returns error if path escapes containment
sanitizePlatform(platform string) - Reconstructs platform from validated values:
- Only allows whitelisted OS values: linux, windows, darwin
- Only allows whitelisted architectures: amd64, arm64, arm, 386, ppc64le, s390x, riscv64
- Reconstructs string from validated parts (never uses raw user input in paths)

Defense in Depth

Even though platform values are validated against a whitelist, we apply multiple layers of protection:

Validation first: validatePlatform() rejects invalid platforms with 400 error
Sanitization: sanitizePlatform() reconstructs from whitelist values only
Path containment: validatePathContainment() verifies final path stays within expected directory

Checklist

… default

Copilot

Pull request overview

This PR adds platform-specific Docker image download support, allowing users to explicitly request images for specific OS/architecture combinations (e.g., linux/amd64, linux/arm64) via a new platform query parameter. Previously, images defaulted to the server's architecture.

Key changes:

Added Platform struct and related functions (ParsePlatform, DefaultPlatform) to handle platform specification
Modified image download flow to accept and use platform parameter throughout the stack
Updated cache filename format to include platform information to prevent conflicts
Enhanced error messages to show available platforms when requested platform is unavailable

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
registry.go	Adds Platform struct with parsing/serialization functions; updates ImageReference to include Platform field; modifies manifest selection to use requested platform instead of hardcoded linux/amd64
server.go	Adds platform query parameter parsing and validation; updates cache key generation to include platform; modifies all image serving functions to accept platform parameter
image.go	Updates DownloadImage signature to accept platform parameter; modifies output filename format to include platform information
main.go	Improves config file handling to make it optional with automatic detection of config.yaml
registry_test.go	Adds comprehensive tests for Platform parsing, serialization, and default values
server_test.go	Adds tests for platform parameter handling, validation, URL encoding, and cache filename generation
image_test.go	Adds integration tests for downloading with different platforms and handling unsupported platforms

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

server.go

image_test.go

…ate downloads

…re correct format for filename suffix

server.go

+		platform = DefaultPlatform().String()
+	}
+
+	// Create a unique cache key combining image name and platform


server.go

 	safeImageName := strings.ReplaceAll(ref.Repository, "/", "_")
-	return fmt.Sprintf("%s_%s.tar.gz", safeImageName, ref.Tag)
+	safePlatform := strings.ReplaceAll(ref.Platform.String(), "/", "_")
+	return fmt.Sprintf("%s_%s_%s.tar.gz", safeImageName, ref.Tag, safePlatform)


…traversal attacks

… prevent path traversal vulnerabilities

…vulnerabilities

jadolg · 2026-01-08T20:58:35Z

Please document how to download images in the README (using wget) and (optional) update the website so users can download images without curl/wget

jadolg

I'm ok with using AI. Most of this new code is AI generated. But please review before requesting changes.

main.go

README.md

image.go

index.html

server.go

…ate README notes.

…mproved error parsing.

…and directly sanitizing image repository names.

…placement for filename generation.

…parators with underscores.

jadolg · 2026-01-30T11:05:09Z

Mind fixing the problems found by CodeQL?
https://github.com/jadolg/DockerImageSave/pull/191/checks?check_run_id=60988930014

stescobedo92 added 4 commits January 8, 2026 10:37

Add multi-platform support to image handling and validation

24ba68b

Add platform support to DownloadImage and createOutputTar functions

650f279

Add platform support and related tests for image handling

5ebe13a

Refactor config loading to allow optional config path and fallback to…

01db961

… default

Copilot AI review requested due to automatic review settings January 8, 2026 16:42

Copilot started reviewing on behalf of stescobedo92 January 8, 2026 16:43 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

server.go Show resolved Hide resolved

server.go Show resolved Hide resolved

image_test.go Outdated Show resolved Hide resolved

stescobedo92 added 2 commits January 8, 2026 11:08

Normalize empty platform to default in imageHandler to prevent duplic…

439df9c

…ate downloads

Enhance platform validation in TestDownloadImage_WithPlatform to ensu…

1dc9f7a

…re correct format for filename suffix

github-advanced-security bot found potential problems Jan 8, 2026

View reviewed changes

stescobedo92 added 3 commits January 8, 2026 11:25

Sanitize and validate platform input in imageHandler to prevent path …

1af2318

…traversal attacks

Enhance output path validation and sanitization in createOutputTar to…

49f9ea9

… prevent path traversal vulnerabilities

Implement path validation and sanitization to prevent path traversal …

5da6699

…vulnerabilities

stescobedo92 mentioned this pull request Jan 8, 2026

Add support for different architecture #158

Open

jadolg self-requested a review January 8, 2026 20:42

Update README to enhance download instructions and add platform support

225cfc4

jadolg reviewed Jan 15, 2026

View reviewed changes

jadolg self-assigned this Jan 15, 2026

stescobedo92 and others added 6 commits January 20, 2026 21:43

refactor: simplify config loading to require an explicit path and upd…

fc0abba

…ate README notes.

feat: Implement Docker image platform selection with UI updates and i…

5587ab9

…mproved error parsing.

refactor: simplify filename generation by removing sanitizeForPath …

2a9bb13

…and directly sanitizing image repository names.

refactor: remove sanitizePathComponent and inline path separator re…

477ebe9

…placement for filename generation.

fix: Sanitize platform string in image filenames by replacing path se…

e1b92ac

…parators with underscores.

Merge branch 'master' into feature/158-multi-platform-support

4a2208b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Platform Support for Docker Image Downloads #191

Add Platform Support for Docker Image Downloads #191

Uh oh!

stescobedo92 commented Jan 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check failure

Check failure

jadolg commented Jan 8, 2026

Uh oh!

jadolg left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jadolg commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Add Platform Support for Docker Image Downloads #191

Are you sure you want to change the base?

Add Platform Support for Docker Image Downloads #191

Uh oh!

Conversation

stescobedo92 commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Usage

Changes by File

registry.go

image.go

server.go

main.go

New Unit Tests

registry_test.go

server_test.go

image_test.go

Testing

Security Enhancements

Path Traversal Protection

Defense in Depth

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check failure

Uh oh!

Check failure

Uh oh!

jadolg commented Jan 8, 2026

Uh oh!

jadolg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jadolg commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stescobedo92 commented Jan 8, 2026 •

edited

Loading

`registry.go`

`image.go`

`server.go`

`main.go`

`registry_test.go`

`server_test.go`

`image_test.go`