Skip to main content

Create custom policies with YARA

The secure.software 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 secure.software 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 secure.software 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 secure.software 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 secure.software products, it must conform to a special schema described in this guide. However, rules designed for secure.software 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.

To use a rule for secure.software 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

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
PlatformSubplatforms
ABAP
Android
AOL
ArchiveACE, AR, ARJ, BZIP2, CAB, GZIP, ISO, JAR, LZH, RAR, 7ZIP, SZDD, TAR, XAR, ZIP, ZOO
AudioWAV
BeOS
Binary
Blackberry
Boot
ByteCodeJAVA, MSIL, SWF
Console
DocumentAccess, CHM, Cookie, Excel, HTML, Multimedia, Office, OLE, PDF, PowerPoint, Project, Publisher, RTF, Visio, Word, XML
DOS
EmailMIME, MSG
EPOC
FreeBSD
ImageANI, BMP, EMF, EPS, GIF, JPEG, OTF, PNG, TIFF, TTF, WMF
iOS
Linux
MacOS
Menuet
Novell
OS2
PackageNuGet
Palm
PDF
ScriptActiveX, 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
AdwareBackdoorBrowserCertificateCoinminerDialer
DownloaderDropperExploitFormatHacktoolHyperlink
InfostealerKeyloggerMailMalwareNetworkPacked
PhishingPUARansomwareRogueRootkitSpam
SpywareTrojanVirusWorm

Rule metadata​

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

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.

FieldDescriptionDefault
tc_policy_statusSets the CI/CD build status. Supported values: pass, failpass
tc_policy_severitySets the issue severity. Supported values: low, medium, highlow
tc_policy_effortSets the remediation level of effort for the issue. Supported values: low, medium, highlow
tc_policy_descriptionSets 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"

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 secure.software 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: