Integrate Rust Symbol Demangling into Symbol Processing Pipeline

[unclesp1d3r]

Context

The README mentions Rust symbol demangling as a feature, but the integration is not yet implemented. The project needs to add rustc-demangle as a dependency and integrate it into the existing symbol processing pipeline.

Current State

• ✅ Import/export extraction implemented across all formats (ELF, PE, Mach-O)
• ✅ ImportInfo and ExportInfo structures in src/types.rs
• ✅ Container parsers in src/container/ (elf.rs, pe.rs, macho.rs)
• ❌ rustc-demangle not in Cargo.toml
• ❌ No demangling logic in symbol processing
• ❌ No RustSymbol tag in Tag enum

Rust Mangling Schemes

Rust uses two mangling schemes that need to be detected and demangled:

1. Legacy mangling: Symbols start with _ZN (Itanium-style)

   • Example: _ZN4core3fmt3num52_$LT$impl$...
   • Same prefix as C++ mangling, but distinct format

2. v0 mangling: Symbols start with _R (Rust-specific)

   • Example: _RNvC6mycratefunction
   • Introduced in Rust 1.59+, more compact and efficient

The rustc-demangle crate handles both schemes automatically.

Proposed Solution

1. Add Dependency

Add to Cargo.toml:

[dependencies]
rustc-demangle = "0.1"

2. Extend Tag Enum

Add to src/types.rs in the Tag enum:

#[serde(rename = "rust-symbol")]
RustSymbol,

3. Create Demangler Module

Create src/demangler.rs or add to existing classification:

• Function detect_rust_symbol(name: &str) -> bool
  • Check for _ZN or _R prefix
• Function demangle_rust_symbol(name: &str) -> Option<String>
  • Use rustc_demangle::try_demangle()
  • Return demangled string or None on failure

4. Integrate into Container Parsers

Modify symbol extraction in:

• src/container/elf.rs: extract_imports() and extract_exports()
• src/container/pe.rs: extract_imports() and extract_exports()
• src/container/macho.rs: extract_imports() and extract_exports()

When processing symbols:

1. Detect if symbol is Rust-mangled
2. Store original mangled name
3. Attempt demangling
4. If successful, store demangled version as primary name
5. Add RustSymbol tag to classification

5. Update ImportInfo/ExportInfo

Consider extending structures in src/types.rs:

pub struct ImportInfo {
    pub name: String,              // Demangled name (if applicable)
    pub mangled_name: Option<String>,  // Original mangled name
    pub library: Option<String>,
    pub address: Option<u64>,
}

Or maintain backward compatibility by storing demangled name in name field and preserving mangled name in comments/logs.

6. Scoring Integration

In the string ranking/scoring system:

• Demangled Rust symbols should score higher than mangled symbols
• Human-readable function names (e.g., core::fmt::Display::fmt) are more useful than mangled versions
• Consider boost multiplier for demangled symbols

7. Output Format

JSON output should include both versions when demangling succeeds:

{
  "name": "core::fmt::Display::fmt",
  "mangled_name": "_ZN4core3fmt7Display3fmt17h...",
  "tags": ["import", "rust-symbol"]
}

Implementation Notes

• Graceful failure: If demangling fails, use original mangled name
• Performance: rustc-demangle is fast; minimal overhead
• Testing: Use real Rust binaries (from cargo build) in integration tests
• Cross-platform: Works on all platforms (ELF, PE, Mach-O can all contain Rust symbols)

Integration Points

Primary Files to Modify

1. Cargo.toml - Add rustc-demangle dependency
2. src/types.rs - Add RustSymbol tag, optionally extend ImportInfo/ExportInfo
3. src/container/elf.rs - Lines 85-146 (import/export extraction)
4. src/container/pe.rs - Lines 88-120 (import/export extraction)
5. src/container/macho.rs - Lines 112-195 (import/export extraction)
6. src/classification/mod.rs or new src/demangler.rs - Demangling logic

Testing

Create tests/integration_rust_demangle.rs:

• Test legacy _ZN demangling
• Test v0 _R demangling
• Test non-Rust symbols (should pass through unchanged)
• Test malformed symbols (graceful failure)
• Test real Rust binary (e.g., cargo-built executable)

Acceptance Criteria

• rustc-demangle added to Cargo.toml
• RustSymbol tag added to Tag enum in src/types.rs
• Rust symbol detection function (checks _ZN or _R prefix)
• Demangling function using rustc_demangle::try_demangle()
• Integration into ELF import/export extraction
• Integration into PE import/export extraction
• Integration into Mach-O import/export extraction
• Both mangled and demangled names preserved (either in structure or output)
• Demangled symbols receive higher scores in ranking
• Graceful handling of demangle failures
• Integration tests with real Rust binaries
• Unit tests for detection and demangling functions

Example Output

Before (current):

_ZN4core3fmt3num52_$LT$impl$u20$core..fmt..Display$u20$for$u20$i32$GT$3fmt17h1234567890abcdef

After (with demangling):

<core::fmt::num::<impl core::fmt::Display for i32>::fmt>
  (mangled: _ZN4core3fmt3num52_$LT$impl$u20$core..fmt..Display$u20$for$u20$i32$GT$3fmt17h1234567890abcdef)
  [tags: rust-symbol, import]

References

• Parent Epic: Epic: v0.2 - PE Resources, Symbol Demangling & Import/Export Enhancement
• rustc-demangle crate: https://crates.io/crates/rustc-demangle
• Rust symbol mangling: https://rust-lang.github.io/rfcs/2603-rust-symbol-name-mangling-v0.html

---

Related Work

This feature builds on the existing symbol extraction infrastructure and complements:

• Integrate Import/Export Symbol Extraction into String Analysis Pipeline #59 - Import/Export Enhancement (if exists)
• Add relocation-based string ranking to identify code-referenced addresses #60 - PE Resources (if exists)

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[traycerai]

Warning

Rate limit exceeded. Please try after 234 seconds.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Fetch current issue #58 details
echo "=== Current Issue #58 ==="
gh issue view 58 --json title,body,labels,assignees,milestone,state

echo -e "\n=== Parent Epic Issue #40 ==="
gh issue view 40 --json title,body,labels,state

# Check repository structure
echo -e "\n=== Repository Structure ==="
fd -t f -e rs -e toml | head -20

# Check for rustc-demangle in dependencies
echo -e "\n=== Cargo.toml Dependencies ==="
cat Cargo.toml | grep -A 20 "\[dependencies\]"

# Check README for Rust demangling mentions
echo -e "\n=== README Rust Mentions ==="
rg -i "rust.*demangle|demangle.*rust" README.md -C 2

# Look for existing symbol/demangling related code
echo -e "\n=== Symbol Processing Code ==="
rg -l "symbol|demangle" --type rust | head -10

Length of output: 8620

---

🏁 Script executed:

#!/bin/bash

# List all available labels in the repository
echo "=== Available Repository Labels ==="
gh label list --limit 100

# Check for symbol processing in container modules
echo -e "\n=== ELF Container Symbol Processing ==="
rg -n "symbol|import|export" src/container/elf.rs -C 2 | head -40

echo -e "\n=== PE Container Symbol Processing ==="
rg -n "symbol|import|export" src/container/pe.rs -C 2 | head -40

# Check types.rs for data structures
echo -e "\n=== Types Structure ==="
cat src/types.rs | head -100

# Check extraction module
echo -e "\n=== Extraction Module Files ==="
fd . src/extraction/

# Look for any existing demangle references
echo -e "\n=== Existing Demangle References ==="
rg -n "demangle" --type rust

Length of output: 7090

---

🏁 Script executed:

#!/bin/bash

# Get full types.rs to see ImportInfo and ExportInfo structures
echo "=== ImportInfo and ExportInfo Structures ==="
rg -A 10 "pub struct (Import|Export)Info" src/types.rs

# Check extraction module implementation
echo -e "\n=== Extraction Module Implementation ==="
cat src/extraction/mod.rs | head -150

# Look at classification module to understand semantic tagging
echo -e "\n=== Classification Module ==="
cat src/classification/mod.rs | head -100

# Check if there are any comments about future demangle work
echo -e "\n=== TODO or FIXME comments about demangle ==="
rg -i "todo|fixme" --type rust | rg -i "demangle|rust.*symbol|mangle"

Length of output: 789

---

🏁 Script executed:

#!/bin/bash

# Get the actual content of the files
echo "=== Full types.rs (ImportInfo/ExportInfo section) ==="
cat src/types.rs

echo -e "\n=== Full extraction/mod.rs ==="
cat src/extraction/mod.rs

echo -e "\n=== Full classification/mod.rs ==="
cat src/classification/mod.rs

Length of output: 5302

---

🏁 Script executed:

#!/bin/bash

# Check main.rs and lib.rs for actual implementation
echo "=== lib.rs content ==="
cat src/lib.rs

echo -e "\n=== main.rs content (first 200 lines) ==="
head -200 src/main.rs

# Check where strings are actually processed from imports/exports
echo -e "\n=== Container module structure ==="
rg -n "fn.*import|fn.*export|fn.*extract" src/container/*.rs | head -30

# Look for where FoundString is created from imports/exports
echo -e "\n=== FoundString creation from imports/exports ==="
rg -n "FoundString" src/container/*.rs -A 5 -B 2

Length of output: 3754

---

🏁 Script executed:

#!/bin/bash

# Update the issue with enhanced content
gh issue edit 58 --title "Integrate Rust Symbol Demangling into Symbol Processing Pipeline" --body "## Context

The README mentions Rust symbol demangling as a feature, but the integration is not yet implemented. The project needs to add \`rustc-demangle\` as a dependency and integrate it into the existing symbol processing pipeline.

### Current State

- ✅ Import/export extraction implemented across all formats (ELF, PE, Mach-O)
- ✅ \`ImportInfo\` and \`ExportInfo\` structures in \`src/types.rs\`
- ✅ Container parsers in \`src/container/\` (elf.rs, pe.rs, macho.rs)
- ❌ \`rustc-demangle\` not in \`Cargo.toml\`
- ❌ No demangling logic in symbol processing
- ❌ No \`RustSymbol\` tag in \`Tag\` enum

### Rust Mangling Schemes

Rust uses two mangling schemes that need to be detected and demangled:

1. **Legacy mangling**: Symbols start with \`_ZN\` (Itanium-style)
   - Example: \`_ZN4core3fmt3num52_\$LT\$impl\$...\`
   - Same prefix as C++ mangling, but distinct format

2. **v0 mangling**: Symbols start with \`_R\` (Rust-specific)
   - Example: \`_RNvC6mycratefunction\`
   - Introduced in Rust 1.59+, more compact and efficient

The \`rustc-demangle\` crate handles both schemes automatically.

## Proposed Solution

### 1. Add Dependency

Add to \`Cargo.toml\`:
\`\`\`toml
[dependencies]
rustc-demangle = \"0.1\"
\`\`\`

### 2. Extend Tag Enum

Add to \`src/types.rs\` in the \`Tag\` enum:
\`\`\`rust
#[serde(rename = \"rust-symbol\")]
RustSymbol,
\`\`\`

### 3. Create Demangler Module

Create \`src/demangler.rs\` or add to existing classification:
- Function \`detect_rust_symbol(name: &str) -> bool\`
  - Check for \`_ZN\` or \`_R\` prefix
- Function \`demangle_rust_symbol(name: &str) -> Option<String>\`
  - Use \`rustc_demangle::try_demangle()\`
  - Return demangled string or None on failure

### 4. Integrate into Container Parsers

Modify symbol extraction in:
- \`src/container/elf.rs\`: \`extract_imports()\` and \`extract_exports()\`
- \`src/container/pe.rs\`: \`extract_imports()\` and \`extract_exports()\`
- \`src/container/macho.rs\`: \`extract_imports()\` and \`extract_exports()\`

When processing symbols:
1. Detect if symbol is Rust-mangled
2. Store original mangled name
3. Attempt demangling
4. If successful, store demangled version as primary name
5. Add \`RustSymbol\` tag to classification

### 5. Update ImportInfo/ExportInfo

Consider extending structures in \`src/types.rs\`:
\`\`\`rust
pub struct ImportInfo {
    pub name: String,              // Demangled name (if applicable)
    pub mangled_name: Option<String>,  // Original mangled name
    pub library: Option<String>,
    pub address: Option<u64>,
}
\`\`\`

Or maintain backward compatibility by storing demangled name in \`name\` field and preserving mangled name in comments/logs.

### 6. Scoring Integration

In the string ranking/scoring system:
- Demangled Rust symbols should score higher than mangled symbols
- Human-readable function names (e.g., \`core::fmt::Display::fmt\`) are more useful than mangled versions
- Consider boost multiplier for demangled symbols

### 7. Output Format

JSON output should include both versions when demangling succeeds:
\`\`\`json
{
  \"name\": \"core::fmt::Display::fmt\",
  \"mangled_name\": \"_ZN4core3fmt7Display3fmt17h...\",
  \"tags\": [\"import\", \"rust-symbol\"]
}
\`\`\`

## Implementation Notes

- **Graceful failure**: If demangling fails, use original mangled name
- **Performance**: \`rustc-demangle\` is fast; minimal overhead
- **Testing**: Use real Rust binaries (from \`cargo build\`) in integration tests
- **Cross-platform**: Works on all platforms (ELF, PE, Mach-O can all contain Rust symbols)

## Integration Points

### Primary Files to Modify

1. \`Cargo.toml\` - Add rustc-demangle dependency
2. \`src/types.rs\` - Add RustSymbol tag, optionally extend ImportInfo/ExportInfo
3. \`src/container/elf.rs\` - Lines 85-146 (import/export extraction)
4. \`src/container/pe.rs\` - Lines 88-120 (import/export extraction)  
5. \`src/container/macho.rs\` - Lines 112-195 (import/export extraction)
6. \`src/classification/mod.rs\` or new \`src/demangler.rs\` - Demangling logic

### Testing

Create \`tests/integration_rust_demangle.rs\`:
- Test legacy \`_ZN\` demangling
- Test v0 \`_R\` demangling
- Test non-Rust symbols (should pass through unchanged)
- Test malformed symbols (graceful failure)
- Test real Rust binary (e.g., cargo-built executable)

## Acceptance Criteria

- [ ] \`rustc-demangle\` added to \`Cargo.toml\`
- [ ] \`RustSymbol\` tag added to \`Tag\` enum in \`src/types.rs\`
- [ ] Rust symbol detection function (checks \`_ZN\` or \`_R\` prefix)
- [ ] Demangling function using \`rustc_demangle::try_demangle()\`
- [ ] Integration into ELF import/export extraction
- [ ] Integration into PE import/export extraction
- [ ] Integration into Mach-O import/export extraction
- [ ] Both mangled and demangled names preserved (either in structure or output)
- [ ] Demangled symbols receive higher scores in ranking
- [ ] Graceful handling of demangle failures
- [ ] Integration tests with real Rust binaries
- [ ] Unit tests for detection and demangling functions

## Example Output

**Before** (current):
\`\`\`
_ZN4core3fmt3num52_\$LT\$impl\$u20\$core..fmt..Display\$u20\$for\$u20\$i32\$GT\$3fmt17h1234567890abcdef
\`\`\`

**After** (with demangling):
\`\`\`
<core::fmt::num::<impl core::fmt::Display for i32>::fmt>
  (mangled: _ZN4core3fmt3num52_\$LT\$impl\$u20\$core..fmt..Display\$u20\$for\$u20\$i32\$GT\$3fmt17h1234567890abcdef)
  [tags: rust-symbol, import]
\`\`\`

## References

- Parent Epic: [Epic: v0.2 - PE Resources, Symbol Demangling & Import/Export Enhancement](https://github.com/EvilBit-Labs/StringyMcStringFace/issues/40)
- \`rustc-demangle\` crate: https://crates.io/crates/rustc-demangle
- Rust symbol mangling: https://rust-lang.github.io/rfcs/2603-rust-symbol-name-mangling-v0.html

---

## Related Work

This feature builds on the existing symbol extraction infrastructure and complements:
- #59 - Import/Export Enhancement (if exists)
- #60 - PE Resources (if exists)
" --add-label "lang:rust,area:analyzer,needs:tests,priority:medium"

echo "Issue #58 updated successfully"

Length of output: 92

---

@unclesp1d3r, I've successfully enhanced issue #58 with comprehensive technical details and proper metadata. Here's what was updated:

🎯 Title Enhancement

New Title: "Integrate Rust Symbol Demangling into Symbol Processing Pipeline"

📋 Key Additions

1. Current State Analysis

• Documented that rustc-demangle is not currently in Cargo.toml (despite README mentions)
• Confirmed existing import/export infrastructure is ready for integration
• Identified missing RustSymbol tag in the Tag enum

2. Technical Context

• Explained both Rust mangling schemes:
  • Legacy mangling: _ZN prefix (Itanium-style)
  • v0 mangling: _R prefix (Rust 1.59+)
• Provided concrete examples of each scheme

3. Detailed Implementation Plan

Seven-step solution with specific code examples:

• Dependency addition
• Type system updates
• Demangler module creation
• Integration into all three container parsers (ELF, PE, Mach-O)
• Data structure enhancements
• Scoring system integration
• Output format specification

4. Precise Integration Points

Identified exact files and line numbers to modify:

• src/container/elf.rs (lines 85-146)
• src/container/pe.rs (lines 88-120)
• src/container/macho.rs (lines 112-195)
• Plus Cargo.toml, src/types.rs, and classification module

5. Expanded Acceptance Criteria

12 detailed, testable criteria covering detection, demangling, integration, scoring, and testing

6. Before/After Examples

Clear visual demonstration of expected output transformation

🏷️ Metadata Applied

Labels added:

• lang:rust - Rust-specific implementation
• area:analyzer - Binary analyzer functionality
• needs:tests - Requires test coverage
• priority:medium - Medium priority

Already set (preserved):

• Assignee: unclesp1d3r
• Milestone: v0.2
• Label: enhancement

🔗 Related References

• Linked to parent epic Epic: v0.2 - PE Resources, Symbol Demangling & Import/Export Enhancement #40
• Added references to rustc-demangle crate documentation
• Included Rust RFC 2603 (symbol mangling specification)

The issue is now ready for implementation with clear technical guidance and acceptance criteria! 🚀

---

(\___/)
(='.'=)  *excited rabbit*
(")_(")  Ready to demangle!