Orchestrata Ultimate / Specs / 066-powershell-tool

066-powershell-tool: PowerShellTool - Windows PowerShell Execution

The PowerShellTool provides secure, sandboxed execution of PowerShell commands and scripts on Windows systems with comprehensive output filtering, command allowlisting, and execution timeouts.

At a glance

Reading this spec

This spec describes PowerShellTool, a tool for sandboxed execution of PowerShell commands and scripts on Windows hosts, for AI agents and automation workflows. The spec is archived: a note at its top records that on 2026-07-12 (session 227, the tool-wave ruling) it was archived because it targets Windows hosts while the deployment fleet is Linux-only, so no PowerShell runtime exists or is planned. The note adds that shell execution is covered by the registered run_shell volk. The status line reads "Archived (2026-07-12 — Windows-only, no target host; was: Complete)".

For historical reference, the scope was single command execution, script file execution with parameter binding, output sanitization and filtering, a command allowlist as the security sandbox, execution timeouts, and detection of the PowerShell binary across platforms. The target systems were Windows Server 2019 or later, Windows 10 and 11, and PowerShell 5.1 or later. Four user stories give the intent: Windows service management, an Active Directory user query, an Azure resource inventory, and file system operations under security restrictions. The functional requirements (FR-001 onward) cover command execution, script execution, allowlist enforcement, execution timeout and output handling.

The 194 requirement IDs (REQ-066-NNN) cover these functions plus security, audit and test conditions. Examples are that the tool executes single commands and captures output within the timeout, sanitizes connection strings, and logs every execution with timestamp, user, command and result for the audit trail.

No code module cites this spec, consistent with the archive decision. The requirements traceability matrix lists every ID. The spec tracks 2 files. No src/ symbol cites any of the 194 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 194 requirements have no citing symbol; untraced means no @traces names the ID.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Other tracked files

• specs/066-powershell-tool/compliance-audit.md

Full spec text

Verbatim from specs/066-powershell-tool/spec.md; headings are pushed down two levels.

SPEC-066: PowerShellTool - Windows PowerShell Execution

ARCHIVED 2026-07-12 (session 227, tool-wave ruling — plans/tool-wave-plan.md): this spec targets Windows hosts; the deployment fleet is Linux-only (CachyOS host + Incus containers). No PowerShell runtime exists or is planned in this environment. Shell execution is covered by the registered run_shell volk tool and SPEC-063 REPLTool (bash sessions). Revisit only if a Windows target enters the fleet.

Metadata

• Spec ID: 066-powershell-tool
• Title: PowerShellTool - Windows PowerShell Execution with Security Sandboxing
• Author: Mohamed
• Status: Archived (2026-07-12 — Windows-only, no target host; was: Complete)
• Created: 2026-04-08
• Last Updated: 2026-04-09
• Priority: P1
• Version: 1.0.0

Overview

2.1 Purpose

The PowerShellTool provides secure, sandboxed execution of PowerShell commands and scripts on Windows systems with comprehensive output filtering, command allowlisting, and execution timeouts.

2.2 Scope

This tool enables AI agents and automation workflows to execute PowerShell commands on Windows hosts with the following capabilities:

• Single command execution
• Script file execution with parameter binding
• Output sanitization and filtering
• Security sandboxing via command allowlist
• Execution timeout enforcement
• Cross-platform PowerShell binary detection

2.3 Target Systems

• Windows Server 2019+
• Windows 10/11
• PowerShell 5.1+
• PowerShell Core 7.x

User Scenarios

US-001: Windows Service Management

As a DevOps engineer I want to execute PowerShell commands to check and manage Windows services So that I can monitor service status across multiple servers and perform recovery actions

Acceptance Criteria:

• Tool executes Get-Service commands to retrieve service states
• Tool can use Restart-Service for recovery actions
• Output is returned in structured JSON format
• Command is validated against allowlist before execution

US-002: Active Directory User Query

As an IT administrator I want to query Active Directory for user account information So that I can identify stale accounts for cleanup purposes

Acceptance Criteria:

• Tool executes AD PowerShell cmdlets with proper filtering
• Results include LastLogonDate and DisplayName
• Output is filtered for relevant accounts
• Sensitive data is sanitized from results

US-003: Azure Resource Inventory

As a cloud administrator I want to generate an inventory of Azure VMs in a subscription So that I can track VM status, size, and resource groups

Acceptance Criteria:

• Tool executes Azure PowerShell commands
• Results include Name, ResourceGroupName, PowerState, VMSize
• Output is returned in structured table format
• Authentication is handled via Azure PowerShell modules

US-004: File System Operations with Security Restrictions

As a file operations team member I want to list files in a specific directory with time-based filtering So that I can identify old files while remaining restricted from dangerous commands

Acceptance Criteria:

• Command is validated against allowlist before execution
• Only safe filesystem operations are permitted
• Output includes file metadata (name, path, last write time)
• Dangerous commands like Remove-Item are blocked

Terminology

Functional Requirements

FR-001: Single Command Execution

REQ-066-001: The tool MUST execute single PowerShell commands and capture output within the specified timeout period.

Success Criteria:

• REQ-066-002: Command is executed using detected PowerShell binary
• REQ-066-003: Stdout and stderr are captured separately
• REQ-066-004: Exit code is returned in result
• REQ-066-005: Execution time is measured in milliseconds

FR-002: Script File Execution

REQ-066-006: The tool MUST execute PowerShell script files (.ps1) with parameter binding.

Success Criteria:

• REQ-066-007: Script path is validated to exist and end in .ps1
• REQ-066-008: Parameters are bound using -File parameter syntax
• REQ-066-009: Execution follows same security rules as single commands
• REQ-066-010: Errors during parameter binding return descriptive messages

FR-003: Command Allowlist Enforcement

REQ-066-011: The tool MUST enforce a command allowlist for security sandboxing.

Success Criteria:

• REQ-066-012: Commands are validated before execution
• REQ-066-013: Default patterns include Get-, Test-, Select-, Where-, Sort-*
• REQ-066-014: Custom allowlists can be specified per execution
• REQ-066-015: Blocked commands return ERR-003 error

FR-004: Execution Timeout

REQ-066-016: The tool MUST implement configurable execution timeout.

Success Criteria:

• REQ-066-017: Default timeout is 60 seconds
• REQ-066-018: Timeout range is 1-600 seconds
• REQ-066-019: Process tree is killed on timeout
• REQ-066-020: Timeout error (ERR-002) is returned on expiration

FR-005: Output Sanitization

REQ-066-021: The tool MUST sanitize command output to remove sensitive data.

Success Criteria:

• REQ-066-022: Passwords, tokens, keys are replaced with [REDACTED]
• REQ-066-023: Connection strings are sanitized
• REQ-066-024: Private keys are masked
• REQ-066-025: Custom patterns can be configured

FR-006: PowerShell Binary Detection

REQ-066-026: The tool MUST detect PowerShell binary across platforms.

Success Criteria:

• REQ-066-027: Windows: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
• REQ-066-028: Cross-platform: pwsh in PATH
• REQ-066-029: Linux/macOS: /usr/bin/pwsh
• REQ-066-030: Returns ERR-001 if not found

FR-007: Structured Output

REQ-066-031: The tool MUST parse and return structured output (JSON/text).

Success Criteria:

• REQ-066-032: PowerShell objects are serialized to JSON
• REQ-066-033: Text output is preserved as-is
• REQ-066-034: output_json field contains parsed objects when applicable
• REQ-066-035: Null when output cannot be parsed as JSON

FR-008: Working Directory Support

REQ-066-036: The tool MUST support working directory specification.

Success Criteria:

• REQ-066-037: Optional working_directory parameter
• REQ-066-038: Validates directory exists before execution
• REQ-066-039: ERR-009 returned if directory invalid

FR-009: Execution Cancellation

REQ-066-040: The tool MUST implement execution cancellation.

Success Criteria:

• REQ-066-041: cancel() method accepts execution_id
• REQ-066-042: SIGINT signal sent first (soft cancel)
• REQ-066-043: Force kill after 5 second grace period
• REQ-066-044: ERR-012 returned if cancelled

FR-010: Audit Logging

REQ-066-045: The tool MUST log all executions for audit trail.

Success Criteria:

• REQ-066-046: Timestamp recorded for each execution
• REQ-066-047: Command, user, result, and duration logged
• REQ-066-048: Logs include success/failure status
• REQ-066-049: Audit trail is queryable

Non-Functional Requirements

9.1 Performance Requirements

9.2 Reliability Requirements

9.3 Security Requirements

9.4 Compatibility Requirements

9.5 Observability Requirements

Data Models

5.1 Tool Request Schema

REQ-066-050: A tool request SHALL conform to the PowerShellToolRequest JSON Schema below: command of length 1-10000, script_path matching \.ps1$, parameters as an object of string/number/boolean/array/object values, timeout an integer 1-600 defaulting to 60, an optional working_directory, an optional allowlist array of strings, and exactly one of command or script_path required.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "PowerShellToolRequest",
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "PowerShell command or script to execute",
      "minLength": 1,
      "maxLength": 10000
    },
    "script_path": {
      "type": "string",
      "description": "Path to PowerShell script file (.ps1)",
      "pattern": "\\.ps1$"
    },
    "parameters": {
      "type": "object",
      "description": "Parameters to bind to script",
      "additionalProperties": {
        "type": ["string", "number", "boolean", "array", "object"]
      }
    },
    "timeout": {
      "type": "integer",
      "description": "Execution timeout in seconds",
      "minimum": 1,
      "maximum": 600,
      "default": 60
    },
    "working_directory": {
      "type": "string",
      "description": "Working directory for execution"
    },
    "allowlist": {
      "type": "array",
      "description": "Custom command allowlist for this execution",
      "items": {
        "type": "string"
      }
    }
  },
  "oneOf": [
    { "required": ["command"] },
    { "required": ["script_path"] }
  ]
}

5.2 Tool Result Schema

REQ-066-051: A tool result SHALL conform to the PowerShellToolResult JSON Schema below, carrying success, output (sanitized), output_json (parsed JSON output when applicable), error, exit_code, execution_time_ms and timestamp, with success, exit_code and execution_time_ms required.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "PowerShellToolResult",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether execution completed successfully"
    },
    "output": {
      "type": "string",
      "description": "Command output (sanitized)"
    },
    "output_json": {
      "type": ["object", "array", "null"],
      "description": "Parsed JSON output if applicable"
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    },
    "exit_code": {
      "type": "integer",
      "description": "Process exit code"
    },
    "execution_time_ms": {
      "type": "integer",
      "description": "Execution duration in milliseconds"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Execution timestamp"
    }
  },
  "required": ["success", "exit_code", "execution_time_ms"]
}

5.3 Command Validation Schema

REQ-066-052: A command validation result SHALL conform to the CommandValidationResult JSON Schema below, carrying allowed (required), blocked_reason and matched_pattern.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CommandValidationResult",
  "type": "object",
  "properties": {
    "allowed": {
      "type": "boolean",
      "description": "Whether command is allowed by allowlist"
    },
    "blocked_reason": {
      "type": "string",
      "description": "Reason for blocking if not allowed"
    },
    "matched_pattern": {
      "type": "string",
      "description": "The allowlist pattern that matched"
    }
  },
  "required": ["allowed"]
}

5.4 Security Configuration Schema

REQ-066-053: Security configuration SHALL conform to the PowerShellSecurityConfig JSON Schema below, including command_allowlist, command_blocklist, blocked_patterns, execution_timeout_seconds (1-600, default 60), max_output_size_bytes (1024-10485760, default 1048576), sensitive_data_patterns, require_working_directory (default false), and sandbox_mode (one of none, allowlist, blocklist, strict; default allowlist).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "PowerShellSecurityConfig",
  "type": "object",
  "properties": {
    "command_allowlist": {
      "type": "array",
      "description": "Allowed cmdlet patterns",
      "items": {
        "type": "string"
      },
      "default": ["Get-*", "Test-*", "Select-*", "Where-*", "Sort-*"]
    },
    "command_blocklist": {
      "type": "array",
      "description": "Explicitly blocked cmdlet patterns",
      "items": {
        "type": "string"
      },
      "default": ["Remove-Item", "Stop-Process", "Stop-Computer", "Restart-Computer", "Format-Volume"]
    },
    "blocked_patterns": {
      "type": "array",
      "description": "Regex patterns to block in commands",
      "items": {
        "type": "string"
      },
      "default": ["-exec\\s", "Invoke-Expression", "iex\\s", "Invoke-Command.*-ScriptBlock"]
    },
    "execution_timeout_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600,
      "default": 60
    },
    "max_output_size_bytes": {
      "type": "integer",
      "minimum": 1024,
      "maximum": 10485760,
      "default": 1048576
    },
    "sensitive_data_patterns": {
      "type": "array",
      "description": "Patterns to redact from output",
      "items": {
        "type": "string"
      },
      "default": ["password", "secret", "token", "key", "api_?key", "connectionstring"]
    },
    "require_working_directory": {
      "type": "boolean",
      "description": "Require working directory to be specified",
      "default": false
    },
    "sandbox_mode": {
      "type": "string",
      "enum": ["none", "allowlist", "blocklist", "strict"],
      "default": "allowlist"
    }
  }
}

Error Conditions

ERR-001: PowerShell Binary Not Found

ERR-002: Command Timeout

ERR-003: Command Not in Allowlist

ERR-004: Command Matches Blocklist

ERR-005: Command Matches Blocked Pattern

ERR-006: Script File Not Found

ERR-007: Script File Invalid

ERR-008: Parameter Binding Failure

ERR-009: Working Directory Invalid

ERR-010: Output Size Exceeded

ERR-011: Execution Permission Denied

ERR-012: Execution Cancelled

ERR-013: PowerShell Module Not Found

ERR-014: Invalid Command Syntax

ERR-015: Encoding Error

ERR-016: Command Exceeds Maximum Length

ERR-017: Invalid Timeout Value

ERR-018: Path Traversal Detected

ERR-019: No Command Provided

API Contracts

8.1 Tool Interface

REQ-066-073: The tool SHALL expose the PowerShellTool interface shown below — the name, description and version attributes plus execute, execute_script, validate_command, sanitize_output, get_powershell_path and cancel — implementing BaseTool.

class PowerShellTool(BaseTool):
    """Execute PowerShell commands on Windows with security sandboxing."""
    
    name: str = "PowerShellTool"
    description: str = "Execute PowerShell commands with security sandboxing"
    version: str = "1.0.0"
    
    def __init__(
        self,
        config: PowerShellSecurityConfig = None,
        logger: logging.Logger = None
    ) -> None:
        """Initialize PowerShell tool with security configuration."""
    
    async def execute(
        self,
        command: str,
        timeout: int = 60,
        working_directory: str = None,
        allowlist: List[str] = None
    ) -> ToolResult:
        """Execute a PowerShell command."""
    
    async def execute_script(
        self,
        script_path: str,
        parameters: Dict[str, Any] = None,
        timeout: int = 120,
        working_directory: str = None
    ) -> ToolResult:
        """Execute a PowerShell script file with parameters."""
    
    def validate_command(self, command: str) -> CommandValidationResult:
        """Validate command against security rules."""
    
    def sanitize_output(self, output: str) -> str:
        """Remove sensitive data from output."""
    
    def get_powershell_path(self) -> str:
        """Detect and return PowerShell binary path."""
    
    async def cancel(self, execution_id: str) -> bool:
        """Cancel a running execution."""

8.2 Tool Result Interface

REQ-066-074: The tool SHALL return the ToolResult structure shown below, with the fields success, output, output_json, error, exit_code, execution_time_ms and timestamp.

@dataclass
class ToolResult:
    success: bool
    output: str
    output_json: Optional[Union[Dict, List]]
    error: Optional[str]
    exit_code: int
    execution_time_ms: int
    timestamp: datetime

8.3 REST API Endpoints (Tool Server)

REQ-066-075: The tool server SHALL expose the REST endpoints shown below: POST /api/v1/tools/powershell/execute, POST /api/v1/tools/powershell/execute-script, POST /api/v1/tools/powershell/validate and GET /api/v1/tools/powershell/health.

POST /api/v1/tools/powershell/execute
Content-Type: application/json

Request:
{
  "command": "Get-Service -Name wuauserv",
  "timeout": 30,
  "working_directory": "C:\\Scripts"
}

Response:
{
  "success": true,
  "output": "Name       Status   StartType\n----       ------   ---------\nwuauserv   Running  Automatic",
  "output_json": null,
  "error": null,
  "exit_code": 0,
  "execution_time_ms": 245,
  "timestamp": "2026-04-08T10:30:00Z"
}

POST /api/v1/tools/powershell/execute-script
Content-Type: application/json

Request:
{
  "script_path": "C:\\Scripts\\deploy.ps1",
  "parameters": {
    "Environment": "Production",
    "Verbose": true
  },
  "timeout": 300
}

Response:
{
  "success": true,
  "output": "Deployment started...",
  "output_json": { "status": "started", "deployment_id": "dep-12345" },
  "error": null,
  "exit_code": 0,
  "execution_time_ms": 15230,
  "timestamp": "2026-04-08T10:30:00Z"
}

POST /api/v1/tools/powershell/validate
Content-Type: application/json

Request:
{
  "command": "Remove-Item -Path C:\\* -Recurse"
}

Response:
{
  "allowed": false,
  "blocked_reason": "Command matches blocklist pattern",
  "matched_pattern": "Remove-Item"
}

GET /api/v1/tools/powershell/health
Response:
{
  "status": "healthy",
  "powershell_path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
  "version": "5.1.22621.1"
}

Examples

11.1 Single Command Execution Example

Request:

{
  "command": "Get-Service -Name wuauserv",
  "timeout": 30
}

Response:

{
  "success": true,
  "output": "Name       Status   StartType\n----       ------   ---------\nwuauserv   Running  Automatic",
  "output_json": null,
  "error": null,
  "exit_code": 0,
  "execution_time_ms": 245,
  "timestamp": "2026-04-08T10:30:00Z"
}

11.2 Script Execution Example

Request:

{
  "script_path": "C:\\Scripts\\deploy.ps1",
  "parameters": {
    "Environment": "Production",
    "Verbose": true
  },
  "timeout": 300
}

Response:

{
  "success": true,
  "output": "Deployment started for Production environment...",
  "output_json": {
    "status": "started",
    "deployment_id": "dep-12345",
    "environment": "Production"
  },
  "error": null,
  "exit_code": 0,
  "execution_time_ms": 15230,
  "timestamp": "2026-04-08T10:30:00Z"
}

11.3 Command Validation Example

Request:

{
  "command": "Remove-Item -Path C:\\* -Recurse -Force"
}

Response:

{
  "allowed": false,
  "blocked_reason": "Command matches blocklist pattern",
  "matched_pattern": "Remove-Item"
}

11.4 Error Response Example

Request:

{
  "command": "Start-Sleep -Seconds 120",
  "timeout": 10
}

Response:

{
  "success": false,
  "output": "",
  "output_json": null,
  "error": "Command execution exceeded timeout of 10s",
  "exit_code": -1,
  "execution_time_ms": 10050,
  "timestamp": "2026-04-08T10:30:00Z"
}

11.5 Output Sanitization Example

Input:

Server=localhost;Password=«redacted»
api_key=abc123xyz
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Sanitized Output:

Server=localhost;Password=«redacted»
api_key=[REDACTED]
Bearer [REDACTED]

Security Requirements

12.1 Command Allowlist

REQ-066-076: The tool implements a command allowlist system with the following default patterns:

Allowed Cmdlet Patterns (Default):

• Get-* - Read operations (Get-Process, Get-Service, Get-Content, etc.)
• Test-* - Testing operations (Test-Path, Test-Connection, etc.)
• Select-* - Selection and projection
• Where-* - Filtering operations
• Sort-* - Sorting operations
• Measure-* - Measurement operations
• Compare-* - Comparison operations
• ConvertTo-* - Conversion operations
• Format-* - Formatting operations
• Out-* - Output operations

REQ-066-077: The tool SHALL explicitly block the cmdlets listed below.

Explicitly Blocked Cmdlets:

• Remove-Item - File/directory deletion
• Remove-ItemProperty - Property deletion
• Stop-Process - Process termination
• Stop-Computer - System shutdown
• Restart-Computer - System restart
• Format-Volume - Disk formatting
• Clear-Disk - Disk clearing
• Set-ExecutionPolicy - Execution policy changes (in remote context)
• Invoke-Expression - Dynamic code execution
• iex - Alias for Invoke-Expression

12.2 Command Block Patterns

REQ-066-078: The following regex patterns trigger automatic blocking:

BLOCKED_PATTERNS = [
    r"-exec\s",                           # Shell execution
    r"Invoke-Expression",                 # Dynamic code execution
    r"iex\s",                             # Short form Invoke-Expression
    r"Invoke-Command.*-ScriptBlock",      # Remote script block
    r"Start-Process.*-Verb\s+RunAs",     # Elevated execution
    r"DownloadString",                    # Web download to memory
    r"DownloadFile",                      # File download
    r"WebClient\.Download",               # WebClient download
    r"\[System\.Reflection\.Assembly\]", # Dynamic assembly loading
    r"Add-Type.*-TypeDefinition",         # Dynamic type creation
]

12.3 Output Sanitization

REQ-066-079: Output sanitization removes or masks the following patterns:

SENSITIVE_PATTERNS = [
    (r"(password|passwd|pwd)[=:]\s*\S+", "[REDACTED]"),
    (r"(secret|api_key|apikey|api-key)[=:]\s*\S+", "[REDACTED]"),
    (r"(token|auth_token|access_token)[=:]\s*\S+", "[REDACTED]"),
    (r"(connectionstring|conn_str)[=:]\s*\S+", "[REDACTED]"),
    (r"Bearer\s+\S+", "Bearer [REDACTED]"),
    (r"Basic\s+\S+", "Basic [REDACTED]"),
    (r"-----BEGIN\s+\w+\s+PRIVATE\s+KEY-----.*-----END\s+\w+\s+PRIVATE\s+KEY-----", "[RSA PRIVATE KEY REDACTED]"),
    (r"x-api-key[:\s]+\S+", "x-api-key: «redacted»
]

12.4 Execution Timeout

REQ-066-080: The tool SHALL support the timeout levels below: a Default of 60 seconds for standard commands, an Extended 120 seconds for script execution, and a Custom value of 1-600 seconds when user-specified.

Timeout Enforcement:

• REQ-066-081: Hard timeout kills PowerShell process tree
• REQ-066-082: Soft timeout sends Ctrl+C signal first
• REQ-066-083: Grace period of 5 seconds after soft timeout
• REQ-066-084: Force kill if process doesn't terminate

12.5 Additional Security Measures

1. REQ-066-085: Working Directory Restriction: Optional enforcement of working directory to prevent path traversal
2. REQ-066-086: Output Size Limitation: Maximum 1MB output by default, configurable up to 10MB
3. REQ-066-087: Module Isolation: Prevent loading of untrusted PowerShell modules
4. REQ-066-088: Script Signing: Optional enforcement of signed scripts only
5. REQ-066-089: Audit Logging: All executions logged with timestamp, user, command, and result

Testing Requirements

Test Coverage Requirements

Functional Testing Requirements

Security Testing Requirements

Performance Testing Requirements

Test Environment Requirements

Test Execution Requirements

• REQ-066-149: All unit tests must pass before merge
• REQ-066-150: All integration tests must pass before release
• REQ-066-151: Security tests must pass 100% before deployment
• REQ-066-152: Performance tests must meet thresholds

Testing Requirements

15.1 Unit Tests

15.2 Integration Tests

15.3 Security Tests

15.4 Test Data

# Test commands for allowlist validation
ALLOWLIST_TEST_CASES = [
    ("Get-Process", True),
    ("Get-Service -Name wuauserv", True),
    ("Test-Path C:\\Windows", True),
    ("Select-Object Name, Value", True),
    ("Where-Object {$_.Status -eq 'Running'}", True),
    ("Remove-Item C:\\test.txt", False),
    ("Stop-Process -Name notepad", False),
    ("Invoke-Expression 'malicious'", False),
]

# Test commands for output sanitization
SANITIZATION_TEST_CASES = [
    ("password=secret123", "password=«redacted»
    ("api_key=abc123xyz", "api_key=«redacted»
    ("Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", "Bearer [REDACTED]"),
    ("ConnectionString=Server=localhost;Password=pwd", "ConnectionString=[REDACTED]"),
]

# Test timeout scenarios
TIMEOUT_TEST_CASES = [
    (30, "Start-Sleep -Seconds 10", True),   # Under timeout
    (5, "Start-Sleep -Seconds 10", False),   # Over timeout
    (60, "Get-Process", True),               # Default timeout
]

15.5 Test Framework

# Run unit tests
pytest tests/unit/test_powershell_tool.py -v

# Run integration tests
pytest tests/integration/test_powershell_tool.py -v

# Run security tests
pytest tests/security/test_powershell_sandbox.py -v

# Run all tests with coverage
pytest tests/ -v --cov=src.powershell_tool --cov-report=html

Integration Points

16.1 Tool Orchestration Integration

REQ-066-090: The PowerShell tool integrates with the orchestrata-ultimate tool ecosystem through:

• BaseTool Interface: Implements standard tool contract for lifecycle management
• Async Execution: Full async/await support for concurrent operations
• Structured Logging: JSON logs compatible with orchestrata logging system
• Error Propagation: Standardized error codes and messages

16.2 Security Framework Integration

REQ-066-091: The tool SHALL integrate with the security framework as listed below — PAM++ enforcement of the tool:powershell permission requirement, audit logging of all executions to the central audit system, and support for dynamic allowlist updates from security policy.

• PAM++ Integration: Enforces tool:powershell permission requirement
• Audit Logging: All executions logged to central audit system
• Allowlist Management: Supports dynamic allowlist updates from security policy

16.3 API Server Integration

REQ-066-092: The tool SHALL integrate with the API server as listed below — HTTP endpoints exposing a REST API for remote PowerShell execution, compatibility with the orchestrata authentication framework, and integration with tool server rate limiting.

• HTTP Endpoints: Exposes REST API for remote PowerShell execution
• Authentication: Compatible with orchestrata authentication framework
• Rate Limiting: Integrates with tool server rate limiting

16.4 Monitoring Integration

REQ-066-093: The tool SHALL integrate with monitoring as listed below — export of execution metrics (duration, count, success rate), OpenTelemetry spans for distributed tracing, and a /health endpoint for load balancer integration.

• Metrics: Exports execution metrics (duration, count, success rate)
• Tracing: OpenTelemetry spans for distributed tracing
• Health Checks: /health endpoint for load balancer integration

Success Criteria

17.1 Functional Completion

17.2 Performance Targets

17.3 Security Objectives

17.4 Quality Gates

• [ ] REQ-066-180: All unit tests pass (>85% coverage)
• [ ] REQ-066-181: All integration tests pass (100%)
• [ ] REQ-066-182: All security tests pass (100%)
• [ ] REQ-066-183: Documentation complete and reviewed
• [ ] REQ-066-184: Performance benchmarks met
• [ ] REQ-066-185: Security audit passed
• [ ] REQ-066-186: Compliance check passed

17.5 Operational Readiness

• [ ] REQ-066-187: Deployment scripts tested
• [ ] REQ-066-188: Monitoring dashboards configured
• [ ] REQ-066-189: Runbooks documented
• [ ] REQ-066-190: Incident response procedures defined
• [ ] REQ-066-191: Backup/restore procedures tested

Dependencies

14.1 Python Dependencies

REQ-066-192: The tool SHALL declare the dependencies shown below: python >=3.11, aiofiles >=23.0.0 and pydantic >=2.0.0, with the listed dev extras.

[project.dependencies]
python = ">=3.11"
aiofiles = ">=23.0.0"
pydantic = ">=2.0.0"

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.12.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

14.2 System Requirements

14.3 External Dependencies

Technical Design

10.1 PowerShell Detection Strategy

REQ-066-094: PowerShell binary detection SHALL proceed in the order shown below — C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe (Windows), pwsh in PATH (PowerShell Core), /usr/bin/pwsh (Linux/macOS), then powershell in PATH (Windows fallback) — and SHALL raise E001 if none is found.

1. Check C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe (Windows)
2. Check pwsh in PATH (PowerShell Core)
3. Check /usr/bin/pwsh (Linux/macOS)
4. Check powershell in PATH (Windows fallback)
5. Raise E001 if not found

10.2 Execution Strategy

REQ-066-095: Command execution SHALL proceed in the order shown below: validate the command against the allowlist/blocklist, create a subprocess with timeout, capture stdout and stderr separately, convert output to UTF-8 with error handling, sanitize output for sensitive data, check output size against the limit, and return a structured ToolResult.

1. Validate command against allowlist/blocklist
2. Create subprocess with timeout
3. Capture stdout and stderr separately
4. Convert output to UTF-8 with error handling
5. Sanitize output for sensitive data
6. Check output size against limit
7. Return structured ToolResult

10.3 Script Execution Strategy

REQ-066-096: Script execution SHALL proceed in the order shown below: validate that the script path exists and ends in .ps1, build the parameter string from the parameters dict, execute with powershell.exe -NoProfile -ExecutionPolicy Bypass -File <script> <params>, and apply the same validation and sanitization as command execution.

1. Validate script path exists and ends in .ps1
2. Build parameter string from parameters dict
3. Execute with: powershell.exe -NoProfile -ExecutionPolicy Bypass -File <script> <params>
4. Apply same validation and sanitization as command execution

Governance

Policy Enforcement

REQ-066-097: Execution SHALL require tool:powershell, the allowlist SHALL be enforced, and output SHALL be sanitized.

• Execution requires tool:powershell
• Allowlist enforced
• Output sanitized

Audit Logging

async def log_execution(command: str, result: dict):
    await audit_log({
        "event_type": "powershell_execution",
        "command": command,
        "success": result.success,
        "duration_ms": result.duration_ms
    })

Observability

Logging Requirements

REQ-066-193: Component logging SHALL log all major operations with appropriate log levels, include correlation IDs for request tracing, log performance metrics for critical operations, and log errors with full context for debugging.

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

Metrics Requirements

REQ-066-194: Performance metrics SHALL comprise operation duration histograms, request/error rate counters, resource utilization gauges, and business metrics relevant to the domain.

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

Tracing Requirements

REQ-066-195: Distributed tracing SHALL provide trace propagation across component boundaries, span attributes for domain-specific context, and trace sampling based on operational needs.

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

Alerting Requirements

REQ-066-196: Critical alerts SHALL cover error rate spikes, performance degradation, resource exhaustion, and business metric anomalies.

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

Dashboard Requirements

REQ-066-197: The operational dashboard SHALL present real-time system health, performance trends, error analysis, and resource monitoring.

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

Revision History

Related

• RTM page for 066-powershell-tool
• All specs
• RTM overview
• Gates