Create rule writing step-by-step guide

[mr-tz]

Motivation

We should make it more straight-forward to get started writing rules using a step-by-step guide. This guide should go into the doc or the CONTRIBUTING file and be easily accessible.

I'm collecting some initial ideas here. It's really rough for now, but I wanted to get this going.

Content

Most importantly, rule writing should be easy and fun! Even if you can't work on the rule yourself, please submit the rule idea in a GitHub issue.

Prerequisites

• install capa (link)
  • tip: exclude capa directory from AV especially when pulling capa-testfiles
• look at some existing rules, they are hopefully easy to read
  • all rule features are detailed in the capa-rules doc (link)
• it's best if you have a sample to test with, but you can also work of source code or other descriptions of a capability

Using the capa-explorer IDA Pro plugin

• install / usage links?
• open your sample in IDA Pro and run the plugin
• ...

Writing a rule in your favorite text editor

• copy an existing rule / use our rule template (should we add this?)
• start with the features section
  • identify the features you want to use
  • combine them logically
• fill out the meta section

Linting/testing rules

• run the rule linter scripts/lint.py on your rule
  • lint failures must be addressed
  • lint warnings are informational, but should be addressed if possible

TODOs

• [ ] add must/optional indicators to each item
• [ ] add help where to put rule file / how to pick namespace
• [ ] help on finding ATTCK/MBC tags

[johnk3r]

One difficulty I had initially was to use the binary "capafmt.py".

I cloned the repository on Ubuntu. When executing the binary, he informed that he was unable to import the "capa.rules".

It took me a while to understand what was going on. So I think it is important to document how to use these background tools.

[mr-tz]

Thanks, that's really valuable feedback. We'll document this better to make it easier for everyone.

[johnk3r]

Also, it is important to exemplify how to submit good samples to @capa-testfiles

Example: A good sample should be processed in 60 seconds.

There were cases where it took me a while to find a sample to validate the rule, but it was not a good sample to be referenced in the rule.

[recvfrom]

Another awesome topic would be how to debug rules that aren't matching as expected - specifically using show-features.py

[mr-tz]

Another awesome topic would be how to debug rules that aren't matching as expected - specifically using show-features.py

Exactly, I just went through it and encountered a case where IDA (lods) and vivisect (lodsb) use different instruction mnemonics. We should document how to do this and common gotchas like this (I've seen similar cases before).

[Dextera0007]

Learning capa rules, objective is to analyze various packets using capa rules: PE, ELF and .net files any help you can provide would be greatly appreciated. Here are the errors below when attempting to run a PE files :

capa -s capa-master\sigs -r capa-rules-master file.exe error:capta: Input file does not appear to be a PE file or ELF file error:capa: capa currently only supports analyzing PE and ELF files (or shellcode, when using --fomrat sc32|sc64