update main packages in embeddings examples

Author: slimslenderslacks

examples/embeddings/README.md

@@ -10,7 +10,7 @@ Downloads the embeddings OCI artifact and installs the vector.db directory to `~
 
 ```bash
 # From repository root
-go run ./examples/embeddings/pull.go
+go run ./examples/embeddings/pull/main.go
 ```
 
 The Pull function will:
@@ -28,14 +28,14 @@ Creates an OCI artifact from a local vector.db directory and pushes it to a regi
 
 ```bash
 # From repository root
-go run ./examples/embeddings/push.go <vector-db-path> <oci-ref>
+go run ./examples/embeddings/push/main.go <vector-db-path> <oci-ref>
 ```
 
 ### Example
 
 ```bash
 # Push the local vectors.db to your own registry
-go run ./examples/embeddings/push.go ~/.docker/mcp/vectors.db jimclark106/embeddings:v1.0
+go run ./examples/embeddings/push/main.go ~/.docker/mcp/vectors.db jimclark106/embeddings:v1.0
 ```
 
 The Push function will:

examples/embeddings/pull.go renamed to examples/embeddings/pull/main.go

@@ -130,18 +130,27 @@ func extractLayer(layer interface{ Uncompressed() (io.ReadCloser, error) }, dest
 		}
 
 		target := filepath.Join(destDir, header.Name)
-		// Clean the path to resolve any ".." elements and ensure it's within destDir
-		cleanedTarget := filepath.Clean(target)
+
+		// Resolve any previously-extracted symbolic links in the target path
+		// This prevents symlink chaining attacks where a symlink could be used
+		// to escape the destination directory
+		resolvedTarget, err := filepath.EvalSymlinks(target)
+		if err != nil {
+			// If EvalSymlinks fails (e.g., path doesn't exist yet), fall back to Clean
+			// This is expected for new files/dirs that haven't been created yet
+			resolvedTarget = filepath.Clean(target)
+		}
+
 		cleanedDestDir := filepath.Clean(destDir)
 
-		// Use filepath.Rel to check if target is within destDir
+		// Use filepath.Rel to check if resolved target is within destDir
 		// If the relative path starts with "..", it's trying to escape
-		relPath, err := filepath.Rel(cleanedDestDir, cleanedTarget)
+		relPath, err := filepath.Rel(cleanedDestDir, resolvedTarget)
 		if err != nil || len(relPath) == 0 || (relPath[0] == '.' && len(relPath) > 1 && relPath[1] == '.') {
 			return fmt.Errorf("invalid tar entry path (potential path traversal): %s", header.Name)
 		}
 
-		target = cleanedTarget
+		target = filepath.Clean(target)
 
 		switch header.Typeflag {
 		case tar.TypeDir:
@@ -167,7 +176,30 @@ func extractLayer(layer interface{ Uncompressed() (io.ReadCloser, error) }, dest
 			file.Close()
 
 		case tar.TypeSymlink:
-			// Handle symlinks
+			// Handle symlinks - validate the link target to prevent symlink attacks
+			// Reject absolute symlink targets
+			if filepath.IsAbs(header.Linkname) {
+				return fmt.Errorf("invalid symlink target (absolute path not allowed): %s -> %s", header.Name, header.Linkname)
+			}
+
+			// Calculate where the symlink target would resolve to
+			// The symlink is created at 'target', and points to 'header.Linkname'
+			linkTargetPath := filepath.Join(filepath.Dir(target), header.Linkname)
+
+			// Resolve any previously-extracted symbolic links in the target path
+			// This prevents symlink chaining attacks
+			resolvedLinkTarget, err := filepath.EvalSymlinks(linkTargetPath)
+			if err != nil {
+				// If EvalSymlinks fails, fall back to Clean (target doesn't exist yet)
+				resolvedLinkTarget = filepath.Clean(linkTargetPath)
+			}
+
+			// Ensure the symlink target is within the destination directory
+			relLinkPath, err := filepath.Rel(cleanedDestDir, resolvedLinkTarget)
+			if err != nil || len(relLinkPath) == 0 || (relLinkPath[0] == '.' && len(relLinkPath) > 1 && relLinkPath[1] == '.') {
+				return fmt.Errorf("invalid symlink target (potential path traversal): %s -> %s", header.Name, header.Linkname)
+			}
+
 			if err := os.Symlink(header.Linkname, target); err != nil {
 				return fmt.Errorf("failed to create symlink: %w", err)
 			}

examples/embeddings/push.go renamed to examples/embeddings/push/main.go

@@ -4,7 +4,6 @@ import (
 	"archive/tar"
 	"bytes"
 	"io"
-	"os"
 	"path/filepath"
 	"testing"
 )
@@ -145,45 +144,137 @@ func (m *mockLayer) Uncompressed() (io.ReadCloser, error) {
 
 // TestExtractLayerSymlinkSafety tests that symlinks are handled safely
 func TestExtractLayerSymlinkSafety(t *testing.T) {
+	tests := []struct {
+		name        string
+		symlinkName string
+		symlinkDest string
+		shouldError bool
+		description string
+	}{
+		{
+			name:        "legitimate relative symlink",
+			symlinkName: "vectors.db/link",
+			symlinkDest: "data.db",
+			shouldError: false,
+			description: "should allow relative symlinks within destination",
+		},
+		{
+			name:        "absolute symlink target",
+			symlinkName: "vectors.db/link",
+			symlinkDest: "/etc/passwd",
+			shouldError: true,
+			description: "should reject absolute symlink targets",
+		},
+		{
+			name:        "symlink escaping with ..",
+			symlinkName: "vectors.db/link",
+			symlinkDest: "../../etc/passwd",
+			shouldError: true,
+			description: "should reject symlinks that escape destination directory",
+		},
+		{
+			name:        "symlink to parent that stays within",
+			symlinkName: "vectors.db/subdir/link",
+			symlinkDest: "../data.db",
+			shouldError: false,
+			description: "should allow .. if it resolves within destination",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			destDir := t.TempDir()
+
+			// Create a tar with a directory and a symlink
+			var buf bytes.Buffer
+			tw := tar.NewWriter(&buf)
+
+			// Add the parent directory first
+			dirHeader := &tar.Header{
+				Name:     "vectors.db/",
+				Mode:     0o755,
+				Typeflag: tar.TypeDir,
+			}
+			if err := tw.WriteHeader(dirHeader); err != nil {
+				t.Fatalf("failed to write directory header: %v", err)
+			}
+
+			// Add subdirectory if needed
+			if filepath.Dir(tt.symlinkName) != "vectors.db" {
+				subdirHeader := &tar.Header{
+					Name:     filepath.Dir(tt.symlinkName) + "/",
+					Mode:     0o755,
+					Typeflag: tar.TypeDir,
+				}
+				if err := tw.WriteHeader(subdirHeader); err != nil {
+					t.Fatalf("failed to write subdirectory header: %v", err)
+				}
+			}
+
+			// Add the symlink
+			header := &tar.Header{
+				Name:     tt.symlinkName,
+				Linkname: tt.symlinkDest,
+				Typeflag: tar.TypeSymlink,
+			}
+			if err := tw.WriteHeader(header); err != nil {
+				t.Fatalf("failed to write symlink header: %v", err)
+			}
+
+			tw.Close()
+
+			layer := &mockLayer{data: buf.Bytes()}
+
+			// Extract and check result
+			err := extractLayer(layer, destDir)
+
+			if tt.shouldError {
+				if err == nil {
+					t.Errorf("%s: expected error but got none", tt.description)
+				}
+			} else {
+				if err != nil {
+					t.Errorf("%s: unexpected error: %v", tt.description, err)
+				}
+			}
+		})
+	}
+}
+
+// TestExtractLayerSymlinkChaining tests protection against symlink chaining attacks
+func TestExtractLayerSymlinkChaining(t *testing.T) {
 	destDir := t.TempDir()
 
-	// Create a tar with a directory and a symlink
+	// Create a malicious tar with symlink chaining:
+	// 1. vectors.db/link -> .. (points outside destDir to parent directory)
+	// 2. vectors.db/escape -> link/.. (chains through the symlink to escape further)
 	var buf bytes.Buffer
 	tw := tar.NewWriter(&buf)
 
-	// Add the parent directory first
-	dirHeader := &tar.Header{
-		Name:     "vectors.db/",
-		Mode:     0o755,
-		Typeflag: tar.TypeDir,
-	}
-	if err := tw.WriteHeader(dirHeader); err != nil {
-		t.Fatalf("failed to write directory header: %v", err)
+	// Add directory
+	if err := tw.WriteHeader(&tar.Header{Name: "vectors.db/", Mode: 0o755, Typeflag: tar.TypeDir}); err != nil {
+		t.Fatalf("failed to write header: %v", err)
 	}
 
-	// Add a symlink
-	header := &tar.Header{
+	// Add first symlink that points outside: vectors.db/link -> ../..
+	// This creates: destDir/vectors.db/link -> ../.. which resolves to parent of destDir
+	if err := tw.WriteHeader(&tar.Header{
 		Name:     "vectors.db/link",
-		Linkname: "/etc/passwd",
+		Linkname: "../..",
 		Typeflag: tar.TypeSymlink,
-	}
-	if err := tw.WriteHeader(header); err != nil {
+	}); err != nil {
 		t.Fatalf("failed to write symlink header: %v", err)
 	}
 
 	tw.Close()
 
 	layer := &mockLayer{data: buf.Bytes()}
 
-	// Extract should succeed (we extract the symlink but validate the path)
+	// This should fail because the symlink escapes the destination directory
 	err := extractLayer(layer, destDir)
-	if err != nil {
-		t.Errorf("unexpected error extracting symlink: %v", err)
-	}
-
-	// Verify the symlink was created in the destination
-	linkPath := filepath.Join(destDir, "vectors.db", "link")
-	if _, err := os.Lstat(linkPath); err != nil {
-		t.Errorf("symlink was not created: %v", err)
+	if err == nil {
+		t.Error("Expected error for symlink chaining attack, but extraction succeeded")
+	} else {
+		t.Logf("Symlink chaining attack correctly blocked: %v", err)
 	}
 }

pkg/gateway/embeddings/oci.go

@@ -32,7 +32,7 @@ func keywordStrategy(configuration Configuration) mcp.ToolHandler {
 	return func(_ context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		// Parse parameters
 		var params struct {
-			Prompt string `json:"prompt"`
+			Query string `json:"query"`
 			Limit  int    `json:"limit"`
 		}
 
@@ -49,7 +49,7 @@ func keywordStrategy(configuration Configuration) mcp.ToolHandler {
 			return nil, fmt.Errorf("failed to parse arguments: %w", err)
 		}
 
-		if params.Prompt == "" {
+		if params.Query == "" {
 			return nil, fmt.Errorf("query parameter is required")
 		}
 
@@ -58,7 +58,7 @@ func keywordStrategy(configuration Configuration) mcp.ToolHandler {
 		}
 
 		// Search through the catalog servers
-		query := strings.ToLower(strings.TrimSpace(params.Prompt))
+		query := strings.ToLower(strings.TrimSpace(params.Query))
 		var matches []ServerMatch
 
 		for serverName, server := range configuration.servers {
@@ -177,7 +177,7 @@ func keywordStrategy(configuration Configuration) mcp.ToolHandler {
 		}
 
 		response := map[string]any{
-			"prompt":        params.Prompt,
+			"prompt":        params.Query,
 			"total_matches": len(results),
 			"servers":       results,
 		}
@@ -197,7 +197,7 @@ func embeddingStrategy(g *Gateway) mcp.ToolHandler {
 	return func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		// Parse parameters
 		var params struct {
-			Prompt string `json:"prompt"`
+			Query string `json:"query"`
 			Limit  int    `json:"limit"`
 		}
 
@@ -214,7 +214,7 @@ func embeddingStrategy(g *Gateway) mcp.ToolHandler {
 			return nil, fmt.Errorf("failed to parse arguments: %w", err)
 		}
 
-		if params.Prompt == "" {
+		if params.Query == "" {
 			return nil, fmt.Errorf("query parameter is required")
 		}
 
@@ -223,13 +223,13 @@ func embeddingStrategy(g *Gateway) mcp.ToolHandler {
 		}
 
 		// Use vector similarity search to find relevant servers
-		results, err := g.findServersByEmbedding(ctx, params.Prompt, params.Limit)
+		results, err := g.findServersByEmbedding(ctx, params.Query, params.Limit)
 		if err != nil {
 			return nil, fmt.Errorf("failed to find servers: %w", err)
 		}
 
 		response := map[string]any{
-			"prompt":        params.Prompt,
+			"prompt":        params.Query,
 			"total_matches": len(results),
 			"servers":       results,
 		}

pkg/gateway/embeddings/oci_test.go

@@ -16,6 +16,8 @@ import (
 )
 
 // readServersFromURL fetches and parses server definitions from a URL
+//
+//nolint:unused // TODO: This function will be used when registry import feature is enabled
 func (g *Gateway) readServersFromURL(ctx context.Context, url string) (map[string]catalog.Server, error) {
 	servers := make(map[string]catalog.Server)
 
@@ -63,6 +65,7 @@ func (g *Gateway) readServersFromURL(ctx context.Context, url string) (map[strin
 	return nil, fmt.Errorf("unable to parse response as OCI catalog or direct catalog format")
 }
 
+//nolint:unused // TODO: This handler will be used when registry import feature is enabled
 func registryImportHandler(g *Gateway, configuration Configuration) mcp.ToolHandler {
 	return func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		// Parse parameters