DECISION-NATIVE-TOOLCHAIN-401: Native Lifter and Demangler Selection

Status: Published Version: 1.0.0 Published: 2025-12-13 Owners: Scanner Guild, Platform Guild Unblocks: SCANNER-NATIVE-401-015, SCAN-REACH-401-009

Part of the Stella Ops Contracts index. Audience: Scanner and Platform implementers building native binary analysis, and reviewers checking that the chosen toolchain preserves determinism and the offline/air-gap posture.

Decision Summary

This decision record fixes the toolchain selection for native binary analysis in Stella Ops — the parsers, demanglers, disassemblers, and callgraph strategy used to extract native symbols, callgraphs, and demangled names from ELF/PE/Mach-O binaries. The guiding constraints are determinism, portability, and zero runtime dependency on external tools so that analysis runs identically in CI and in air-gapped deployments.

1. Component Decisions

1.1 ELF Parser

Decision: Use custom pure-C# ELF parser

Rationale:

• No native dependencies, portable across platforms
• Already implemented in StellaOps.Scanner.Analyzers.Native
• Sufficient for symbol table, dynamic section, and relocation parsing
• Avoids licensing complexity of external libraries

Implementation: src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Native/Internal/Elf/

1.2 PE Parser

Decision: Use custom pure-C# PE parser

Rationale:

• No native dependencies
• Already implemented in StellaOps.Scanner.Analyzers.Native
• Handles import/export tables, Debug directory
• Compatible with air-gapped deployment

Implementation: src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Native/Internal/Pe/

1.3 Mach-O Parser

Decision: Use custom pure-C# Mach-O parser

Rationale:

• Consistent with ELF/PE approach
• No native dependencies
• Sufficient for symbol table and load commands

Implementation: src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Native/Internal/MachO/

1.4 Symbol Demangler

Decision: Use per-language managed demanglers with native fallback

Rationale:

• Managed demanglers provide determinism and portability
• Native fallback only for edge cases
• No runtime dependency on external tools

NuGet packages:

<PackageReference Include="Demangler.Net" Version="1.0.0" />

1.5 Disassembler (Optional, for heuristic analysis)

Decision: Use Iced (x86/x64) + Capstone.NET (ARM/others)

Rationale:

• Iced is pure managed, no native deps for x86
• Capstone.NET wraps Capstone with native lib
• Disassembly is optional for heuristic edge detection

1.6 Callgraph Extraction

Decision: Static analysis only (no dynamic execution)

Methods:

1. Relocation-based: Extract call targets from relocations
2. Import/Export: Map import references to exports
3. Symbol-based: Direct and indirect call targets from symbol table
4. CFG heuristics: Basic block boundary detection (x86 only)

No dynamic analysis: Avoids execution risks, portable.

2. CI Toolchain Requirements

2.1 Build Requirements

2.2 Test Fixture Strategy

Decision: Ship pre-built binary fixtures, not source + compiler

Rationale:

• Deterministic: Same binary hash every run
• No compiler dependency in CI
• Smaller CI image footprint
• Cross-platform: Same fixtures on all runners

Fixture locations:

tests/Binary/fixtures/
  elf-x86_64/
    binary.elf           # Pre-built
    expected.json        # Expected graph
    expected-hashes.txt  # Determinism check
  pe-x64/
    binary.exe
    expected.json
  macho-arm64/
    binary.dylib
    expected.json

2.3 Fixture Generation (Offline)

Fixtures are generated offline by maintainers:

# Generate ELF fixture (run once, commit result)
cd tools/fixtures
./generate-elf-fixture.sh

# Verify hashes match
./verify-fixtures.sh

3. Demangling Contract

3.1 Output Format

Demangled names follow this format:

{
  "symbol": {
    "mangled": "_ZN4Curl7Session4readEv",
    "demangled": "Curl::Session::read()",
    "source": "itanium-abi",
    "confidence": 1.0
  }
}

3.2 Demangling Sources

3.3 Failed Demangling

When demangling fails:

{
  "symbol": {
    "mangled": "_Z15unknown_format",
    "demangled": null,
    "source": "none",
    "confidence": 0.3,
    "demangling_error": "Unrecognized mangling scheme"
  }
}

4. Callgraph Edge Types

4.1 Edge Type Enumeration

4.2 Unknown Targets

When call target cannot be resolved:

{
  "unknowns": [
    {
      "id": "unknown:call:0x12345678",
      "type": "unresolved_call_target",
      "source_id": "sym:binary:abc...",
      "call_site": "0x12345678",
      "reason": "Indirect call through register"
    }
  ]
}

5. Performance Constraints

5.1 Size Limits

5.2 Timeout Constraints

6. Integration Points

6.1 Scanner Plugin Interface

public interface INativeAnalyzer : IAnalyzerPlugin
{
    Task<NativeObservationDocument> AnalyzeAsync(
        Stream binaryStream,
        NativeAnalyzerOptions options,
        CancellationToken ct);
}

6.2 RichGraph Integration

Native analysis results feed into RichGraph:

NativeObservation → NativeReachabilityGraph → RichGraph nodes/edges

6.3 Signals Integration

Native symbols with runtime hits:

Signals runtime-facts + RichGraph → ReachabilityFact with confidence

7. Implementation Checklist

8. Related Documents

• richgraph-v1 Contract
• Build-ID Propagation
• Init-Section Roots
• Binary Reachability Schema

Changelog