Skip to content

Latest commit

 

History

History
176 lines (113 loc) · 6.06 KB

CONTRIBUTING.md

File metadata and controls

176 lines (113 loc) · 6.06 KB
Raw

Contributing

Found a new malware? Great! Add a new sample and rule in 5 minutes.

  1. Add malware file
  2. Find a literal string or regex that identifies the malware
  3. Run tests to validate results
  4. Make Pull Request
  5. Profit!

Every malware should have at least 1 corresponding rule.

Every rule should have at least 1 corresponding malware.

How to add malware

After installing the requirements, malware can be added by following these steps.

Install required tools

Using Debian/Ubuntu

sudo apt install -qy yara

Using CentOS

# If you don't have EPEL yet, for CentOS 6:
wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
sudo rpm -ivh epel-release-latest-6.noarch.rpm

sudo yum -y install yara

Using macOS

If you don't have Homebrew yet, follow instructions on https://brew.sh/

brew install coreutils python3 yara md5sha1sum gnu-sed

Gather your malware samples

Save your malware sample in the corpus/incoming/frontend folder for JavaScript samples, or corpus/incoming/backend folder for PHP samples.

Create an MD5 hash of the file, rename it and move it to the appropriate corpus.

For PHP samples:

tools/backend_md5_to_incoming.sh

For JavaScript samples:

tools/frontend_md5_to_incoming.sh

Check if your sample isn't already detected:

tools/validate_signatures.py

If it's not recognized yet, it will show you a warning. Please proceed to contribute it!

Create a rule

Please edit frontend.txt or backend.txt in the rules folder. You have two options here:

  1. Create a string literal: just copy/past a relevant portion of the malware. It will be scanned as-is (no backslash escaping etc).
  2. Create a regular expression. This is more powerful, but also slower. Please only use if absolutely necessary.

Malware signatures can be extremely specific (a file checksum) or too generic (check for suspicious eval()). In case of doubt, choose specific. We try to avoid false positives at all costs!

Example malware

<?php @eval(stripslashes($_REQUEST[q]));

Example rule

# eval looks evil
@eval(stripslashes($_REQUEST[q]));

The above example is simple and sufficient. More advanced samples may require more complex signatures. See below for signature writing strategies. In short:

  1. One signature can cover multiple strains of malware.
  2. It's better to be specific and have less coverage, than broad coverage and possibly raise false positives.
  3. Prefer string match over regex match (for speed)
  4. If using regex, limit the use of unbound match operators (+ or *) as they might have to scan the whole file. Better: {,x} to limit to x characters.

For more information on writing rules, refer to the documentation below

Test your rules

Re-run the validator to verify that your signature indeed identifies the new malware:

tools/validate_signatures.py

No warnings? Great! Please commit and PR.

Testing against multiple Magento installations

Once you submit a PR, our Travis job will check your signature against a plethora of Magento installations, just in case. You can also run this locally:

The tools/mageffcheck.sh bash script has a couple of commands available to get you started. The idea is to download and extract various vanilla Magento packages and run the YARA tests against it. When these tests return output, it's most likely a false flag.

Running the following command will output some information:

tools/mageffcheck.sh

# OR

tools/mageffcheck.sh help

You can initialize the test setup by appending the init argument

tools/mageffcheck.sh init

This will download and extract several Magento packages from the OpenMage Magento Mirror.

Note: When using an IDE

Downloading and extracting several Magento package may trigger the IDE's indexation. Due to the amount of code it may lag or even hang (for a while). These packages will be stored in ./tmp make sure to mark this directory as excluded before or right after running init.

After this you could run the following to trigger the YARA tests against the vanilla code.

tools/mageffcheck.sh run

You should expect no output from running this command.

Whitelisting

  1. View the content of the file you consider a false positive
  2. Make sure you understand every character of the content
  3. Make sure there is no hidden text at the end of lines by using lots of spaces
  4. Create a part of the path as sub directories in corpus/whitelisted, for example Vendorname/Extensionname
  5. Place the file in the directory
  6. Build the rules using tools/validate_signatures.py
  7. Test if your file is now skipping using:
mwscan -r build/mwscan.yar -w build/mwscan.yar /path/to/magento

Signature strategies

Malware signatures can be extremely specific (a file checksum) to generic (check for suspicious eval()) or anything in between. As a signature author, you have to decide on a proper balance. Pro specific: no chance for false positives. Pro generic: less work, as one signature will catch multiple strains of malware.

In case of doubt, choose specific.

Taking a shortcut with a more generic signature might be tempting, but if it causes false positives (possibly in the future), you will have to deal with the fallout, plus have to repeat your malware analysis.

Remember, we can already win a lot by de-duplicating unique malware instance identification across organisations. Identifying future, or merely suspicious, malware is also desireable but requires a different strategy.

Other malware research suggests that malwares are quickly morphing, rendering the average lifespan of a unique malware instance to be only 58 seconds. But I haven't seen this behaviour in Magento specific malware yet. Let's enjoy the tide while it lasts.