path.go RawHistoryFolder
1// Package validation provides input validation functions for security-critical operations.
2// These functions implement defense-in-depth against path traversal and injection attacks.
3package validation
4
5import (
6 "fmt"
7 "path/filepath"
8 "regexp"
9 "strings"
10)
11
12// Repository name validation per Docker spec:
13// - Lowercase letters, digits, and separators (., _, -)
14// - Separators must not be adjacent and cannot start/end the name
15// - Allows nested paths like "myorg/myapp"
16var repoNameRegex = regexp.MustCompile(`^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$`)
17
18// Reference (tag) validation per Docker spec:
19// - Case-sensitive alphanumeric (both uppercase and lowercase allowed)
20// - Dots, underscores, and hyphens allowed after first character
21// - Must start with an alphanumeric character
22// - Max 128 characters
23var referenceRegex = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$`)
24
25// Digest validation for content-addressable storage:
26// - Format: algorithm:hex
27// - Supported algorithms: sha256 (64 hex chars), sha512 (128 hex chars)
28var digestRegex = regexp.MustCompile(`^(sha256:[a-f0-9]{64}|sha512:[a-f0-9]{128})$`)
29
30// UUID validation for blob uploads:
31// - Format: standard UUID v4 (e.g., 550e8400-e29b-41d4-a716-446655440000)
32var uuidRegex = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
33
34// MaxRepositoryNameLength is the maximum allowed length for repository names.
35const MaxRepositoryNameLength = 256
36
37// ValidateRepositoryName validates a Docker repository name.
38// Returns an error if the name is invalid or could enable path traversal.
39func ValidateRepositoryName(name string) error {
40 if name == "" {
41 return fmt.Errorf("repository name cannot be empty")
42 }
43
44 if len(name) > MaxRepositoryNameLength {
45 return fmt.Errorf("repository name too long: %d chars (max %d)", len(name), MaxRepositoryNameLength)
46 }
47
48 // Check for path traversal attempts
49 if strings.Contains(name, "..") {
50 return fmt.Errorf("repository name contains path traversal sequence")
51 }
52
53 // Validate format
54 if !repoNameRegex.MatchString(name) {
55 return fmt.Errorf("invalid repository name format: must contain only lowercase letters, digits, and separators (., _, -)")
56 }
57
58 return nil
59}
60
61// ValidateReference validates a Docker tag or reference.
62// Also accepts digest format for manifest references by digest.
63func ValidateReference(reference string) error {
64 if reference == "" {
65 return fmt.Errorf("reference cannot be empty")
66 }
67
68 // Check for path traversal attempts
69 if strings.Contains(reference, "..") {
70 return fmt.Errorf("reference contains path traversal sequence")
71 }
72
73 // Allow digest format (sha256:... or sha512:...)
74 if digestRegex.MatchString(reference) {
75 return nil
76 }
77
78 // Validate tag format
79 if !referenceRegex.MatchString(reference) {
80 return fmt.Errorf("invalid reference format: must be a valid tag or digest")
81 }
82
83 return nil
84}
85
86// ValidateDigest validates a Docker content digest.
87// Format must be algorithm:hex where algorithm is sha256 or sha512.
88func ValidateDigest(digest string) error {
89 if digest == "" {
90 return fmt.Errorf("digest cannot be empty")
91 }
92
93 // Check for path traversal attempts
94 if strings.Contains(digest, "..") {
95 return fmt.Errorf("digest contains path traversal sequence")
96 }
97
98 if !digestRegex.MatchString(digest) {
99 return fmt.Errorf("invalid digest format: must be sha256:<64 hex chars> or sha512:<128 hex chars>")
100 }
101
102 return nil
103}
104
105// IsDigest checks if a string is a valid Docker content digest.
106// Returns true if the string is a valid digest format.
107func IsDigest(digest string) bool {
108 return ValidateDigest(digest) == nil
109}
110
111// ValidateUUID validates a blob upload UUID.
112// UUIDs are server-generated but still validated for safety.
113func ValidateUUID(uuid string) error {
114 if uuid == "" {
115 return fmt.Errorf("UUID cannot be empty")
116 }
117
118 // Check for path traversal attempts
119 if strings.Contains(uuid, "..") {
120 return fmt.Errorf("UUID contains path traversal sequence")
121 }
122
123 if !uuidRegex.MatchString(uuid) {
124 return fmt.Errorf("invalid UUID format")
125 }
126
127 return nil
128}
129
130// ValidatePath sanitizes and validates a path component to prevent traversal attacks.
131// Returns the cleaned path or an error if the path is unsafe.
132func ValidatePath(path string) (string, error) {
133 if path == "" {
134 return "", fmt.Errorf("path cannot be empty")
135 }
136
137 // Clean the path to normalize it
138 cleanPath := filepath.Clean(path)
139
140 // Check for path traversal after cleaning
141 if strings.Contains(cleanPath, "..") {
142 return "", fmt.Errorf("path traversal not allowed")
143 }
144
145 // Reject absolute paths
146 if filepath.IsAbs(cleanPath) {
147 return "", fmt.Errorf("absolute paths not allowed")
148 }
149
150 return cleanPath, nil
151}
152
153// ValidatePathWithinRoot validates that a constructed path stays within the root directory.
154// This provides defense-in-depth after filepath.Join operations.
155func ValidatePathWithinRoot(rootDir, fullPath string) error {
156 cleanRoot := filepath.Clean(rootDir)
157 cleanPath := filepath.Clean(fullPath)
158
159 // Ensure the path starts with the root directory
160 if !strings.HasPrefix(cleanPath, cleanRoot+string(filepath.Separator)) && cleanPath != cleanRoot {
161 return fmt.Errorf("path escapes root directory")
162 }
163
164 return nil
165}