Implement .thvignore-driven bind mount filtering with tmpfs overlays (#1137)

This PR implements a comprehensive security filtering system for MCP server containers that uses .thvignore files (similar to .gitignore) to exclude sensitive files and directories from container access while maintaining real-time bind mount functionality for development workflows.

Signed-off-by: Juan Antonio Osorio <[email protected]>
Co-authored-by: Don Browne <[email protected]>
Co-authored-by: amirejaz <[email protected]>

Author: 3 people

cmd/thv/app/run_flags.go

@@ -73,6 +73,10 @@ type RunFlags struct {
 
 	// Configuration import
 	FromConfig string
+
+	// Ignore functionality
+	IgnoreGlobally bool
+	PrintOverlays  bool
 }
 
 // AddRunFlags adds all the run flags to a command
@@ -160,6 +164,12 @@ func AddRunFlags(cmd *cobra.Command, config *RunFlags) {
 		"Filter MCP server tools (comma-separated list of tool names)",
 	)
 	cmd.Flags().StringVar(&config.FromConfig, "from-config", "", "Load configuration from exported file")
+
+	// Ignore functionality flags
+	cmd.Flags().BoolVar(&config.IgnoreGlobally, "ignore-globally", true,
+		"Load global ignore patterns from ~/.config/toolhive/thvignore")
+	cmd.Flags().BoolVar(&config.PrintOverlays, "print-resolved-overlays", false,
+		"Debug: show resolved container paths for tmpfs overlays")
 }
 
 // BuildRunnerConfig creates a runner.RunConfig from the configuration
@@ -267,6 +277,8 @@ func BuildRunnerConfig(
 		types.ProxyMode(runConfig.ProxyMode),
 		runConfig.Group,
 		runConfig.ToolsFilter,
+		runConfig.IgnoreGlobally,
+		runConfig.PrintOverlays,
 	)
 }
 

docs/cli/thv_run.md

@@ -26,6 +26,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/container/docker/sdk"
 	"github.com/stacklok/toolhive/pkg/container/images"
 	"github.com/stacklok/toolhive/pkg/container/runtime"
+	"github.com/stacklok/toolhive/pkg/ignore"
 	lb "github.com/stacklok/toolhive/pkg/labels"
 	"github.com/stacklok/toolhive/pkg/logger"
 	"github.com/stacklok/toolhive/pkg/networking"
@@ -83,12 +84,21 @@ func convertEnvVars(envVars map[string]string) []string {
 func convertMounts(mounts []runtime.Mount) []mount.Mount {
 	result := make([]mount.Mount, 0, len(mounts))
 	for _, m := range mounts {
-		result = append(result, mount.Mount{
-			Type:     mount.TypeBind,
-			Source:   m.Source,
-			Target:   m.Target,
-			ReadOnly: m.ReadOnly,
-		})
+		if m.Type == runtime.MountTypeTmpfs {
+			// Create tmpfs mount to mask/hide sensitive directories
+			result = append(result, mount.Mount{
+				Type:   mount.TypeTmpfs,
+				Target: m.Target,
+				// No TmpfsOptions needed - default size is sufficient for masking
+			})
+		} else {
+			result = append(result, mount.Mount{
+				Type:     mount.TypeBind,
+				Source:   m.Source,
+				Target:   m.Target,
+				ReadOnly: m.ReadOnly,
+			})
+		}
 	}
 	return result
 }
@@ -432,6 +442,8 @@ func generatePortBindings(labels map[string]string,
 // DeployWorkload creates and starts a workload.
 // It configures the workload based on the provided permission profile and transport type.
 // If options is nil, default options will be used.
+//
+//nolint:gocyclo // This function has high complexity due to comprehensive workload setup
 func (c *Client) DeployWorkload(
 	ctx context.Context,
 	image,
@@ -445,7 +457,11 @@ func (c *Client) DeployWorkload(
 	isolateNetwork bool,
 ) (string, int, error) {
 	// Get permission config from profile
-	permissionConfig, err := c.getPermissionConfigFromProfile(permissionProfile, transportType)
+	var ignoreConfig *ignore.Config
+	if options != nil {
+		ignoreConfig = options.IgnoreConfig
+	}
+	permissionConfig, err := c.getPermissionConfigFromProfile(permissionProfile, transportType, ignoreConfig)
 	if err != nil {
 		return "", 0, fmt.Errorf("failed to get permission config: %w", err)
 	}
@@ -894,7 +910,11 @@ func (c *Client) IsRunning(ctx context.Context) error {
 // getPermissionConfigFromProfile converts a permission profile to a container permission config
 // with transport-specific settings (internal function)
 // addReadOnlyMounts adds read-only mounts to the permission config
-func (*Client) addReadOnlyMounts(config *runtime.PermissionConfig, mounts []permissions.MountDeclaration) {
+func (*Client) addReadOnlyMounts(
+	config *runtime.PermissionConfig,
+	mounts []permissions.MountDeclaration,
+	ignoreConfig *ignore.Config,
+) {
 	for _, mountDecl := range mounts {
 		source, target, err := mountDecl.Parse()
 		if err != nil {
@@ -919,12 +939,20 @@ func (*Client) addReadOnlyMounts(config *runtime.PermissionConfig, mounts []perm
 			Source:   absPath,
 			Target:   target,
 			ReadOnly: true,
+			Type:     runtime.MountTypeBind,
 		})
+
+		// Process ignore patterns and add tmpfs overlays
+		addIgnoreOverlays(config, absPath, target, ignoreConfig)
 	}
 }
 
 // addReadWriteMounts adds read-write mounts to the permission config
-func (*Client) addReadWriteMounts(config *runtime.PermissionConfig, mounts []permissions.MountDeclaration) {
+func (*Client) addReadWriteMounts(
+	config *runtime.PermissionConfig,
+	mounts []permissions.MountDeclaration,
+	ignoreConfig *ignore.Config,
+) {
 	for _, mountDecl := range mounts {
 		source, target, err := mountDecl.Parse()
 		if err != nil {
@@ -962,8 +990,62 @@ func (*Client) addReadWriteMounts(config *runtime.PermissionConfig, mounts []per
 				Source:   absPath,
 				Target:   target,
 				ReadOnly: false,
+				Type:     runtime.MountTypeBind,
 			})
 		}
+
+		// Process ignore patterns and add tmpfs overlays
+		addIgnoreOverlays(config, absPath, target, ignoreConfig)
+	}
+}
+
+// addIgnoreOverlays processes ignore patterns for a mount and adds overlay mounts
+func addIgnoreOverlays(config *runtime.PermissionConfig, sourceDir, containerPath string, ignoreConfig *ignore.Config) {
+	// Skip if no ignore configuration is provided
+	if ignoreConfig == nil {
+		return
+	}
+
+	// Create ignore processor with configuration
+	ignoreProcessor := ignore.NewProcessor(ignoreConfig)
+
+	// Load global ignore patterns if enabled
+	if ignoreConfig.LoadGlobal {
+		if err := ignoreProcessor.LoadGlobal(); err != nil {
+			logger.Debugf("Failed to load global ignore patterns: %v", err)
+			// Continue without global patterns
+		}
+	}
+
+	// Load local ignore patterns from the source directory
+	if err := ignoreProcessor.LoadLocal(sourceDir); err != nil {
+		logger.Debugf("Failed to load local ignore patterns from %s: %v", sourceDir, err)
+		// Continue without local patterns
+	}
+
+	// Get overlay mounts (both tmpfs for directories and bind for files)
+	overlayMounts := ignoreProcessor.GetOverlayMounts(sourceDir, containerPath)
+
+	// Add overlay mounts to the configuration
+	for _, overlayMount := range overlayMounts {
+		var mountType runtime.MountType
+		var source string
+
+		if overlayMount.Type == "tmpfs" {
+			mountType = runtime.MountTypeTmpfs
+			source = "" // No source for tmpfs
+		} else {
+			mountType = runtime.MountTypeBind
+			source = overlayMount.HostPath
+		}
+
+		config.Mounts = append(config.Mounts, runtime.Mount{
+			Source:   source,
+			Target:   overlayMount.ContainerPath,
+			ReadOnly: false,
+			Type:     mountType,
+		})
+		logger.Debugf("Added %s overlay for ignored path: %s -> %s", overlayMount.Type, source, overlayMount.ContainerPath)
 	}
 }
 
@@ -992,6 +1074,7 @@ func convertRelativePathToAbsolute(source string, mountDecl permissions.MountDec
 func (c *Client) getPermissionConfigFromProfile(
 	profile *permissions.Profile,
 	transportType string,
+	ignoreConfig *ignore.Config,
 ) (*runtime.PermissionConfig, error) {
 	// Start with a default permission config
 	config := &runtime.PermissionConfig{
@@ -1003,8 +1086,8 @@ func (c *Client) getPermissionConfigFromProfile(
 	}
 
 	// Add mounts
-	c.addReadOnlyMounts(config, profile.Read)
-	c.addReadWriteMounts(config, profile.Write)
+	c.addReadOnlyMounts(config, profile.Read, ignoreConfig)
+	c.addReadWriteMounts(config, profile.Write, ignoreConfig)
 
 	// Validate transport type
 	switch transportType {

docs/server/docs.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"time"
 
+	"github.com/stacklok/toolhive/pkg/ignore"
 	"github.com/stacklok/toolhive/pkg/permissions"
 )
 
@@ -157,6 +158,21 @@ const (
 	TypeKubernetes Type = "kubernetes"
 )
 
+// MountType represents the type of mount
+type MountType string
+
+const (
+	// MountTypeBind represents a bind mount
+	MountTypeBind MountType = "bind"
+	// MountTypeTmpfs represents a tmpfs mount
+	MountTypeTmpfs MountType = "tmpfs"
+)
+
+// String returns the string representation of the mount type
+func (mt MountType) String() string {
+	return string(mt)
+}
+
 // PermissionConfig represents container permission configuration
 type PermissionConfig struct {
 	// Mounts is the list of volume mounts
@@ -196,6 +212,10 @@ type DeployWorkloadOptions struct {
 	// SSEHeadlessServiceName is the name of the Kubernetes service to use for the workload
 	// Only applicable when using Kubernetes runtime and SSE transport
 	SSEHeadlessServiceName string
+
+	// IgnoreConfig contains configuration for ignore patterns and tmpfs overlays
+	// Used to filter bind mount contents by hiding sensitive files
+	IgnoreConfig *ignore.Config
 }
 
 // PortBinding represents a host port binding
@@ -226,6 +246,8 @@ type Mount struct {
 	Target string
 	// ReadOnly indicates if the mount is read-only
 	ReadOnly bool
+	// Type is the mount type (bind or tmpfs)
+	Type MountType
 }
 
 // IsKubernetesRuntime returns true if the runtime is Kubernetes