Import YARA Rules from GitHub

If your team keeps its YARA rules in a GitHub repository, Stairwell can subscribe to that repository and keep the rules in sync. You point it at a repository, and the rules in that repository become a read-only rule set of their own, running alongside the rules you write in the product and the rule sets Stairwell maintains. Public and private repositories are both supported.

This is the right approach when the repository is your source of truth: rules stay under review in Git, and the rule set in Stairwell follows what you merge. If you want to load a directory of rules once, without an ongoing link, use the bulk upload in Manage YARA Rules instead.

How do I subscribe to a repository?

1. Select the gear icon at the bottom of the sidebar to open Settings.
2. Open YARA repositories.
3. Select Add YARA rule set.
4. Paste the repository URL. Required.
5. Enter a branch name if you want one other than the repository's default branch. Optional.
6. Paste an SSH private key if the repository is private. Stairwell stores the key encrypted and uses it only to read that repository.
7. Select Add rule set.

Importing takes a few minutes, and the dialog says so while it works. If YARA repositories is not present in your Settings, ask your Stairwell contact to enable rule set imports for your organization.

Which repository URLs are supported?

GitHub repositories, at the repository root, in either of two forms:

https://github.com/user/repo.git
[email protected]:user/repo.git

Some things that do not work, each of which is a real mistake people make:

• Hosts other than github.com. Other Git hosts are rejected.
• Directory-specific URLs. A link to a folder or a file inside a repository, or a tree/ or blob/ URL from your browser's address bar, is not a repository URL. Give the repository itself.
• A branch expressed in the URL. Put the branch in the branch field.

You do not need to point at the rules. Stairwell searches the repository recursively and picks up every .yar and .yara file it finds, at any depth.

When do the rules appear, and how often do they refresh?

Expect the rule set to appear within about ten minutes of subscribing, and to refresh roughly every four hours from then on.

Each refresh reconciles the rule set against the current state of the repository:

• Rules added to the repository are created in the rule set.
• Rules whose text changed are saved as a new version, so the rule's history in Stairwell reflects the history of your edits.
• Rules whose text did not change are left alone, which is why an unchanged rule does not show a new modified date after every refresh.
• Rules removed from the repository are removed from the rule set.

Every imported rule goes through the same checks as a rule typed into the editor, so a rule with an error in it is skipped rather than accepted. Rules marked global or private are also skipped, since Stairwell does not support them. If a rule you expected is missing from the rule set, that is the first thing to check, along with the guidance in Writing Your First YARA Rule about imports and references to other rules, which are the two most common reasons a rule written elsewhere does not run here.

Where do the imported rules show up?

In the Rules screen, as their own rule set, named after the repository URL. Filter the list by that rule set to see only those rules, and treat their match counts the way you would treat your own: read My objects and Malware objects together, as described in Manage YARA Rules.

Matches from imported rules appear on the object panel alongside every other rule match, and the rule name shown is the name from the rule body.

Can I edit an imported rule in Stairwell?

No. An imported rule set is read-only in the product, because the repository is the source of truth and an edit made here would be reverted by the next refresh. Edit the rule in the repository and merge it, and the change arrives on the next sync.

If you want to change a rule without changing the repository, copy its body into a new rule of your own. Your copy is an independent rule with its own name and history, and it will not track later changes to the original.

How do I stop syncing a repository?

Ask your Stairwell contact. Removing a subscription is not currently available from the Settings screen, so it is handled for you rather than by you. In the meantime, if the rules from a repository are noisy, you can disable them individually or in bulk from the Rules list. See Manage YARA Rules.

What should I read next?

• Manage YARA Rules, for bulk-loading rules without an ongoing subscription, and for reading match counts.
• YARA Rule Feeds, for the rule sets Stairwell maintains alongside yours.
• YARA Rule Best Practices, worth a read before importing a large public rule set, since public sets vary widely in how narrow their rules are.