pinwhell / mhtr

MHTR is a Multi-Threaded Cross-Platform Binary Analysis Framework

Metadata Hunter (MHTR)

Metadata Hunter (MHTR) is a robust binary analysis framework designed for reverse engineering and security analysis purposes. It facilitates the identification and extraction of metadata from binary files, aiding in tasks such as vulnerability analysis, software debugging, and malware analysis.

Features

• Cross-Platform: MHTR is designed to work seamlessly across various operating systems, ensuring versatility and broad usability.

• Command-Line Interface (CLI): MHTR offers a CLI interface for convenient interaction, allowing users to specify targets, configure options, and generate reports.

• Multithreading: To enhance performance, MHTR employs multithreading to parallelize metadata lookup operations across multiple targets.

CLI Quick Start

To quickly get started with the MHCLI tool and generate results from the samples directory, follow these steps:

Step 1: Navigate to the Samples Directory

Ensure that you are in the directory containing the targets.json file. If not, navigate to the samples directory using the cd command:

cd path/to/samples

Replace path/to/samples with the actual path to your samples directory.

Step 2: Run MHCLI Command

Execute the following command to run MHCLI with the specified parameters:

MHCLI --targets targets.json --report rs.txt --rhpp rs.hpp --rhpprt rs.rt.hpp

Make sure that MHCLI is included in your system's PATH directory, or provide the full path to the MHCLI executable if it's not.

Step 3: Verify Results

After executing the command, MHCLI will generate the results in the specified files (rs.txt, rs.hpp, rs.rt.hpp). You can then review these files to analyze the output generated by MHCLI.

That's it! You've successfully run MHCLI on the samples directory and generated results.

Integrated Plugin/Add-ons System

Extend MHTR's functionality with an integrated plugin system, enabling users to add custom features and tools. This system allows for the development and integration of additional modules, enhancing the tool's capabilities and adapting to specific analysis needs.

Metadata Lookup

MHTR provides a flexible framework for performing various types of metadata lookups within binary files, including offsets, patterns, and other identifying information. This feature allows for detailed inspection and analysis of binary content, facilitating tasks such as vulnerability detection and malware analysis. The metadata lookup types include:

• INSN_IMM: Parses instruction and lists all the immediate values (imm), offsets, and displacements. Users can select any of them by specifying the immIndex.

{
  "name": "Bar",
  "type": "INSN_IMM",
  "pattern": "42 00 ? B9",
  "disp": -2,
  "immIndex": 0,
  "scanRange": "FooFuncRange"
}

PATTERN_VALIDATE: Validates a pattern to ensure it is present and unique, then forwards the pattern itself to the report.

{
  "name": "BarPattern",
  "type": "PATTERN_VALIDATE",
  "pattern": "42 00 ? B9",
  "disp": -2,
  "scanRange": "FooFuncRange"
}

PATTERN_SINGLE_RESULT: Validates a pattern to ensure it is present and unique, then forwards the relative position of the pattern to the report.

{
  "name": "BarPatternResult",
  "type": "PATTERN_SINGLE_RESULT",
  "pattern": "42 00 ? B9",
  "disp": -2,
  "scanRange": "FooFuncRange"
}

FAR_ADDR: Resolves position-independent code (PIC) references, such as those found in ARM architectures, by emulating PC-relative Load Effective Address Operations such as ADRP + LDRin ARM.

{
  "name": "Baz",
  "type": "FAR_ADDR",
  "pattern": "49 78 44 ? 4A ? 4B",
  "disp": -1,
  "scanRange": "FooFuncRange"
}

Binary Targets

Binary targets in Metadata Hunter (MHTR) are crucial components that define the scope and parameters of metadata analysis. Each binary target entry encapsulates essential information required by MHTR's CLI to initiate the scanning process. Here's a breakdown of the components within a binary target:

• binaryPath: Specifies the path to the binary file to be analyzed. This path ensures that MHTR can locate and access the binary for metadata extraction.

• namespace: Defines the namespace associated with the binary file. This namespace helps organize and categorize metadata within the analysis framework.

• metadataPath: Indicates the path to the JSON file containing metadata lookup definitions for the corresponding binary file. This file contains detailed instructions and patterns for MHTR to identify and extract metadata from the binary.

Binary targets are structured as an array, allowing MHTR Framework to process multiple targets in a single analysis session. Below is an example array of binary targets:

[
  {
    "binaryPath": "libdummy.so",
    "namespace": "Dummy",
    "metadataPath": "libdummy.json"
  },
  ...
]

Report Formats

Reports generated by Metadata Hunter (MHTR) provide valuable insights into the metadata extracted from binary files. Here are the different report formats available:

Hpp Static Compile-Time Report

#pragma once

#include <cstdint>

namespace Dummy {
    constexpr uint64_t Baz = 0x2640;
    constexpr uint64_t BarPatternResult = 0x1A94;
    constexpr uint64_t Bar = 0x42;
    constexpr uint64_t Foo = 0x15B0;
    constexpr auto BarPattern = "42 00 ? B9";
}

This report format is optimized for static compile-time usage in languages like C++. It provides compile-time constants for metadata values, enabling efficient integration into codebases with minimal runtime overhead.

MHTRSDK Integration Report

#pragma once

#include <MHTRSDK.h>

namespace Dummy {
    MHTR::MetadataProvider DummyCreate()
    {
        MHTR::MetadataMap result;
        result["Dummy::BarPatternResult"] = 0x1a94ull;
        result["Dummy::Baz"] = 0x2640ull;
        result["Dummy::Foo"] = 0x15b0ull;
        result["Dummy::Bar"] = 0x42ull;
        result["Dummy::BarPattern"] = "42 00 ? B9";
        return MHTR::MetadataProvider(std::move(result));
    }

    MHTR::MetadataProvider AllCreate()
    {
        MHTR::MetadataProvider all;
        all += DummyCreate();
        return  all;
    }
}

This report format leverages the MHTRSDK to generate a metadata provider function, which encapsulates the metadata values in a format suitable for integration with the MHTR framework. This allows seamless usage of metadata within MHTR-enabled environments.

Simple Text Report

Dummy:
{
    Baz: 0x2640
    BarPatternResult: 0x1a94
    Bar: 0x42
    Foo: 0x15b0
    BarPattern: "42 00 ? B9"
}

The simple text report provides a human-readable summary of the extracted metadata in a clear and concise format. It presents the metadata values alongside their corresponding identifiers, making it easy to understand and interpret the results of the analysis.

Each report format serves different purposes and caters to distinct use cases, offering flexibility and adaptability to meet the diverse needs of users conducting binary analysis with MHTR.

Usage

To use MHTR, follow these steps:

1. Prepare a JSON file containing metadata targets.
2. Invoke the MHCLI with the appropriate options, specifying the path to the JSON targets file and any other desired parameters.
3. Monitor the progress and review the generated reports for metadata extraction results.

Here's an example of how to use the MHCLI:

MHCLI -j4 --targets metadata_targets.json --report output_report.txt --report-hpp output_report.hpp --report-hpprt output_report_rt.hpp

License

MHTR is licensed under the MIT License. Feel free to use, modify, and distribute it according to the terms of the license.