molly

README

Molly
=====

Molly (after Molly Hooper in Sherlock Holmes, not the drug) is an automated file analysis and extraction tool. It can search files for user-defined patterns and perform various actions when a match is found.

Molly was initially developed in the SECONDS (Secure Connected Devices) project for binary extraction from foreign firmware images.


Installation
------------

To build from source::

    sudo apt install golang build-essential git
    git clone https://github.com/avahidi/molly
    cd molly
    make && make test && make run

To build command-line tool from go::

    go install github.com/avahidi/molly/cmd/mh@latest


Example
-------

Lets run the Molly command-line utility "mh" on itself::

    $ mh -o output -p config.builtin=true ./mh
    SCAN RESULTS:
            * File mh (0 errors):
                    => ELF ELF_le ELF_x64

It seems mh recognizes itself being an ELF binary. Lets look at the generated report::

    $ ls output/
    match.json  mh  mh_molly.json  rules.json  summary.json

    $ cat output/summary.json
    ....
        "matches": { "mh": 1},
        "tags": {
                "elf": [ "mh" ],
                "executable": [ "mh"]
    ...


Rules
-----

Molly uses a rule database to store known patterns. The rules have a simple and familiar syntax, for example consider the ELF rule::

    rule ELF (tag = "executable,elf") {
        /* variables */
        var magic = String(0, 4);
        var class = Byte(4);
        var data = Byte(5);
        var version = Byte(6);
        /* conditions */
        if magic== "\x7FELF" && (version == 1)
            && (class == 1 || class == 2)
            && (data == 1 || data == 2);
    }


Rules can have children, which alllows multiple related file formats to be defined with minimal effort. For example::

    rule ELF_le (bigendian = false) : ELF {
        var machine = Short(18);
        if data == 1;
    }
    rule ELF_be (bigendian = true) : ELF {
        var machine = Short(18);
        if data == 2;
    }
    rule ELF_x86 (tag = "x86") : ELF_le {
        if machine == 0x0003;
    }

Rules can also define actions to be performed when a match is found. For example::

    rule ELF (tag = "executable,elf") {
        ...
        analyze("strings", "string_analysis");
        analyze("version", "");
    }

The resulting report file::

    $ ls output/
    match.json  mh  mh_molly.json  rules.json  summary.json

    $ cat output/mh_molly.json
    {
        "filename": "mh",
        ...
        "strings": [
            "runtime.throw",
            "compress/zlib.NewReader",
            "bufio.NewReader",
            "c=FrX",
        ...
        "possible-version": [
            "GLIBC_2.3.2",
            "GLIBC_2.2.5",
            "go1.18.1",
            ...

Documentation

Overview

Package molly is the root for the library API in molly

Index

• func ExtractReport(m *types.Molly) *types.Report
• func LoadBuiltinRules() ([]string, []string)
• func LoadRules(m *types.Molly, files ...string) error
• func LoadRulesFromText(m *types.Molly, source, text string) error
• func New() *types.Molly
• func ScanData(m *types.Molly, data []byte) error
• func ScanFiles(m *types.Molly, files ...string) error
• func Version() (int, int, int)

Functions

func ExtractReport

func ExtractReport(m *types.Molly) *types.Report

ExtractReport generates a report

func LoadBuiltinRules

func LoadBuiltinRules() ([]string, []string)

built-in rules are stored as embedded data and are loaded from here

func LoadRules

func LoadRules(m *types.Molly, files ...string) error

LoadRules reads rules from files

func LoadRulesFromText

func LoadRulesFromText(m *types.Molly, source, text string) error

LoadRulesFromText reads rules from a string

func New

func New() *types.Molly

New creates a new molly context

func ScanData

func ScanData(m *types.Molly, data []byte) error

ScanData scans a byte vector for matches.

func ScanFiles

func ScanFiles(m *types.Molly, files ...string) error

ScanFiles scans a set of files for matches.

func Version

func Version() (int, int, int)

Version returns the library version (major, minor, maintenance)