Show prevalence of rules in the output

capa/render/default.py

@@ -7,6 +7,7 @@
 # See the License for the specific language governing permissions and limitations under the License.
 
 import collections
+from typing import Dict
 
 import tabulate
 
@@ -73,19 +74,30 @@ def rec(match: rd.Match):
 
 def render_capabilities(doc: rd.ResultDocument, ostream: StringIO):
     """
+    render capabilities sorted by:
+      - prevalence (rare to unknown)
+      - namespace (alphabetical)
+
     example::
 
-        +-------------------------------------------------------+-------------------------------------------------+
-        | CAPABILITY                                            | NAMESPACE                                       |
-        |-------------------------------------------------------+-------------------------------------------------|
-        | check for OutputDebugString error (2 matches)         | anti-analysis/anti-debugging/debugger-detection |
-        | read and send data from client to server              | c2/file-transfer                                |
-        | ...                                                   | ...                                             |
-        +-------------------------------------------------------+-------------------------------------------------+
+        +-------------------------------------------------------+-------------------------------------------------+------------+
+        | CAPABILITY                                            | NAMESPACE                                       | PREVALENCE |
+        |-------------------------------------------------------+-------------------------------------------------|------------|
+        | check for OutputDebugString error (2 matches)         | anti-analysis/anti-debugging/debugger-detection | rare       |
+        | ...                                                   | ...                                             | ...        |
+        |-------------------------------------------------------|-------------------------------------------------|------------|
+        | read and send data from client to server              | c2/file-transfer                                | common     |
+        | ...                                                   | ...                                             | ...        |
+        +-------------------------------------------------------+-------------------------------------------------+------------+
     """
     subrule_matches = find_subrule_matches(doc)
 
-    rows = []
+    # seperate rules based on their prevalence
+    common: Dict[str, str] = {"capability": "", "namespace": "", "prevalence": ""}
+    had_common = False
+    rare: Dict[str, str] = {"capability": "", "namespace": "", "prevalence": ""}
+    had_rare = False
+
     for rule in rutils.capability_rules(doc):
         if rule.meta.name in subrule_matches:
             # rules that are also matched by other rules should not get rendered by default.
@@ -98,11 +110,34 @@ def render_capabilities(doc: rd.ResultDocument, ostream: StringIO):
             capability = rutils.bold(rule.meta.name)
         else:
             capability = f"{rutils.bold(rule.meta.name)} ({count} matches)"
-        rows.append((capability, rule.meta.namespace))
+
+        namespace = rule.meta.namespace if rule.meta.namespace is not None else ""
+        prevalence = rutils.bold(rule.meta.prevalence) if rule.meta.prevalence != "unknown" else "unknown"
+
+        if "rare" in prevalence:
+            rare["capability"] += capability + "\n"
+            rare["namespace"] += namespace + "\n"
+            rare["prevalence"] += prevalence + "\n"
+            had_rare = True
+        else:
+            common["capability"] += capability + "\n"
+            common["namespace"] += namespace + "\n"
+            common["prevalence"] += prevalence + "\n"
+            had_common = True
+
+    rows = []
+    if had_rare:
+        rows.append((rare["capability"], rare["namespace"], rare["prevalence"]))
+    if had_common:
+        rows.append((common["capability"], common["namespace"], common["prevalence"]))
 
     if rows:
         ostream.write(
-            tabulate.tabulate(rows, headers=[width("Capability", 50), width("Namespace", 50)], tablefmt="mixed_outline")
+            tabulate.tabulate(
+                rows,
+                headers=[width("Capability", 50), width("Namespace", 50), width("Prevalence", 10)],
+                tablefmt="mixed_grid",
+            )
         )
         ostream.write("\n")
     else:

capa/render/result_document.py

@@ -10,6 +10,7 @@
 from enum import Enum
 from typing import Dict, List, Tuple, Union, Literal, Optional
 from pathlib import Path
+from functools import lru_cache
 
 from pydantic import Field, BaseModel, ConfigDict
 from typing_extensions import TypeAlias
@@ -19,6 +20,7 @@
 import capa.features.common
 import capa.features.freeze as frz
 import capa.features.address
+import capa.render.rules_prevalence
 import capa.features.freeze.features as frzf
 from capa.rules import RuleSet
 from capa.engine import MatchResults
@@ -569,9 +571,33 @@ class MaecMetadata(FrozenModel):
     model_config = ConfigDict(frozen=True, populate_by_name=True)
 
 
+@lru_cache(maxsize=None)
+def load_rules_prevalence() -> Dict[str, str]:
+    """
+    Load and return a dictionary containing prevalence information for rules defined in capa.
+
+    Returns:
+        Dict[str, str]: A dictionary where keys are rule names, and values are prevalence levels.
+
+    Example:
+        {
+            "capture screenshot": "rare",
+            "send data": "common",
+            "receive and write data from server to client": "common",
+            "resolve DNS": "common",
+            "reference HTTP User-Agent string": "rare"
+        }
+
+    Note:
+        Prevalence levels can be one of the following: "common", "rare"
+    """
+    return capa.render.rules_prevalence.RULES_PREVALENCE
+
+
 class RuleMetadata(FrozenModel):
     name: str
     namespace: Optional[str] = None
+    prevalence: str = "unknown"
     authors: Tuple[str, ...]
     scopes: capa.rules.Scopes
     attack: Tuple[AttackSpec, ...] = Field(alias="att&ck")
@@ -589,6 +615,7 @@ def from_capa(cls, rule: capa.rules.Rule) -> "RuleMetadata":
         return cls(
             name=rule.meta.get("name"),
             namespace=rule.meta.get("namespace"),
+            prevalence=load_rules_prevalence().get(rule.meta.get("name"), "unknown"),
             authors=rule.meta.get("authors"),
             scopes=capa.rules.Scopes.from_dict(rule.meta.get("scopes")),
             attack=tuple(map(AttackSpec.from_str, rule.meta.get("att&ck", []))),