dynamic: add "span of calls" scope

[williballenthin]

This PR implements the dynamic "span of calls" scope introduced here: mandiant/capa-rules#951

In summary, we want a way to match across calls (in dynamic mode) without resorting to the entire thread (which may be very long, like thousands of events). So, we add a new scope "span of calls" that represents the sliding 20-tuples of calls across each thread. Rules can match against any set of logic within each of these 20-tuples.

For example, consider the initial behavior of thread 3064 in our test CAPE file 0000a657:

This is a long thread with many calls, so yesterday it was tough to write a rule for any behavior that spans multiple calls without introducing false positives. Consider matching on the dynamic resolution and invocation of AddVectoredExceptionHandler. Now we can write a rule like:

So, within a region of 20 calls, match all this logic.

Here's what the output looks like:

The implementation is pretty easy: maintain a deque of the trailing 20 call events, merging and matching those features.

I picked 20 fairly randomly. I think we can tweak this number as necessary. Smaller and its harder to match logic. Larger and the performance might decrease a bit, and then there's more FP possibility. But I don't think this is too risky.

I think this will affect runtime a bit, since we're matching features twice for each call event (one for the precise call event, one for the sliding window).

There's probably some edge cases to work out around overlapping windows. Consider a rule that matches a single call event within a sequence: that call event is contained by 20 sequences (some covering the events before, some covering the events after). So, we may have to do a little more work (TODO) to not emit those matches twice. I'm not precisely sure of the behavior at this moment. I'll write a test for it.

Checklist

• changelog update needed
• documentation needed

CHANGELOG updated or no update needed, thanks! 😄

[williballenthin]

we also may want to update the vverbose render to only show each call event once, leaving the match details to a separate section, maybe like:

sequence: processs1, pid, tid, calls{1, 2}
  and:
    api: CreateFile @ call{1}
    api: CloseFile @ call{2}
  referenced call events:
    call{1}: CreateFile
    call{2}: CloseFile

[williballenthin]

@jorik-utwente FYI

[williballenthin]

I realize I dropped this PR without much warning 😇 I went from "I wonder how this would work" to "huh, it seems to work OK" pretty quickly.

[mr-tz]

awesome, this looks very promising already!!

major things to discuss include the naming and potentially handling of loops

[williballenthin]

potentially handling of loops

Good point. I think we'd want to see how this works in practice against a large number of samples and the rules we can translate to use this construct. In particular, loops (like you say) such as you'd see in ransomware.

[mike-hunhoff]

Great work, I'm excited about where this is going for an initial implementation. I echo a few of @mr-tz 's comments/concerns. Additionally, the value 5 comes close to being too small for some of our existing rules, e.g. https://github.com/mandiant/capa-rules/blob/e033410c8910f8b46718a5eefd9f0c7768be1b99/communication/c2/shell/create-reverse-shell.yml#L19-L23 so we'll need to do some additional work to find the sweet spot.

[mr-tz]

I spent a few moments focusing on the core extension here and added some places for additional documentation.

[williballenthin]

computing the features for the sequence, which involves merging features from many calls, seems to take quite a bit of time:

i'll have to think on whether there's a creative way to optimize this

---

profile information

before: sequence length: 20

before: sequence length: 0

(convenient this works!)

optimized, sequence length 1 and 20:

conclusion:

So, there's a bit of overhead to use this new algorithm, but it's independent of SEQUENCE_LENGTH, which is desirable.

[mr-tz]

TODO?!

• test sequence scope with submatch (call scope)
• test sequence scope with submatch (sequence scope)
• test sequence scope with submatch (thread or other scope - error?)

[mike-hunhoff]

I'm seeing incorrect results for the call list, e.g. in the following output there is only one call displayed but four call ids are listed:

$ python -m capa.main tests/data/dynamic/vmray/2f8a79b12a7a989ac7e5f6ec65050036588a92e65aeb6841e08dc228ff0e21b4_min_archive.zip -vv

[...]
capture screenshot
namespace  collection/screenshot                                            
author     [email protected], @_re_fox, [email protected]
scope      span of calls                                                    
att&ck     Collection::Screen Capture [T1113]                               
mbc        Collection::Screen Capture::WinAPI [E1113.m01]                   
span of calls @ mulvpilibfy.exe (C:\Users\8qy2SK\Desktop\mulvpilibfy.exe){pid:7104,tid:7108,calls:{36462,36465,37084,37146}}
  or:
    call:
      and:
        api: BitBlt @ mulvpilibfy.exe (C:\Users\8qy2SK\Desktop\mulvpilibfy.exe){pid:7104,tid:7108,call:37146}
          BitBlt(
            hdc: 0x2a010781,
            x: 0,
            y: 0,
            cx: 1440,
            cy: 900,
            hdcSrc: 0x4d010784,
            x1: 0,
            y1: 0,
            rop: 0xcc0020,
          ) -> ret_val: 1
[...]

And I've encountered other instances where multiple call matches are displayed but only the call id of the last match displayed is listed.

[williballenthin]

good catch! there's definitely some weirdness happening.

I think that when we collect all the potentially relevant call IDs, we're not validating that they come from branches that evaluated to True. Oops.

Here's my work:

I'll fix this up early next week. Not anticipating this to be a major problem.

[williballenthin]

e.g., here: https://github.com/mandiant/capa/pull/2532/files#diff-603cfd484a8c3bc11c9b7251492139889b9f2d4c29e1b5a8054b6eac373737a6R339-R340

we should first ensure the node evaluated to true before collecting from the children.

[williballenthin]

nice example - false negative for the more specific branch GetDC/BitBlt/CreateCompatibleDC.

maybe we need to:

• add DISPLAY* to CreateDC
• add Gdip routines (GdipCreateBitmapFromScan0, GdipGetImageGraphicsContext, GdipGetDC)

[williballenthin]

resolved in 9c24e3a

[mike-hunhoff]

@williballenthin this still appears incorrect after additional testing where the following example is missing call id 709

spawn thread to RWX shellcode
namespace  load-code/shellcode                                            
author     [email protected]                                      
scope      span of calls                                                  
mbc        Memory::Allocate Memory [C0007], Process::Create Thread [C0038]
span of calls @ [...] {pid:2484,tid:2488,call:713}
  and:
    match: allocate or change RWX memory
      and:
        or:
          match: allocate memory
            or:
              api: NtAllocateVirtualMemory @ call:709
[...]
        or:
          number: 0x40 = PAGE_EXECUTE_READWRITE @ call:709
[...]
    match: create thread
      or:
        and:
          os: windows
          or:
            api: NtCreateThreadEx @ call:713
[...]

where [...] simply omits the formatted call.

[williballenthin]

I suspect what's happening here is due to the match node.

Recall that the logic of the subrule is not directly inlined, but there's a sort of pointer to another rule with its own matching results. So I bet when we collect the set of relevant call ids, we don't resolve the match subrule results and collect its call ids; probably we just stop recursing at the match statement.

Since you've mentioned this, I gather it would be nice to have working better? I don't think it would take much work, but would require a little more code.

[mike-hunhoff]

I noticed this while attempting to incorporate the code somewhere else. If it's not too much work then ideally capa's output would display the correct call ids, but it's not a showstopper at this time.

[williballenthin]

ok i understand thanks. i will try to provide a fix tomorrow or monday.

[mike-hunhoff]

Great work @williballenthin - this is looking great! The code looks sensible to me and I trust (and appreciate) the tests that you've added 🚀

[mike-hunhoff]

Suggested change

	# We matches spans as the sliding window of calls with size SPAN_SIZE.
	# We match spans as the sliding window of calls with size SPAN_SIZE.

[mike-hunhoff]

Collecting matched call ids still appears to be incorrect.