Create custom policies with YARA

The Spectra Assure CLI integrates with YARA, allowing you to extend policy configuration with YARA rules.

YARA is a tool for rule-based identification and classification of files. A YARA rule contains textual or binary patterns and Boolean expressions that determine the rule logic. When a file matches the pattern found in a YARA rule, one or more actions are triggered according to the criteria described in the rule. For example, a file may be classified as malicious, assigned to a specific malware family, or identified as a specific file format.

While analyzing your software, all Spectra Assure products rely on built-in policies to determine if the contents of your software are problematic or even malicious. Policies validate your software against a number of quality, behavior, and security criteria, and impact the final verdict on how secure your software is. You can extend this built-in set by writing your own policies in the form of YARA rules.

The CLI supports using YARA rules for the following purposes:

• SDLC policy controls - to detect software quality issues early and prevent secrets exposure by controlling the CI/CD build status.
• Threat detection - to protect your system from threats by classifying software components as suspicious or malicious.

In this guide, you will learn the basics of creating your own YARA rules and using them with Spectra Assure products.

Prerequisites

To successfully create and deploy custom policies with YARA rules, you should:

• Install rl-secure locally. Follow the instructions in the installation guide.

• Set up a project and package(s) to work with. If you haven't yet created any projects and packages, follow the instructions in the quick start guide.

• Familiarize yourself with YARA rule syntax and features. If you haven't previously written any YARA rules, we strongly recommend you learn more about them from the official YARA documentation before proceeding with this guide.

YARA rule structure

To use a YARA rule with Spectra Assure products, it must conform to a special schema described in this guide. However, rules designed for Spectra Assure will work in any other environment that runs YARA.

The basic structure of a rule includes the following sections:

1. Rule header
2. Rule metadata
3. Strings
4. Condition

YARA rule schema

rule Rule_Name : tc_policy or tc_detection  1️⃣
{
    meta:  2️⃣
        // Mandatory - SDLC policy only
        tc_policy_identifier  = "YR12345"
    
        // Optional - SDLC policy only
        tc_policy_status      = "fail" // Default: pass
        tc_policy_severity    = "high" // Default: low
        tc_policy_effort      = "high" // Default: low
        tc_policy_description = "Detects YARA matches for a custom SDLC policy"
        
        // Mandatory - Threat detection only
        tc_detection_type = "Malware type"
        tc_detection_name = "Malware family name"
        tc_detection_factor = 5
            
    strings:  3️⃣
        ...
    
    condition:  4️⃣
        ...
}

Rule header

The rule header is where you define a YARA rule by assigning it a name. A YARA rule name may be followed by a special tag, usually to identify the rule purpose.

Guidelines for YARA rule names

• YARA rule names are character-limited, so it is recommended to keep the name length between 3 and 30 characters.
• Generally, the underscore ( _ ) should be used instead of spaces, and any other special characters should be avoided.
• It is recommended to only use numbers (0-9) and a-z/A-Z letters in YARA rule names.
• The first character in the rule name must not be a digit.
• For the full list of reserved keywords that can't be used as the rule name, consult the official YARA documentation.

SDLC policy controls

To use a rule for Spectra Assure policy controls, the rule name must be followed by a special tc_policy tag. This tag indicates the rule should be interpreted as a custom policy.

Example

rule PuTTy_Encrypted_Key : tc_policy

Threat detection

To classify files with a YARA rule, the rule name must be followed by a special tc_detection tag and the classification you want to set for the matching files (malicious, suspicious).

It's recommended to use the malware threat name as the rule name. The malware threat name should follow the ReversingLabs malware naming standard.

Example

rule Text_Infostealer_IconBurst : tc_detection malicious

ReversingLabs malware naming standard

The ReversingLabs malware naming standard specifies the structure and contents of the detection string used in all ReversingLabs products.

The detection string consists of three mandatory parts separated by dots.

Platform-Subplatform.Type.Family

1. The first part of the string indicates the platform targeted by the malware. For some platforms, there will be an additional subplatform string. Platform and subplatform strings are separated by a hyphen ( - ).

2. The second part of the detection string describes the malware type.

3. The third part represents the malware family name. This usually corresponds to the common name used for the malware in the global cybersecurity community.

For example, if backdoor malware is a PHP script with the family name “Jones”, the detection string will be Script-PHP.Backdoor.Jones.

Platform, subplatform, and malware type cannot be arbitrary, and must match the values supported by the standard.

Supported platforms and subplatforms

Platform	Subplatforms
ABAP
Android
AOL
Archive	ACE, AR, ARJ, BZIP2, CAB, GZIP, ISO, JAR, LZH, RAR, 7ZIP, SZDD, TAR, XAR, ZIP, ZOO
Audio	WAV
BeOS
Binary
Blackberry
Boot
ByteCode	JAVA, MSIL, SWF
Console
Document	Access, CHM, Cookie, Excel, HTML, Multimedia, Office, OLE, PDF, PowerPoint, Project, Publisher, RTF, Visio, Word, XML
DOS
Email	MIME, MSG
EPOC
FreeBSD
Image	ANI, BMP, EMF, EPS, GIF, JPEG, OTF, PNG, TIFF, TTF, WMF
iOS
Linux
MacOS
Menuet
Novell
OS2
Package	NuGet
Palm
PDF
Script	ActiveX, AppleScript, ASP, AutoIt, AutoLISP, BAT, CGI, CorelDraw, Ferite, INF, INI, IRC, JS, KiXtart, Logo, Lua, Macro, Makefile, Matlab, Perl, PHP, PowerShell, Python, Registry, Ruby, Shell, Shockware, SQL, SubtitleWorkshop, VBS, WinHelp, WScript
Shortcut
Solaris
SunOS
Symbian
Text
Unix
Unknown
Video
WebAssembly
Win32
Win64
WinCE
WinPhone

Supported malware types

Malware types
Adware	Backdoor	Browser	Certificate	Coinminer	Dialer
Downloader	Dropper	Exploit	Format	Hacktool	Hyperlink
Infostealer	Keylogger	Mail	Malware	Network	Packed
Phishing	PUA	Ransomware	Rogue	Rootkit	Spam
Spyware	Trojan	Virus	Worm

Rule metadata

The metadata section is where you specify the details about the rule.

SDLC policy controls

The metadata must include the policy identifier (tc_policy_identifier) as a 7-character string starting with YR, followed by 5 digits (YRxxxxx, example: YR12345). You're free to determine the sequence of your identifiers.

Every custom SDLC policy you create must have a unique identifier.

The metadata may include your custom policy configuration that will apply when there is a match for the rule. If you omit the policy configuration, default values are used.

The following table lists optional policy configuration fields.

Field	Description	Default
tc_policy_status	Sets the CI/CD build status. Supported values: pass, fail	pass
tc_policy_severity	Sets the issue severity. Supported values: low, medium, high	low
tc_policy_effort	Sets the remediation level of effort for the issue. Supported values: low, medium, high	low
tc_policy_description	Sets a custom description for the policy.	N/A

meta:
      tc_policy_identifier  = "YR12345" 
      tc_policy_status      = "fail" 
      tc_policy_severity    = "high"
      tc_policy_effort      = "high" 
      tc_policy_description = "Detects YARA matches for a custom SDLC policy"

Threat detection

The metadata must include file classification fields that will apply when there is a match for the rule. Those fields are validated against the ReversingLabs malware naming standard. If their values are not valid, a generic malware threat name (Platform.Malware.YARA) is used for files classified by the rule.

The metadata may include additional fields to further describe and categorize the rule. ReversingLabs YARA rules conform to the CCCS YARA Specification and include a set of informative metadata fields from the specification.

Learn more

Read our blog post on writing custom YARA rules for actionable tips from ReversingLabs threat researchers.

The following table lists required file classification fields.

Field	Description	Default
tc_detection_type	Malware type. It's recommended to use the same type here and in the YARA rule name. Must be one of the values supported by the ReversingLabs malware naming standard.	Malware
tc_detection_name	Malware family name. It's recommended to use the same family name here and in the YARA rule name.	YARA
tc_detection_factor	When the rule is used to classify files as malicious or suspicious, the factor indicates threat severity (how dangerous the file is). The field supports integer values from 0 to 5, with 0 being the least dangerous, and 5 the most dangerous.	5

meta:
      tc_detection_type = "Infostealer"
      tc_detection_name = "IconBurst"
      tc_detection_factor = 5

Strings

The strings section is used to define patterns that a file must contain to be considered a match. You can specify those patterns as hexadecimal strings, text strings, and regular expressions.

Generally, the strings section is optional in YARA rules, but you will almost always need it for Spectra Assure policy controls.

Condition

The condition section is used to define criteria that must be met to trigger a match on a file. You can specify the criteria by using Boolean expressions.

The condition section is required in YARA rules.

YARA rule location

Custom YARA rules must be created as files with the .yara file extension and saved into a previously initialized rl-secure package store.

The exact placement of the rule in the package store hierarchy depends on how widely you want the rule to apply.

• To apply the rule to the entire package store, save it to the .yara directory in the root of the package store.
• To apply the rule to a specific project only, save it to the projects/my-project/.yara directory.
• To apply the rule to a specific package only, save it to the projects/my-project/packages/my-package/.yara directory.

Next steps

Follow our tutorials to create your first YARA rule:

• Create an SDLC policy YARA rule
• Create a threat detection YARA rule