baseer

بصير (Baseer)

بصير (Baseer) is a modular, extensible binary analysis framework written in C. It allows developers to inspect, disassemble, debug, and decompile binary files using a flexible callback system. Baseer identifies file formats using magic numbers and executes corresponding handlers dynamically.

Note: This project is under active development. See CHANGELOG.md for recent changes.

Architecture

1. Core

The Core handles the essential operations:

Open File: Read files in raw byte format.
Extract Byte Blocks: load block of bytes into memory.
Close File: Release resources when done.
Handle Extensions: Load and manage various extensions.
Manage Pipeline: Pass byte blocks through extensions sequentially or in parallel.

2. Extensions

Extensions add advanced capabilities:

Fix Header: Repair file headers or order.
Identify Block Type: Detect byte block type or metadata.
Disassembler: Convert binaries to assembly instructions.
Decompiler: Convert binaries to readable source code.
Debugger: Dynamically monitor and analyze files.

Baseer in details

Baseer is designed around a callback tree. Each file format (e.g., ELF, TAR, etc.) is represented by a branch that defines its own callbacks. Callbacks can perform operations such as reading metadata, disassembling, debugging, or decompiling.

Baseer Architecture Diagram

Key Concepts

bparser — the main parser structure that holds file information.
bmagic — defines a magic number, the file type name, and the function callback used for parsing.
inputs — holds runtime arguments and a hashmap for communication between callbacks.
bparser_apply() — dispatches the execution of a callback for a given format.
Callbacks (bx_<format>) — per-format handler (e.g., bx_elf, bx_tar) that interprets command-line flags.
Tools (b_<tool>) — actions executed by callbacks, such as b_debugger, b_disasm, b_elf_metadata, etc.

Each branch in the diagram represents a callback path from the main function → Baseer callback → format handler → specific tools.

docs

Libraries Used

udis86: Used for disassembling x86 and x64 architecture binaries.
GitHub Repository
RetDec: Used as the decompiler for translating binaries into a higher-level representation.
GitHub Repository

Build Instructions

Baseer uses a standard Makefile for compilation.

Clone the repository

git clone https://github.com/thxa/baseer.git
cd baseer

Build Baseer

cmake CMakeLists.txt
make

Run Baseer on a binary

./build/baseer <target-file> -m

Compile and analyze file

64 bit

cmake CMakeLists.txt && make && ./build/baseer examples/64bit_x86_64 -m | less -r

32 bit

cmake CMakeLists.txt && make && ./build/baseer examples/32bit_x86 -m | less -r

Requirements

GCC
CMake (>= 3.10)
Linux environment

Run Tests

cmake -S . -B build && cmake --build build --target check

Environment Variables

Variable	Description	Default
`BASEER_RETDEC_BIN`	Path to RetDec decompiler binary	`/opt/baseer/decompiler/bin/retdec-decompiler`
`BASEER_LOG_LEVEL`	Logging verbosity (0=error, 1=warn, 2=info, 3=debug)	`2`
`BLOCK_LENGTH`	Number of bytes per hex dump line	`16`

Install Baseer

Installation on Arch Linux

Baseer on AUR

You can install Baseer from the AUR using an AUR helper like yay:

yay -S baseer

Make sure you have an AUR helper installed (e.g., yay, paru) before running the command.

Uninstallation

To remove Baseer, use:

pacman -Rs baseer

Install from Source

To install Baseer from source:

cmake CMakeLists.txt && make install

To uninstall:

cmake CMakeLists.txt && make uninstall

Usage

Analyze a file using one of the following modes:

Show metadata:
```
baseer <file> -m
```
Disassemble:
```
baseer <file> -a
```
Launch debugger:
```
baseer <file> -d
```
Launch REPL:
```
baseer -i
```

Features

Written in C for speed and low-level control.
Language-agnostic: works with files from any programming language.
Modular and extensible architecture.
Supports complex analysis pipelines.
Easy API for creating new extensions.

How Baseer Works

When you run Baseer with a target file, it:

Reads the file header and detects its magic number.
Searches the bmagic array for a match.
Calls the corresponding callback (bx_<format>) to handle the file.
Executes tools (b_<tool>) depending on command-line flags (e.g., -m for metadata, -a for disassembly, -d for debugging).

Example of the format registration:

bmagic magics[] = {
    {"ELF", ELF_MAGIC, reverse_bytes(ELF_MAGIC), bx_elf, 0},
    {"TAR", TAR_MAGIC, reverse_bytes(TAR_MAGIC), bx_tar, 257},
    // {"PDF", PDF_MAGIC, reverse_bytes(PDF_MAGIC), NULL, 0},
    // {"PNG", PNG_MAGIC, reverse_bytes(PNG_MAGIC), NULL, 0},
    // {"ZIP", ZIP_MAGIC, reverse_bytes(ZIP_MAGIC), NULL, 0},
    // {"Mach-o", MACHO_MAGIC, reverse_bytes(MACHO_MAGIC), NULL, 0},
};

Example: ELF Extensions

Below is an example of an already built extension for ELF .

bool bx_elf(bparser* parser, void *arg)
{
    int argc = *((inputs*)arg)->argc;
    char** args = ((inputs*)arg)->args;

    for (int i = 2; i < argc; i++) {
        if (strcmp("-m", args[i]) == 0)
            bparser_apply(parser, print_meta_data, arg);
        else if (strcmp("-a", args[i]) == 0)
            bparser_apply(parser, print_elf_disasm, arg);
        else if (strcmp("-d", args[i]) == 0)
            bparser_apply(parser, b_debugger, arg);
        else if (strcmp("-c", args[i]) == 0)
            bparser_apply(parser, decompile_elf, arg);
        else
            fprintf(stderr, "[!] Unsupported flag: %s\n", args[i]);
    }

    return true;
}

Adding New Formats

Baseer is built to be easily extended. To add a new format (e.g., PDF, PNG, ZIP):

Create a new file in modules/<format>/bx_<format>.c.
Define your format callback (bx_<format>).
Implement your tools (e.g., b_<tool1>, b_<tool2>).
Register your format in the bmagic array.
Rebuild Baseer with make.

See CONTRIBUTING.md for a detailed guide.

Supported File Types (Magic Numbers)

Use this checklist to see which file types Baseer can currently handle:

This checklist is based on the Wikipedia list of file signatures. You can extend Baseer to support more types in the future.

This site is open source. Improve this page.