Metadata-Version: 2.4
Name: elf-checker
Version: 2.0.0
Summary: A tool to visualize and check where ELF sections are located in different types of binaries
License-Expression: MPL-2.0
License-File: COPYING.md
License-File: LICENSE
Keywords: elf,elf-parser,section-headers,program-headers,binary-comparison,embedded,rtems,binutils,ci
Author: Celeres GmbH
Maintainer: Thomas Wucher
Maintainer-email: thomas.wucher@celeres.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Utilities
Requires-Dist: pyelftools (>=0.31,<1.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Project-URL: Changelog, https://gitlab.com/gtd-gmbh/elf-checker/-/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gtd-gmbh.gitlab.io/elf-checker/
Project-URL: Homepage, https://gitlab.com/gtd-gmbh/elf-checker
Project-URL: Issues, https://gitlab.com/gtd-gmbh/elf-checker/-/issues
Project-URL: Repository, https://gitlab.com/gtd-gmbh/elf-checker
Description-Content-Type: text/markdown

# ELF Checker

ELF Checker visualises and checks where ELF sections are located in different
types of binaries (ELF files, stripped ELF files, binary files).

It answers the questions that come up when a linker script, a post-processing
step, or a flashing tool moves things around:

* Which sections does each ELF file describe, at which address, length, and alignment?
* Do the sections an ELF file describes match the bytes of a raw binary image at the addresses the ELF file expects?
* Which gaps in a raw binary are padding, and is that padding really zero?
* Which section differs between two builds, and where does the difference start?

Every run writes a text table to standard output and a JSON report to
`report.json`, including SHA-256 hashes of section, binary, and padding data, so
the same run can be read by a person and consumed by CI.

## Installation

The latest release is published on PyPI. Install it with
[pipx](https://pipx.pypa.io/), which keeps the tool in its own virtual
environment:

```
pipx install elf-checker
```

`pipx` is packaged as `pipx` or `python-pipx` by most distributions. Plain `pip`
works too, inside a virtual environment:

```
python3 -m venv .venv
. .venv/bin/activate
pip install elf-checker
```

ELF Checker requires Python 3.11 or newer.

## Quick start

### Inspect an ELF file

```
elf-checker -e test/artifacts/sparc-rtems6-qual-runner.elf
```

```
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃                 ┃ ...parc-rtems6-qual-runner.el ┃                    ┃                  ┃        ┃
┃ Section Name    ┃ f                             ┃ Type               ┃ Flags            ┃ Errors ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│                 │ Address ┃   Length ┃ Alignme… │                    │                  │        │
│ ━━━━━━━━━━━━━━━ │ ━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━ │ ━━━━━━━━━━━━━━━━━━ │ ━━━━━━━━━━━━━━━━ │ ━━━━━━ │
│ .comment        │ 0x0     │     0x63 │      0x1 │ SHT_PROGBITS       │ MERGE, STRINGS   │ -      │
│ .debug_abbrev   │ 0x0     │  0x245C4 │      0x1 │ SHT_PROGBITS       │ -                │ -      │
│ .debug_aranges  │ 0x0     │   0x2930 │      0x8 │ SHT_PROGBITS       │ -                │ -      │
│ …               │         │          │          │                    │                  │        │
│ .data           │ 0x2A640 │   0x3C80 │      0x8 │ SHT_PROGBITS       │ ALLOC, WRITE     │ -      │
│ .bss            │ 0x2E2C0 │ 0x410C30 │     0x40 │ SHT_NOBITS         │ ALLOC, WRITE     │ -      │
└─────────────────┴───────────────────────────────┴────────────────────┴──────────────────┴────────┘
```

### Compare ELF files side by side

Pass more than one ELF file to the same option. A section that is absent from an
input is kept and reported with placeholders, which is what makes the
comparison of an unstripped and a stripped ELF file readable:

```
elf-checker \
  -e test/artifacts/sparc-rtems6-qual-runner.elf \
  test/artifacts/sparc-rtems6-qual-runner-stripped.elf
```

```
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃                 ┃ ...parc-rtems6-qual-runn ┃ ...s6-qual-runner-stripp ┃                    ┃                  ┃         ┃
┃ Section Name    ┃ er.elf                   ┃ ed.elf                   ┃ Type               ┃ Flags            ┃ Errors  ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│                 │ Addre… ┃ Length ┃ Align… │ Addre… ┃ Length ┃ Align… │                    │                  │         │
│ ━━━━━━━━━━━━━━━ │ ━━━━━━━╇━━━━━━━━╇━━━━━━━ │ ━━━━━━━╇━━━━━━━━╇━━━━━━━ │ ━━━━━━━━━━━━━━━━━━ │ ━━━━━━━━━━━━━━━━ │ ━━━━━━━ │
│ .comment        │ 0x0    │   0x63 │    0x1 │ 0x0    │   0x63 │    0x1 │ SHT_PROGBITS       │ MERGE, STRINGS   │ -       │
│ .debug_abbrev   │ 0x0    │ 0x245… │    0x1 │ -      │      - │      - │ SHT_PROGBITS       │ -                │ -       │
│ .debug_aranges  │ 0x0    │ 0x2930 │    0x8 │ -      │      - │      - │ SHT_PROGBITS       │ -                │ -       │
│ …               │        │        │        │        │        │        │                    │                  │         │
│ .data           │ 0x2A6… │ 0x3C80 │    0x8 │ 0x2A6… │ 0x3C80 │    0x8 │ SHT_PROGBITS       │ ALLOC, WRITE     │ -       │
│ .bss            │ 0x2E2… │ 0x410… │   0x40 │ 0x2E2… │ 0x410… │   0x40 │ SHT_NOBITS         │ ALLOC, WRITE     │ -       │
└─────────────────┴──────────────────────────┴──────────────────────────┴────────────────────┴──────────────────┴─────────┘
```

Stripping removes section names from `.shstrtab`, so a data mismatch there is
expected: pass `--ignore-sections .shstrtab` together with `--fail-on-errors` to
keep the mismatch visible in the reports without failing on it.

### Compare an ELF file with a raw binary

Select the sections that are present in the raw image. ELF Checker maps their
addresses onto file offsets, compares the bytes, and inspects the gaps between
them:

```
elf-checker \
  -e test/artifacts/sparc-rtems6-qual-runner.elf \
  -b test/artifacts/sparc-rtems6-qual-runner.bin \
  -j .text .data
```

```
│ .text           │ 0x0     │   0x2… │     0x20 │ SHT_PROGBITS       │ ALLOC, EXECINSTR │ 0x0     │  0x2…   │     0x20 │ -        │
│ .rtemsstack     │ 0x28640 │ 0x2000 │     0x40 │ SHT_NOBITS         │ ALLOC, WRITE     │ -       │       - │        - │ -        │
│ padding         │ -       │      - │        - │ -                  │ -                │ 0x285C0 │  0x2080 │        - │ Not Zero │
│ .data           │ 0x2A640 │ 0x3C80 │      0x8 │ SHT_PROGBITS       │ ALLOC, WRITE     │ 0x2A640 │  0x3C80 │      0x8 │ -        │
```

The `padding` row reports bytes in the binary that no selected section claims,
with its offset, length, and a `Not Zero` error when the padding is not filled
with zeros. Use `--binary-base` when offset zero of the image stands for an
address other than the lowest selected section.

### Machine-readable report

`--json-output` writes the same data as JSON. Each ELF input is keyed by its
resolved absolute path:

```json
{
  "file_info": {
    "/home/build/sparc-rtems6-qual-runner.elf": [
      {
        "data_type": "elf_section",
        "address": 0,
        "size": 99,
        "data_sha256": "523dffd99785d2e7fc7bdcc69f4f85e737378c3f6588f3e020db31e34481c319",
        "name": ".comment",
        "alignment": 1,
        "type": "SHT_PROGBITS",
        "flags": "MERGE, STRINGS"
      }
    ]
  },
  "errors": []
}
```

## Command-line options

| Option | Purpose |
| --- | --- |
| `-e`, `--elffile` | One or more ELF files to inspect. Required. |
| `-b`, `--binfile` | Raw binary image to compare with the selected sections. |
| `-j`, `--only-section` | Sections expected in the raw binary. Needs `--binfile`. |
| `--binary-base` | Address that maps to offset zero in the binary. |
| `--strict-sections` | Report a section missing from one of the ELF inputs as an error. |
| `--fail-on-errors` | Exit with status 1 when the report has non-ignored errors. |
| `--ignore-sections` | Section names whose errors do not affect `--fail-on-errors`. |
| `--json-output` | Path of the JSON report. Defaults to `report.json`. |
| `-v`, `--version` | Print the version and exit. |

The
[command-line reference](https://gtd-gmbh.gitlab.io/elf-checker/usage/tutorial.html)
documents every option, the report format, and worked CI examples.

## Exit status

| Status | Meaning |
| --- | --- |
| 0 | The comparison completed. Mismatches do not change the status unless `--fail-on-errors` is given. |
| 1 | `--fail-on-errors` was given and the report contains non-ignored comparison or padding errors. |
| 2 | Invalid arguments, an unreadable input, or an ELF input the checker refuses to interpret. |

## Input validation

An ELF input that cannot be interpreted is rejected with status 2, a diagnostic
naming the affected file and field on standard error, and no JSON report. The
tool validates the ELF identification, the section header table and ELF extended
section numbering, the section name string table, the stored range of every
section, section links, the program header table, and the file range of every
program segment. See
[Input validation](https://gtd-gmbh.gitlab.io/elf-checker/usage/tutorial.html#input-validation)
for the full list and for what is deliberately outside the scope of the tool:
ELF Checker is a section comparison tool, not a general ELF validator.

## Links

* [Documentation](https://gtd-gmbh.gitlab.io/elf-checker/)
* [Changelog](https://gitlab.com/gtd-gmbh/elf-checker/-/blob/main/CHANGELOG.md)
* [Repository](https://gitlab.com/gtd-gmbh/elf-checker)
* [Issue tracker](https://gitlab.com/gtd-gmbh/elf-checker/-/issues)

## License

The ELF Checker source code implemented by Celeres is licensed under the
[Mozilla Public License 2.0](https://gitlab.com/gtd-gmbh/elf-checker/-/blob/main/COPYING.md),
identified by the SPDX expression `MPL-2.0`. Third-party libraries remain
subject to their own license terms.

## Development

Setup for the development environment, the test suite, the pre-commit hooks, and
the documentation build are described in
[CONTRIBUTING.md](https://gitlab.com/gtd-gmbh/elf-checker/-/blob/main/CONTRIBUTING.md).

