1 files changed, 69 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..15b1d08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# PHP Malware Finder
+
+ ```
+  _______  __   __  _______
+ |  ___  ||  |_|  ||       |
+ | |   | ||       ||    ___|
+ | |___| ||       ||   |___   Webshell finder,
+ |    ___||       ||    ___|   kiddies hunter,
+ |   |    | ||_|| ||   |                website cleaner.
+ |___|    |_|   |_||___|
+
+Detect potentially malicious PHP files.
+```
+
+## What does it detect?
+
+PHP-malware-finder does its very best to detect obfuscated/dodgy code as well as files using PHP functions often used in malwares/webshells.
+
+The following list of encoders/obfuscators/webshells are also detected:
+
+* [Best PHP Obfuscator]( http://www.pipsomania.com/best_php_obfuscator.do )
+* [Carbylamine]( https://code.google.com/p/carbylamine/ )
+* [Cipher Design]( http://cipherdesign.co.uk/service/php-obfuscator )
+* [Cyklodev]( http://sysadmin.cyklodev.com/online-php-obfuscator/ )
+* [Joes Web Tools Obfuscator]( http://www.joeswebtools.com/security/php-obfuscator/ )
+* [Php Obfuscator Encode]( http://w3webtools.com/encode-php-online/ )
+* [SpinObf]( http://mohssen.org/SpinObf.php )
+* [Weevely3]( https://github.com/epinna/weevely3 )
+* [atomiku]( http://atomiku.com/online-php-code-obfuscator/ )
+* [cobra obfuscator]( http://obfuscator.uk/example/ )
+* [phpencode]( http://phpencode.org )
+* [webtoolsvn]( http://www.webtoolsvn.com/en-decode/ )
+
+
+## How does it work?
+
+Detection is performed by crawling the filesystem and testing files against a [set]( https://github.com/nbs-system/php-malware-finder/blob/master/malwares.yara )
+of [YARA](https://plusvic.github.io/yara/) rules. Yes, it's that simple!
+
+
+## How to use it?
+
+```
+$ ./phpmalwarefinder -h
+Usage phpmalwarefinder [-cfhw] <file|folder> ...
+        -c  Optional path to a configuration file
+        -f  Fast mode
+        -h  Show this help message
+        -v  Verbose mode
+```
+
+Or if you prefer to use `yara`:
+
+```
+$ yara -r ./malwares.yara /var/www
+```
+
+## Whitelisting
+
+Check the [whitelist.yara]( https://github.com/nbs-system/php-malware-finder/blob/master/whitelist.yara ) file.
+If you're lazy, you can generate whitelists for entire folders with the [generate_whitelist.py]( https://github.com/nbs-system/php-malware-finder/blob/master/generate_whitelist.py ) script.
+
+## Licensing
+
+PHP-malware-finder is [licensed]( https://github.com/nbs-system/php-malware-finder/blob/master/LICENSE ) under the GNU General Public License v3.
+
+YARA (which is bundled with this software) is licensed under the Apache v2.0 license.
+
+Patches, whitelists or samples are of course more than welcome.