bids

README

BIDS

BIDS (Binary Identification of Dependencies with Search). The BIDS project will deliver tooling to analyse ELF binaries and extract key features for indexing and searching. The tooling to index these binary features in a search engine uses an inverted index.

This project is sponsored by NLNET https://nlnet.nl/project/BIDS/.

Installation

To install use the following command:

pip install bids-analyser

Alternatively, just clone the repo and install dependencies using the following command:

pip install -U -r requirements.txt

The tool requires Python 3 (3.9+). It is recommended to use a virtual python environment especially if you are using different versions of python. virtualenv is a tool for setting up virtual python environments which allows you to have all the dependencies for the tool set up in a single environment, or have different environments set up for testing using different versions of Python.

Usage

usage: bids-analyser [-h] [-f FILE] [--description DESCRIPTION] [--exclude-dependency] [--exclude-symbol] [--exclude-callgraph] [-d] [-o OUTPUT_FILE] [-V]

bids-analyser analyses a binary application in ELF format and extracts dependency, symbolic and call graph information into a JSON data stream

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Input:
  -f FILE, --file FILE  identity of binary file
  --description DESCRIPTION
                        description of file
  --exclude-dependency  suppress reporting of dependencies
  --exclude-symbol      suppress reporting of symbols
  --exclude-callgraph   suppress reporting of call graph

Output:
  -d, --debug           add debug information
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)

Operation

The --file option is used to specify the binary file to be processed.

The --description option is used to provide a biref description of the binary being processed.

The --exclude-dependency, --exclude-symbol, and --exclude-callgraph option is used to disable the capture of dependency, symbol or callgraph information respectively.

The --output-file option is used to control the destination of the output generated by the tool. The default is to report to the console but can be stored in a file (specified using --output-file option).

Output File Format

The output file is in JSON format. The content depends on the contents of the file and the specified command line options.

bids-analyser -f go/bin/go --output gobin.json --description "Go binary"

{
  "metadata": {
    "docFormat": "BIDS",
    "specVersion": "1.0",
    "id": "da4ef1aa-f9bb-49df-ab61-51224ea4bfc5",
    "version": 1,
    "timestamp": "2024-11-04T20:44:25Z",
    "tool": "bids_generator:0.1.0",
    "binary": {
      "class": "ELF64",
      "architecture": "x86_64",
      "bits": 64,
      "os": "linux",
      "filename": "go/bin/go",
      "filesize": 12983131,
      "filedate": "Thu Aug 15 19:50:32 2019",
      "checksum": {
        "algorithm": "SHA256",
        "value": "6ef479d2538373f31056cace657508359e39f31adf07a183f8b2d55be72c328c"
      }
    },
    "description": "Go binary"
  },
  "components": {
    "dynamiclibrary": [
      {
        "name": "libpthread.so.0",
        "location": "/usr/lib32/libpthread.so.0"
      },
      {
        "name": "libc.so.6",
        "location": "/usr/lib32/libc.so.6",
        "version": "2.38"
      }
    ],
    "globalsymbol": [
      "__errno_location",
      "abort",
      "fprintf",
      "fputc",
      "free",
      "freeaddrinfo",
      "fwrite",
      "gai_strerror",
      "getaddrinfo",
      "getnameinfo",
      "malloc",
      "nanosleep",
      "pthread_attr_destroy",
      "pthread_attr_getstacksize",
      "pthread_attr_init",
      "pthread_cond_broadcast",
      "pthread_cond_wait",
      "pthread_create",
      "pthread_detach",
      "pthread_mutex_lock",
      "pthread_mutex_unlock",
      "pthread_sigmask",
      "setenv",
      "sigfillset",
      "stderr",
      "strerror",
      "unsetenv",
      "vfprintf"
    ],
    "localsymbols": [
      "_cgo_panic",
      "_cgo_topofstack",
      "crosscall2"
    ]
  },
  "relationships": {
    "libpthread.so.0": [
      "__errno_location",
      "pthread_mutex_lock",
      "pthread_cond_wait",
      "pthread_mutex_unlock",
      "pthread_cond_broadcast",
      "pthread_create",
      "nanosleep",
      "pthread_detach",
      "pthread_attr_init",
      "pthread_attr_getstacksize",
      "pthread_attr_destroy",
      "pthread_sigmask"
    ],
    "libc.so.6": [
      "getnameinfo",
      "getaddrinfo",
      "freeaddrinfo",
      "gai_strerror",
      "stderr",
      "fwrite",
      "vfprintf",
      "fputc",
      "abort",
      "strerror",
      "fprintf",
      "free",
      "sigfillset",
      "setenv",
      "unsetenv",
      "malloc"
    ]
  }
}

Return Values

The following values are returned:

• 0 - Binary analysis completed
• 1 - Error detected in analysis process

License

Licensed under the Apache 2.0 License.

Limitations

The tool has the following limitations:

• Stripped binaries will result in a limited amount of data

• Callgraph processing is not implemented

Feedback and Contributions

Bugs and feature requests can be made via GitHub Issues.