From 13bc864e112e9edbaf0652b0f75216b4c5dc9ab6 Mon Sep 17 00:00:00 2001
From: msm-code <msm@tailcall.net>
Date: Mon, 24 May 2021 17:42:24 +0200
Subject: [PATCH] Extend the readme with code examples (#62)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend the readme with code examples

Co-authored-by: msm <msm@cert.pl>
Co-authored-by: Michał Praszmo <nazywam@gmail.com>
---
 README.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 97 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 291471d..941e315 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,113 @@
-:duck: Malduck
-=========
+# :duck: Malduck
 
 Malduck is your ducky companion in malware analysis journeys. It is mostly based on [Roach](https://github.com/hatching/roach) project, which derives many concepts from [mlib](https://github.com/mak/mlib) 
 library created by [Maciej Kotowicz](https://lokalhost.pl). The purpose of fork was to make Roach independent from [Cuckoo Sandbox](https://cuckoosandbox.org/) project, but still supporting its internal `procmem` format.
 
 Malduck provides many improvements resulting from CERT.pl codebase, making scripts written for malware analysis purposes much shorter and more powerful. 
 
-Improvements
-============
+## Features
 
-* Support for (non)memory-mapped PE images without header fix-up.
-* Searching for wildcarded byte sequences
-* Support for x64 disassembly
-* Fixed-precision integer types
-* Many improvements in ProcessMemory
+- **Cryptography** (AES, Blowfish, Camelie, ChaCha20, Serpent and many others)
+- **Compression algorithms** (aPLib, gzip, LZNT1 (RtlDecompressBuffer))
+- **Memory model objects** (work on memory dumps, PE/ELF, raw files and IDA dumps using the same code)
+- **Extraction engine** (modular extraction framework for config extraction from files/dumps)
+- Fixed integer types (like Uint64) and bitwise utilities
+- String operations (chunks, padding, packing/unpacking etc)
+- Hashing algorithms (CRC32, MD5, SHA1, SHA256)
 
-Usage
-==========
+## Usage examples
 
-Installing may be performed by running
+#### AES
+
+```python
+from malduck import aes
+
+key = b'A'*16
+iv = b'B'*16
+plaintext = b'data'*16
+ciphertext = aes.cbc.encrypt(key, iv, plaintext)
+```
+
+### Serpent
+
+```python
+from malduck import serpent
+
+key = b'a'*16
+iv = b'b'*16
+plaintext = b'data'*16
+ciphertext = serpent.cbc.encrypt(key, plaintext, iv)
+```
+
+### APLib decompression
+
+```python
+from malduck import aplib
+
+# Headerless compressed buffer
+aplib(b'T\x00he quick\xecb\x0erown\xcef\xaex\x80jumps\xed\xe4veur`t?lazy\xead\xfeg\xc0\x00')
+```
+
+### Fixed integer types
+
+```python
+from malduck import DWORD
+
+def sdbm_hash(name: bytes) -> int:
+    hh = 0
+    for c in name:
+        # operations on the DWORD type produce a dword, so a result
+        # is also a DWORD.
+        hh = DWORD(c) + (hh << 6) + (hh << 16) - hh
+    return int(hh)
+```
+
+### Extractor engine - module example
+
+```python
+from malduck import Extractor
+
+class Citadel(Extractor):
+    family = "citadel"
+    yara_rules = ("citadel",)
+    overrides = ("zeus",)
+
+    @Extractor.string("briankerbs")
+    def citadel_found(self, p, addr, match):
+        log.info('[+] `Coded by Brian Krebs` str @ %X' % addr)
+        return True
+
+    @Extractor.string
+    def cit_login(self, p, addr, match):
+        log.info('[+] Found login_key xor @ %X' % addr)
+        hit = p.uint32v(addr + 4)
+        print(hex(hit))
+        if p.is_addr(hit):
+            return {'login_key': p.asciiz(hit)}
+
+        hit = p.uint32v(addr + 5)
+        print(hex(hit))
+        if p.is_addr(hit):
+            return {'login_key': p.asciiz(hit)}
+```
+
+### Memory model objects
+
+```python
+from malduck import procmempe
+
+with procmempe.from_file("notepad.exe", image=True) as p:
+    resource_ data = p.pe.resource("NPENCODINGDIALOG")
+```
+
+## How to start
+
+Install it by running
 
 ```
 pip install malduck
 ```
 
-Usage documentation can be found [on readthedocs](https://malduck.readthedocs.io/en/latest/).
+More documentation can be found on [readthedocs](https://malduck.readthedocs.io/en/latest/).
 
 ![Co-financed by the Connecting Europe Facility by of the European Union](https://www.cert.pl/wp-content/uploads/2019/02/en_horizontal_cef_logo-1.png)