PR #3: Add Python DSL API for Argument Matching (#386)

This introduces the Python DSL API surface for specifying argument constraints in security rules. Rule authors can now use match_name and match_position parameters in the calls matcher to define expected keyword and positional argument values. The DSL automatically generates the appropriate JSON IR structures that the Go executor uses for validation during code analysis.

Author: shivasurya

python-dsl/codepathfinder/matchers.py

@@ -4,24 +4,36 @@
 These matchers generate JSON IR for the Go executor.
 """
 
+from typing import Dict, Optional, Union, List, Any
 from .ir import IRType
 
+ArgumentValue = Union[str, int, float, bool, List[Union[str, int, float, bool]]]
+
 
 class CallMatcher:
     """
-    Matches function/method calls in the callgraph.
+    Matches function/method calls with optional argument constraints.
 
     Examples:
         calls("eval")                    # Exact match
         calls("eval", "exec")            # Multiple patterns
         calls("request.*")               # Wildcard (any request.* call)
         calls("*.json")                  # Wildcard (any *.json call)
+        calls("app.run", match_name={"debug": True})  # Keyword argument matching
+        calls("socket.bind", match_position={0: "0.0.0.0"})  # Positional argument matching
     """
 
-    def __init__(self, *patterns: str):
+    def __init__(
+        self,
+        *patterns: str,
+        match_position: Optional[Dict[int, ArgumentValue]] = None,
+        match_name: Optional[Dict[str, ArgumentValue]] = None,
+    ):
         """
         Args:
             *patterns: Function names to match. Supports wildcards (*).
+            match_position: Match positional arguments by index {position: value}
+            match_name: Match named/keyword arguments {name: value}
 
         Raises:
             ValueError: If no patterns provided or pattern is empty
@@ -34,6 +46,31 @@ def __init__(self, *patterns: str):
 
         self.patterns = list(patterns)
         self.wildcard = any("*" in p for p in patterns)
+        self.match_position = match_position or {}
+        self.match_name = match_name or {}
+
+    def _make_constraint(self, value: ArgumentValue) -> Dict[str, Any]:
+        """
+        Create an argument constraint from a value.
+
+        Automatically detects wildcard characters in string values.
+
+        Args:
+            value: The argument value or list of values
+
+        Returns:
+            Dictionary with 'value' and 'wildcard' keys
+        """
+        # Check if wildcard characters are present in string values
+        has_wildcard = False
+        if isinstance(value, str) and ("*" in value or "?" in value):
+            has_wildcard = True
+        elif isinstance(value, list):
+            has_wildcard = any(
+                isinstance(v, str) and ("*" in v or "?" in v) for v in value
+            )
+
+        return {"value": value, "wildcard": has_wildcard or self.wildcard}
 
     def to_ir(self) -> dict:
         """
@@ -44,16 +81,34 @@ def to_ir(self) -> dict:
                 "type": "call_matcher",
                 "patterns": ["eval", "exec"],
                 "wildcard": false,
-                "match_mode": "any"  # matches if ANY pattern matches
+                "matchMode": "any",
+                "keywordArgs": { "debug": {"value": true, "wildcard": false} },
+                "positionalArgs": { "0": {"value": "0.0.0.0", "wildcard": false} }
             }
         """
-        return {
+        ir = {
             "type": IRType.CALL_MATCHER.value,
             "patterns": self.patterns,
             "wildcard": self.wildcard,
-            "match_mode": "any",
+            "matchMode": "any",
         }
 
+        # Add positional argument constraints
+        if self.match_position:
+            ir["positionalArgs"] = {
+                str(pos): self._make_constraint(value)
+                for pos, value in self.match_position.items()
+            }
+
+        # Add keyword argument constraints
+        if self.match_name:
+            ir["keywordArgs"] = {
+                name: self._make_constraint(value)
+                for name, value in self.match_name.items()
+            }
+
+        return ir
+
     def __repr__(self) -> str:
         patterns_str = ", ".join(f'"{p}"' for p in self.patterns)
         return f"calls({patterns_str})"
@@ -105,12 +160,18 @@ def __repr__(self) -> str:
 
 
 # Public API
-def calls(*patterns: str) -> CallMatcher:
+def calls(
+    *patterns: str,
+    match_position: Optional[Dict[int, ArgumentValue]] = None,
+    match_name: Optional[Dict[str, ArgumentValue]] = None,
+) -> CallMatcher:
     """
-    Create a matcher for function/method calls.
+    Create a matcher for function/method calls with optional argument constraints.
 
     Args:
         *patterns: Function names to match (supports wildcards)
+        match_position: Match positional arguments by index {position: value}
+        match_name: Match named/keyword arguments {name: value}
 
     Returns:
         CallMatcher instance
@@ -124,8 +185,23 @@ def calls(*patterns: str) -> CallMatcher:
 
         >>> calls("urllib.*")
         calls("urllib.*")
+
+        >>> calls("app.run", match_name={"debug": True})
+        calls("app.run")
+
+        >>> calls("socket.bind", match_position={0: "0.0.0.0"})
+        calls("socket.bind")
+
+        >>> calls("yaml.load", match_position={1: ["Loader", "UnsafeLoader"]})
+        calls("yaml.load")
+
+        >>> calls("chmod", match_position={1: "0o7*"})
+        calls("chmod")
+
+        >>> calls("app.run", match_position={0: "localhost"}, match_name={"debug": True})
+        calls("app.run")
     """
-    return CallMatcher(*patterns)
+    return CallMatcher(*patterns, match_position=match_position, match_name=match_name)
 
 
 def variable(pattern: str) -> VariableMatcher:

python-dsl/tests/test_matchers.py

@@ -55,7 +55,7 @@ def test_to_ir(self):
         assert ir["type"] == "call_matcher"
         assert ir["patterns"] == ["eval", "exec"]
         assert ir["wildcard"] is False
-        assert ir["match_mode"] == "any"
+        assert ir["matchMode"] == "any"
 
     def test_to_ir_wildcard(self):
         """Test CallMatcher.to_ir() with wildcard."""
@@ -126,3 +126,217 @@ def test_repr(self):
         """Test VariableMatcher.__repr__() output."""
         matcher = variable("user_input")
         assert repr(matcher) == 'variable("user_input")'
+
+
+class TestCallMatcherKeywordArguments:
+    """Test suite for keyword argument matching (match_name)."""
+
+    def test_single_keyword_arg_string(self):
+        """Test matching single keyword argument with string value."""
+        matcher = calls("app.run", match_name={"debug": "True"})
+        ir = matcher.to_ir()
+
+        assert "keywordArgs" in ir
+        assert "debug" in ir["keywordArgs"]
+        assert ir["keywordArgs"]["debug"]["value"] == "True"
+        assert ir["keywordArgs"]["debug"]["wildcard"] is False
+
+    def test_single_keyword_arg_boolean(self):
+        """Test matching keyword argument with boolean value."""
+        matcher = calls("app.run", match_name={"debug": True})
+        ir = matcher.to_ir()
+
+        assert ir["keywordArgs"]["debug"]["value"] is True
+
+    def test_single_keyword_arg_number(self):
+        """Test matching keyword argument with numeric value."""
+        matcher = calls("app.listen", match_name={"port": 8080})
+        ir = matcher.to_ir()
+
+        assert ir["keywordArgs"]["port"]["value"] == 8080
+
+    def test_multiple_keyword_args(self):
+        """Test matching multiple keyword arguments."""
+        matcher = calls(
+            "app.run", match_name={"host": "0.0.0.0", "port": 5000, "debug": True}
+        )
+        ir = matcher.to_ir()
+
+        assert len(ir["keywordArgs"]) == 3
+        assert ir["keywordArgs"]["host"]["value"] == "0.0.0.0"
+        assert ir["keywordArgs"]["port"]["value"] == 5000
+        assert ir["keywordArgs"]["debug"]["value"] is True
+
+    def test_keyword_arg_or_logic(self):
+        """Test matching keyword argument with multiple values (OR logic)."""
+        matcher = calls(
+            "yaml.load", match_name={"Loader": ["Loader", "UnsafeLoader", "FullLoader"]}
+        )
+        ir = matcher.to_ir()
+
+        assert isinstance(ir["keywordArgs"]["Loader"]["value"], list)
+        assert len(ir["keywordArgs"]["Loader"]["value"]) == 3
+
+
+class TestCallMatcherPositionalArguments:
+    """Test suite for positional argument matching (match_position)."""
+
+    def test_single_positional_arg(self):
+        """Test matching single positional argument."""
+        matcher = calls("socket.bind", match_position={0: "0.0.0.0"})
+        ir = matcher.to_ir()
+
+        assert "positionalArgs" in ir
+        assert "0" in ir["positionalArgs"]  # JSON keys are strings
+        assert ir["positionalArgs"]["0"]["value"] == "0.0.0.0"
+
+    def test_multiple_positional_args(self):
+        """Test matching multiple positional arguments."""
+        matcher = calls("chmod", match_position={0: "/tmp/file", 1: 0o777})
+        ir = matcher.to_ir()
+
+        assert len(ir["positionalArgs"]) == 2
+        assert ir["positionalArgs"]["0"]["value"] == "/tmp/file"
+        assert ir["positionalArgs"]["1"]["value"] == 0o777
+
+    def test_positional_arg_or_logic(self):
+        """Test matching positional argument with multiple values."""
+        matcher = calls("open", match_position={1: ["w", "a", "w+", "a+"]})
+        ir = matcher.to_ir()
+
+        assert isinstance(ir["positionalArgs"]["1"]["value"], list)
+        assert len(ir["positionalArgs"]["1"]["value"]) == 4
+
+
+class TestCallMatcherCombinedArguments:
+    """Test suite for combined positional and keyword argument matching."""
+
+    def test_both_positional_and_keyword(self):
+        """Test matching both positional and keyword arguments."""
+        matcher = calls(
+            "app.run",
+            match_position={0: "localhost"},
+            match_name={"debug": True, "port": 5000},
+        )
+        ir = matcher.to_ir()
+
+        assert "positionalArgs" in ir
+        assert "keywordArgs" in ir
+        assert ir["positionalArgs"]["0"]["value"] == "localhost"
+        assert ir["keywordArgs"]["debug"]["value"] is True
+        assert ir["keywordArgs"]["port"]["value"] == 5000
+
+
+class TestCallMatcherWildcardMatching:
+    """Test suite for wildcard matching in argument values."""
+
+    def test_wildcard_in_string_value(self):
+        """Test automatic wildcard detection in string values."""
+        matcher = calls("chmod", match_position={1: "0o7*"})
+        ir = matcher.to_ir()
+
+        # Wildcard should be auto-detected from '*' in value
+        assert ir["positionalArgs"]["1"]["wildcard"] is True
+
+    def test_wildcard_in_list_value(self):
+        """Test wildcard detection in list of values."""
+        matcher = calls("open", match_position={1: ["w*", "a*"]})
+        ir = matcher.to_ir()
+
+        assert ir["positionalArgs"]["1"]["wildcard"] is True
+
+    def test_explicit_wildcard_flag(self):
+        """Test explicit wildcard flag propagation."""
+        matcher = calls("app.*", match_name={"host": "192.168.1.1"})
+        ir = matcher.to_ir()
+
+        assert ir["wildcard"] is True
+        # Wildcard in function pattern propagates to argument constraints
+        assert ir["keywordArgs"]["host"]["wildcard"] is True
+
+
+class TestCallMatcherBackwardCompatibility:
+    """Test suite for backward compatibility with existing rules."""
+
+    def test_no_arguments_specified(self):
+        """Test that rules without argument constraints still work."""
+        matcher = calls("eval")
+        ir = matcher.to_ir()
+
+        # Should not have argument constraint fields
+        assert "positionalArgs" not in ir
+        assert "keywordArgs" not in ir
+
+    def test_empty_argument_dicts(self):
+        """Test that empty argument dicts don't add IR fields."""
+        matcher = calls("eval", match_position={}, match_name={})
+        ir = matcher.to_ir()
+
+        # Empty dicts should not add fields
+        assert "positionalArgs" not in ir
+        assert "keywordArgs" not in ir
+
+
+class TestCallMatcherIRSerialization:
+    """Test suite for JSON serialization of generated IR."""
+
+    def test_complex_ir_serialization(self):
+        """Test that complex IR can be serialized to JSON."""
+        import json
+
+        matcher = calls(
+            "app.run",
+            match_position={0: "0.0.0.0"},
+            match_name={"debug": True, "port": 5000, "host": ["localhost", "0.0.0.0"]},
+        )
+        ir = matcher.to_ir()
+
+        # Should be JSON-serializable
+        json_str = json.dumps(ir)
+        reconstructed = json.loads(json_str)
+
+        assert reconstructed["type"] == "call_matcher"
+        assert reconstructed["keywordArgs"]["debug"]["value"] is True
+
+    def test_special_values_serialization(self):
+        """Test serialization of special Python values."""
+        import json
+
+        matcher = calls("chmod", match_position={1: 0o777})
+        ir = matcher.to_ir()
+
+        json_str = json.dumps(ir)
+        reconstructed = json.loads(json_str)
+
+        # Octal should be serialized as decimal integer
+        assert reconstructed["positionalArgs"]["1"]["value"] == 511
+
+
+class TestCallMatcherEdgeCases:
+    """Test suite for edge cases and error conditions."""
+
+    def test_none_values_handled(self):
+        """Test that None match_name/match_position are handled."""
+        matcher = calls("eval", match_name=None, match_position=None)
+        ir = matcher.to_ir()
+
+        assert "keywordArgs" not in ir
+        assert "positionalArgs" not in ir
+
+    def test_mixed_value_types(self):
+        """Test mixing different value types in same rule."""
+        matcher = calls(
+            "config.set",
+            match_name={
+                "timeout": 30,  # int
+                "enabled": True,  # bool
+                "host": "localhost",  # string
+                "retry": 5.5,  # float
+            },
+        )
+        ir = matcher.to_ir()
+
+        assert ir["keywordArgs"]["timeout"]["value"] == 30
+        assert ir["keywordArgs"]["enabled"]["value"] is True
+        assert ir["keywordArgs"]["host"]["value"] == "localhost"
+        assert ir["keywordArgs"]["retry"]["value"] == 5.5