Binary diagnostics and comparison
Binary analysis turns a local artifact into facts that an engineer can inspect, compare, and use to choose the next investigation step. It covers artifact discovery, static diagnostics for native formats, whole-artifact and function comparison, and focused native function investigation. See Artifact and application analysis for the wider flow and Application reconstruction for recovery work.
Analysis scope
The system keeps file facts separate from runtime facts. Discovery identifies the bytes, diagnostics explain their declared structure, comparison reports differences between known observations, and native investigation examines selected functions without claiming that static evidence is live behavior.
flowchart LR
A[Local artifact] --> B[Artifact discovery]
B --> C[Format-aware diagnostics]
C --> D[Retained Evidence]
D --> E[Artifact comparison]
D --> F[Native function investigation]
F --> G[Function comparison]
Artifact discovery
Artifact discovery builds a content-addressed view of an application, archive, or package. The view records the root, child occurrences, formats, hashes, locations, and relations such as containment or extraction. Later work can therefore name a stable subject and trace bytes to a logical path.
inspect_artifact returns the graph and its integrity observations in one read-only result. It does not extract files. The result also points to format-based next probes. An integrity mismatch either stops the operation or stays marked as observed but untrusted when the caller chooses record-and-continue.
References: src/…/artifactGraph.ts• L102-176 src/…/artifactInspection.ts• L125-204 src/…/artifactToolContracts.ts• L78-88
Artifact identities
An artifact identity follows observed bytes rather than only a path. A path occurrence can point to shared content, while the manifest records the root digest and graph coverage. This lets comparison detect changed content even when names or container paths stay the same.
Coverage is part of the identity context. Missing entries, unavailable hashes, duplicate paths, and integrity contradictions remain visible instead of becoming equal or absent.
References: src/…/artifactGraph.ts• L102-140 src/…/artifactGraph.ts• L178-212 src/…/artifactComparison.ts• L98-170
Binary session state
A binary session is the lifecycle around an opened executable target and its analysis provider. It keeps the target and provider binding together, records Evidence for the active binding, and reports whether analysis is open, busy, unavailable, or being cleaned up.
Provider discovery and profile checks happen before a provider binds. A route can combine one deep provider with separate readers for other diagnostic work. Runtime failures add an availability view to declared capabilities, so a request failure and a provider-wide failure remain distinct. A bundle can also open as a resource-only session without inventing an executable target.
References: src/…/BinarySession.ts• L161-205 src/…/BinarySession.ts• L553-715 src/…/BinarySessionOpen.ts• L89-149 src/…/AnalysisProviderEvaluation.ts• L22-133 src/…/SessionRuntimeAvailability.ts• L43-155 src/…/BinarySessionStatus.ts• L52-180
Analysis snapshots
An analysis snapshot is a bounded local record of safe provider results for one target and profile. It avoids repeating safe reads and carries Evidence links into a later session.
Replay requires the target, provider identity, and profile to match. Live, stateful, resource-scoped, incomplete, or source-bearing observations stay retained Evidence but do not replay as fresh facts. Target changes and external mutation invalidate cached analysis.
References: src/…/AnalysisSnapshotCache.ts• L49-145 src/…/AnalysisSnapshotCache.ts• L472-587 src/…/ProfilelessNativeWorkflowSnapshot.ts• L12-67
Binary diagnostics
Binary diagnostics answer file-level questions without opening a disassembler target or launching the selected object. They expose structure, hardening indicators, and provenance that help an engineer choose deeper analysis while keeping file ranges, linked addresses, and runtime facts separate.
Binary hardening
Binary hardening inspection summarizes static protection indicators for one ELF, PE, or Mach-O image. It reads headers, program or load tables, symbols, imports, notes, and loader fields from one stable artifact. It does not execute the image or assess exploitability.
The report gives each property a state such as enabled, disabled, partial, unknown, or not_applicable. Each row keeps its evidence basis, location when known, confidence, and next probe. A missing symbol or header field often means that the property is unknown. It does not prove that the related protection is absent.
ELF inspection now treats dynamic-table counts, file-backed virtual-address mappings, symbol-name scans, and GNU property note walks as bounded evidence. Conflicting or incomplete note framing leaves only the affected feature rows unknown while preserving independent header rows. A missing PT_GNU_STACK stays unknown and records the architecture's usual default without applying that default as a claim.
Mach-O inspection reports one image per slice. A universal file can keep valid slices beside malformed or unknown siblings. Slice identity, command ranges, symbol-table limits, encryption declarations, and code-signature presence remain separate facts. A conflicting encryption declaration produces an unknown encryption row rather than hiding otherwise valid header facts.
PE hardening separates header flags, load-configuration data, directory presence, and inferred mitigation labels. These are declarations in the image. They do not show that a mitigation is enforced or that a callback runs.
The provider reads one bounded stable artifact before format dispatch. The service checks the returned identity, row order, ranges, limits, and format scope before creating artifact-bound Evidence. Cancellation before parsing prevents provider work. A late cancellation can retain the acquired observation as partial Evidence.
References: src/…/BinaryHardeningService.ts• L19-111 src/…/BinaryHardeningProvider.ts• L42-127 src/…/ElfHardening.ts• L188-360 src/…/ElfHardening.ts• L745-985 src/…/MachoHardening.ts• L95-150 src/…/MachoHardening.ts• L241-305 src/…/BinaryHardeningParsers.test.ts• L412-555 src/…/binaryHardening.ts• L23-86
ELF layout and metadata diagnostics
ELF diagnostics describe the file's layout and build metadata. Layout inspection reports sections, segments, symbols, relocations, linkage names, and static mitigation indicators. Note, export, DWARF, dependency, unwind, initializer, debug-link, and build-config views add focused facts without turning missing data into runtime claims.
Each view keeps table coverage, file ranges, limits, and parser issues beside the facts. Debug-link inspection reads .gnu_debuglink, .gnu_debugaltlink, .gnu_debugdata, and build IDs. It derives conventional lookup paths but does not search the file system or network. A caller-selected candidate can be compared by CRC32 and build ID. An unreadable or over-budget candidate keeps the image linkage but makes candidate verification partial or unavailable.
References: src/…/BinaryLayoutService.ts• L23-114 src/…/ElfNotesService.ts• L21-125 src/…/DwarfUnitsService.ts• L22-107 src/…/ElfDebugLinkService.ts• L35-109 src/…/ElfDebugLinkService.ts• L453-564 src/…/elfDebugLink.ts• L166-298
ELF dependencies and unwind data
Dependency inspection describes load-time inputs and dynamic symbol needs. It reports the interpreter, needed libraries, search paths, dynamic flags, version facts, and undefined imports. Search tokens such as $ORIGIN remain tokens; the report does not resolve them on the host.
Unwind inspection reports exception and stack-unwind ranges from the relevant tables. It keeps table agreement, pointer encodings, missing coverage, and page totals separate. It does not evaluate call-frame instructions or prove complete runtime unwind behavior.
References: src/…/ElfDependenciesService.ts• L25-103 src/…/elfDependencies.ts• L204-243 src/…/ElfUnwindRangesService.ts• L38-109 src/…/elfUnwindRanges.ts• L98-133
Byte, crash, and system-image diagnostics
Other diagnostics support investigation of bytes and system images. Entropy reports help locate regions that merit review but cannot distinguish compression from encryption. Crash reports preserve historical segments, threads, registers, frames, and mappings without creating a live process. Kernel, module, device-tree, initializer, and shortcut views preserve format facts with bounded coverage.
These outputs are observations about supplied files. A compressed module, unsupported payload, missing debug file, or partial crash join remains an explicit limitation and points to a next probe when one exists.
References: src/…/ByteEntropyService.ts• L59-135 src/…/RecordedCrashService.ts• L15-118 src/…/AppleIpsService.ts• L18-121 src/…/KernelBuildConfigService.ts• L25-77 src/…/KernelModuleService.ts• L28-95 src/…/WindowsShortcutService.ts• L18-133
PE diagnostics
PE diagnostics extend format inspection to the static structures that explain an image's resources, signing data, declared API surface, and loader metadata. Each reader works from a stable PE32 or PE32+ image and reports file-backed ranges, hashes, coverage, and limits without executing the image.
PE resources
PE resource inspection returns the type, name, and language tree. It preserves numeric IDs, UTF-16 names, directory and data-entry locations, payload ranges, and payload hashes. Resource identity stays separate from payload meaning, so an opaque payload remains opaque.
The report links RT_GROUP_ICON entries to candidate RT_ICON resources when numeric ID and language match. It does not decode images, apply Windows language fallback, load resources through Windows, or execute the file.
Traversal accepts only file-backed and unambiguous mappings. Malformed trees, cycles, duplicate identities, ambiguous overlaps, unsupported depth, and exhausted entry or metadata budgets fail without a partial inventory. The provider reports file, entry, and fixed metadata limits as separate recovery information.
References: src/…/PeResourcesProvider.ts• L40-89 src/…/PeResourcesProvider.ts• L93-151 src/…/PeResourcesService.ts• L17-77 src/…/peResourceInventory.ts• L32-77 src/…/peResourceInventory.ts• L158-318 src/…/PeResourcesProvider.test.ts• L33-203
PE certificates
PE certificate inspection reads the security directory as aligned WIN_CERTIFICATE entries. It reports entry locations and hashes. For PKCS#7 entries it also reports structural SignedData, signer identifiers, certificate names, validity times, and algorithm identifiers. Unknown certificate types remain payload observations without a PKCS#7 projection.
The decoder accepts the BER envelope forms used by certificate payloads. Inner X.509 certificate fields still need the required definite DER and X.509 structure. Fixed limits bound ASN.1 nodes, nesting depth, object identifiers, and decoded text. Dual-signed payloads can be read to the supported depth, while unsigned attribute contents remain only OID evidence and make coverage partial. Legacy Teletex names can be retained with an explicit compatibility limitation.
The report validates table entries, alignment padding, nested ranges, and artifact identity before it becomes Evidence. It does not verify cryptographic signatures, certificate chains, timestamps, or Authenticode coverage of image bytes. An absent security directory is an observed absence for that image. It is not proof that no catalog or overlay signature exists.
References: src/…/PeCertificateAsn1.ts• L31-105 src/…/PeCertificateAsn1.ts• L507-605 src/…/PeCertificateAsn1.ts• L730-807 src/…/PeCertificateParser.ts• L48-85 src/…/PeCertificateParser.ts• L102-249 src/…/PeCertificateParser.test.ts• L45-109 src/…/PeCertificatesProvider.test.ts• L50-135
PE imports and load configuration
Import inspection reports standard and delay-load DLLs, descriptor and thunk locations, named or ordinal functions, issues, and coverage. It can emit a pefile-compatible import hash only when the retained rows and file mappings support the same input sequence. When bounds, mapping, name rules, or table heuristics differ, it withholds the hash instead of hashing a partial view.
Load-configuration inspection reports TLS data, callback locations, security-cookie and control-flow table pointers, guard flags, and related fields. It keeps virtual addresses, RVAs, file offsets, and section names separate. It honors the structure's declared size and can retain virtual-only callback targets with no file offset. Guard labels are header observations; mitigation labels are explicit inferences from those observations.
Both reports are static. They do not show which import is bound or reached, whether a TLS callback runs, or whether a mitigation is enforced. Missing directories mean only that the table was absent from the inspected image.
References: src/…/PeImportParser.ts• L53-128 src/…/PeImportParser.ts• L130-229 src/…/PeImportParser.ts• L322-361 src/…/PeLoadConfigParser.ts• L72-126 src/…/PeLoadConfigParser.ts• L129-251 src/…/PeLoadConfigParser.ts• L254-365 src/…/PeLoadConfigParser.ts• L368-480 src/…/PeLoadConfigParser.test.ts• L61-155
Artifact comparison
Artifact comparison answers how two complete discovered artifact graphs differ. It pairs occurrences by normalized logical path and compares content, kind, format, size, executable status, relations, metadata, availability, and integrity.
sequenceDiagram
participant L as Left inventory Evidence
participant C as compare_artifacts
participant R as Right inventory Evidence
participant O as Comparison Evidence
L->>C: Provide complete inventory
R->>C: Provide complete inventory
C->>C: Pair logical paths and inspect coverage
C->>O: Return changes, counts, links, and limits
Comparison status
The result gives one status and one change record per affected logical path. It can report unchanged, added, removed, changed, unknown, truncated, or contradiction states.
Unknown is meaningful. It covers incomplete traversal, unavailable content, ambiguous duplicate paths, different inventory scopes, and other cases where the evidence does not support a safe claim. A missing observation is not evidence of equality. An integrity mismatch is a contradiction, not an ordinary content change.
References: src/…/artifactComparison.ts• L24-50 src/…/artifactComparison.ts• L114-241 src/…/artifactComparison.ts• L244-315
Comparison evidence
Each change links to both input inventories and keeps the affected occurrence and artifact identities when known. The summary counts change classes, while limitations explain why some paths could not be classified.
When a caller supplies an inventory summary view, comparison resolves it to the exact retained complete inventory and rejects a missing or mismatched parent. This prevents a compact view from becoming an unverified comparison source.
References: src/…/ArtifactComparisonEvidence.ts• L13-60 src/…/registerArtifactComparisonTool.ts• L37-99 src/…/artifactComparison.ts• L809-902
Function comparison
Function comparison checks two complete native function dossiers produced from analyze_function Evidence. It uses an explicit pairing and reports each comparison facet as unchanged, changed, or unknown instead of applying fuzzy matching.
Function dimensions
The comparison keeps dimensions separate because a name or layout change does not have the same meaning as a change in calls or control flow.
| Dimension | Purpose |
|---|---|
| Identity | Compare the selected function identity when names are stable. |
| Pseudocode | Compare provider text and bounded line deltas. |
| Assembly | Compare provider instruction text. |
| Comments | Compare normalized comment evidence. |
| Calls | Compare caller and callee relationships. |
| References | Compare incoming and outgoing reference evidence. |
| Strings and names | Compare referenced literals and names. |
| CFG | Compare the normalized control-flow shape. |
References: src/…/functionComparisonSchemas.ts• L7-17 src/…/functionComparisonDimensions.ts• L31-55 src/…/hopperValues.ts• L366-437
Function conclusions
The comparison parses both complete Evidence records, checks provider identity, matches the selected functions, and combines the dimension results. The overall result is unchanged only when every required dimension supports that result. A supported changed dimension produces a changed result.
Missing facet coverage, unstable address-derived names, partial literal data, ambiguous identity, provider differences, or bounded text-diff limits produce unknown results where the evidence is not safe. Text is not equated across different providers. Static comparison does not prove that a function runs or that a changed text form changes application behavior.
References: src/…/functionComparison.ts• L12-45 src/…/functionComparisonResults.ts• L49-83 src/…/functionComparisonDimensions.ts• L76-178
Native binary investigation
Native investigation moves from file facts to a selected executable function. A native provider supplies a function dossier with identity, pseudocode, assembly, comments, calls, references, strings, names, basic blocks, and available native API observations.
Function investigation outputs
The normal path is to inspect the target, select a provider-returned symbol or address, and request a focused function dossier. The dossier is the shared input for later comparisons and for questions about call paths or native API boundaries.
Provider limits and unavailable facets stay explicit. An empty list is not proof that a facet is absent when the provider did not declare coverage.
References: src/…/functionWorkflowToolContracts.ts• L35-45 src/…/functionDossierEvidence.ts• L6-37 src/…/hopperValues.ts• L366-437
Static investigation boundaries
Instruction, call, reference, value-flow, and control-flow results are static observations. They help form a route or hypothesis. They do not establish runtime reachability, actual memory access, calling conventions, or original source intent unless the result states that authority explicitly.
Runtime call and UI observation use a separate workflow. See Native runtime and bridges when the question requires runtime evidence or native-to-managed boundary analysis. For desktop recovery that joins these facts with managed or JavaScript behavior, see JavaScript and desktop reconstruction.
References: docs/native-investigation.md• L107-155 docs/native-investigation.md• L208-252 docs/native-investigation.md• L420-480
Evidence relationships
Evidence links discovery, diagnostics, comparison, and investigation. Derived comparison Evidence cites both source records. Native and artifact observations retain their own artifact identity, provider identity, coverage, and limitations.
When a result is unknown, its limitation is part of the result. Consumers should check coverage, source digests, provider identity, and Evidence links before using a diagnostic fact or comparison as a decision.
References: src/…/registerFunctionComparisonTool.ts• L70-117 src/…/functionComparisonSchemas.ts• L82-109 src/…/artifactComparison.ts• L147-202
Change checklist
When these files or sections are changed, remember to consider these:
- Keep artifact identity, occurrence paths, inventory coverage, and comparison pairing aligned. A mismatch can turn a real difference into
unknownorunchanged. - Keep summary views linked to their retained complete inventory. A changed parent check must not admit stale comparison input.
- Keep provider identity, profile checks, route capabilities, runtime availability, target switches, and snapshot invalidation aligned.
- Keep diagnostic request admission, stable-artifact reads, provider output validation, cancellation, and Evidence provenance aligned.
- Keep hardening property order, format scope, slice identity, row states, and fixed limitations aligned across the domain contract and readers.
- Keep ELF file-backed mappings, dynamic symbol counts, GNU note ownership, overlap handling, alignment, and feature-row unknown states aligned.
- Keep Mach-O slice normalization and malformed-sibling handling aligned. A universal result must not hide a usable slice or create one false overall architecture claim.
- Keep PE resource identity, RVA mapping, shared-range rules, language matching, icon links, and separate file, entry, and metadata limits aligned.
- Keep PE certificate table alignment, PKCS#7 wrapper decoding, X.509 structure, ASN.1 allowances, partial unsigned-attribute coverage, and signing limitations aligned.
- Keep PE import mapping compatibility tied to imphash emission. A partial or differently mapped table must not produce a misleading compatibility hash.
- Keep PE load-configuration field size, callback limits, virtual-only locations, section mapping, and inferred guard facts aligned.
- Keep debug-link lookup strings separate from candidate reads. An unreadable or over-budget candidate must not become a match.
- Keep tool contracts, Evidence links, and summary or page views aligned when output shape or coverage changes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Artifact traversal or hashing is incomplete | Comparison reports unknown or truncated instead of false equality | Check inventory coverage and limitations before using the result |
| A provider candidate is ambiguous or has no valid profile | The session stays unbound or rejects the route | Use candidate status, profile identity, and the selection reason |
| A diagnostic provider reads changed bytes | Evidence is rejected as unstable | Use the reported artifact digest and stable-read result |
| An ELF dynamic table, symbol scan, or note walk exceeds its allowance | Affected hardening rows become unknown while independent rows remain | Read the row basis and structural limitation |
| ELF note tables overlap with different framing or alignment | GNU property rows remain unknown | Treat note coverage as incomplete and inspect the stated reason |
| A universal Mach-O has a malformed or mismatched slice | That slice is unknown or malformed while valid siblings remain | Inspect each slice status and exact slice identity |
| PE resources have ambiguous mappings, cycles, or exhausted limits | No partial resource inventory is returned | Fix the image or use a budget within the accepted ceiling |
| A PE certificate table or alignment range is malformed | Certificate inspection fails instead of claiming signing facts | Distinguish table absence from malformed input |
| PKCS#7 decoding reaches a fixed node, depth, OID, or text allowance | The payload is refused as a parser resource failure | Use the reported fixed allowance; do not treat it as malformed cryptography |
| A certificate is structurally decoded without cryptographic verification | Certificate facts can be mistaken for a valid signature or trust chain | Run a separate trust and signature check when required |
| PE import mappings do not match the compatibility rules | The imphash is withheld | Use issues and the imphash reason instead of hashing retained rows |
| A PE load-config callback or table points outside a clear mapping | The report fails or keeps the file location unknown | Check RVA, section, and file-backed location status |
| A debug-link lookup path is treated as a discovered file | The investigation claims a debug file exists without reading it | Treat lookup paths as untrusted strings and compare an explicit candidate |
| A static native edge is mistaken for runtime behavior | The investigation claims reachability or execution without observation | Use a runtime workflow for runtime claims |
Key files
| File | Why to read it |
|---|---|
| src/…/artifactGraph.ts | Defines artifact identity, occurrences, relations, and coverage. |
| src/…/artifactComparison.ts | Defines pairing, change states, integrity contradictions, and uncertainty. |
| src/…/BinarySession.ts | Shows target lifecycle, provider binding, Evidence, snapshots, and status. |
| src/…/BinaryHardeningService.ts | Shows the Evidence boundary for static hardening facts. |
| src/…/BinaryHardeningProvider.ts | Shows stable-artifact dispatch to ELF, PE, and Mach-O hardening readers. |
| src/…/ElfHardening.ts | Shows how ELF headers, symbols, mappings, and GNU notes become protection rows. |
| src/…/MachoHardening.ts | Shows per-slice Mach-O hardening facts and slice failure isolation. |
| src/…/PeResourcesProvider.ts | Shows bounded PE resource reading and limit reporting. |
| src/…/PeCertificateParser.ts | Shows PE certificate table and structural signing-data output. |
| src/…/PeCertificateAsn1.ts | Shows bounded PKCS#7 and X.509 structural decoding. |
| src/…/PeImportParser.ts | Shows static import inventory and safe imphash decisions. |
| src/…/PeLoadConfigParser.ts | Shows TLS and load-configuration facts with separate address mappings. |
| src/…/ElfDebugLinkService.ts | Shows ELF debug-file linkage and explicit candidate verification. |
| src/…/functionComparison.ts | Connects two complete function dossiers to a derived comparison. |
| docs/native-investigation.md | Describes the user-facing native investigation flow and static boundaries. |