Manage YARA Rules

Every rule you can see lives in the Rules screen, reachable from the sidebar: the rules you wrote, the rules that arrived from a rule set you subscribe to, and the rules Stairwell maintains. From there you create a rule, edit it, turn it off without losing it, delete it, tag it, and see how much each rule is matching. This page covers each of those operations and the one command line path that matters, bulk-loading a directory of rules.

If you have not written a rule yet, start with Writing Your First YARA Rule and come back.

How do I find a rule?

Type into Filter by keyword above the list. It matches on rule name.

Two things shape what you are looking at before you type anything:

• Hide inactive rules is on by default. A rule you turned off will not appear until you clear that filter chip.
• The list spans every rule set you can see, including Stairwell's. Use the filter button to narrow to specific rule sets, or to a range of last-modified dates.

You can also query rules from the search bar instead of the list. rule.name.matches("[Aa]pt"), rule.status != ACTIVE, and rule.version > 5 all work, along with the rest of the rule fields in CEL Query Language.

What do the columns tell me?

Read the last two columns together, because that pair is the fastest read on rule quality you have. A rule with high Malware objects and low My objects is behaving: it recognizes the family and your estate is clean of it. A rule with high My objects and near-zero Malware objects is a rule that has found something ordinary in your own software, and it wants tightening rather than celebrating. Counts above ten thousand display as 10k+.

How do I create a rule?

1. Select Create YARA rule above the list.
2. Confirm the environment the rule will be created in, using the selector in the panel header. A rule belongs to one environment.
3. Write the rule. The editor checks it as you type and lists errors and warnings underneath, each anchored to its line.
4. Select Test Scan and test it. See Writing Your First YARA Rule for what to put in each box.
5. Select Create. This stays unavailable while the rule has an error in it.

The new rule is active immediately and starts working through the files Stairwell already holds.

How do I edit a rule?

1. Select the rule to open its panel.
2. Select the pencil icon.
3. Make your changes. Test Scan is available here too, and it tests the edited text rather than the saved version.
4. Select Submit, or Discard Changes to back out.

Two things to know about editing:

Editing creates a new version rather than overwriting. Each save increments the rule's version, and the previous versions remain on record, which is what lets you tell whether a rule's match counts changed because the world changed or because you changed the rule. rule.version is queryable.

Changing the rule's name in the body renames the rule, which is not a rename. If the name on the rule line differs from the rule's current name when you submit, Stairwell asks you to confirm, then creates a rule under the new name and deletes the old one. Match history follows the name, so do this deliberately.

You can only edit rules in an environment you have write access to. A rule from a subscribed rule set or another organization's environment is read-only; to build on it, copy the body into a new rule of your own.

How do I turn a rule off without deleting it?

Use the toggle at the top right of the rule panel. Turning a rule off removes it from scanning and keeps the body, the version history, and the metadata, which makes it the right move for a rule that is noisy today and might be useful after a rewrite.

For several rules at once: select their checkboxes in the list, open the three-dot menu in the action bar, and choose Set rule status, then Enable all or Disable all. Right-clicking a single row gives you Disable rule or Enable rule directly.

Remember that inactive rules are hidden from the list by default, so clear the Hide inactive rules chip when you go looking for something you turned off.

How do I delete a rule?

Deletion is permanent. If there is any chance you will want the logic back, turn the rule off instead.

• One rule: open it and select the trash icon, then confirm.
• Several: select their checkboxes, open the three-dot menu, and choose Delete rules.

You can delete only rules in an environment you have write access to. Rules from a subscribed rule set cannot be deleted; unsubscribe from the rule set instead.

What else can I do from the list?

Right-click a rule, or select several and use the three-dot menu:

• View matches opens the matching files in search, in this tab or a new one.
• Copy rule names puts the names on your clipboard, one per line.
• Edit Tags applies your team's tags to rules, which is how you group a campaign's worth of rules across rule sets. Tags are queryable as rule.tag.

How do I upload many rules at once?

Use swell, the Stairwell command line tool. Uploading is the operation worth reaching for the command line for, because pasting forty rules into an editor one at a time is not a plan.

# One rule file
swell yara upload --environment_id <ENVIRONMENT_ID> path/to/rule.yar

# Every rule file in a directory
swell yara upload --environment_id <ENVIRONMENT_ID> path/to/rules/

# Recursively, across nested directories
swell yara upload --environment_id <ENVIRONMENT_ID> -r path/to/rules/

# Replace rules that already exist under the same name
swell yara upload --environment_id <ENVIRONMENT_ID> --replace_existing_rules path/to/rules/

The same command group also gives you swell yara list, which prints each rule's name, current version, and whether it is active (--json for machine-readable output); swell yara download, which writes the rules in an environment to a local directory; and swell yara delete --rule_name <NAME> --rule_version <VERSION>, which deletes one rule. The version has to be the rule's current version, which is why swell yara list is the command you run first.

Every rule loaded this way goes through the same checks as a rule typed into the editor, so a rule with an error in it is reported and skipped rather than silently accepted.

Why is my rule not scanning?

Look at the icon in the second column, or open the rule and read the message at the top of the panel. There are four answers.

None of these are punishments. They are the reason a broad rule you wrote on a hunch cannot flood your team, which is what makes it reasonable to write a rule on a hunch in the first place.

While a rule is working through your history, the rule panel shows how far it has got. Match counts in the list fill in as it goes.

What should I read next?

• YARA Rule Best Practices, for fixing a rule the goodware check turned away.
• YARA Rule Feeds, for the rule sets you see alongside your own.
• Hunting and Search, for what to do with a rule's matches once you have them.