程序包 io.agentscope.core.tool.coding

接口 CommandValidator

所有已知实现类:

UnixCommandValidator, WindowsCommandValidator

public interface CommandValidator

Interface for validating shell commands before execution.

Validation Flow:

1. Extract Executable: Parse command to extract the executable name
2. Whitelist Check: If whitelist is empty/null, allow all (backward compatible)
3. Multi-Command Detection: Reject if command contains multiple command separators
4. Relative Path Safety: For commands starting with ./ or .\, verify path doesn't escape current directory
5. Whitelist Validation: Reject if executable not in whitelist

Built-in implementations:

• UnixCommandValidator - For Unix/Linux/macOS systems
• WindowsCommandValidator - For Windows systems

另请参阅:

• UnixCommandValidator
• WindowsCommandValidator
• ShellCommandTool

嵌套类概要

嵌套类

修饰符和类型	接口	说明
static class	CommandValidator.ValidationResult	Result of command validation.

方法概要

修饰符和类型	方法	说明
boolean	containsMultipleCommands(String command)	Check if the command contains multiple command separators.
String	extractExecutable(String command)	Extract the executable name from a command string.
default boolean	isPathWithinCurrentDirectory(String path)	Validate if a relative path (starting with ./ or .\) stays within the current directory.
CommandValidator.ValidationResult	validate(String command, Set<String> allowedCommands)	Validate if a command is allowed to execute.

方法详细资料

validate

CommandValidator.ValidationResult validate(String command,
 Set<String> allowedCommands)

Validate if a command is allowed to execute.

Validation checks (in order):

1. Extract executable name
2. If whitelist is null/empty → allow (backward compatible)
3. Check for multiple command separators → reject if found
4. Check relative path safety → reject if escapes current directory
5. Check whitelist → reject if not in whitelist

参数:

command - The command string to validate

allowedCommands - Set of allowed command executables (null or empty means allow all)

返回:

ValidationResult containing the validation outcome

extractExecutable

String extractExecutable(String command)

Extract the executable name from a command string.

Extraction process:

• Remove surrounding quotes (if present)
• Extract first token (before space/tab)
• Remove directory path (platform-specific)
• Remove file extensions (platform-specific)

参数:

command - The command string

返回:

The executable name, or empty string if extraction fails

containsMultipleCommands

boolean containsMultipleCommands(String command)

Check if the command contains multiple command separators.

Uses platform-specific detection:

• Unix: &, |, ;, newline (escape: \)
• Windows: &, |, newline (escape: ^)

Separators within quotes are ignored.

参数:

command - The command string

返回:

true if multiple commands are detected, false otherwise

isPathWithinCurrentDirectory

default boolean isPathWithinCurrentDirectory(String path)

Validate if a relative path (starting with ./ or .\) stays within the current directory.

Algorithm: Uses depth-tracking to detect directory traversal:

1. Normalize path separators (\ → /)
2. Remove leading ./
3. Split by / into segments
4. Track depth: .. decreases depth, normal dirs increase depth
5. If depth < 0 at any point → path escapes current directory

Examples:

• ./script.sh → ✅ allowed (depth: 0→1)
• ./subdir/script.sh → ✅ allowed (depth: 0→1→2)
• ./a/b/../c/script.sh → ✅ allowed (depth: 0→1→2→1→2)
• ./../script.sh → ❌ rejected (depth: 0→-1)
• ./../../script.sh → ❌ rejected (depth: 0→-1→-2)

Supports both Unix (/) and Windows (\) path separators.

参数:

path - The path to validate

返回:

true if the path stays within current directory, false if it escapes