Rulesets

A Ruleset is a collection of detection rules packaged as an OCI artifact and stored in the Binarly Registry. Rulesets are the unit of deployment — you deploy Rulesets, not individual rules. A Ruleset can contain YARA rules, FwHunt rules, or a mix of both.

Prerequisites

Rulesets are pushed using oras (OCI Registry As Storage), a CLI tool for pushing and pulling OCI artifacts. Install it before proceeding:

macOS
Linux
Windows

brew install oras

VERSION="1.2.0"
curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"
sudo tar -zxf oras_${VERSION}_linux_amd64.tar.gz -C /usr/local/bin oras

Check the oras releases page for a newer version before installing.

winget install oras

Directory structure

Organize your rules in a directory before pushing. You can use any folder structure — oras will push the entire directory tree as a single artifact.

my-ruleset/
├── yara/
│   ├── threat_hunting.yar
│   └── supply_chain.yar
└── fwhunt/
    ├── smm_callouts.yaml
    └── uefi_implants.yaml

Rules do not need to be separated by type, but grouping them makes the Ruleset easier to navigate in the Playground.

Writing rules

YARA
FwHunt

YARA rules follow the standard YARA format. This example detects an embedded PE file with a suspicious import:

rule SuspiciousEmbeddedPE : firmware
{
    meta:
        description = "Detects embedded PE with remote thread creation capability"
        author      = "security-team"
        date        = "2026-01-01"
    strings:
        $mz              = { 4D 5A }
        $remote_thread   = "CreateRemoteThread" wide ascii
        $debug_priv      = "SeDebugPrivilege" wide ascii
    condition:
        $mz at 0 and any of ($remote_thread, $debug_priv)
}

See the YARA documentation for the full rule syntax.

FwHunt rules are YAML-based and target UEFI firmware binaries. This example matches a module by its GUID and checks for a known-bad code pattern:

name: FWHUNT_EXAMPLE_SMM_CALLOUT
version: "1.0"
description: "Detects SMM callout via NVRAM variable in a specific module"
rules:
  - rule:
      guid: "7C436110-AB2A-4BBB-A880-FE41995C9F82"
      strings:
        - name: callout_pattern
          value: "GetVariable"
      wide: false
      condition: any

See the FwHunt documentation for the full rule specification.

Pushing a Ruleset

Find your registry hostname

Your registry hostname is derived from your platform URL. If your platform is at app.{instance}.binarly.cloud, your registry is at registry.{instance}.binarly.cloud. For example, if you access the platform at app.i7sydgb4.binarly.cloud, your registry hostname is registry.i7sydgb4.binarly.cloud.

Use your Binarly account email and password.

oras login registry.{instance}.binarly.cloud -u your@email.com -p <YOUR_PASSWORD>

Push the Ruleset

From the parent directory of your rules folder, push its contents to the registry. Use a meaningful name and tag to identify the Ruleset version.

oras push registry.{instance}.binarly.cloud/<ruleset-name>:latest ./my-ruleset/

To tag a specific version instead of overwriting latest:

oras push registry.{instance}.binarly.cloud/<ruleset-name>:v1.2.0 ./my-ruleset/

Verify in the platform

After a successful push, the Ruleset appears in Rules → Rulesets. From there you can open it in the Playground to test individual rules, or deploy it to run on scans.

Updating a Ruleset

Push to the same name with an updated tag. The platform tracks Ruleset versions — previous versions remain accessible and findings already generated from them are linked to the rule revision that produced them.

# Update the latest tag
oras push registry.{instance}.binarly.cloud/<ruleset-name>:latest ./my-ruleset/

# Or tag a new explicit version
oras push registry.{instance}.binarly.cloud/<ruleset-name>:v1.3.0 ./my-ruleset/

Findings generated from an earlier version of a Ruleset remain visible and continue to link to the specific rule revision that produced them, even after the Ruleset is updated.

Other useful commands

List Rulesets

oras repo ls registry.{instance}.binarly.cloud

oras repo tags registry.{instance}.binarly.cloud/<ruleset-name>

Pull a Ruleset

Download a Ruleset to inspect or modify it locally:

oras pull registry.{instance}.binarly.cloud/<ruleset-name>:v1.2.0 -o ./my-ruleset/

Re-tag without re-pushing

Promote a specific version to latest without uploading the files again:

oras tag registry.{instance}.binarly.cloud/<ruleset-name>:v1.2.0 latest

Log out

oras logout registry.{instance}.binarly.cloud

About

Get Started

Exploring Image Scans

Important Findings

Data Export

Integrations

Organization Management

Custom Rule Management

Prerequisites

Directory structure

Writing rules

Pushing a Ruleset

Updating a Ruleset

Other useful commands

List Rulesets

Pull a Ruleset

Re-tag without re-pushing

Log out

​Prerequisites

​Directory structure

​Writing rules

​Pushing a Ruleset

​Updating a Ruleset

​Other useful commands

​List Rulesets

​List tags

​Pull a Ruleset

​Re-tag without re-pushing

​Log out

Prerequisites

Directory structure

Writing rules

Pushing a Ruleset

Updating a Ruleset

Other useful commands

List Rulesets

List tags

Pull a Ruleset

Re-tag without re-pushing

Log out