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", []))),