Git Product home page Git Product logo

cccs-yara's Introduction

Canadian Centre for Cyber Security

CCCS YARA Specification

The CCCS YARA Specification has been created to define and validate the style and format of YARA rule metadata. It comes with a cli which allow you to validate and generate metadata automatically (such as unique id, rule fingerprint, actor enrichment from ATT&CK).

Over the years we have seen many YARA rules; in order to leverage them to their full potential we always had to modify some of their associated metadata, even for rules we developed ourselves. Adjusting simple elements such as datetime format and adding important information to help analysts.

You can leverage it in your CI/CD pipeplines to automatically verify and enrich your Yara rules before new rules are merged in!

This specification also include fields specific to the MITRE ATT&CK framework to identify techniques and universal MITRE ATT&CK threat groups.

AssemblyLine supports this specification natively and will leverage it to provide more context around YARA signature hits.

vscode-yara creates a custom meta section that aligns with this specification, using the User or Workspace settings file, settings.json. See settings.json for an example.

Sample rule

rule MemoryModule {
    meta:
	id = "6O9mUMvPhziJ72IXHf6muZ"
	fingerprint = "4aa0a23f28698898404d700cb363ddf06dd275f5798815e797113656a2a40ae8"
	version = "1.0"
	date = "2020-05-06"
	modified = "2020-05-06"
	status = "RELEASED"
	sharing = "TLP:WHITE"
	source = "CCCS"
	author = "analyst@CCCS"
	description = "Yara rule to detect usage of MemoryModule Library"
	category = "TECHNIQUE"
	technique = "LOADER:MEMORYMODULE"
	mitre_att = "T1129"
	report = "TA20-0192"
	hash = "812bbe8b9acabad05b08add50ee55c883e1f7998f3a7cae273d3f0d572a79adc"

    strings:
        $func_ptr =    {55 8B EC 6A 00 68 [3] 00 68 [3] 00 68 [3] 00 68 [3] 00 68 [3] 00}
        $func_ptr_64 = {48 [3] 48 [4] 00 00 00 00 48 8? [5] 48 8? [3] 4? 8? [5] 48 8? [3-5] 48 8?}
        $api_1 = "LoadLibraryA"
        $api_2 = "GetProcAddress"
        $api_3 = "FreeLibrary"
        $api_4 = "VirtualFree"
        $api_5 = "VirtualProtect"
        $api_6 = "VirtualAlloc"

    condition:
        uint16(0) == 0x5a4d and all of ($api*) and ($func_ptr or $func_ptr_64)
}

YARA repositories using this standard - thanks!

Components

validator.py: This is the validator library. It is used to validate the metadata section of YARA rules. It verifies specified metadata information, auto-generates some of metadata information and re-sorts the metadata information into the canonical order with all 'unknown' metadata information appended to the bottom.

  • CCCS_YARA.yml: This is the definition of the CCCS YARA Standard in the YAML format. (Limitation: This file is provided to show what fields are expected, currently the yara_validator doeSn't use this file directly, this will be addressed in a future release.)

  • CCCS_YARA_values.yml: File which describe the list of acceptable values for fields defined in the CCCS_YARA.yml

yara_validator: This is a command line interface utility. It takes a file, list of files, a folder looking for files with the .yar or .yara extension.

Requirements

Python 3.6+

All required python packages are in the requirements.txt

The Cyber Threat Intelligence Repository is a submodule of this repository:

git clone https://github.com/CybercentreCanada/CCCS-Yara.git
cd CCCS-Yara
pip install  .

yara_validator usage

yara_validator -h
     ____ ____ ____ ____   __   __ _    ____      _
    / ___/ ___/ ___/ ___|  \ \ / // \  |  _ \    / \
   | |  | |  | |   \___ \   \ V // _ \ | |_) |  / _ \
   | |__| |__| |___ ___) |   | |/ ___ \|  _ <  / ___ \
    \____\____\____|____/    |_/_/   \_\_| \_\/_/   \_\

usage: yara_validator [-h] [-r] [-n] [-v] [-vv] [-f] [-w] [-s] [-st]
                             [-m] [-i | -c]
                             paths [paths ...]

CCCS YARA script to run the CCCS YARA validator, use the -i or -c flags to
generate the id, fingerprint, version, first_imported, or last_modified (if
not already present) and add them to the file.

positional arguments:
  paths                A list of files or folders to be analyzed.

optional arguments:
  -h, --help           show this help message and exit
  -r, --recursive      Recursively search folders provided.
  -n, --no-changes     Makes no changes and outputs potential results to the
                       output.
  -v, --verbose        Verbose mode, will print why a rule was invalid.
  -vv, --very-verbose  Very-verbose mode, will printout what rule is about to
                       be processed, the invalid rules, the reasons they are
                       invalid and all contents of the rule.
  -f, --fail           Fail mode, only prints messages about invalid rules.
  -w, --warnings       This mode will ignore warnings and proceed with other
                       behaviors if the rule is valid.
  -s, --standard       This prints the YARA standard to the screen.
  -st, --strict        This causes the cli to return a non-zero exit code for
                       warnings.
  -m, --module         This flag overrides the check for modules that have not
                       been imported.
  -i, --in-place       Modifies valid files in place, mutually exclusive with
                       -c.
  -c, --create-files   Writes a new file for each valid file, mutually
                       exclusive with -i.

Quick example:

# Rule will be converted inline
python yara_validator -v -i <path>

Centre canadien pour la cybersécurité

Spécification YARA du CCCS

La Spécification YARA du CCCS a été créé pour définir et validé le style et le format des attributs pour les règles YARA. Un outil ligne de commandes permet de valider et généré les tags automatiquement!

Au fil des années nous avons vu beaucoup de régles YARA; mais pour pouvoir les utilisées à leur plein potentiel nous devions modifiée les méta données associtiées, parfois même pour nos propres règles. En ajustant des éléments aussi simples que le format de date et en ajoutant des attributs important pour les analystes.

Ce standard pour les méta données inclus aussi des champs spécifique au MITRE ATT&CK framework pour identifier les techniques et les groups d'acteurs MITRE ATT&CK threat groups.

AssemblyLine supporte cette spécification nativement et l'utilisera pour fournir d'avantage d'information à l'utilisateur lors du déclanchement d'une signature.

Exemple

rule MemoryModule {
    meta:
	id = "6O9mUMvPhziJ72IXHf6muZ"
	fingerprint = "4aa0a23f28698898404d700cb363ddf06dd275f5798815e797113656a2a40ae8"
	version = "1.0"
	date = "2020-05-06"
	modified = "2020-05-06"
	status = "RELEASED"
	sharing = "TLP:WHITE"
	source = "CCCS"
	author = "analyst@CCCS"
	description = "Yara rule to detect usage of MemoryModule Library"
	category = "TECHNIQUE"
	technique = "LOADER:MEMORYMODULE"
	mitre_att = "T1129"
	report = "TA20-0192"
	hash = "812bbe8b9acabad05b08add50ee55c883e1f7998f3a7cae273d3f0d572a79adc"

    strings:
        $func_ptr =    {55 8B EC 6A 00 68 [3] 00 68 [3] 00 68 [3] 00 68 [3] 00 68 [3] 00}
        $func_ptr_64 = {48 [3] 48 [4] 00 00 00 00 48 8? [5] 48 8? [3] 4? 8? [5] 48 8? [3-5] 48 8?}
        $api_1 = "LoadLibraryA"
        $api_2 = "GetProcAddress"
        $api_3 = "FreeLibrary"
        $api_4 = "VirtualFree"
        $api_5 = "VirtualProtect"
        $api_6 = "VirtualAlloc"

    condition:
        uint16(0) == 0x5a4d and all of ($api*) and ($func_ptr or $func_ptr_64)
}

Répertoires de règles YARA qui utilise ce standard - merci!

Composantes

validator.py: La librairie de validation. Elle permet de vérifier si une règle YARA a tous les attributs nécessaires, elle auto-génère aussi certain attribut et les ordonnent selon l'ontologie. Tous les attributs supplémentaires ne faisant pas partie de la spécification sont placé à la fin.

  • CCCS_YARA.yml: Fichier de de définition de la spécification. (Limitation: Ce fichier démontre les attributs nécessaires, présentement le validateur n'utilise pas se fichier directement, ceci sera améliorer dans le futur.)

  • CCCS_YARA_values.yml: Fichier qui décrit les valeurs acceptables pour chacun des attributs définit dans CCCS_YARA.yml.

yara_validator: Utilitaire de validation pour la ligne de commande. Il accepte une règle, une liste de règles ou un dossier pour validé les fichiers se terminant par .yar ou .YARA.

Exigences

Python 3.6+

Tous les libraries python sont dans le fichier requirements.txt

Cyber Threat Intelligence Repository est un sous module de ce répertoire:

git clone https://github.com/CybercentreCanada/CCCS-Yara.git
cd CCCS-Yara
pip install  .

yara_validator en ligne de commandes

yara_validator -h
     ____ ____ ____ ____   __   __ _    ____      _
    / ___/ ___/ ___/ ___|  \ \ / // \  |  _ \    / \
   | |  | |  | |   \___ \   \ V // _ \ | |_) |  / _ \
   | |__| |__| |___ ___) |   | |/ ___ \|  _ <  / ___ \
    \____\____\____|____/    |_/_/   \_\_| \_\/_/   \_\

usage: yara_validator [-h] [-r] [-n] [-v] [-vv] [-f] [-w] [-s] [-st]
                             [-m] [-i | -c]
                             paths [paths ...]

CCCS YARA script to run the CCCS YARA validator, use the -i or -c flags to
generate the id, fingerprint, version, first_imported, or last_modified (if
not already present) and add them to the file.

positional arguments:
  paths                A list of files or folders to be analyzed.

optional arguments:
  -h, --help           show this help message and exit
  -r, --recursive      Recursively search folders provided.
  -n, --no-changes     Makes no changes and outputs potential results to the
                       output.
  -v, --verbose        Verbose mode, will print why a rule was invalid.
  -vv, --very-verbose  Very-verbose mode, will printout what rule is about to
                       be processed, the invalid rules, the reasons they are
                       invalid and all contents of the rule.
  -f, --fail           Fail mode, only prints messages about invalid rules.
  -w, --warnings       This mode will ignore warnings and proceed with other
                       behaviors if the rule is valid.
  -s, --standard       This prints the YARA standard to the screen.
  -st, --strict        This causes the cli to return a non-zero exit code for
                       warnings.
  -m, --module         This flag overrides the check for modules that have not
                       been imported.
  -i, --in-place       Modifies valid files in place, mutually exclusive with
                       -c.
  -c, --create-files   Writes a new file for each valid file, mutually
                       exclusive with -i.

cccs-yara's People

Contributors

0xthiebaut avatar bartblaze avatar cccs-gm avatar cccs-jp avatar cccs-js avatar cccs-kun avatar cccs-ma avatar cccs-rs avatar cccs-walle avatar dependabot-preview[bot] avatar johnlatwc avatar malvidin avatar xe6077 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

cccs-yara's Issues

Validation Reject Valid Rules with Non-ASCII Characters

Rules that contain non-ASCII characters in metadata are inappropriately rejected. YARA reads the rules in as bytes, and processes the metadata strings similarly to strings.

There are more issues with escaped values in metadata strings (\x00, \x80-\xFF) than with printable non-ASCII strings.

Recommend accepting non-ASCII characters in rules, modifying rules that contain values that can be unescaped (\000, \x80-\xFF, etc.), and performing a test compilation of the rules with yara-python.
VirusTotal/yara#1242

yr = yara.compile(source=r'rule test:tag {meta: emoji = "👍" escaped = "\x7E" condition: true}')
... print(yr.match(data='')[0].meta)
{'emoji': '👍', 'escaped': '~'}

yr = yara.compile(source=r'rule test:tag {meta: emoji = "👍" escaped = "\x7F" condition: true}')
... print(yr.match(data='')[0].meta)
{'emoji': '👍', 'escaped': '\x7f'}

yr = yara.compile(source=r'rule test:tag {meta: emoji = "👍" escaped = "\x80" condition: true}')
... print(yr.match(data='')[0].meta)
Process finished with exit code -1073741819 (0xC0000005)

Bug: Whitespace Formatting Loop

Hey guys,

I found a strange bug. Under certain conditions re-running yara_validator_cli.py with inplace modification adds unnecessary whitespace to a file

I've been using cccs-yara to help validate a repo of yara rules. As part of that workflow, the rules end up being checked pretty consistently with the flags -i -v for in place changes to be made. Rerunning the validation can add up to kilobytes of whitespace to a file.

A test yara rule which triggers the bug can be seen below:

rule TEST_WhitespaceFeedback {
    meta:
        author = "TEST"
        date = "2021-02-04"
        description = "Testing to see how repeated uses of the validator result in large whitespace getting added"
        version = "1.0"
        info = "TEST CASE"
        category = "INFO"
        id = "h6DuDsSCZf8tvpoqorxKB"
        fingerprint = "ef3a9feef8f376382ecb07a970b37790ba56b7adce6bf072acfb8c94e0858ba6"
        first_imported = "2021-02-04"
        last_modified = "2021-02-04"
        status = "TESTING"
        sharing = "TLP:WHITE"
        source = "TESTING"

    strings:
        $s1 = "test123"
                        
         $s2 = "abc456"
        $s3 = "blah blah blah"

    condition:
        all of them
}

Note there is whitespace added longer than the usual tabs between $s1 and $s2.

Issue with import modules

When validating Yara rules with imported modules, the validator appears to fail. Any ideas?

$ cat ~/test.yara
import "pe"

rule test
{
    meta:
    condition:
        pe.number_of_resources > 1
}
$ python yara_validator_cli.py -v ~/test.yara
Validating Rule file:                   /root/test.yara
🍩 Invalid Rule File:                   /root/test.yara
     - Errors:
       - test.yara:                     Error Compiling YARA file with yara:    'line 6: syntax error'

README Suggestions

When creating a PR I noticed the README documentation seems to be out of date.

  • Documentation suggests using yara_validator_cli.py. However that does not appear to exist when installing via the latest from master. Setup.py appears to install this component as yara_validator. May need to switch the README to just yara_validator instead and update associated usage.
  • Also noticed the library yara_validator.py appears to have been changed to just validator.py but is still referenced using the old name.

I'd toss in a PR candidate for this, but my French is not so great. Depending on the desired documentation updates being made, would require more than I can offer in that department! :)

Metadata Parsing Errors

In a few situations, a valid rule fails to be written (using -c or -i) with the following error:

./CCCS-Yara/yara-validator/yara_file_processor.py", line 184, in strings_of_rules_to_original_file
    changed_rule_string = rule.rule_return.validated_rule.splitlines()
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'list' object has no attribute 'splitlines'

These regular expressions appear to the cause of the issue:

meta_regex = r'^\s*meta\s*:\s*$'
next_section = r'^\s*(?:strings|condition)\s*:\s*$'

Based on these expressions:

  • meta and : must be on the same line, and be the only contents of that line.
  • The following strings or condition and : must be on the same line, and be the only contents of that line.

This breaks otherwise valid rules:

rule testing 
{ meta:
    key = "value"
  condition:
    true
}
rule testing {
  meta:
    key = "value"
  strings: $re = /test/
  condition: $re
}
rule testing 
{ meta:
    key = "value"
  condition: true
}

And on the most extreme end:

rule testing { meta: key = "value" condition: true }

Invalid field name "typelib"

Hi folks,

Compiled some new rules and updated to the standard - however, one rule imports the dotnet module - which the YARA validator does not seem to like as I'm getting an error compiling with an invalid field name of typelib.

In the yara_file_processor.py I see several modules that are not defined - are they not supported natively in AL? Or is there another reason to not have these included?

Thanks!

last_modified date being overwritten

When running yara_validator_cli.py, the last_modified metadata attribute is being overwritten with the current date whether the value already exists in the yara rule or not. This is only happening for last_modified and not first_imported.

I would think the expected behavior is to leave the last_modified date as-is if found in the rule metadata.

The scenario where i ran into this was when importing an external ruleset that already had last_modified dates set. I would like to keep those dates as-is for context.

Feature Request: Treat Warnings as Errors

Hey guys, your tool is amazing.

I would like a feature to make warnings get treated as errors.

In my workflow, I want to allow the metadata entry "hash" but don't want to allow "hash1, hash2, etc." Right now, if hash1 is included then a warning is thrown that it is similar to hash. I want that to be treated by an error.

If theres already a way to accomplish that, I'd happily take some advice on it.

Thanks again.

Add an option to ignore private rules ?

Private yara rules are not reported by yara when they match. I believe many people uses them for rules such as:

private rule IsPE {
    meta:
        description = "Ientifies Portable Executable binaries that has a valid magic in DOS and NT header"
    condition:
        (uint16(0) == 0x5A4D or uint16(0) == 0x4D5A) and uint32(uint32(0x3c)) == 0x00004550
}

Because these rules are never reported, and they are mostly referenced by other rules, does it make sense to ignore them in the validation process by adding a flag in the CLI or an option in the py package ?

This will save us from being obliged to add meta attributes to these rules. What do you think ?

Cheers.

Bug: Invalid yara rules pass validation

Yara validation appears to succeed when the rule doesn't contain a closing bracket. Example yara rule:

rule APT_CN_TestYara {
   meta:
      description = "Detect malware"
      author = "TEST"
      date = "2021-01-12"
      version = "1.0"

   strings:
      $s1 = "test"
   condition:
      $s1

In case its relevant, there is no newline at the end of the file. This was tested using the default CCCS_YARA.yml file from commit (91e66c4)

Recommended changes

I wonder why you haven't looked a the thousands of published YARA rules before you've decided on the fields in your standard.

I recommend the following changes to align your specs with the best practices in the real world:

source > reference

^ source could imply that the rule was copied from somewhere else, although most often it's derived from a sample or blog article.

first_imported > date

what does first imported even mean? It implies that you "import" a YARA rule somewhere and limits the field to that use case.

last_modified > modified

The prefix last_ is unnecessary.

Recommended further fields currently missing:

minimum_yara

^ indicating the minimal YARA version required to run the rule. This is very important since new modifiers, module features and keywords get added every few months. (e.g. icontains, xor)

e.g.

minimum_yara = "4.2"

Furthermore, have you considered using the YARA tags instead of certain fields?
For tags of all kinds, one could add a field tags and format it as a comma separated list.

e.g.


rule EXPL_LOG_ProxyNotShell_OWASSRF_PowerShell_Proxy_Log_Dec22_1_RID3C7E {
   meta:
      description = "Detects traces of exploitation activity in relation to ProxyNotShell MS Exchange vulnerabilities CVE-2022-41040 and CVE-2022-41082"
      author = "Florian Roth"
      reference = "https://www.crowdstrike.com/blog/owassrf-exploit-analysis-and-recommendations/"
      date = "2022-12-22 21:14:11"
      score = 70
      customer = "demo"
      license = "CC-BY-NC https://creativecommons.org/licenses/by-nc/4.0/"
      
      tags = "CVE_2022_41040, CVE_2022_41082, DEMO, EXPLOIT, HKTL, LOG, SCRIPT, T1028, T1059_001, T1086, T1090"
      minimum_yara = "1.7"
      
   strings:
      $s1 = "/owa/mastermailbox%40outlook.com/powershell" ascii wide
      $sa1 = " 200 " ascii wide
      $sa2 = " POST " ascii wide
      $fp1 = "ClientInfo" ascii wide fullword
      $fp2 = "Microsoft WinRM Client" ascii wide fullword
      $fp3 = "Exchange BackEnd Probes" ascii wide fullword
   condition: 
      all of ( $s* ) and not 1 of ( $fp* )
}

Following your approach, e.g. with the fields mitre_att and sharing, we would get an ever growing specification with many more fields. A field that lists all tags would be more ... practical IMHO.

Rule Hashing Duplicates plyara Function

Looking at the differences between generate_logic_hash from plyara.utils and calculate_rule_hash from the CCCS-Yara validator_functions, I can't see a significant benefit from duplicating the capability.

Is there an issue with the plyara function that hasn't been raised there?

How to describe cases when a yara rule have multiple hashes

Hello,

Sometimes, it is useful to reference more than one hash in a yara rule, this comes often when we have a same malware family, but multiple versions.

What's the best way to do that ? I saw some people just separating hashes with a ,.

Sample rule is not CCCS valid

The following meta tag in the sample rule in the README.md file is not CCCS valid:

technique = "LOADER:MEMORYMODULE"

This is due to the colon in place. Removing this colon makes the rule valid, but I'm not sure if that is what is intended.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.