[Phase 1.4] Implement tool execution subsystem

[anchapin]

Summary

Implements Phase 1.4 tool execution subsystem for secure subprocess execution of MCP tools.

Changes

New Module: orchestrator/src/tools/

Core Components:

• validator.rs: Command validation to prevent shell injection

  • Whitelist of known-safe commands (npx, python, node, cargo, etc.)
  • Shell metacharacter detection (;, &, |, $, `, (, ), <, >, newline, tab, *, ?, [, ])
  • Custom whitelist support via CommandValidator::with_whitelist()
  • Path-based command support (Unix and Windows)

• executor.rs: Secure subprocess execution

  • Uses tokio::process::Command (no shell=True) - primary security measure
  • Timeout handling (configurable, default 30s)
  • Output size limits (1MB default) to prevent memory exhaustion
  • Working directory support
  • Proper error handling and cleanup

Security Features:

• Defense-in-depth approach: validation + safe subprocess API
• Never uses shell=True (critical security requirement)
• Whitelist documents expected command surface
• Metacharacter detection catches obvious injection attempts
• Output truncation prevents memory exhaustion
• Timeout enforcement prevents hanging processes

Updated Files

• orchestrator/src/lib.rs: Added tools module

Test Coverage

• 29 comprehensive unit tests
• Property-based tests with proptest
• 99.57% line coverage (executor.rs)
• 98.31% line coverage (validator.rs)
• Both exceed the 75% target

Test Scenarios

• ✅ Simple command execution (echo, cat, etc.)
• ✅ Timeout handling
• ✅ Output truncation
• ✅ Command validation (safe commands pass)
• ✅ Command validation (metacharacters rejected)
• ✅ Path-based commands (Unix and Windows)
• ✅ Custom whitelists
• ✅ Working directory support
• ✅ Non-existent command handling
• ✅ Property-based tests for validation logic

Acceptance Criteria

• Create tool execution module in orchestrator/src/
• Implement subprocess spawning with list invocation
• Add command validation to prevent shell injection
• Whitelist known-safe commands (npx, python, node, cargo)
• Add timeout handling
• Add comprehensive tests
• Target 75% test coverage (achieved: 98%+)

Usage Example

use luminaguard_orchestrator::tools::{ToolExecutor, ExecutorConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let executor = ToolExecutor::new();
    
    // Execute a simple command
    let result = executor.execute(&["echo", "hello world"]).await?;
    assert!(result.success);
    assert_eq!(result.stdout, "hello world\n");
    
    // Execute with custom timeout
    let config = ExecutorConfig::with_timeout(5);
    let executor = ToolExecutor::with_config(config);
    let result = executor.execute(&["sleep", "1"]).await?;
    assert!(result.success);
    
    Ok(())
}

Test Plan

• All unit tests pass (29/29)
• Property-based tests pass
• Coverage exceeds 75% (98%+)
• No compiler warnings
• Pre-commit hooks pass

Closes #519

---

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @anchapin, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery