emtrace 0.1.2__tar.gz → 0.2.0__tar.gz

emtrace-0.2.0/.gitignore

@@ -0,0 +1,2 @@
+/dist
+/emtrace/_build_info.py

{emtrace-0.1.2 → emtrace-0.2.0}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Jonas Beyer
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{emtrace-0.1.2 → emtrace-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: emtrace
-Version: 0.1.2
+Version: 0.2.0
 Summary: A tool to parse and format emtrace data.
 Author-email: Jonas Beyer <reyeb.sanoj@googlemail.com>
 License:                                  Apache License
@@ -191,7 +191,7 @@ License:                                  Apache License
               same "printed page" as the copyright notice for easier
               identification within third-party archives.
         
-           Copyright [yyyy] [name of copyright owner]
+           Copyright 2026 Jonas Beyer
         
            Licensed under the Apache License, Version 2.0 (the "License");
            you may not use this file except in compliance with the License.
@@ -206,7 +206,7 @@ License:                                  Apache License
            limitations under the License.
 License-File: LICENSE
 Keywords: embedded,logging,tracing
-Requires-Dist: pyelftools>=0.31
+Requires-Dist: lief>=0.17
 Provides-Extra: test
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
 Requires-Dist: pytest>=8.2.2; extra == 'test'

emtrace-0.2.0/emtrace/__init__.py

@@ -0,0 +1,64 @@
+"""emtrace: parse and format emtrace trace data (pure-python library).
+
+The command-line interface lives in :mod:`emtrace.cli` and is intentionally
+*not* imported here, so ``import emtrace`` stays lightweight and free of
+CLI side effects.
+"""
+
+__version__ = "0.2.0"
+
+from .edit import nonload_binary, strip_binary
+from .engine import (
+    FormatInfoResult,
+    RunReport,
+    TraceInfoFormat,
+    emtrace,
+    load_format_info,
+)
+from .errors import Issue, Report
+from .exemod import (
+    ExeError,
+    ExeImage,
+    NonloadReport,
+    NotSupportedError,
+    SectionNotFoundError,
+    StripReport,
+)
+from .inspector import (
+    ArchiveDetails,
+    BinaryDetails,
+    CheckReport,
+    ExportReport,
+    InspectReport,
+    RawDetails,
+    check_section,
+    export_section,
+    inspect_path,
+)
+
+__all__ = [
+    "ArchiveDetails",
+    "BinaryDetails",
+    "CheckReport",
+    "ExeError",
+    "ExeImage",
+    "ExportReport",
+    "FormatInfoResult",
+    "InspectReport",
+    "Issue",
+    "NonloadReport",
+    "NotSupportedError",
+    "RawDetails",
+    "Report",
+    "RunReport",
+    "SectionNotFoundError",
+    "StripReport",
+    "TraceInfoFormat",
+    "check_section",
+    "emtrace",
+    "export_section",
+    "inspect_path",
+    "load_format_info",
+    "nonload_binary",
+    "strip_binary",
+]

emtrace-0.2.0/emtrace/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli.main import main
+
+sys.exit(main())

emtrace-0.2.0/emtrace/_build_info.py

@@ -0,0 +1,4 @@
+"""Generated by hatch_build.py at build time; do not edit or commit."""
+
+COMMIT: str | None = 'f7061e85ac9fe5746afc484ff48fdecd8dd8ac0c'
+DIRTY = False

emtrace-0.2.0/emtrace/_lief.py

@@ -0,0 +1,74 @@
+"""Sole adapter for the optional ``lief`` dependency.
+
+``lief`` is a default install dependency of the ``emtrace`` package, but the
+library also works without it: anything that does not need to parse an
+executable (raw ``binary`` and ``json`` inputs, record-level helpers) keeps
+working, while executable-based operations report a clear "lief is not
+installed" issue instead of failing at import time.
+
+This module is the only place that touches ``lief`` availability:
+
+- ``HAS_LIEF`` tells callers whether the dependency is present.
+- ``parse_binary()`` / ``find_section_bytes()`` are defined exactly once
+  (typing-only imports under ``TYPE_CHECKING`` keep type checkers happy
+  without requiring the package at runtime).
+- :func:`lief_missing_error` builds the standard issue message so every
+  command refuses identically.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+try:
+    import lief as _lief
+except ImportError:
+    _lief = None  # type: ignore[assignment]
+
+#: Whether the optional ``lief`` dependency is installed.
+HAS_LIEF: bool = _lief is not None
+
+
+def lief_missing_error(operation: str) -> str:
+    """The standard message for refusing *operation* without lief installed."""
+    return (
+        f"{operation} requires the 'lief' package, which is not installed "
+        f"(install the default 'emtrace' dependencies to enable it)"
+    )
+
+
+def parse_binary(kind: str, path: Path) -> Any | None:
+    """Parse *path* as a binary of *kind* (Tier 1: ``None`` when unavailable).
+
+    *kind* is one of ``"exe"``, ``"elf"``, ``"pe"``, ``"macho"`` or ``"oat"``.
+    Returns ``None`` when lief is not installed, when the file is not of the
+    requested kind, or when parsing fails.
+    """
+    if _lief is None:
+        return None
+    if kind == "exe":
+        return _lief.parse(path)
+    if kind == "elf":
+        return _lief.ELF.parse(path)
+    if kind == "pe":
+        return _lief.PE.parse(path)
+    if kind == "macho":
+        return _lief.parse(path) if _lief.is_macho(path) else None
+    if kind == "oat":
+        return _lief.OAT.parse(path)
+    raise ValueError(f"unknown binary kind: {kind!r}")
+
+
+def find_section_bytes(
+    trace_info_file: Path, section_name: str, parse: Callable[[Path], Any | None]
+) -> bytes | None:
+    """Extract section bytes via *parse* (Tier 1: ``None`` when absent)."""
+    exe = parse(trace_info_file)
+    if exe is None:
+        return None
+    section = exe.get_section(section_name)
+    if section is None:
+        return None
+    return bytes(section.content)

emtrace-0.2.0/emtrace/cobs.py

@@ -0,0 +1,64 @@
+import sys
+from collections.abc import Callable
+from typing import Any
+
+
+def cobs_get_frame(
+    istream: Callable[[int], bytes], passthrough: Callable[[bytes], Any] | None = None
+) -> bytes | None:
+    """
+    Decodes and returns the next COBS frame in the given input stream.
+    The stream is queried until a full COBS frame was received or the stream is empty.
+    Optionally provide a passthrough function to decode according to COBS "passthrough" rules.
+    In that case frames have to start with a null-byte as well as ending in one,
+    and any bytes before the first null-byte, are "passed through" to the provided callback.
+    Since a COBS frame cannot consist of just a single null-byte,
+    a pair of null-bytes (which would otherwise mean starting and immediately ending a frame)
+    is interpreted as an escaped null-byte in the passthrough stream.
+    """
+
+    buffer = bytearray()
+    data = istream(1)
+
+    if passthrough is not None:
+        while len(data) != 0:
+            if data[0] == 0:
+                data = istream(1)
+                if len(data) == 0:
+                    return None
+                # two successive null-bytes in input are interpreted as an escaped null-byte
+                # in the passthrough stream
+                if data[0] != 0:
+                    break
+            passthrough(data)
+            data = istream(1)
+
+    if len(data) == 0:
+        return None
+    if data[0] == 0:
+        print("COBS decoding error: zero byte at start of frame", file=sys.stderr)
+        return bytes(buffer)
+
+    while True:
+        block_prefix = data[0]
+
+        block_size = 254 if block_prefix == 0xFF else block_prefix - 1
+
+        data = istream(block_size)
+        if 0 in data:
+            print(
+                f"COBS decoding error: zero byte in data block: {data}", file=sys.stderr
+            )
+        buffer.extend(data)
+        if len(data) < block_size:
+            if len(buffer) == 0:
+                return None
+            return bytes(buffer)
+        assert len(data) == block_size
+
+        data = istream(1)
+        if len(data) == 0 or data[0] == 0:
+            return bytes(buffer)
+        if block_prefix != 0xFF:
+            buffer.append(0)
+        block_prefix = -1

emtrace-0.2.0/emtrace/edit.py

@@ -0,0 +1,103 @@
+"""Post-link editing operations for emtrace sections (library core).
+
+``strip`` removes the section completely (ELF, PE, and Mach-O); ``nonload``
+makes the section non-loadable on ELF, the same effect as an ``(INFO)``
+region in a linker script (clear SHF_ALLOC and sh_addr, keep the section
+bytes in the file so the traces remain parseable).
+
+Both operations rebuild the binary with LIEF; the guarantees are behavioral
+(the section entry is gone, its symbols are deleted, its content no longer
+parses, and the binary still runs) rather than byte-exact.
+
+All entry points return :class:`StripReport` / :class:`NonloadReport` with
+``errors`` set on failure — this module never prints. File writing lives in
+:mod:`emtrace.cli.edit_cmds`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .exemod import (
+    ExeError,
+    ExeImage,
+    NonloadReport,
+    NotSupportedError,
+    SectionNotFoundError,
+    StripReport,
+)
+
+__all__ = ["nonload_binary", "strip_binary"]
+
+
+def _open_image(
+    source: Path, command: str, experimental_be: bool
+) -> tuple[ExeImage | None, str | None]:
+    """Open *source* for *command*; return ``(image, None)`` or ``(None, error)``."""
+    try:
+        return ExeImage.open(source, experimental_be=experimental_be), None
+    except (ExeError, NotSupportedError, SectionNotFoundError) as e:
+        return None, f"{command}: {e}"
+
+
+def strip_binary(
+    path: str | Path,
+    section_name: str = ".emtrace",
+    *,
+    experimental_be: bool = False,
+) -> StripReport:
+    """Remove the section *section_name* from the binary at *path* (Tier 2).
+
+    On success, ``report.data`` holds the rebuilt binary bytes.
+    """
+    source = Path(path).resolve()
+    report = StripReport(section=section_name)
+    if not source.is_file():
+        report.fail(f"{source} does not exist.")
+        return report
+
+    image, open_error = _open_image(source, "strip", experimental_be)
+    if image is None:
+        report.fail(open_error or f"strip: cannot open {source}.")
+        return report
+
+    try:
+        inner = image.strip_section(section_name)
+    except (SectionNotFoundError, NotSupportedError, ExeError) as e:
+        report.fail(f"strip: {e}")
+        return report
+
+    inner.data = image.bytes()
+    return inner
+
+
+def nonload_binary(
+    path: str | Path,
+    section_name: str = ".emtrace",
+    *,
+    experimental_be: bool = False,
+) -> NonloadReport:
+    """Make *section_name* non-loadable in the binary at *path* (Tier 2).
+
+    On success with changes, ``report.data`` holds the rebuilt binary bytes.
+    """
+    source = Path(path).resolve()
+    report = NonloadReport(section=section_name)
+    if not source.is_file():
+        report.fail(f"{source} does not exist.")
+        return report
+
+    image, open_error = _open_image(source, "nonload", experimental_be)
+    if image is None:
+        report.fail(open_error or f"nonload: cannot open {source}.")
+        return report
+
+    try:
+        inner = image.make_nonload(section_name)
+    except (SectionNotFoundError, NotSupportedError, ExeError) as e:
+        report.fail(f"nonload: {e}")
+        return report
+
+    if inner.changed:
+        inner.data = image.bytes()
+    return inner

emtrace-0.2.0/emtrace/elf_backend.py

@@ -0,0 +1,151 @@
+"""ELF backend for :mod:`emtrace.exemod` (LIEF-based).
+
+Refusal rules (ported from the previous hand-rolled surgery):
+- unlinked object files (ET_REL) are refused; only ET_EXEC/ET_DYN are edited.
+- only data sections (PROGBITS/NOBITS) can be removed: symbol tables, string
+  tables, relocations, and other metadata sections are refused, since their
+  linkages cannot be expressed safely here.
+- removal is refused when a dynamic symbol references the section (dynamic
+  hash tables cannot be rebuilt here) or when a relocation targets the
+  section's address range or a deleted symbol.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import lief
+
+from .errors import ExeError
+
+FORMAT = "elf"
+
+_ET_REL = 1
+_ET_EXEC = 2
+_ET_DYN = 3
+
+
+def _linked_only(binary: Any) -> None:
+    file_type = binary.header.file_type
+    if file_type not in (
+        lief.ELF.Header.FILE_TYPE.EXEC,
+        lief.ELF.Header.FILE_TYPE.DYN,
+    ):
+        raise ExeError(
+            "input is an unlinked ELF object file; "
+            "run this command on a linked executable or shared object instead"
+        )
+
+
+def try_parse(path: Path, *, experimental_be: bool = False) -> Any | None:
+    """Parse *path* as ELF, or return None when the magic does not match.
+
+    Big-endian inputs are refused unless *experimental_be* is set (their
+    rebuild is unverified and may produce corrupt output).
+    """
+    with path.open("rb") as f:
+        ident = f.read(6)
+        if ident[:4] != b"\x7fELF":
+            return None
+        if ident[5] == 2 and not experimental_be:
+            raise ExeError(
+                f"cannot edit '{path}': "
+                f"big-endian ELF binaries are not supported "
+                f"(use --experimental-be to try anyway; "
+                f"rebuilding them is unverified)"
+            )
+    binary = lief.ELF.parse(str(path))
+    if binary is None:
+        raise ExeError(f"unable to parse '{path}' as ELF")
+    _linked_only(binary)
+    return binary
+
+
+def section_names(binary: Any) -> list[str]:
+    """Names of all sections in the image."""
+    return [section.name for section in binary.sections]
+
+
+def find_section(binary: Any, name: str) -> Any | None:
+    """The section called *name*, or None when it does not exist."""
+    return binary.get_section(name)
+
+
+def _section_index(binary: Any, section: Any) -> int:
+    return int(binary.get_section_idx(section))
+
+
+def check_strippable(binary: Any, section: Any) -> list[Any]:
+    """Validate that *section* can be removed; return bound static symbols.
+
+    Raises ExeError when removal is unsafe.
+    """
+    sec_type = section.type
+    if sec_type not in (
+        lief.ELF.Section.TYPE.PROGBITS,
+        lief.ELF.Section.TYPE.NOBITS,
+    ):
+        raise ExeError(
+            f"cannot remove '{section.name}': "
+            f"only data sections can be removed (section type {sec_type})"
+        )
+
+    index = _section_index(binary, section)
+
+    bound = [symbol for symbol in binary.symbols if int(symbol.shndx) == index]
+    bound_names = {symbol.name for symbol in bound}
+
+    for symbol in binary.dynamic_symbols:
+        if int(symbol.shndx) == index:
+            raise ExeError(
+                f"cannot remove '{section.name}': dynamic symbol '{symbol.name}' "
+                f"references it (dynamic hash tables cannot be rebuilt here)"
+            )
+
+    start = int(section.virtual_address)
+    end = start + int(section.size)
+    for relocation in binary.relocations:
+        address = int(relocation.address)
+        if start <= address < end:
+            raise ExeError(
+                f"cannot remove '{section.name}': "
+                f"a relocation targets its address range"
+            )
+        symbol = relocation.symbol if hasattr(relocation, "symbol") else None
+        if symbol is not None and symbol.name in bound_names:
+            raise ExeError(
+                f"cannot remove '{section.name}': "
+                f"a relocation references deleted symbol '{symbol.name}'"
+            )
+    return bound
+
+
+def delete_symbols(binary: Any, symbols: list[Any]) -> int:
+    """Delete static *symbols* from the symbol table; return the count."""
+    for symbol in symbols:
+        binary.remove_symtab_symbol(symbol)
+    return len(symbols)
+
+
+def remove_section(binary: Any, section: Any) -> None:
+    """Remove *section*, clearing its content so no traces remain."""
+    binary.remove(section, clear=True)
+
+
+def apply_nonload(_binary: Any, section: Any) -> tuple[int, int, bool]:
+    """Clear SHF_ALLOC and the section address; return (old_flags, old_addr, changed)."""
+    old_flags = int(section.flags)
+    old_addr = int(section.virtual_address)
+    if not section.has(lief.ELF.Section.FLAGS.ALLOC):
+        return old_flags, old_addr, False
+    section.flags = lief.ELF.Section.FLAGS(
+        old_flags & ~int(lief.ELF.Section.FLAGS.ALLOC)
+    )
+    section.virtual_address = 0
+    return old_flags, old_addr, True
+
+
+def rebuild(binary: Any) -> bytes:
+    """Rebuild the binary and return the new file content."""
+    return bytes(binary.write_to_bytes())