Metadata-Version: 2.1
Name: bids-analyser
Version: 0.1.0
Summary: Analyser for ELF files
Home-page: https://github.com/aph10/BIDS
Author: Anthony Harrison
Author-email: anthony@aph10.com
Maintainer: Anthony Harrison
Maintainer-email: anthony@aph10.com
License: Apache-2.0
Keywords: security,tools,ELF,Dependency,Symbols,Binary Analsyis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyelftools
Requires-Dist: typecode[full]

# 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.

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

```json
{
  "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.
