Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,13 @@ past roughly six lines it belongs in the PR the entry links.

### Added

- **(loaders)** Analyze ordinary x86/x64 ELF relocatable and COFF objects with deterministic section placement,
section-relative symbols and supported relocations. Preserve the original input hash and record the derived layout,
aliases and unresolved external references in `xmetadata.object_image`; no archive support is added.
Synthetic fixtures cover both architectures. A pinned Ubuntu CRC32 kernel module additionally checks nine recovered
bodies against its symbol addresses, extents and independent instruction counts, including the padding-label case.
Unsupported relocations, TLS and extended object variants remain errors; linked-image recovery is unchanged by design.

### Changed

### Deprecated
Expand Down
99 changes: 99 additions & 0 deletions docs/OBJECT_FILES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Relocatable objects

SMDA accepts ordinary little-endian x86/x64 ELF relocatable objects (`.o` and
uncompressed `.ko`) and conventional COFF objects (`.obj`) through
`Disassembler.disassembleFile()`. No compiler, linker, kernel loader or analyzed
program runs during analysis. Static archives (`.a` and `.lib`) are not supported.

These inputs have no final load addresses. SMDA assigns allocated sections
deterministic analysis addresses in section-table order, beginning at
`0x10000000`, honors their alignment, zero-fills BSS/common storage and applies
supported relocations. Function offsets of zero in different sections remain
distinct. The SHA-256 still identifies the original file, not this derived
analysis image. Addresses and bytes in the mapped view are not those of an
upstream final linked image.

`report.xmetadata["object_image"]` records the input format, layout policy,
section addresses, symbol aliases, known function sizes, the number of applied
relocations and unresolved external symbols. The individual relocation records
stay on `binary_info.object_image.relocations` and are not serialized. Unknown
externals receive analysis-only addresses directly after the mapped image; no
executable stub or implementation is supplied. Aliases share one recovered body. Ordinary C++ decorations use the
same readable-name logic as linked images.

Sized ELF symbols of at most 64 bytes containing only decoded NOP padding and ending at another
declared function entry are preserved as symbol aliases but are not seeded as
function entries. Trap-only bodies remain eligible. This is based on bytes
and extents rather than a `__pfx_` naming rule. For objects, known function
extents prevent a guessed interior prologue from splitting an existing body;
explicit function-symbol starts remain eligible, and calls located inside a
known extent still count as references to their targets. COFF function-definition
auxiliary sizes are used when present. Objects without such sizes still depend
on the normal recovery heuristics and may have fragmented/unnamed code.

## Initial scope

Supported ELF relocations:

* x86: `R_386_32`, `PC32`, `PLT32`, `GOT32`, `GOTOFF`, `GOTPC`, `GOT32X`.
* x64: `R_X86_64_64`, `PC32`, `PLT32`, `GOTPCREL`, `32`, `32S`, `PC64`,
`GOTPCRELX`, `REX_GOTPCRELX`.

Supported COFF relocations:

* x86: `DIR32`, `DIR32NB`, `REL32`, `SECTION`, `SECREL`.
* x64: `ADDR64`, `ADDR32`, `ADDR32NB`, `REL32` through `REL32_5`, `SECTION`,
`SECREL`.

Absolute/no-op relocation entries are skipped. COFF weak externals resolve to
their default symbol and are not listed as unresolved. COFF debug symbols such
as `.file` are ignored. Input that starts with a COFF machine value but whose
section or symbol table does not fit the file is not treated as an object. TLS, compressed allocated ELF
sections, ELF extended section numbering, unsupported architectures/relocations,
COFF relocation-overflow tables, and unsupported weak-external modes are
explicit errors. Bigobj and COFF import-object variants are not recognized by
this initial object loader. COMDAT sections are retained within an individual
object; SMDA does not perform link-time selection across separate objects.
There is no archive iteration, decompression, dependency linking or kernel
version emulation. Non-code objects are refused rather than scanning their
data as machine instructions.

Malformed table/section/symbol bounds and relocation overflows fail analysis.
The existing maximum image size bounds section/GOT/common allocations.
`MAX_OBJECT_SYMBOLS` (250,000), `MAX_OBJECT_RELOCATIONS` (1,000,000), and
`MAX_OBJECT_NAME_LENGTH` (4,096 bytes) bound object-table bookkeeping; zero
disables the corresponding limit.
Symbols whose targets are outside allocated sections are not silently mapped
to arbitrary code. The existing linked-image loaders and CIL backend are kept;
there is no new hash-escape version or report-format version.

## Verification

`tests/testObjectFileLoader.py` constructs harmless ELF32/ELF64 and COFF32/COFF64
objects in memory. Tests cover section-relative zero symbols, call and data
relocations, negative addends, weak externals, debug symbols, BSS/common alignment, external references, padding and aliases,
known function extents, readable names, report serialization, malformed input,
allocation bounds and the continued exclusion of archives.

An optional real-file regression uses Ubuntu's `crc32_generic.ko` from
`linux-modules-6.8.0-31-generic`, version `6.8.0-31.31`:

* Package URL: https://archive.ubuntu.com/ubuntu/pool/main/l/linux/linux-modules-6.8.0-31-generic_6.8.0-31.31_amd64.deb
* Package SHA-256, checked against Ubuntu's noble main package index:
`3f17f2c279257eb50e40da44390bdf8272c440ca078831c348773d1314b5c2fe`.
* Extracted module SHA-256:
`8dcf24cc22b706cc3ee8d8c3368b0ba42a45441198af5ba44c5de60be1567982`.

The test requires an already extracted, uncompressed file and performs no
network access or module loading:

```sh
SMDA_TEST_KO_FILE=/path/to/crc32_generic.ko pytest tests/testObjectFileLoader.py
```

It checks all nine distinct CRC32 bodies against the original ELF symbol
addresses, sizes and independent instruction counts, plus the init/cleanup
aliases. Without this exact supplied file the optional regression is skipped;
the synthetic object tests still run. Neither the module nor a package archive
is committed as a fixture. This is evidence for one real module, not a claim
that every kernel version, architecture or object dialect is supported.
1 change: 1 addition & 0 deletions src/smda/Disassembler.py
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,7 @@ def _populateBinaryInfo(self, loader, file_path=""):
binary_info.code_areas = loader.getCodeAreas()
binary_info.has_backend = loader.getHasBackend()
binary_info.format_recognized = loader.getFormatRecognized()
binary_info.object_image = loader.getObjectImage()
return binary_info

def _ensureHashes(self, binary_info):
Expand Down
3 changes: 3 additions & 0 deletions src/smda/SmdaConfig.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ class SmdaConfig:
TIMEOUT = 300
# maximum number of bytes to allocate while loading
MAX_IMAGE_SIZE = 100 * 1024 * 1024
MAX_OBJECT_SYMBOLS = 250000
MAX_OBJECT_RELOCATIONS = 1000000
MAX_OBJECT_NAME_LENGTH = 4096
# store raw binary buffer in SmdaReport to enable carving data from refs
STORE_BUFFER = False
# extract strings during disassembly
Expand Down
19 changes: 18 additions & 1 deletion src/smda/common/BinaryInfo.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

from smda.common.labelprovider.ElfSymbolProvider import ElfSymbolProvider
from smda.common.labelprovider.MachoSymbolProvider import MachoSymbolProvider
from smda.common.labelprovider.PeSymbolProvider import PeSymbolProvider
from smda.common.labelprovider.PeSymbolProvider import PeSymbolProvider, _readable_name
from smda.utility.ElfFileLoader import ElfFileLoader
from smda.utility.lief_helper import lief_name, safe_lief_parse
from smda.utility.MachoFileLoader import MachoFileLoader
Expand Down Expand Up @@ -83,6 +83,7 @@ def __init__(self, binary: bytes):
self._lief_type = None
self._position_independent_elf = None
self._symbol_provider = None
self.object_image = None
self.abi = ""

def _getLiefType(self):
Expand Down Expand Up @@ -136,6 +137,8 @@ def getBinaryData(self):
return data

def getLiefBinary(self):
if self.object_image is not None:
return None
binary_data = self.getBinaryData()
if self._lief_binary is None and binary_data:
if MachoFileLoader.isCompatible(binary_data):
Expand All @@ -150,6 +153,8 @@ def getLiefBinary(self):
return self._lief_binary

def getOep(self):
if self.object_image is not None:
return None
if self.oep is None:
lief_result = self.getLiefBinary()
lief_type = self._getLiefType()
Expand All @@ -171,6 +176,8 @@ def getOep(self):
return self.oep

def getExportedFunctions(self):
if self.object_image is not None:
return {}
if self.exported_functions is None:
lief_result = self.getLiefBinary()
lief_type = self._getLiefType()
Expand All @@ -184,6 +191,8 @@ def getExportedFunctions(self):
return self.exported_functions

def getExportedSymbols(self):
if self.object_image is not None:
return {}
if self.exported_symbols is None:
lief_result = self.getLiefBinary()
lief_type = self._getLiefType()
Expand All @@ -198,6 +207,8 @@ def getExportedSymbols(self):
return self.exported_symbols

def getImportedFunctions(self):
if self.object_image is not None:
return {address: ("", name) for address, name in self.object_image.imports.items()}
if self.imported_functions is None:
lief_result = self.getLiefBinary()
lief_type = self._getLiefType()
Expand All @@ -211,6 +222,8 @@ def getImportedFunctions(self):
return self.imported_functions

def getSymbols(self):
if self.object_image is not None:
return {address: _readable_name(name) for address, name in self.object_image.functions.items()}
if self.symbols is None:
lief_result = self.getLiefBinary()
lief_type = self._getLiefType()
Expand All @@ -233,6 +246,10 @@ def getSections(self):
PE uses ``base_addr + section.virtual_address``; ELF uses LIEF absolute
``section.virtual_address``; Mach-O applies the Mach-O base/adjustment offset.
"""
if self.object_image is not None:
for section in self.object_image.sections.values():
yield section.name, section.address, section.address + section.size
return
parsed_binary = self.getLiefBinary()
if not parsed_binary:
return
Expand Down
7 changes: 6 additions & 1 deletion src/smda/common/FunctionCandidateManager.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ class FunctionCandidateManager:
CANDIDATE_CLASS = None
#: instruction-start alignment a recovered candidate address has to satisfy
CANDIDATE_ALIGNMENT = 1
_object_image = None

def __init__(self, config):
self.config = config
Expand Down Expand Up @@ -86,6 +87,7 @@ def init(self, disassembly, cbAnalysisTimeout=None):
if disassembly.binary_info.code_areas:
self._code_areas = disassembly.binary_info.code_areas
self.disassembly = disassembly
self._object_image = getattr(disassembly.binary_info, "object_image", None)
self._cb_analysis_timeout = cbAnalysisTimeout
self.lang_analyzer = LanguageAnalyzer(disassembly, self.delphi_resolvers)
self.disassembly.language = self.lang_analyzer.identify()
Expand All @@ -95,9 +97,12 @@ def init(self, disassembly, cbAnalysisTimeout=None):
self.disassembly.identified_alignment = self.identified_alignment
self._buildQueue()

def _passesCodeFilter(self, addr):
def _passesCodeFilter(self, addr, allow_function_interior=False):
if addr is None:
return False
image = self._object_image
if image is not None and not allow_function_interior and image.is_function_interior(addr):
return False
areas = self._code_areas
if not areas:
return True
Expand Down
2 changes: 2 additions & 0 deletions src/smda/common/RecursiveDisassembler.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
from smda.common.labelprovider.ElfSymbolProvider import ElfSymbolProvider
from smda.common.labelprovider.GoLabelProvider import GoSymbolProvider
from smda.common.labelprovider.MachoSymbolProvider import MachoSymbolProvider
from smda.common.labelprovider.ObjectSymbolProvider import ObjectSymbolProvider
from smda.common.labelprovider.PdbSymbolProvider import PdbSymbolProvider
from smda.common.labelprovider.PeSymbolProvider import PeSymbolProvider
from smda.common.labelprovider.RustSymbolProvider import RustSymbolProvider
Expand Down Expand Up @@ -68,6 +69,7 @@ def __init__(self, config, backend, forced_bitness=None):
self._cb_analysis_timeout = None

def _addLabelProviders(self):
self._registerLabelProvider(ObjectSymbolProvider(self.config))
self._registerLabelProvider(WinApiResolver(self.config))
self._registerLabelProvider(ElfApiResolver(self.config))
# Language-specific symbol providers (checked first for proper demangling)
Expand Down
2 changes: 2 additions & 0 deletions src/smda/common/SmdaReport.py
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,8 @@ def __init__(self, disassembly=None, config=None, buffer: Optional[bytes] = None
"imported_functions": self._mergeImportedFunctions(disassembly),
"symbols": disassembly.binary_info.getSymbols(),
}
if getattr(disassembly.binary_info, "object_image", None) is not None:
self.xmetadata["object_image"] = disassembly.binary_info.object_image.metadata()

@staticmethod
def _mergeImportedFunctions(disassembly):
Expand Down
39 changes: 39 additions & 0 deletions src/smda/common/labelprovider/ObjectSymbolProvider.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
from smda.common.labelprovider.AbstractLabelProvider import AbstractLabelProvider
from smda.common.labelprovider.PeSymbolProvider import _readable_name


class ObjectSymbolProvider(AbstractLabelProvider):
def __init__(self, config):
super().__init__(config)
self.image = None
self.functions = {}

def update(self, binary_info):
self.image = getattr(binary_info, "object_image", None)
self.functions = (
{address: _readable_name(name) for address, name in self.image.functions.items()}
if self.image is not None
else {}
)

def getApi(self, to_addr, absolute_addr=None):
if self.image is not None:
name = self.image.imports.get(to_addr) or self.image.imports.get(absolute_addr)
if name:
return "", name
return None, None

def getSymbol(self, address):
return self.functions.get(address, "")

def getFunctionSymbols(self):
return self.functions

def isApiProvider(self):
return True

def isSymbolProvider(self):
return True

def is_active(self):
return self.image is not None
2 changes: 1 addition & 1 deletion src/smda/intel/FunctionCandidateManager.py
Original file line number Diff line number Diff line change
Expand Up @@ -691,7 +691,7 @@ def locateReferenceCandidates(self):
for match_count, call_match in enumerate(re.finditer(b"\xe8", self.disassembly.binary_info.binary)):
if match_count % _TIMEOUT_POLL_INTERVAL == 0 and self._candidateTimeoutTripped():
return
if not self._passesCodeFilter(self.disassembly.binary_info.base_addr + call_match.start()):
if not self._passesCodeFilter(self.disassembly.binary_info.base_addr + call_match.start(), True):
continue
if len(self.disassembly.binary_info.binary) - call_match.start() >= 5:
packed_call = self.disassembly.getRawBytes(call_match.start() + 1, 4)
Expand Down
29 changes: 29 additions & 0 deletions src/smda/utility/FileLoader.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@
LOGGER = logging.getLogger(__name__)


def _load_object(data):
# import the object loader only for ELF ET_REL or i386/AMD64 COFF input
is_elf_rel = data[:4] == b"\x7fELF" and len(data) >= 18 and data[16:18] in (b"\x01\x00", b"\x00\x01")
if is_elf_rel or data[:2] in (b"\x4c\x01", b"\x64\x86"):
from smda.utility.ObjectFileLoader import load_object

return load_object(data)
return None


class FileLoader:
_file_path = None
_map_file = False
Expand All @@ -30,6 +40,7 @@ def __init__(self, file_path, load_file=True, map_file=False, buffer=None):
self._map_file = map_file
self._code_areas = []
self._has_backend = False
self._object_image = None
if load_file:
self._loadFile(buffer)

Expand All @@ -54,8 +65,23 @@ def _loadFile(self, buffer=None):
self._has_backend = False
self._format_recognized = False
self._code_areas = []
self._object_image = None
self._raw_data = buffer if buffer is not None else self._loadRawFileContent()
if self._map_file:
self._object_image = _load_object(self._raw_data)
if self._object_image is not None:
image = self._object_image
if not image.code_areas:
raise ValueError("Object contains no executable sections to disassemble")
self._data = bytes(image.data)
self._base_addr = image.base
self._bitness = image.bitness
self._architecture = "intel"
self._abi = image.abi
self._code_areas = image.code_areas
self._has_backend = True
self._format_recognized = True
return
for loader in self.file_loaders:
if loader.isCompatible(self._raw_data):
# PE/ELF/MachO loaders expose parseBinary() so we can
Expand Down Expand Up @@ -98,6 +124,9 @@ def _loadFile(self, buffer=None):
def getData(self):
return self._data

def getObjectImage(self):
return self._object_image

def getRawData(self):
return self._raw_data

Expand Down
Loading
Loading