Update docs

Author: Willem de Groot

CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing
+
+Found a new malware? Great! Add a new sample and rule in 5 minutes.
+
+1. Add malware file
+1. Find a literal string or regex that identifies the malware
+1. Run tests to validate results
+1. Make Pull Request
+1. 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.
+
+## Gather your malware samples
+
+Gather your malware samples in the `malware/incoming` folder of the _magento-malware-scanner_. To check if your samples aren't already detected by the current set of rules.
+
+```bash
+yara -r ./rules/all-confirmed.yar ./malware/incoming
+```
+
+If your sample is already detected for the right reasons, you may skip this sample.
+
+## Process the samples
+
+Running `md5_to_incoming.sh` will move your samples to the `malware/backend` directory and rename them with an md5 checksum.
+
+```bash
+./tools/md5_to_incoming.sh
+```
+
+We can now generate boilerplate rules using `tools/runtests.py`. This will make sure that each sample is covered by a YARA rule. If not, a boilerplate rule will be outputted.
+
+__example output__
+
+```
+// malware/backend/4c4b3d4ba5bce7191a5138efa2468679
+rule md5_4c4b3d4ba5bce7191a5138efa2468679 {
+    strings: $ = ""
+    condition: any of them
+}
+```
+
+Copy over the boilerplate rule(s) to `rules/backend.yar` and start editing them.
+
+## Creating rules
+
+Using the boilerplate rules, creating a rule can be as simple as defining a string to match.
+Malware signatures can be extremely specific (a file checksum) or too generic (check for suspicious `eval()`).
+
+__Example malware__
+
+```PHP
+<?php @eval(stripslashes($_REQUEST[q]));
+```
+__Example rule__
+
+```
+rule md5_d201d61510f7889f1a47257d52b15fa2 { // rule name (sample filename or descriptive name)
+    strings: $ = "@eval(stripslashes($_REQUEST[q]));" // string(s) to match
+    condition: any of them  // conditions
+}
+```
+
+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.
+1. It's better to be specific and have less coverage, than broad coverage and possibly raise false positives.
+1. Prefer Yara rules that have "any of them" as these rules can be converted in simple `grep` rules.
+1. Prefer string match over regex match (for speed)
+1. 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
+
+* [Writing YARA rules](http://yara.readthedocs.io/en/v3.5.0/writingrules.html)
+* [YARA in a Nutshell](http://virustotal.github.io/yara/)
+* [Example Yara Rules](https://github.com/Yara-Rules/rules)
+
+# 4. Test your rules
+
+This repository contains 2 tools and automated tests to make sure samples and fingerprints have at least one match and don't raise false flags.
+Run these before sending a pull request.
+
+## Verifying that samples and fingerprints have matches
+
+To verify this, run the following command from the project root:
+
+```bash
+python tools/validate_signatures.py
+```
+
+## Checking for false flags against vanilla Magento code
+
+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:
+
+```bash
+./tools/mageffcheck.sh
+
+# OR
+
+./tools/mageffcheck.sh help
+```
+
+You can initialize the test setup by appending the `init` argument
+
+```bash
+./tools/mageffcheck.sh init
+```
+
+This will download and extract several Magento packages from the [OpenMage Magento Mirror](https://github.com/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.
+
+```bash
+./tools/mageffcheck.sh run
+```
+You should expect _no output_ from running this command.
+
+
+# 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](https://twitter.com/jeremiahg/status/799734794737184768). But I haven't seen this behaviour in Magento specific malware yet. Let's enjoy the tide while it lasts.
+

CONTRIBUTING.md

@@ -1,5 +1,5 @@
 {
-  "name": "gwillem/magento-malware-collection",
+  "name": "gwillem/magento-malware-scanner",
   "description": "A collection of Magento malware detection rules",
   "type": "library",
   "homepage": "https://www.magereport.com/",