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, 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:

{
  "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

The command-line reference documents every option, the report format, and worked CI examples.

Exit status

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 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
• Changelog
• Repository
• Issue tracker

License

The ELF Checker source code implemented by Celeres is licensed under the Mozilla Public License 2.0, 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.