mercury-python

The goal of the mercury-python package is to expose mercury's network protocol analysis functionality via python. The cython interface is given in mercury.pyx.

Installation

Recommended Installation

pip install mercury-python

From Source

You will first need to build mercury and install cython and optionally wheel:

pip install Cython
pip install wheel
pip install setuptools

From the top of the mercury source tree, the top-level Makefile builds the package:

make cython       # build the Cython extension and a pip-installable wheel
make test-cython  # run the cython interface tests

The wheel and the .so are placed under build/<variant>/cython/ (default variant: RelWithDebInfo).

Usage

Initialization

import mercury

libmerc = mercury.Mercury()                                                            # initialization for packet parsing
libmerc = mercury.Mercury(do_analysis=True, resources=b'/<path>/<to>/<resources.tgz>') # initialization for analysis

Parsing packets

hex_packet = '5254001235020800273a230d08004500...'
libmerc.get_mercury_json(bytes.fromhex(hex_packet))

{
    "fingerprints": {
        "tls": "tls/(0303)(13011303...)((0000)...)"
    },
    "tls": {
        "client": {
            "version": "0303",
            "random": "0d4e266cf66416689ded443b58d2b12bb2f53e8a3207148e3c8f2be2476cbd24",
            "session_id": "67b5db473da1b71fbca9ed288052032ee0d5139dcfd6ea78b4436e509703c0e4",
            "cipher_suites": "130113031302c02bc02fcca9cca8c02cc030c00ac009c013c014009c009d002f0035000a",
            "compression_methods": "00",
            "server_name": "content-signature-2.cdn.mozilla.net",
            "application_layer_protocol_negotiation": [
                "h2",
                "http/1.1"
            ],
            "session_ticket": ""
        }
    },
    "src_ip": "10.0.2.15",
    "dst_ip": "13.249.64.25",
    "protocol": 6,
    "src_port": 32972,
    "dst_port": 443,
}

Analysis

There are two methods to invoke mercury's analysis functionality. The first operates on the full hex packet:

libmerc.analyze_packet(bytes.fromhex(hex_packet))

{
    "tls": {
        "client": {
            "server_name": "content-signature-2.cdn.mozilla.net"
        }
    },
    "fingerprint_info": {
        "status": "labeled",
        "type": "tls",
        "str_repr": "tls/1/(0303)(13011303...)[(0000)...]"
    },
    "analysis": {
        "process": "firefox",
        "score": 0.9992411956652674,
        "malware": false,
        "p_malware": 8.626882751003134e-06
    }

The second method operates directly on the data features (network protocol fingerprint string and destination context):

libmerc.perform_analysis('tls/1/(0303)(13011303...)[(0000)...]', 'content-signature-2.cdn.mozilla.net', '13.249.64.25', 443)

{
    "fingerprint_info": {
        "status": "labeled"
    },
    "analysis": {
        "process": "firefox",
        "score": 0.9992158715704546,
        "malware": false,
        "p_malware": 8.745628825189023e-06
    }
}

Static functions

Parsing base64 representations of certificate data:

b64_cert = 'MIIJRDC...'
mercury.parse_cert(b64_cert)

output:

{
    "version": "02",
    "serial_number": "00eede6560cd35c0af02000000005971b7",
    "signature_identifier": {
        "algorithm": "sha256WithRSAEncryption"
    },
    "issuer": [
        {
            "country_name": "US"
        },
        {
            "organization_name": "Google Trust Services"
        },
        {
            "common_name": "GTS CA 1O1"
        }
    ],
    ...

Parsing base64 representations of DNS data:

b64_dns = '1e2BgAAB...'
mercury.parse_dns(b64_dns)

output:

{
    "response": {
        "question": [
            {
                "name": "live.github.com.",
                "type": "AAAA",
                "class": "IN"
            }
        ],
        ...