feat(security): add data flow security with agent hook integration (Spec 027)

Detect and prevent data exfiltration by tracking how data flows between
internal tools (Read, databases) and external tools (WebFetch, Slack).
Operates in two modes: proxy-only (universal, any agent) and full mode
with agent hook integration for intercepting agent-internal tool calls.

Key components:
- Tool/server classifier with internal/external/hybrid/unknown categories
- Content hasher using SHA256 per-field extraction for flow matching
- Flow tracker with session-scoped origin recording and edge detection
- Policy evaluator with configurable actions (allow/warn/ask/deny)
- Session correlator linking agent hook sessions to MCP proxy sessions
- Hook CLI commands (install/uninstall/status/evaluate) for Claude Code
- POST /api/v1/hooks/evaluate REST endpoint
- Activity logging for hook_evaluation and flow_summary event types
- Web UI nudge system for hook installation when in proxy-only mode
- E2E tests for both proxy-only and hook-enhanced flow detection

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Dumbris

CLAUDE.md

@@ -61,6 +61,17 @@ mcpproxy doctor                     # Run health checks
 
 See [docs/cli-management-commands.md](docs/cli-management-commands.md) for complete reference.
 
+### Hook Integration CLI (Spec 027)
+```bash
+mcpproxy hook install --agent claude-code          # Install hooks (project scope)
+mcpproxy hook install --agent claude-code --scope user  # Install hooks (user scope)
+mcpproxy hook uninstall --agent claude-code         # Remove hooks
+mcpproxy hook status --agent claude-code            # Check hook installation status
+mcpproxy hook evaluate --event PreToolUse           # Evaluate tool call (reads JSON from stdin)
+```
+
+Hooks enable full data flow security by intercepting agent-internal tool calls (Read, Write, Bash, etc.) that the MCP proxy cannot see directly.
+
 ### Activity Log CLI
 ```bash
 mcpproxy activity list              # List recent activity
@@ -105,6 +116,7 @@ See [docs/cli-output-formatting.md](docs/cli-output-formatting.md) for complete
 | `internal/storage/` | BBolt database |
 | `internal/management/` | Centralized server management |
 | `internal/oauth/` | OAuth 2.1 with PKCE |
+| `internal/security/flow/` | Data flow security: classification, tracking, policy |
 | `internal/logs/` | Structured logging with per-server files |
 
 See [docs/architecture.md](docs/architecture.md) for diagrams and details.
@@ -194,6 +206,7 @@ See [docs/configuration.md](docs/configuration.md) for complete reference.
 | `POST /api/v1/servers/{name}/enable` | Enable/disable server |
 | `POST /api/v1/servers/{name}/quarantine` | Quarantine/unquarantine server |
 | `GET /api/v1/tools` | Search tools across servers |
+| `POST /api/v1/hooks/evaluate` | Evaluate tool call for data flow security |
 | `GET /api/v1/activity` | List activity records with filtering |
 | `GET /api/v1/activity/{id}` | Get activity record details |
 | `GET /api/v1/activity/export` | Export activity records (JSON/CSV) |
@@ -379,6 +392,63 @@ mcpproxy activity export --sensitive-data --output audit.jsonl  # Export for com
 
 See [docs/features/sensitive-data-detection.md](docs/features/sensitive-data-detection.md) for complete reference.
 
+## Data Flow Security (Spec 027)
+
+Detects data exfiltration patterns by tracking how data flows between internal tools (Read, databases) and external tools (WebFetch, Slack). Operates in two modes:
+
+- **Proxy-only mode**: Monitors MCP tool calls through the proxy (universal, any agent)
+- **Full mode**: Also intercepts agent-internal tools via hooks (requires hook installation)
+
+### Key Concepts
+
+- **Classification**: Tools/servers classified as internal, external, hybrid, or unknown
+- **Flow Types**: internal→internal (safe), internal→external (critical), external→internal, external→external
+- **Content Hashing**: SHA256 per-field hashing to detect data movement without storing content
+- **Session Correlation**: Links agent hook sessions to MCP proxy sessions via argument hash matching
+
+### Configuration
+
+```json
+{
+  "security": {
+    "flow_tracking": {
+      "enabled": true,
+      "session_timeout_minutes": 30,
+      "max_origins_per_session": 10000,
+      "hash_min_length": 20
+    },
+    "classification": {
+      "server_overrides": {
+        "my-private-slack": "internal"
+      }
+    },
+    "flow_policy": {
+      "internal_to_external": "ask",
+      "sensitive_data_external": "deny",
+      "suspicious_endpoints": ["pastebin.com", "webhook.site"]
+    },
+    "hooks": {
+      "enabled": true,
+      "fail_open": true,
+      "correlation_ttl_seconds": 5
+    }
+  }
+}
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `internal/security/flow/classifier.go` | Server/tool classification (internal/external) |
+| `internal/security/flow/tracker.go` | Flow session and origin tracking |
+| `internal/security/flow/hasher.go` | Content hashing for flow detection |
+| `internal/security/flow/service.go` | Flow service orchestrator |
+| `internal/security/flow/correlator.go` | Session correlation (hook↔MCP) |
+| `internal/security/flow/policy.go` | Policy evaluation engine |
+| `internal/httpapi/hooks.go` | POST /api/v1/hooks/evaluate endpoint |
+| `cmd/mcpproxy/hook_cmd.go` | Hook CLI commands (install/uninstall/status/evaluate) |
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -471,6 +541,8 @@ See `docs/prerelease-builds.md` for download instructions.
 - BBolt database (`~/.mcpproxy/config.db`) - ActivityRecord model (024-expand-activity-log)
 - Go 1.24 (toolchain go1.24.10) + BBolt (storage), Chi router (HTTP), Zap (logging), regexp (stdlib), existing ActivityService (026-pii-detection)
 - BBolt database (`~/.mcpproxy/config.db`) - ActivityRecord.Metadata extension (026-pii-detection)
+- Go 1.24 (toolchain go1.24.10) + BBolt (storage), Chi router (HTTP), Zap (logging), mcp-go (MCP protocol), regexp (stdlib), crypto/sha256 (stdlib), existing `security.Detector` (027-data-flow-security)
+- BBolt database (`~/.mcpproxy/config.db`) - ActivityRecord.Metadata extension for hook_evaluation type. Flow sessions are in-memory only (not persisted). (027-data-flow-security)
 
 ## Recent Changes
 - 001-update-version-display: Added Go 1.24 (toolchain go1.24.10)

cmd/mcpproxy/activity_cmd.go

@@ -42,6 +42,8 @@ var (
 	activityNoIcons       bool   // Disable emoji icons in output
 	activityDetectionType string // Spec 026: Filter by detection type (e.g., "aws_access_key")
 	activitySeverity      string // Spec 026: Filter by severity level (critical, high, medium, low)
+	activityFlowType      string // Spec 027: Filter by flow type (e.g., "internal_to_external")
+	activityRiskLevel     string // Spec 027: Filter by risk level (e.g., "critical", "high")
 
 	// Show command flags
 	activityIncludeResponse bool
@@ -72,6 +74,8 @@ type ActivityFilter struct {
 	SensitiveData *bool  // Spec 026: Filter by sensitive data detection
 	DetectionType string // Spec 026: Filter by detection type
 	Severity      string // Spec 026: Filter by severity level
+	FlowType      string // Spec 027: Filter by flow type
+	RiskLevel     string // Spec 027: Filter by risk level
 }
 
 // Validate validates the filter options
@@ -81,6 +85,8 @@ func (f *ActivityFilter) Validate() error {
 		validTypes := []string{
 			"tool_call", "policy_decision", "quarantine_change", "server_change",
 			"system_start", "system_stop", "internal_tool_call", "config_change", // Spec 024: new types
+			"hook_evaluation", // Spec 027: hook evaluation events
+			"flow_summary",    // Spec 027: flow session summaries
 		}
 		// Split by comma for multi-type support
 		types := strings.Split(f.Type, ",")
@@ -144,6 +150,36 @@ func (f *ActivityFilter) Validate() error {
 		}
 	}
 
+	// Validate flow_type (Spec 027)
+	if f.FlowType != "" {
+		validFlowTypes := []string{"internal_to_internal", "internal_to_external", "external_to_internal", "external_to_external"}
+		valid := false
+		for _, ft := range validFlowTypes {
+			if f.FlowType == ft {
+				valid = true
+				break
+			}
+		}
+		if !valid {
+			return fmt.Errorf("invalid flow-type '%s': must be one of %v", f.FlowType, validFlowTypes)
+		}
+	}
+
+	// Validate risk_level (Spec 027)
+	if f.RiskLevel != "" {
+		validRiskLevels := []string{"none", "low", "medium", "high", "critical"}
+		valid := false
+		for _, rl := range validRiskLevels {
+			if f.RiskLevel == rl {
+				valid = true
+				break
+			}
+		}
+		if !valid {
+			return fmt.Errorf("invalid risk-level '%s': must be one of %v", f.RiskLevel, validRiskLevels)
+		}
+	}
+
 	// Validate time formats
 	if f.StartTime != "" {
 		if _, err := time.Parse(time.RFC3339, f.StartTime); err != nil {
@@ -213,6 +249,13 @@ func (f *ActivityFilter) ToQueryParams() url.Values {
 	if f.Severity != "" {
 		q.Set("severity", f.Severity)
 	}
+	// Spec 027: Add data flow security filters
+	if f.FlowType != "" {
+		q.Set("flow_type", f.FlowType)
+	}
+	if f.RiskLevel != "" {
+		q.Set("risk_level", f.RiskLevel)
+	}
 	return q
 }
 
@@ -706,7 +749,7 @@ func init() {
 	activityCmd.AddCommand(activityExportCmd)
 
 	// List command flags
-	activityListCmd.Flags().StringVarP(&activityType, "type", "t", "", "Filter by type (comma-separated for multiple): tool_call, system_start, system_stop, internal_tool_call, config_change, policy_decision, quarantine_change, server_change")
+	activityListCmd.Flags().StringVarP(&activityType, "type", "t", "", "Filter by type (comma-separated for multiple): tool_call, system_start, system_stop, internal_tool_call, config_change, policy_decision, quarantine_change, server_change, hook_evaluation, flow_summary")
 	activityListCmd.Flags().StringVarP(&activityServer, "server", "s", "", "Filter by server name")
 	activityListCmd.Flags().StringVar(&activityTool, "tool", "", "Filter by tool name")
 	activityListCmd.Flags().StringVar(&activityStatus, "status", "", "Filter by status: success, error, blocked")
@@ -722,6 +765,9 @@ func init() {
 	activityListCmd.Flags().Bool("sensitive-data", false, "Filter to show only activities with sensitive data detected")
 	activityListCmd.Flags().StringVar(&activityDetectionType, "detection-type", "", "Filter by detection type (e.g., aws_access_key, stripe_key)")
 	activityListCmd.Flags().StringVar(&activitySeverity, "severity", "", "Filter by severity level: critical, high, medium, low")
+	// Spec 027: Data flow security filters
+	activityListCmd.Flags().StringVar(&activityFlowType, "flow-type", "", "Filter by data flow type: internal_to_internal, internal_to_external, external_to_internal, external_to_external")
+	activityListCmd.Flags().StringVar(&activityRiskLevel, "risk-level", "", "Filter by risk level (>= comparison): none, low, medium, high, critical")
 
 	// Watch command flags
 	activityWatchCmd.Flags().StringVarP(&activityType, "type", "t", "", "Filter by type (comma-separated): tool_call, system_start, system_stop, internal_tool_call, config_change, policy_decision, quarantine_change, server_change")
@@ -816,6 +862,8 @@ func runActivityList(cmd *cobra.Command, _ []string) error {
 		SensitiveData: sensitiveDataPtr,
 		DetectionType: activityDetectionType,
 		Severity:      activitySeverity,
+		FlowType:      activityFlowType,
+		RiskLevel:     activityRiskLevel,
 	}
 
 	if err := filter.Validate(); err != nil {

cmd/mcpproxy/doctor_cmd.go

@@ -417,6 +417,17 @@ func displaySecurityFeaturesStatus() {
 		fmt.Println("  ✗ Sensitive Data Detection: disabled")
 		fmt.Println("    Enable: set sensitive_data_detection.enabled = true in config")
 	}
+
+	// Data Flow Security status (Spec 027)
+	secCfg := cfg.GetSecurityConfig()
+	if secCfg.IsFlowTrackingEnabled() {
+		fmt.Println("  ✓ Data Flow Security: enabled")
+		fmt.Println("    Coverage: proxy_only (hooks not installed)")
+		fmt.Println("    Upgrade:  mcpproxy hook install --agent claude-code")
+	} else {
+		fmt.Println("  ✗ Data Flow Security: disabled")
+		fmt.Println("    Enable: set security.flow_tracking.enabled = true in config")
+	}
 }
 
 // formatCategoryList formats a list of categories for display, truncating if too long.