Skip to content

Build and run agents you can see, understand and trust.

fix(tool): match Bash permission rules against every subcommand of a compound command (#3513)

Kiko03013ca8dc309572
diff --git a/src/agentscope/permission/_engine.py b/src/agentscope/permission/_engine.py
index 434acfd10..a15e8a44a 100644
--- a/src/agentscope/permission/_engine.py
+++ b/src/agentscope/permission/_engine.py
@@ -763,14 +763,20 @@ class PermissionEngine:
ALLOW decision if a rule matches, None otherwise
"""
rules = self.context.allow_rules.get(tool.name, [])
- for rule in rules:
- if await self._rule_matches(tool, rule, input_data):
- return PermissionDecision(
- behavior=PermissionBehavior.ALLOW,
- message=f"Permission granted for {tool.name}",
- updated_input=input_data,
- )
- return None
+ inputs = tool.get_permission_inputs(input_data)
+ if not inputs:
+ return None
+ for operation in inputs:
+ for rule in rules:
+ if await self._rule_matches(tool, rule, operation):
+ break
+ else:
+ return None
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message=f"Permission granted for {tool.name}",
+ updated_input=input_data,
+ )
async def _rule_matches(
self,
@@ -803,11 +809,21 @@ class PermissionEngine:
# ``_execute_async_or_sync_func`` keeps backward compatibility
# with third-party tools that still override match_rule with a
# sync ``def`` (the framework's signature is now ``async def``).
- return await _execute_async_or_sync_func(
- tool.match_rule,
- rule.rule_content,
- input_data,
+ # Restrictions apply to any operation, while allow coverage is
+ # aggregated across all operations by _check_allow_rules.
+ inputs = (
+ tool.get_permission_inputs(input_data)
+ if rule.behavior != PermissionBehavior.ALLOW
+ else [input_data]
)
+ for operation in inputs:
+ if await _execute_async_or_sync_func(
+ tool.match_rule,
+ rule.rule_content,
+ operation,
+ ):
+ return True
+ return False
async def _generate_suggestions(
self,
diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.py
index 3ea982e45..e8e78f756 100644
--- a/src/agentscope/tool/_base.py
+++ b/src/agentscope/tool/_base.py
@@ -319,6 +319,19 @@ class ToolBase(ABC):
"""
return self.is_read_only
+ def get_permission_inputs(
+ self,
+ tool_input: dict[str, Any],
+ ) -> list[dict[str, Any]]:
+ """Return the inputs that must each be covered by permission rules.
+
+ Compound tools may split an invocation into individual operations.
+ Deny and ask rules apply when any operation matches; allow rules
+ must cover every operation. Safety checks still receive the
+ original input. The returned list must not be empty.
+ """
+ return [tool_input]
+
async def match_rule(
self,
rule_content: str | None,
diff --git a/src/agentscope/tool/_builtin/_bash.py b/src/agentscope/tool/_builtin/_bash.py
index ee493b0a2..316bc0d39 100644
--- a/src/agentscope/tool/_builtin/_bash.py
+++ b/src/agentscope/tool/_builtin/_bash.py
@@ -393,12 +393,23 @@ easier to review tool calls and give permission.
message=f"Execute bash command: {command}",
)
+ def get_permission_inputs(
+ self,
+ tool_input: dict[str, Any],
+ ) -> list[dict[str, Any]]:
+ """Return complete subcommands for permission rule evaluation."""
+ command = tool_input.get("command", "")
+ return [
+ {**tool_input, "command": subcommand}
+ for subcommand in self._bash_parser.split_into_subcommands(command)
+ ]
+
async def match_rule(
self,
rule_content: str | None,
tool_input: dict[str, Any],
) -> bool:
- r"""Match Bash command using regex-based wildcard matching.
+ r"""Match one Bash operation using regex-based wildcard matching.
Implements wildcard matching with escape sequences:
- Supports \* for literal asterisk and \\ for literal backslash
@@ -409,12 +420,16 @@ easier to review tool calls and give permission.
- If rule_content is None, matches all invocations
(tool-name-level rule)
+ Matches the supplied operation without parsing or splitting it.
+ The permission engine uses :meth:`get_permission_inputs` to split
+ compound invocations and aggregate matches by rule behavior.
+
Args:
rule_content: The command pattern to match, or None to match all
- tool_input: Must contain a "command" key with the command string
+ tool_input: Must contain a "command" key with the operation string
Returns:
- True if pattern matches the command
+ True if the pattern matches the supplied operation
"""
# None = tool-name-level rule, matches everything
if rule_content is None:
diff --git a/src/agentscope/tool/_builtin/_bash_parser.py b/src/agentscope/tool/_builtin/_bash_parser.py
index 23c41be9a..ea27e536b 100644
--- a/src/agentscope/tool/_builtin/_bash_parser.py
+++ b/src/agentscope/tool/_builtin/_bash_parser.py
@@ -172,25 +172,20 @@ class BashCommandParser:
if ">" in cmd:
return False
- # Check if it's a compound command
- if any(op in cmd for op in ["&&", "||", ";", "|"]):
- # Split into subcommands and check each one
- try:
- tree = self.parser.parse(bytes(cmd, "utf8"))
- root = tree.root_node
- subcommands = self.split_compound_command(root, cmd)
-
- # All subcommands must be read-only
- for subcmd in subcommands:
- if not self._is_single_command_read_only(subcmd.strip()):
- return False
- return True
- except Exception:
- # If parsing fails, be conservative
+ # Use the same boundaries as rule matching, including newlines and
+ # background operators, so the read-only fast path cannot skip them.
+ try:
+ tree = self.parser.parse(bytes(cmd, "utf8"))
+ if tree.root_node.has_error:
return False
-
- # Single command - check directly
- return self._is_single_command_read_only(cmd)
+ subcommands = self.split_compound_command(tree.root_node, cmd)
+ return all(
+ self._is_single_command_read_only(subcmd.strip())
+ for subcmd in subcommands
+ )
+ except Exception:
+ # If parsing fails, be conservative.
+ return False
def _is_single_command_read_only(self, cmd: str) -> bool:
"""Check if a single (non-compound) command is read-only.
@@ -510,9 +505,14 @@ class BashCommandParser:
if not command or not command.strip():
return []
- # Parse command to AST
- tree = self.parser.parse(bytes(command, "utf8"))
+ # Do not suggest broad allow rules from an incomplete parse.
+ try:
+ tree = self.parser.parse(bytes(command, "utf8"))
+ except Exception:
+ return []
root = tree.root_node
+ if root.has_error:
+ return []
# Split compound commands
subcommands = self.split_compound_command(root, command)
@@ -532,6 +532,32 @@ class BashCommandParser:
return prefixes
+ def split_into_subcommands(self, command: str) -> List[str]:
+ """Parse a command string and split it into subcommands.
+
+ Convenience wrapper around :meth:`split_compound_command` that
+ parses ``command`` first. Returns ``[command]`` when the command
+ is empty or no subcommands can be extracted.
+
+ Args:
+ command (`str`):
+ The bash command string (may be compound)
+
+ Returns:
+ `List[str]`:
+ List of individual subcommands, e.g.,
+ ``["git status", "npm install"]`` for
+ ``"git status && npm install"``
+ """
+ if not command or not command.strip():
+ return [command]
+ try:
+ tree = self.parser.parse(bytes(command, "utf8"))
+ return self.split_compound_command(tree.root_node, command)
+ except Exception:
+ # Keep the original input for the tool's safety check.
+ return [command]
+
def split_compound_command(self, root: Node, command: str) -> List[str]:
"""Split compound commands using tree-sitter for precise parsing.
@@ -547,23 +573,32 @@ class BashCommandParser:
`List[str]`:
List of individual subcommands
"""
+ if root.has_error:
+ return [command]
+ source = command.encode("utf8")
subcommands = []
def extract_commands(node: Node) -> None:
- """Recursively extract commands from AST."""
- if node.type == "command":
- # Extract command text
- cmd_text = command[node.start_byte : node.end_byte]
- subcommands.append(cmd_text)
- elif node.type in ["list", "pipeline", "command_list"]:
- # Recursively process compound structures
- for child in node.children:
- if child.type not in ["&&", "||", ";", "|", "|&"]:
- extract_commands(child)
- else:
- # Continue traversing
- for child in node.children:
+ """Split lists and pipelines without discarding shell syntax."""
+ if node.type in ["program", "list", "pipeline", "command_list"]:
+ for child in node.named_children:
extract_commands(child)
+ return
+ if node.type == "comment":
+ return
+ if node.type == "redirected_statement":
+ body = node.child_by_field_name("body")
+ if body is not None and body.type in ["list", "pipeline"]:
+ extract_commands(body)
+ # Trailing redirections on a list or pipeline belong
+ # to its last command, not to the entire structure.
+ subcommands[-1] += source[
+ body.end_byte : node.end_byte
+ ].decode("utf8")
+ return
+ subcommands.append(
+ source[node.start_byte : node.end_byte].decode("utf8"),
+ )
extract_commands(root)
return subcommands if subcommands else [command]
@@ -936,6 +971,8 @@ class BashCommandParser:
try:
tree = self.parser.parse(bytes(command, "utf8"))
+ if tree.root_node.has_error:
+ return "Command parsing failed, cannot verify safety"
return self._walk_for_dangerous_nodes(tree.root_node)
except Exception:
# If parsing fails, be conservative and require review
diff --git a/tests/permission_bash_parser_test.py b/tests/permission_bash_parser_test.py
index 3c493a74d..720ee15dc 100644
--- a/tests/permission_bash_parser_test.py
+++ b/tests/permission_bash_parser_test.py
@@ -8,6 +8,81 @@ from agentscope.tool._builtin._bash_parser import BashCommandParser
from agentscope.tool import Bash
+class BashPermissionSplitTest(unittest.TestCase):
+ """Verify lossless permission boundaries without executing a shell."""
+
+ def test_subshell_redirection_keeps_scope(self) -> None:
+ """Keep a redirected subshell intact as a single operation."""
+ command = "(cat public.txt && cat public.txt) > private.txt"
+ parser = BashCommandParser()
+ self.assertEqual(parser.split_into_subcommands(command), [command])
+ self.assertEqual(
+ parser.split_into_subcommands(
+ "git status && "
+ "(cat public.txt && cat public.txt) > private.txt",
+ ),
+ ["git status", command],
+ )
+
+ def test_split_preserves_shell_operations(self) -> None:
+ """Keep Unicode, redirects, assignments, and quoted operators."""
+ cases = [
+ ("", [""]),
+ (" ", [" "]),
+ (
+ "git add '中文.txt' && git commit -m update",
+ ["git add '中文.txt'", "git commit -m update"],
+ ),
+ (
+ "git add 'ééééé' && curl git -o output.txt",
+ ["git add 'ééééé'", "curl git -o output.txt"],
+ ),
+ (
+ "cat public.txt && cat public.txt > private.txt",
+ ["cat public.txt", "cat public.txt > private.txt"],
+ ),
+ (
+ "git status && > output.txt",
+ ["git status", "> output.txt"],
+ ),
+ (
+ "cat a | cat b > output.txt",
+ ["cat a", "cat b > output.txt"],
+ ),
+ (
+ "git status && X=hello",
+ ["git status", "X=hello"],
+ ),
+ (
+ "git commit -m 'a && b | c' && git status",
+ ["git commit -m 'a && b | c'", "git status"],
+ ),
+ ("git status # comment", ["git status"]),
+ ("git status &&", ["git status &&"]),
+ (
+ "cat <<EOF\nhello\nEOF\ngit status",
+ ["cat <<EOF\nhello\nEOF", "git status"],
+ ),
+ ]
+ parser = BashCommandParser()
+ self.assertEqual(
+ [parser.split_into_subcommands(command) for command, _ in cases],
+ [expected for _, expected in cases],
+ )
+
+ def test_all_command_separators(self) -> None:
+ """Recognize every list and pipeline separator."""
+ parser = BashCommandParser()
+ for separator in (" && ", " || ", "; ", " | ", " |& ", "\n", " & "):
+ command = separator.join(["git status", "curl example.com"])
+ with self.subTest(separator=separator):
+ self.assertEqual(
+ parser.split_into_subcommands(command),
+ ["git status", "curl example.com"],
+ )
+ self.assertEqual(parser.is_read_only_command(command), False)
+
+
@unittest.skipIf(
sys.platform == "win32",
"Bash tool is not supported on Windows",
diff --git a/tests/permission_engine_test.py b/tests/permission_engine_test.py
index 14294fa2c..19d3f6a7e 100644
--- a/tests/permission_engine_test.py
+++ b/tests/permission_engine_test.py
@@ -11,6 +11,7 @@ import sys
import tempfile
import unittest
from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import patch
from agentscope.permission import (
PermissionEngine,
@@ -29,6 +30,191 @@ from agentscope.tool import (
)
+class PermissionEngineCompoundBashTest(IsolatedAsyncioTestCase):
+ """Exercise compound permissions without running shell commands."""
+
+ async def test_parser_failure_requires_confirmation(self) -> None:
+ """A parser exception must yield a safety ASK, not raw-prefix ALLOW."""
+ engine = PermissionEngine(PermissionContext())
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content="git:*",
+ behavior=PermissionBehavior.ALLOW,
+ source="test",
+ ),
+ )
+ with patch("agentscope.tool._builtin._bash_parser.Parser") as parser:
+ parser.return_value.parse.side_effect = ValueError(
+ "Parser unavailable",
+ )
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": "git status && curl example.com"},
+ )
+ self.assertEqual(
+ decision,
+ PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ message="Permission required: Command parsing failed, "
+ "cannot verify safety",
+ decision_reason="Safety check: command contains dynamic "
+ "expansion that cannot be statically analyzed",
+ suggested_rules=[],
+ bypass_immune=True,
+ ),
+ )
+
+ async def test_restrictions_match_any_operation(self) -> None:
+ """Deny and ask rules retain priority in every permission mode."""
+ for mode in PermissionMode:
+ for behavior in (PermissionBehavior.DENY, PermissionBehavior.ASK):
+ engine = PermissionEngine(PermissionContext(mode=mode))
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content="git:*",
+ behavior=PermissionBehavior.ALLOW,
+ source="test",
+ ),
+ )
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content="git push:*",
+ behavior=behavior,
+ source="test",
+ ),
+ )
+ expected = (
+ PermissionBehavior.DENY
+ if mode == PermissionMode.DONT_ASK
+ else behavior
+ )
+ for separator in (" && ", " || ", "; ", " | ", "\n", " & "):
+ for commands in (
+ ["git push origin main", "git status"],
+ ["git status", "git push origin main"],
+ ):
+ command = separator.join(commands)
+ with self.subTest(
+ mode=mode,
+ behavior=behavior,
+ command=command,
+ ):
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": command},
+ )
+ self.assertEqual(decision.behavior, expected)
+
+ async def test_allow_rules_cover_all_operations(self) -> None:
+ """Different allow rules may jointly cover a compound invocation."""
+ engine = PermissionEngine(PermissionContext())
+ for pattern in ("git:*", "npm:*", "install"):
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content=pattern,
+ behavior=PermissionBehavior.ALLOW,
+ source="test",
+ ),
+ )
+ for command in (
+ "git add . && git commit",
+ "npm install && pip install",
+ "git add . && npm test",
+ "npm test && git add .",
+ "git add '中文.txt' && git commit -m update",
+ "git commit -m 'a && b' && git status",
+ ):
+ tool_input = {"command": command, "description": "Test coverage"}
+ with self.subTest(command=command):
+ self.assertEqual(
+ await engine.check_permission(Bash(), tool_input),
+ PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="Permission granted for Bash",
+ updated_input=tool_input,
+ ),
+ )
+
+ async def test_uncovered_operations_require_confirmation(self) -> None:
+ """No prefix, wildcard, or substring may hide another operation."""
+ cases = [
+ ("git:*", "git status && echo pwned > /tmp/pwned"),
+ (
+ "git commit:*",
+ "git commit -m 'x' && curl http://evil.com",
+ ),
+ ("install", "npm install && rm -rf /tmp/data"),
+ ("git *", "git add . && echo hi"),
+ ("git:*", "git log | tee /tmp/log"),
+ ("git:*", "git status && curl example.com"),
+ ("git *", "git status | curl example.com"),
+ ("install", "npm install && curl example.com"),
+ ("git:*", "git add 'ééééé' && curl git -o output.txt"),
+ ("git:*", "git status && > output.txt"),
+ ("git:*", "git status && X=hello"),
+ ("git:*", "git status\ncurl example.com"),
+ ("git:*", "git status & curl example.com"),
+ (
+ "cat *public.txt",
+ "cat public.txt && cat public.txt > private.txt",
+ ),
+ (
+ "cat *public.txt",
+ "cat public.txt | cat public.txt > private.txt",
+ ),
+ ]
+ for pattern, command in cases:
+ with self.subTest(pattern=pattern, command=command):
+ engine = PermissionEngine(PermissionContext())
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content=pattern,
+ behavior=PermissionBehavior.ALLOW,
+ source="test",
+ ),
+ )
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": command},
+ )
+ self.assertEqual(decision.behavior, PermissionBehavior.ASK)
+
+ async def test_safety_checks_keep_original_command(self) -> None:
+ """Whole-command safety checks must precede any allow coverage."""
+ for command in (
+ "git status &&",
+ "git status && git add 'unterminated",
+ "git status && git add $(pwd)",
+ "git status && git log > .env",
+ "git status && for x in a; do git add x; done",
+ ):
+ for mode, expected in (
+ (PermissionMode.DEFAULT, PermissionBehavior.ASK),
+ (PermissionMode.DONT_ASK, PermissionBehavior.DENY),
+ (PermissionMode.BYPASS, PermissionBehavior.ALLOW),
+ ):
+ with self.subTest(mode=mode, command=command):
+ engine = PermissionEngine(PermissionContext(mode=mode))
+ engine.add_rule(
+ PermissionRule(
+ tool_name="Bash",
+ rule_content=None,
+ behavior=PermissionBehavior.ALLOW,
+ source="test",
+ ),
+ )
+ decision = await engine.check_permission(
+ Bash(),
+ {"command": command},
+ )
+ self.assertEqual(decision.behavior, expected)
+
+
class PermissionEngineRulePriorityTest(IsolatedAsyncioTestCase):
"""Test cases for rule priority and decision-making."""