add flavored scopes

CHANGELOG.md

@@ -10,6 +10,7 @@
 - Add a CAPE file format and CAPE-based dynamic feature extraction to scripts/show-features.py #1566 @yelhamer
 - Add a new process scope for the dynamic analysis flavor #1517 @yelhamer
 - Add a new thread scope for the dynamic analysis flavor #1517 @yelhamer
+- Add support for flavor-based rule scopes @yelhamer
 
 ### Breaking Changes
 - Update Metadata type in capa main [#1411](https://github.com/mandiant/capa/issues/1411) [@Aayush-Goel-04](https://github.com/aayush-goel-04) @manasghandat

capa/rules/__init__.py

@@ -91,6 +91,42 @@ class Scope(str, Enum):
 GLOBAL_SCOPE = "global"
 
 
+# these literals are used to check if the flavor
+# of a rule is correct.
+STATIC_SCOPES = (
+    FILE_SCOPE,
+    GLOBAL_SCOPE,
+    FUNCTION_SCOPE,
+    BASIC_BLOCK_SCOPE,
+    INSTRUCTION_SCOPE,
+)
+DYNAMIC_SCOPES = (
+    FILE_SCOPE,
+    GLOBAL_SCOPE,
+    PROCESS_SCOPE,
+    THREAD_SCOPE,
+)
+
+
+class Flavor:
+    def __init__(self, static: str, dynamic: str, definition=""):
+        self.static = static if static in STATIC_SCOPES else ""
+        self.dynamic = dynamic if dynamic in DYNAMIC_SCOPES else ""
+        self.definition = definition
+
+        if static != self.static:
+            raise InvalidRule(f"'{static}' is not a valid static scope")
+        if dynamic != self.dynamic:
+            raise InvalidRule(f"'{dynamic}' is not a valid dynamic scope")
+        if (not self.static) and (not self.dynamic):
+            raise InvalidRule("rule must have at least one scope specified")
+
+    def __eq__(self, scope) -> bool:
+        # Flavors aren't supposed to be compared directly.
+        assert isinstance(scope, Scope) or isinstance(scope, str)
+        return (scope == self.static) or (scope == self.dynamic)
+
+
 SUPPORTED_FEATURES: Dict[str, Set] = {
     GLOBAL_SCOPE: {
         # these will be added to other scopes, see below.
@@ -215,20 +251,31 @@ def __repr__(self):
         return str(self)
 
 
-def ensure_feature_valid_for_scope(scope: str, feature: Union[Feature, Statement]):
+def ensure_feature_valid_for_scope(scope: Union[str, Flavor], feature: Union[Feature, Statement]):
     # if the given feature is a characteristic,
     # check that is a valid characteristic for the given scope.
+    supported_features = set()
+    if isinstance(scope, Flavor):
+        if scope.static:
+            supported_features.update(SUPPORTED_FEATURES[scope.static])
+        if scope.dynamic:
+            supported_features.update(SUPPORTED_FEATURES[scope.dynamic])
+    elif isinstance(scope, str):
+        supported_features.update(SUPPORTED_FEATURES[scope])
+    else:
+        raise InvalidRule(f"{scope} is not a valid scope")
+
     if (
         isinstance(feature, capa.features.common.Characteristic)
         and isinstance(feature.value, str)
-        and capa.features.common.Characteristic(feature.value) not in SUPPORTED_FEATURES[scope]
+        and capa.features.common.Characteristic(feature.value) not in supported_features
     ):
         raise InvalidRule(f"feature {feature} not supported for scope {scope}")
 
     if not isinstance(feature, capa.features.common.Characteristic):
         # features of this scope that are not Characteristics will be Type instances.
         # check that the given feature is one of these types.
-        types_for_scope = filter(lambda t: isinstance(t, type), SUPPORTED_FEATURES[scope])
+        types_for_scope = filter(lambda t: isinstance(t, type), supported_features)
         if not isinstance(feature, tuple(types_for_scope)):  # type: ignore
             raise InvalidRule(f"feature {feature} not supported for scope {scope}")
 
@@ -438,7 +485,7 @@ def pop_statement_description_entry(d):
     return description["description"]
 
 
-def build_statements(d, scope: str):
+def build_statements(d, scope: Union[str, Flavor]):
     if len(d.keys()) > 2:
         raise InvalidRule("too many statements")
 
@@ -647,8 +694,29 @@ def second(s: List[Any]) -> Any:
     return s[1]
 
 
+def parse_flavor(scope: Union[str, Dict[str, str]]) -> Flavor:
+    if isinstance(scope, str):
+        if scope in STATIC_SCOPES:
+            return Flavor(scope, "", definition=scope)
+        elif scope in DYNAMIC_SCOPES:
+            return Flavor("", scope, definition=scope)
+        else:
+            raise InvalidRule(f"{scope} is not a valid scope")
+    elif isinstance(scope, dict):
+        if "static" not in scope:
+            scope.update({"static": ""})
+        if "dynamic" not in scope:
+            scope.update({"dynamic": ""})
+        if len(scope) != 2:
+            raise InvalidRule("scope flavors can be either static or dynamic")
+        else:
+            return Flavor(scope["static"], scope["dynamic"], definition=scope)
+    else:
+        raise InvalidRule(f"scope field is neither a scope's name or a flavor list")
+
+
 class Rule:
-    def __init__(self, name: str, scope: str, statement: Statement, meta, definition=""):
+    def __init__(self, name: str, scope: Union[Flavor, str], statement: Statement, meta, definition=""):
         super().__init__()
         self.name = name
         self.scope = scope
@@ -788,7 +856,10 @@ def from_dict(cls, d: Dict[str, Any], definition: str) -> "Rule":
         name = meta["name"]
         # if scope is not specified, default to function scope.
         # this is probably the mode that rule authors will start with.
+        # each rule has two scopes, a static-flavor scope, and a
+        # dynamic-flavor one. which one is used depends on the analysis type.
         scope = meta.get("scope", FUNCTION_SCOPE)
+        scope = parse_flavor(scope)
         statements = d["rule"]["features"]
 
         # the rule must start with a single logic node.
@@ -799,9 +870,6 @@ def from_dict(cls, d: Dict[str, Any], definition: str) -> "Rule":
         if isinstance(statements[0], ceng.Subscope):
             raise InvalidRule("top level statement may not be a subscope")
 
-        if scope not in SUPPORTED_FEATURES.keys():
-            raise InvalidRule("{:s} is not a supported scope".format(scope))
-
         meta = d["rule"]["meta"]
         if not isinstance(meta.get("att&ck", []), list):
             raise InvalidRule("ATT&CK mapping must be a list")
@@ -910,7 +978,7 @@ def to_yaml(self) -> str:
 
         # the name and scope of the rule instance overrides anything in meta.
         meta["name"] = self.name
-        meta["scope"] = self.scope
+        meta["scope"] = self.scope.definition if isinstance(self.scope, Flavor) else self.scope
 
         def move_to_end(m, k):
             # ruamel.yaml uses an ordereddict-like structure to track maps (CommentedMap).
@@ -1399,22 +1467,22 @@ def match(self, scope: Scope, features: FeatureSet, addr: Address) -> Tuple[Feat
         except that it may be more performant.
         """
         easy_rules_by_feature = {}
-        if scope is Scope.FILE:
+        if scope == Scope.FILE:
             easy_rules_by_feature = self._easy_file_rules_by_feature
             hard_rule_names = self._hard_file_rules
-        elif scope is Scope.PROCESS:
+        elif scope == Scope.PROCESS:
             easy_rules_by_feature = self._easy_process_rules_by_feature
             hard_rule_names = self._hard_process_rules
-        elif scope is Scope.THREAD:
+        elif scope == Scope.THREAD:
             easy_rules_by_feature = self._easy_thread_rules_by_feature
             hard_rule_names = self._hard_thread_rules
-        elif scope is Scope.FUNCTION:
+        elif scope == Scope.FUNCTION:
             easy_rules_by_feature = self._easy_function_rules_by_feature
             hard_rule_names = self._hard_function_rules
-        elif scope is Scope.BASIC_BLOCK:
+        elif scope == Scope.BASIC_BLOCK:
             easy_rules_by_feature = self._easy_basic_block_rules_by_feature
             hard_rule_names = self._hard_basic_block_rules
-        elif scope is Scope.INSTRUCTION:
+        elif scope == Scope.INSTRUCTION:
             easy_rules_by_feature = self._easy_instruction_rules_by_feature
             hard_rule_names = self._hard_instruction_rules
         else:

tests/test_rules.py

@@ -376,25 +376,49 @@ def test_subscope_rules():
                     """
                 )
             ),
+            capa.rules.Rule.from_yaml(
+                textwrap.dedent(
+                    """
+                    rule:
+                        meta:
+                            name: test subscopes for scope flavors
+                            scope: 
+                                static: function
+                                dynamic: process
+                        features:
+                            - and:
+                                - string: /etc/shadow
+                                - or:
+                                    - api: open
+                                    - instruction:
+                                        - mnemonic: syscall
+                                        - number: 2 = open syscall number
+                    """
+                )
+            ),
         ]
     )
     # the file rule scope will have two rules:
     #  - `test function subscope` and `test process subscope`
     assert len(rules.file_rules) == 2
 
-    # the function rule scope have one rule:
-    #  - the rule on which `test function subscope` depends
-    assert len(rules.function_rules) == 1
+    # the function rule scope have two rule:
+    # - the rule on which `test function subscope` depends, and
+    # the `test subscopes for scope flavors` rule
+    assert len(rules.function_rules) == 2
 
-    # the process rule scope has one rule:
-    # - the rule on which `test process subscope` and depends
-    # as well as `test thread scope`
-    assert len(rules.process_rules) == 2
+    # the process rule scope has three rules:
+    # - the rule on which `test process subscope` depends,
+    # `test thread scope` , and `test subscopes for scope flavors`
+    assert len(rules.process_rules) == 3
 
     # the thread rule scope has one rule:
     # - the rule on which `test thread subscope` depends
     assert len(rules.thread_rules) == 1
 
+    # the rule on which `test subscopes for scope flavors` depends
+    assert len(rules.instruction_rules) == 1
+
 
 def test_duplicate_rules():
     with pytest.raises(capa.rules.InvalidRule):
@@ -499,6 +523,66 @@ def test_invalid_rules():
                 """
             )
         )
+    with pytest.raises(capa.rules.InvalidRule):
+        r = capa.rules.Rule.from_yaml(
+            textwrap.dedent(
+                """
+                rule:
+                    meta:
+                        name: test rule
+                        scope:
+                            static: basic block
+                            behavior: process
+                    features:
+                        - number: 1
+                """
+            )
+        )
+    with pytest.raises(capa.rules.InvalidRule):
+        r = capa.rules.Rule.from_yaml(
+            textwrap.dedent(
+                """
+                rule:
+                    meta:
+                        name: test rule
+                        scope:
+                            legacy: basic block
+                            dynamic: process
+                    features:
+                        - number: 1
+                """
+            )
+        )
+    with pytest.raises(capa.rules.InvalidRule):
+        r = capa.rules.Rule.from_yaml(
+            textwrap.dedent(
+                """
+                rule:
+                    meta:
+                        name: test rule
+                        scope:
+                            static: process
+                            dynamic: process
+                    features:
+                        - number: 1
+                """
+            )
+        )
+    with pytest.raises(capa.rules.InvalidRule):
+        r = capa.rules.Rule.from_yaml(
+            textwrap.dedent(
+                """
+                rule:
+                    meta:
+                        name: test rule
+                        scope:
+                            static: basic block
+                            dynamic: function
+                    features:
+                        - number: 1
+                """
+            )
+        )
 
 
 def test_number_symbol():