Back to Ruflo

Claude-Flow Integration: Network Sandboxing & DevTools

v2/docs/sdk/SDK-ADVANCED-FEATURES-INTEGRATION.md

3.6.3018.7 KB
Original Source

Claude-Flow Integration: Network Sandboxing & DevTools

Advanced SDK Feature Integration for Swarm Orchestration

Version: 2.5.0-alpha.130 Date: 2025-09-30 Status: Design Phase


🎯 Overview

This document explores how to integrate two advanced Claude Code SDK features into Claude-Flow's swarm orchestration system:

  1. Network Request Sandboxing - Per-agent network isolation and governance
  2. React DevTools Integration - Real-time swarm visualization and profiling

1️⃣ Network Request Sandboxing Integration

SDK Feature Analysis

typescript
// Discovered in @anthropic-ai/claude-code CLI source
interface NetworkPermission {
  hostPattern: { host: string; port: number };
  allow: boolean;
  rememberForSession: boolean;
}

// Implementation pattern (inferred from minified code)
function promptNetworkAccess(
  hostPattern: { host: string; port: number }
): Promise<NetworkPermissionResponse> {
  // SDK prompts user for approval
  // Returns: { allow: boolean, rememberForSession: boolean }
}

Key Capabilities:

  • ✅ Host-level network isolation
  • ✅ Port-specific access control
  • ✅ Session-persistent permissions
  • ✅ Interactive approval flow

🚀 Claude-Flow Integration Strategy

Use Case 1: Per-Agent Network Policies

Scenario: Different agents need different network access levels

  • Research agents → Full internet access
  • Code analysis agents → GitHub API only
  • Validation agents → No network access (sandboxed)

Implementation:

typescript
// src/swarm/network-policy-manager.ts
import { AgentType, SwarmConfig } from './types';

interface AgentNetworkPolicy {
  agentType: AgentType;
  allowedHosts: Array<{ host: string; port: number }>;
  deniedHosts: Array<{ host: string; port: number }>;
  defaultBehavior: 'allow' | 'deny' | 'prompt';
}

export class NetworkPolicyManager {
  private policies: Map<AgentType, AgentNetworkPolicy> = new Map();

  constructor() {
    this.initializeDefaultPolicies();
  }

  private initializeDefaultPolicies() {
    // Research agent - broad access
    this.policies.set('researcher', {
      agentType: 'researcher',
      allowedHosts: [
        { host: '*.anthropic.com', port: 443 },
        { host: '*.github.com', port: 443 },
        { host: '*.stackoverflow.com', port: 443 },
        { host: '*.npmjs.com', port: 443 }
      ],
      deniedHosts: [],
      defaultBehavior: 'prompt'
    });

    // Coder agent - restricted to documentation and package registries
    this.policies.set('coder', {
      agentType: 'coder',
      allowedHosts: [
        { host: 'api.github.com', port: 443 },
        { host: 'registry.npmjs.org', port: 443 },
        { host: 'pypi.org', port: 443 }
      ],
      deniedHosts: [],
      defaultBehavior: 'deny'
    });

    // Analyst agent - no network access (sandboxed)
    this.policies.set('analyst', {
      agentType: 'analyst',
      allowedHosts: [],
      deniedHosts: [{ host: '*', port: '*' }],
      defaultBehavior: 'deny'
    });

    // Optimizer agent - metrics endpoints only
    this.policies.set('optimizer', {
      agentType: 'optimizer',
      allowedHosts: [
        { host: 'api.anthropic.com', port: 443 }
      ],
      deniedHosts: [],
      defaultBehavior: 'deny'
    });
  }

  async checkNetworkAccess(
    agentType: AgentType,
    host: string,
    port: number,
    sessionId: string
  ): Promise<{ allowed: boolean; reason: string }> {
    const policy = this.policies.get(agentType);
    if (!policy) {
      return { allowed: false, reason: 'No policy found for agent type' };
    }

    // Check explicit denials first
    if (this.isHostDenied(host, port, policy.deniedHosts)) {
      return {
        allowed: false,
        reason: `Host ${host}:${port} is explicitly denied for ${agentType} agents`
      };
    }

    // Check explicit allows
    if (this.isHostAllowed(host, port, policy.allowedHosts)) {
      return {
        allowed: true,
        reason: `Host ${host}:${port} is whitelisted for ${agentType} agents`
      };
    }

    // Apply default behavior
    switch (policy.defaultBehavior) {
      case 'allow':
        return { allowed: true, reason: 'Default allow policy' };
      case 'deny':
        return { allowed: false, reason: 'Default deny policy' };
      case 'prompt':
        // Delegate to SDK's interactive prompt
        return await this.promptUserForAccess(agentType, host, port, sessionId);
    }
  }

  private isHostAllowed(
    host: string,
    port: number,
    allowedHosts: Array<{ host: string; port: number }>
  ): boolean {
    return allowedHosts.some(pattern =>
      this.matchesPattern(host, pattern.host) &&
      (pattern.port === '*' || pattern.port === port)
    );
  }

  private isHostDenied(
    host: string,
    port: number,
    deniedHosts: Array<{ host: string; port: number }>
  ): boolean {
    return deniedHosts.some(pattern =>
      this.matchesPattern(host, pattern.host) &&
      (pattern.port === '*' || pattern.port === port)
    );
  }

  private matchesPattern(host: string, pattern: string): boolean {
    // Wildcard pattern matching
    const regex = new RegExp(
      '^' + pattern.replace(/\*/g, '.*').replace(/\./g, '\\.') + '$'
    );
    return regex.test(host);
  }

  private async promptUserForAccess(
    agentType: AgentType,
    host: string,
    port: number,
    sessionId: string
  ): Promise<{ allowed: boolean; reason: string }> {
    // Use SDK's native network prompt
    const response = await this.sdkNetworkPrompt({ host, port });

    if (response.rememberForSession) {
      // Cache decision for this session
      this.cacheSessionDecision(sessionId, host, port, response.allow);
    }

    return {
      allowed: response.allow,
      reason: response.allow
        ? `User approved access to ${host}:${port}`
        : `User denied access to ${host}:${port}`
    };
  }

  async setAgentPolicy(agentType: AgentType, policy: AgentNetworkPolicy): Promise<void> {
    this.policies.set(agentType, policy);
  }

  async getAgentPolicy(agentType: AgentType): Promise<AgentNetworkPolicy | undefined> {
    return this.policies.get(agentType);
  }
}

Use Case 2: Swarm-Level Network Isolation

Scenario: Entire swarm operates in restricted network environment

typescript
// src/swarm/swarm-network-manager.ts
export class SwarmNetworkManager {
  private policyManager: NetworkPolicyManager;
  private swarmSessions: Map<string, NetworkSessionData> = new Map();

  async initializeSwarm(
    swarmId: string,
    config: SwarmNetworkConfig
  ): Promise<void> {
    this.swarmSessions.set(swarmId, {
      isolationMode: config.isolationMode,
      allowedHosts: config.allowedHosts || [],
      deniedHosts: config.deniedHosts || [],
      agentPermissions: new Map()
    });
  }

  async beforeAgentNetworkRequest(
    agentId: string,
    agentType: AgentType,
    request: NetworkRequest
  ): Promise<NetworkRequestResult> {
    const swarmId = this.getSwarmIdForAgent(agentId);
    const session = this.swarmSessions.get(swarmId);

    if (!session) {
      throw new Error(`No network session found for swarm ${swarmId}`);
    }

    // Check swarm-level restrictions first
    if (session.isolationMode === 'strict') {
      const swarmAllowed = this.isHostAllowedInSwarm(
        request.host,
        request.port,
        session
      );

      if (!swarmAllowed) {
        return {
          allowed: false,
          reason: `Swarm ${swarmId} operates in strict isolation mode`,
          blockedBy: 'swarm-policy'
        };
      }
    }

    // Check agent-level policy
    const agentCheck = await this.policyManager.checkNetworkAccess(
      agentType,
      request.host,
      request.port,
      agentId
    );

    if (!agentCheck.allowed) {
      return {
        allowed: false,
        reason: agentCheck.reason,
        blockedBy: 'agent-policy'
      };
    }

    // Record permission grant for audit
    this.recordNetworkAccess(swarmId, agentId, request);

    return {
      allowed: true,
      reason: 'Approved by swarm and agent policies'
    };
  }

  async getSwarmNetworkAudit(swarmId: string): Promise<NetworkAuditLog> {
    // Return complete audit trail of network requests
    return {
      swarmId,
      totalRequests: this.getTotalRequests(swarmId),
      approvedRequests: this.getApprovedRequests(swarmId),
      deniedRequests: this.getDeniedRequests(swarmId),
      requestsByAgent: this.getRequestsByAgent(swarmId),
      requestsByHost: this.getRequestsByHost(swarmId)
    };
  }
}

Use Case 3: Dynamic Network Policy Updates

Scenario: Adjust network policies based on swarm behavior

typescript
// src/swarm/adaptive-network-policy.ts
export class AdaptiveNetworkPolicy {
  async analyzeSwarmBehavior(swarmId: string): Promise<PolicyRecommendations> {
    const audit = await this.networkManager.getSwarmNetworkAudit(swarmId);

    const recommendations: PolicyRecommendations = {
      expansions: [],
      restrictions: [],
      warnings: []
    };

    // Detect patterns of denied requests
    const frequentlyDenied = this.findFrequentlyDeniedHosts(audit);
    if (frequentlyDenied.length > 0) {
      recommendations.warnings.push({
        type: 'frequent-denials',
        hosts: frequentlyDenied,
        suggestion: 'Consider adding these hosts to allowlist if trusted'
      });
    }

    // Detect suspicious network patterns
    const suspiciousActivity = this.detectSuspiciousPatterns(audit);
    if (suspiciousActivity.length > 0) {
      recommendations.restrictions.push({
        type: 'suspicious-activity',
        details: suspiciousActivity,
        action: 'Recommend restricting network access for affected agents'
      });
    }

    return recommendations;
  }

  private detectSuspiciousPatterns(audit: NetworkAuditLog): SuspiciousPattern[] {
    const patterns: SuspiciousPattern[] = [];

    // Port scanning detection
    const portScans = this.detectPortScanning(audit);
    if (portScans.length > 0) {
      patterns.push({
        type: 'port-scan',
        agents: portScans,
        severity: 'high'
      });
    }

    // Unusual TLD access
    const unusualTLDs = this.detectUnusualTLDs(audit);
    if (unusualTLDs.length > 0) {
      patterns.push({
        type: 'unusual-tld',
        hosts: unusualTLDs,
        severity: 'medium'
      });
    }

    return patterns;
  }
}

2️⃣ React DevTools Integration

SDK Feature Analysis

typescript
// Discovered in @anthropic-ai/claude-code CLI source
window.__REACT_DEVTOOLS_COMPONENT_FILTERS__

// SDK includes full React DevTools backend for TUI rendering
// React Fiber profiling
// Component tree inspection
// Performance timeline tracking

Key Capabilities:

  • ✅ Real-time component tree visualization
  • ✅ Performance profiling (render times, re-renders)
  • ✅ State inspection
  • ✅ Props tracking
  • ✅ Timeline analysis

🚀 Claude-Flow Integration Strategy

Use Case 1: Swarm Visualization Dashboard

Scenario: Real-time visualization of swarm topology and agent states

typescript
// src/ui/swarm-devtools.tsx
import React, { useEffect, useState } from 'react';
import { Box, Text, useApp } from 'ink';

interface SwarmNode {
  id: string;
  type: string;
  status: 'idle' | 'busy' | 'failed';
  connections: string[];
  metrics: {
    tasksCompleted: number;
    avgExecutionTime: number;
    errorRate: number;
  };
}

export const SwarmDevToolsDashboard: React.FC<{
  swarmId: string;
}> = ({ swarmId }) => {
  const [topology, setTopology] = useState<SwarmNode[]>([]);
  const [selectedNode, setSelectedNode] = useState<string | null>(null);

  useEffect(() => {
    // Subscribe to swarm state updates
    const unsubscribe = SwarmMonitor.subscribe(swarmId, (state) => {
      setTopology(state.agents);
    });

    return unsubscribe;
  }, [swarmId]);

  return (
    <Box flexDirection="column" padding={1}>
      <Box borderStyle="round" borderColor="cyan">
        <Text bold color="cyan">
          🐝 Swarm Topology: {swarmId}
        </Text>
      </Box>

      <Box flexDirection="row" marginTop={1}>
        <Box flexDirection="column" width="50%">
          {topology.map((node) => (
            <AgentCard
              key={node.id}
              node={node}
              selected={selectedNode === node.id}
              onSelect={() => setSelectedNode(node.id)}
            />
          ))}
        </Box>
        <Box flexDirection="column" width="50%" paddingLeft={2}>
          {selectedNode && (
            <AgentDetailsPanel
              node={topology.find((n) => n.id === selectedNode)!}
            />
          )}
        </Box>
      </Box>
      <Box marginTop={2}>
        <SwarmNetworkGraph topology={topology} />
      </Box>
    </Box>
  );
};

Use Case 2: Agent Performance Profiling

Scenario: Profile individual agent performance using React Fiber data

typescript
// src/profiling/agent-profiler.ts
export class AgentProfiler {
  private fiberData: Map<string, FiberPerformanceData> = new Map();

  async captureAgentProfile(agentId: string): Promise<AgentProfile> {
    // Hook into React DevTools profiling API
    const profiler = this.getReactProfiler();

    // Start profiling
    profiler.startProfiling();

    // Let agent execute
    await this.executeAgentTasks(agentId);

    // Stop and collect data
    const profilingData = profiler.stopProfiling();

    return this.analyzeProfilingData(agentId, profilingData);
  }

  private analyzeProfilingData(
    agentId: string,
    data: ReactProfilingData
  ): AgentProfile {
    return {
      agentId,
      totalRenderTime: data.commitTime,
      componentBreakdown: data.durations.map(([id, duration]) => ({
        component: this.getComponentName(id),
        renderTime: duration,
        percentage: (duration / data.commitTime) * 100
      })),
      slowestComponents: this.findSlowestComponents(data),
      renderCount: data.durations.length,
      recommendations: this.generateOptimizationRecommendations(data)
    };
  }

  private generateOptimizationRecommendations(
    data: ReactProfilingData
  ): Recommendation[] {
    const recommendations: Recommendation[] = [];

    // Detect unnecessary re-renders
    const unnecessaryRerenders = this.detectUnnecessaryRerenders(data);
    if (unnecessaryRerenders.length > 0) {
      recommendations.push({
        type: 'unnecessary-rerenders',
        severity: 'medium',
        components: unnecessaryRerenders,
        suggestion: 'Add React.memo or useMemo to prevent unnecessary renders'
      });
    }

    // Detect expensive computations
    const expensiveComputations = this.detectExpensiveComputations(data);
    if (expensiveComputations.length > 0) {
      recommendations.push({
        type: 'expensive-computations',
        severity: 'high',
        components: expensiveComputations,
        suggestion: 'Move expensive computations to useMemo or worker threads'
      });
    }

    return recommendations;
  }
}

Use Case 3: Real-Time Swarm Monitoring UI

Scenario: Live dashboard showing all swarm activity

typescript
// src/ui/swarm-monitor.tsx
export const SwarmMonitorUI: React.FC = () => {
  const [swarms, setSwarms] = useState<SwarmState[]>([]);
  const [metrics, setMetrics] = useState<SwarmMetrics>({});

  useEffect(() => {
    // Enable React DevTools bridge
    if (typeof window !== 'undefined') {
      window.__REACT_DEVTOOLS_GLOBAL_HOOK__ = {
        inject: (renderer) => {
          // Hook into React renderer for swarm components
          this.interceptSwarmComponents(renderer);
        }
      };
    }

    // Subscribe to swarm updates
    const unsubscribe = SwarmCoordinator.subscribeToAll((updates) => {
      setSwarms(updates.swarms);
      setMetrics(updates.metrics);
    });

    return unsubscribe;
  }, []);

  return (
    <Box flexDirection="column">
      <Box borderStyle="double" borderColor="green">
        <Text bold color="green">
          🌊 Claude-Flow Swarm Monitor v2.5.0
        </Text>
      </Box>
      <Box flexDirection="row" flexWrap="wrap" marginTop={1}>
        {swarms.map((swarm) => (
          <SwarmCard
            key={swarm.id}
            swarm={swarm}
            metrics={metrics[swarm.id]}
          />
        ))}
      </Box>
      <Box marginTop={2} borderStyle="single" borderColor="cyan">
        <GlobalMetricsPanel metrics={this.aggregateMetrics(metrics)} />
      </Box>
      <Box marginTop={2}>
        <PerformanceTimeline swarms={swarms} />
      </Box>
    </Box>
  );
};

🔧 Implementation Plan

Phase 1: Network Sandboxing (Week 1)

  1. Create NetworkPolicyManager class
  2. Implement per-agent network policies
  3. Add SDK network prompt integration
  4. Create swarm-level network isolation
  5. Build network audit logging

Phase 2: React DevTools Bridge (Week 2)

  1. Set up React DevTools hook integration
  2. Create swarm visualization components
  3. Implement agent profiling system
  4. Build real-time monitoring dashboard
  5. Add performance recommendations

Phase 3: Integration & Testing (Week 3)

  1. Integrate with existing swarm coordinator
  2. Add configuration options
  3. Create comprehensive test suite
  4. Performance benchmarking
  5. Documentation

📊 Expected Benefits

Network Sandboxing

  • Security: Prevent unauthorized network access by agents
  • Compliance: Audit trail for all network requests
  • Control: Fine-grained per-agent network policies
  • Visibility: Real-time monitoring of network activity

React DevTools Integration

  • Monitoring: Real-time swarm state visualization
  • Debugging: Component-level agent inspection
  • Performance: Identify bottlenecks in agent execution
  • Optimization: Data-driven performance improvements

🎯 Success Metrics

MetricTargetMeasurement
Network Policy Violations0Audit log analysis
Dashboard Render Performance<16msReact DevTools profiler
Agent Profile Collection Overhead<5%Benchmark comparison
Network Request Latency<2ms addedPerformance tests

📝 Configuration Examples

Network Policy Configuration

typescript
// claude-flow.config.ts
export default {
  swarm: {
    networkPolicies: {
      researcher: {
        allowedHosts: ['*.github.com', '*.stackoverflow.com'],
        defaultBehavior: 'prompt'
      },
      coder: {
        allowedHosts: ['registry.npmjs.org', 'pypi.org'],
        defaultBehavior: 'deny'
      },
      analyst: {
        allowedHosts: [],
        defaultBehavior: 'deny' // Fully sandboxed
      }
    },
    networkIsolation: {
      mode: 'strict', // 'strict' | 'permissive' | 'audit-only'
      allowedGlobalHosts: ['api.anthropic.com']
    }
  },
  devTools: {
    enabled: true,
    dashboard: {
      port: 3000,
      enableProfiling: true,
      updateInterval: 1000
    }
  }
};

Integration design for Claude-Flow v2.5.0-alpha.130