You can create custom YARA rules which contain tags that are assigned to tracked files.

Prerequisites

To get familiar with YARA rule parameters, see YARA Rule Parameters.

For a list of the YARA tags that have predefined meanings, see YARA Rule Tags.

To get familiar with YARA CBEP attributes, see YARA CBEP Attributes.

Important: In general, consider YARA rules to be completely case-sensitive.
  • Rule identifiers can differ only by case, for example, "ABC" and "abc" can identify completely different rules.
  • Operators such as == and contains use case-sensitive semantics and may return counter-intuitive results. For example, hash.sha1(0, filesize) == "7193B6EDF651EAC1AB437F64B2FD6F203F8B702F" will never return true because YARA hashes use lower case hexadecimal digits. There are no modifiers or workarounds available for this.
  • Regular expressions can be used as workarounds for case-sensitivity. For example, == returns false for hashes with differing case. However, the required results can be obtained by using a case insensitive regular expression: (cbep.analysis.file.signature.codesigning_chain[0].cert[0].sha1_thumbprint matches /^09A5C5E9AF1B96091B22F92E0356B1C33A410420$/is. For information on regular expressions, see https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference.
  • The Windows Agent generally ignores the case of YARA tags, however, it is recommended always to use lower case when using predefined tags. Tags in the Classification namespace are always treated case-insensitively, for example, QUARANTINE becomes quarantine. However, some of the predefined tags in the IsInteresting namespace must be lower case for them to be recognized. These tags are: archive, dep_incompatible, executable, filetype, installer, invalid, script, and script_interpreter.
For more information, see https://yara.readthedocs.io/en/stable/index.html.
Warning: The quarantine tag will cause a file to be deleted if tagged with it.
Important: YARA rules are powerful and can have far-reaching, unexpected consequences. It is strongly recommended that you test a rule before you enable it for your endpoints. Ensure you are familiar with the instructions in Test a YARA Rule.

Procedure

  1. On the console menu, navigate to the Rules > Software Rules page.
  2. Click the YARA tab and select the Add YARA Rule button.
    The Add YARA Rule page appears.
  3. In the Name field, enter the name you want to appear on the YARA rules table.
  4. Select the namespace for the rule.
    Important: It is recommended to add rules to the Classification namespace. Do not add rules to the IsInteresting namespace unless they are required. The agent picks up executable (PE format) files and scripts from existing script rules. There is little to no benefit for adding additional IsInteresting rules.
  5. Optional. Provide a description for the YARA rule.
  6. Optional. Enter a macro for the YARA rule in the Qualifiers field.
  7. To enable the rule, click Enabled in the Status field.
  8. Enter the YARA rule.
    Note: For the agent to apply any tags set by one or more rules where the namespace is specified as IsInteresting, the final tag applied to a file must be filetype. The agent will only treat a file as interesting if either the executable tag or the script tag was applied before the filetype tag. The archive tag and the installer tag can also be used, although they do not determine the interesting status.
    Warning: Ensure tags are used in only one namespace. For example, do not use the same tag in a rule in the Classification namespace and subsequently in a rule in the IsInteresting namespace. Otherwise, tags might not be removed from an analysis when a YARA rule is edited or deleted.
  9. Do one of the following actions to choose when to rescan files:
    • For a YARA rule where the Namespace is specified as Classification, if you want to rescan known files, click Rescan known files, and then select to rescan the files immediately or schedule the rescan to begin later.
    • For a YARA rule where the Namespace is specified as IsInteresting, for Full scan for new files, select to perform the full system scan immediately or schedule the scan to begin later. The full scan could impact the performance of a lot of machines.
  10. Under Detected Tags, verify tags in your YARA rule that already exist and were provided by VMware Carbon Black. If you do not intend that a tag is used in your rule, update the rule. Alternatively, you might want to specify in your rule that a tag is approved.
  11. Before you save the rule to create it, it is strongly recommended to test it by following some or all of the steps in Test a YARA Rule.
  12. When you are satisfied with the rule, click Save & Exit to create it.

Results

The new rule appears in the YARA Rules table.

The agent must sync with the server and download the new rule for it to become effective.

If the YARA rule is enabled and the Namespace is defined as Classification, all new or modified files will be scanned and the rule tags will be assigned if the rule criteria is met. If you chose to rescan known files, they are rescanned immediately or the rescan will begin during the time range you selected.

If the YARA rule is enabled and the Namespace is defined as IsInteresting, all new or modified files will be scanned and the rule tags will be assigned if the rule criteria is met. If you chose to perform a full system scan, it is performed immediately or will begin during the time range you selected.

What to do next

You can use native custom rules or create a custom rule to determine an action to be taken on a file based on if it has a tag from the new rule assigned to it.