Capa rules (analysis.capa)

analysis.capa: malcat.CapaScan: The analysis.capa object is a malcat.CapaScan instance that gives you access to all matching and unmatching capa rules evaluated against the current file.

The capa analysis is run on-demand. The attribute analysis.capa starts empty and is populated only after the user has run capa through the GUI, or after a script has explicitly called either malcat.Analysis.capa_run() or malcat.CapaScan.run().

Accessing / enumerating capa capabilities hits 

Malcat embeds a capa scanner as one of its analyses. The result of the scan is available through the analysis.capa python object. Accessing the result of the scan can be useful in your scripts. If you plan to check whether a file resolves Windows APIs dynamically for instance, a simple "resolve function by parsing PE exports" in analysis.capa is enough.

class malcat.CapaScan

matching

Iterate over all matching capa rules.

for rule in analysis.capa.matching:
    print(f"{rule.name} did match at:")
    for match in rule:
        print(f"    - {match.address}")

Return type:: iterator over CapaRule objects

__iter__()

iterator over the matching rules

Return type:: iterator over CapaRule objects

all

Iterate over all capa rules, even the non-matching ones. Generated subscope and library rules are not exposed in this list.

Return type:: iterator over CapaRule objects

attack: List[CapaAttackTechnique]: All unique ATT&CK techniques referenced by matching capa rules.

mbc: List[CapaMbcBehavior]: All unique MBC behaviors referenced by matching capa rules.

__getitem__(name)

Returns the capa rule object whose name is name. If no such rule can be found, None is returned.

rule = analysis.capa["resolve function by parsing PE exports"]
if rule is not None:
    print(rule.description)

Parameters:: name (str) – capa rule name to search for
Return type:: malcat.CapaRule

__contains__(name)

return True iff a capa rule named name is known to the scan result, matching or not.

if "resolve function by parsing PE exports" in analysis.capa:
    print("the rule is available")

Parameters:: name (str) – capa rule name to search for
Return type:: bool

__len__(self)

return the number of matching capa rules

Return type:: int

run()

Perform a Capa scan. While Malcat uses its own native port of the Capa scanner, a scan can still take a couple of seconds and is thus only performed on demand.

If the scanner was already run, run it again (e.g. if the ruleset changed).

Analysis.capa is updated.

Return type:: malcat.CapaScan

Rule object 

Capa rule 

malcat.CapaRule are python objects returned by CapaScan.matching, CapaScan.all, CapaScan.__getitem__() and CapaRuleMatch.rule. They offer the following interface:

class malcat.CapaRule

name: str: capa rule name

scope: str: capa rule scope. Possible values are file, function, basic block and instruction.

namespace: str: capa rule namespace

author: str: comma-separated list of rule authors

authors: List[str]: list of rule authors

description: str: capa rule description

attack: List[CapaAttackTechnique]: ATT&CK techniques referenced by the rule

mbc: List[CapaMbcBehavior]: MBC behaviors referenced by the rule

readonly: bool: is the rule part of Malcat’s read-only standard capa rules

path: str: path to the rule source. Standard rules stored in Malcat’s capa zip archive use the archive path.

definition: str: the rule definition text

matches: List[malcat.CapaRuleMatch]: a list of objects that the rule matched against

matching: bool: did the rule match? True iff matches is not empty

__iter__()

Iterate over matches

Return type:: iterator over CapaRuleMatch

__len__()

number of capa matches for this rule

Return type:: int

Capa match 

CapaRuleMatch is a python objects which registers where a rule has matched. It offers the following interface:

class malcat.CapaRuleMatch

rule: CapaRule: the matching capa rule

scope: str: scope at which the rule matched

address: int: match effective address. Use CapaEvalResult.locations for the detailed list of effective addresses contributing to the match.

result: CapaEvalResult: rule evaluation tree

Evaluation result 

Evaluation results are python objects of type CapaEvalResult. They expose the rule evaluation tree for a match.

class malcat.CapaEvalResult

success: bool: did this statement match?

statement: str: the statement, e.g. “and”, or “os: windows” or “api: kernel32.WriteFile”

locations: Set[int]: Malcat effective addresses contributing to this evaluation result

children: List[CapaEvalResult]: child evaluation results

ATT&CK 

ATT&CK entries are python objects of type CapaAttackTechnique and offer the following interface:

class malcat.CapaAttackTechnique

tactic: str: ATT&CK tactic name

technique: str: ATT&CK technique name

subtechnique: str: ATT&CK subtechnique name, if any

id: str: ATT&CK identifier, e.g. T1027

value: str: original capa metadata value

MBC 

MBC entries are python objects of type CapaMbcBehavior and offer the following interface:

class malcat.CapaMbcBehavior

objective: str: MBC objective name

behavior: str: MBC behavior name

method: str: MBC method name, if any

id: str: MBC identifier, e.g. B0001

value: str: original capa metadata value

Capa rules (analysis.capa)

Accessing / enumerating capa capabilities hits

Rule object

Capa rule

Capa match

Evaluation result

ATT&CK

MBC