mandiant / mandiant/capa-rules

Create rule writing step-by-step guide

Open
#307 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
No language data
Stars
736
Forks
245
Avg merge
4d 53m
Merged PRs (30d)
2

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review existing rules and the capa-rules documentation first, then inspect scripts/lint.py and the current docs or CONTRIBUTING file to identify where the guide belongs. Cover prerequisites, the IDA Pro plugin and text-editor workflows, rule placement and naming, and linting; done means a newcomer can follow the guide from setup through a tested rule.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.