Implement Symbol Classification and Import/Export Tagging

[unclesp1d3r]

Summary

Implement the classification layer for import/export symbols and section names, converting parsed binary metadata into tagged, scored FoundString objects for analysis.

Current State

✅ Container Parsers Implemented: All three parsers (ELF, PE, Mach-O) successfully extract import/export metadata:

• ImportInfo: Symbol names, library names, addresses
• ExportInfo: Symbol names, addresses, ordinals
• Section metadata with full classification

🚧 Classification Module Empty: src/classification/mod.rs contains only a comment. Need to implement symbol processing logic.

Requirements

4.2: Import Name Identification and Tagging

• Convert ImportInfo objects into FoundString with Tag::Import
• Set source: StringSource::ImportName
• Apply semantic classification (e.g., crypto APIs, network APIs)
• Boost relevance scores for security-relevant imports

4.3: Export Name Identification and Tagging

• Convert ExportInfo objects into FoundString with Tag::Export
• Set source: StringSource::ExportName
• Demangle Rust symbols using rustc-demangle
• Identify entry points and special exports

4.4: Section Name Processing and Classification

• Treat section names as high-value strings
• Tag with relevant semantic categories
• Use section names to provide context for other strings

Proposed Solution

Implementation Structure

Create src/classification/symbols.rs module with:

pub struct SymbolClassifier {
    crypto_apis: HashSet<String>,
    network_apis: HashSet<String>,
    file_apis: HashSet<String>,
}

impl SymbolClassifier {
    pub fn process_imports(imports: &[ImportInfo]) -> Vec<FoundString>;
    pub fn process_exports(exports: &[ExportInfo]) -> Vec<FoundString>;
    pub fn classify_symbol(name: &str) -> Vec<Tag>;
    pub fn demangle_rust_symbol(name: &str) -> Option<String>;
}

Key Features

1. Import Processing

   • Convert each ImportInfo to FoundString
   • Base score: +20 points (high value)
   • Additional tags based on API name patterns:
     • Crypto: CryptEncrypt, EVP_*, crypto_*
     • Network: socket, connect, WSA*, curl_*
     • File I/O: CreateFile, open, fopen
   • Preserve library information in metadata

2. Export Processing

   • Convert each ExportInfo to FoundString
   • Attempt Rust symbol demangling
   • Identify special exports:
     • Entry points: main, DllMain, _start
     • Mangled Rust functions
   • Base score: +15 points

3. Symbol Demangling

   • Use rustc-demangle crate for Rust symbols
   • Preserve both mangled and demangled forms
   • Add context-specific tags (panic, alloc, etc.)

4. Section Name Processing

   • Extract section names from SectionInfo
   • High relevance score (+10)
   • Use for contextualizing other strings in same section

API Design

// Main entry point for symbol processing
pub fn extract_symbol_strings(container_info: &ContainerInfo) -> Vec<FoundString> {
    let mut strings = Vec::new();
    
    let classifier = SymbolClassifier::new();
    strings.extend(classifier.process_imports(&container_info.imports));
    strings.extend(classifier.process_exports(&container_info.exports));
    strings.extend(extract_section_names(&container_info.sections));
    
    strings
}

Test Requirements

Create tests/classification_symbols.rs with:

1. Import Classification Tests

   • Test crypto API detection (CryptEncrypt, AES_encrypt)
   • Test network API detection (socket, WSAStartup)
   • Verify Tag::Import applied correctly
   • Check library attribution preserved

2. Export Classification Tests

   • Test basic export tagging
   • Test entry point detection (main, DllMain)
   • Verify Tag::Export applied

3. Rust Demangling Tests

   • Test successful demangling of Rust symbols
   • Verify both forms preserved
   • Test context tag detection (panic, main, etc.)
   • Handle non-Rust symbols gracefully

4. Section Name Tests

   • Verify section names extracted as strings
   • Check appropriate scoring applied
   • Test all three formats (ELF, PE, Mach-O)

Success Criteria

• SymbolClassifier implemented in src/classification/symbols.rs
• All imports converted to FoundString with Tag::Import
• All exports converted to FoundString with Tag::Export
• Rust symbol demangling working with rustc-demangle
• Semantic API classification (crypto, network, file I/O)
• Section names processed as high-value strings
• Unit tests achieving >90% coverage
• Integration tests for all three formats
• Documentation with examples

Dependencies

• ✅ Symbol Processing (container parsers extract symbols)
• 📦 rustc-demangle crate (add to Cargo.toml)

Technical Notes

• Use lazy_static for compiled API pattern sets
• Preserve all original metadata (addresses, ordinals, library names)
• Scoring should be additive: base score + semantic boosts
• Handle edge cases: empty names, duplicate symbols, stripped binaries
• Consider memory efficiency with large symbol tables

Example Output

{
  "text": "CryptEncrypt",
  "encoding": "Ascii",
  "offset": 0,
  "section": ".idata",
  "tags": ["import", "crypto"],
  "score": 25,
  "source": "ImportName"
}

References

• Architecture docs: docs/src/architecture.md (Symbol Classification section)
• Classification docs: docs/src/classification.md (Symbol Classifier implementation)
• Concept doc: concept.md (Demangling requirements)
• Related: Container parsing implementation (✅ complete)

[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]

Plan

Observations

The codebase has a well-structured foundation with complete container parsers (ELF, PE, Mach-O) that extract imports, exports, and section metadata. The types.rs module defines all necessary data structures including FoundString, ImportInfo, ExportInfo, Tag, and StringSource enums. The classification module is currently empty and ready for implementation. Integration tests demonstrate the expected behavior with real binary fixtures.

Approach

Implement a symbol classification system that converts parsed import/export metadata into tagged FoundString objects with semantic analysis. Create a SymbolClassifier struct with API pattern detection for crypto, network, and file I/O operations. Add Rust symbol demangling support using the rustc-demangle crate. Implement section name extraction as high-value strings. Follow the existing test patterns with comprehensive unit and integration tests.

Reasoning

Explored the repository structure and identified that container parsers are complete and provide ImportInfo/ExportInfo data. Reviewed the type definitions to understand the FoundString structure and available tags. Examined existing integration tests to understand testing patterns. Reviewed documentation to understand the scoring system and semantic classification requirements. Confirmed that the classification module is empty and ready for implementation.

Proposed File Changes

📄 Cargo.toml ^(MODIFY) 🔗

Add the rustc-demangle dependency to support Rust symbol demangling as specified in the requirements. The version should be compatible with the current Rust edition (2024). This dependency is essential for processing Rust export symbols and extracting meaningful function names from mangled symbols.

📄 src/classification/mod.rs ^(MODIFY) 🔗

Transform this module from a placeholder into the classification module entry point. Declare the symbols submodule and re-export key types for public API access. Add module-level documentation explaining the classification system's purpose and how it processes binary metadata into tagged strings. Export the main entry point function extract_symbol_strings that will be called by the extraction pipeline.

📄 src/classification/symbols.rs ^(NEW) 🔗

References

• 📄 src/types.rs ^(MODIFY)
• 📄 src/container/elf.rs
• 📄 src/container/pe.rs

Create the core symbol classification module with the following components:

1. SymbolClassifier struct: Main classifier with HashSet-based API pattern collections for crypto APIs (CryptEncrypt, EVP_, AES_, crypto_, etc.), network APIs (socket, connect, bind, listen, accept, send, recv, WSAStartup, WSASocket, curl_, etc.), and file I/O APIs (CreateFile, CreateFileW, open, fopen, fread, fwrite, ReadFile, WriteFile, etc.). Initialize these sets efficiently, potentially using lazy initialization patterns.

2. process_imports method: Convert each ImportInfo from ContainerInfo into a FoundString with:

   • text: The import symbol name
   • encoding: Ascii (imports are always ASCII)
   • offset: 0 (imports don't have file offsets)
   • rva: Use the address from ImportInfo if available
   • section: Use library name or ".idata" for PE, ".dynsym" for ELF
   • length: Calculate from name length
   • tags: Start with Tag::Import, then add semantic tags based on API classification
   • score: Base score of 20 as specified, with additional boosts for security-relevant APIs
   • source: StringSource::ImportName

3. process_exports method: Convert each ExportInfo into a FoundString with:

   • Similar structure to imports but with Tag::Export
   • Attempt Rust symbol demangling using rustc-demangle::try_demangle
   • If demangling succeeds, use demangled name as text and add context-specific tags
   • Identify entry points (main, DllMain, _start, WinMain) and add appropriate tags
   • Base score of 15 as specified
   • source: StringSource::ExportName

4. classify_symbol method: Analyze symbol names and return appropriate semantic tags:

   • Check against crypto_apis set for cryptographic operations
   • Check against network_apis set for network operations
   • Check against file_apis set for file I/O operations
   • Return a Vec with all matching classifications

5. demangle_rust_symbol method: Use rustc-demangle::try_demangle to convert mangled Rust symbols:

   • Return Some(demangled_string) on success
   • Return None for non-Rust symbols or demangling failures
   • Extract context from demangled names (e.g., detect "panic", "main", "alloc" patterns)

6. extract_section_names function: Process section names from ContainerInfo.sections:

   • Create a FoundString for each section name
   • Set score to 10 (high value but lower than imports/exports)
   • Use StringSource::SectionData
   • Add appropriate tags based on section type

Implement comprehensive error handling and ensure all methods are well-documented with examples.

📄 tests/classification_symbols.rs ^(NEW) 🔗

References

• 📄 tests/integration_elf.rs
• 📄 src/types.rs ^(MODIFY)

Create comprehensive unit and integration tests for symbol classification:

1. Import Classification Tests:

   • test_crypto_api_detection: Verify crypto APIs like "CryptEncrypt", "AES_encrypt", "EVP_EncryptInit" are tagged correctly
   • test_network_api_detection: Verify network APIs like "socket", "connect", "WSAStartup", "curl_easy_perform" are tagged correctly
   • test_file_api_detection: Verify file APIs like "CreateFileW", "fopen", "ReadFile" are tagged correctly
   • test_import_tag_applied: Verify Tag::Import is always present
   • test_import_library_preserved: Verify library names from ImportInfo are preserved in section field
   • test_import_base_score: Verify base score of 20 is applied
   • test_import_semantic_boost: Verify additional score boosts for security-relevant APIs

2. Export Classification Tests:

   • test_export_basic_tagging: Verify Tag::Export is applied to all exports
   • test_export_entry_point_detection: Verify "main", "DllMain", "_start", "WinMain" are identified as entry points
   • test_export_base_score: Verify base score of 15 is applied

3. Rust Demangling Tests:

   • test_rust_symbol_demangling_success: Test with real mangled Rust symbols (e.g., "ZN4core3fmt3num52$LT$impl$u20$core..fmt..Display$u20$for$u20$i32$GT$3fmt17h")
   • test_rust_symbol_demangling_preserves_both_forms: Verify both mangled and demangled forms are accessible
   • test_rust_panic_detection: Verify panic-related symbols are tagged appropriately
   • test_rust_main_detection: Verify Rust main functions are identified
   • test_non_rust_symbol_handling: Verify non-Rust symbols are handled gracefully without demangling

4. Section Name Tests:

   • test_section_name_extraction: Verify section names are extracted as FoundString objects
   • test_section_name_scoring: Verify score of 10 is applied
   • test_section_name_all_formats: Test with ELF (.rodata, .text), PE (.rdata, .rsrc), and Mach-O (__TEXT,__cstring) section names

5. Integration Tests:

   • test_extract_symbol_strings_elf: Use the ELF test fixture from tests/fixtures/test_binary_elf and verify complete symbol extraction
   • test_extract_symbol_strings_pe: Use PE fixture if available
   • test_extract_symbol_strings_macho: Use Mach-O fixture
   • test_empty_container_info: Verify graceful handling of ContainerInfo with no imports/exports

Follow the testing patterns established in tests/integration_elf.rs, using the insta crate for snapshot testing where appropriate. Each test should be well-documented and include assertions for all relevant fields of FoundString.

📄 src/types.rs ^(MODIFY) 🔗

Evaluate whether additional Tag variants are needed for the symbol classification system. Based on the requirements and documentation review:

1. Consider adding new Tag variants if not already present:
   • Crypto for cryptographic API functions
   • Network for network-related API functions
   • FileIO for file I/O operations
   • EntryPoint for main/DllMain/_start functions

However, review the existing Tag enum carefully. The current tags (Import, Export, etc.) may be sufficient if we use them in combination. If new tags are needed, add them to the enum with appropriate serde rename attributes for JSON serialization consistency. Update any Display or other trait implementations accordingly.

If no new tags are needed (existing tags are sufficient), document this decision in the implementation and use tag combinations to represent semantic categories.

📄 docs/src/classification.md ^(MODIFY) 🔗

References

• 📄 src/classification/symbols.rs ^(NEW)

Update the Symbol Classification section (lines 172-231) with concrete implementation details now that the module is implemented:

1. Update the SymbolClassifier example code to reflect the actual implementation structure
2. Add documentation for the API pattern sets (crypto_apis, network_apis, file_apis) with examples of detected patterns
3. Document the scoring system: base scores (+20 for imports, +15 for exports, +10 for section names) and semantic boosts
4. Add examples of classified symbols with their resulting FoundString representation
5. Document the Rust demangling behavior and how both mangled/demangled forms are handled
6. Add a section on entry point detection with examples
7. Include usage examples showing how to call extract_symbol_strings with a ContainerInfo object

Ensure the documentation matches the actual implementation and provides clear guidance for users and future maintainers.

📄 README.md ^(MODIFY) 🔗

Update the README to reflect the newly implemented symbol classification feature. Add a section describing:

1. Symbol classification capabilities (import/export processing)
2. Semantic API detection (crypto, network, file I/O)
3. Rust symbol demangling support
4. Example output showing classified symbols with tags and scores

Ensure the feature list and status indicators are updated to show that symbol classification is now implemented. Keep the tone consistent with the existing README style.

Diagram

sequenceDiagram
    participant CP as ContainerParser
    participant CI as ContainerInfo
    participant SC as SymbolClassifier
    participant FS as Vec<FoundString>
    
    Note over CP,CI: Container Parsing Phase (Already Complete)
    CP->>CI: parse() returns ContainerInfo
    Note over CI: Contains imports, exports, sections
    
    Note over SC,FS: Symbol Classification Phase (New Implementation)
    CI->>SC: extract_symbol_strings(&container_info)
    
    SC->>SC: process_imports(&imports)
    loop For each ImportInfo
        SC->>SC: classify_symbol(name)
        Note over SC: Check crypto/network/file APIs
        SC->>FS: Create FoundString with Tag::Import + semantic tags
        Note over FS: Base score: 20 + semantic boosts
    end
    
    SC->>SC: process_exports(&exports)
    loop For each ExportInfo
        SC->>SC: demangle_rust_symbol(name)
        alt Rust symbol
            Note over SC: Use demangled name
        else Non-Rust symbol
            Note over SC: Use original name
        end
        SC->>SC: Detect entry points (main, DllMain, etc.)
        SC->>FS: Create FoundString with Tag::Export
        Note over FS: Base score: 15
    end
    
    SC->>SC: extract_section_names(&sections)
    loop For each SectionInfo
        SC->>FS: Create FoundString from section name
        Note over FS: Score: 10
    end
    
    SC-->>CI: Return Vec<FoundString>
    Note over FS: Ready for ranking and output

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The codebase has a well-structured foundation with complete container parsers (ELF, PE, Mach-O) that extract imports, exports, and section metadata. The `types.rs` module defines all necessary data structures including `FoundString`, `ImportInfo`, `ExportInfo`, `Tag`, and `StringSource` enums. The classification module is currently empty and ready for implementation. Integration tests demonstrate the expected behavior with real binary fixtures.

### Approach

Implement a symbol classification system that converts parsed import/export metadata into tagged `FoundString` objects with semantic analysis. Create a `SymbolClassifier` struct with API pattern detection for crypto, network, and file I/O operations. Add Rust symbol demangling support using the `rustc-demangle` crate. Implement section name extraction as high-value strings. Follow the existing test patterns with comprehensive unit and integration tests.

### Reasoning

Explored the repository structure and identified that container parsers are complete and provide `ImportInfo`/`ExportInfo` data. Reviewed the type definitions to understand the `FoundString` structure and available tags. Examined existing integration tests to understand testing patterns. Reviewed documentation to understand the scoring system and semantic classification requirements. Confirmed that the classification module is empty and ready for implementation.

## Mermaid Diagram

sequenceDiagram
    participant CP as ContainerParser
    participant CI as ContainerInfo
    participant SC as SymbolClassifier
    participant FS as Vec<FoundString>
    
    Note over CP,CI: Container Parsing Phase (Already Complete)
    CP->>CI: parse() returns ContainerInfo
    Note over CI: Contains imports, exports, sections
    
    Note over SC,FS: Symbol Classification Phase (New Implementation)
    CI->>SC: extract_symbol_strings(&container_info)
    
    SC->>SC: process_imports(&imports)
    loop For each ImportInfo
        SC->>SC: classify_symbol(name)
        Note over SC: Check crypto/network/file APIs
        SC->>FS: Create FoundString with Tag::Import + semantic tags
        Note over FS: Base score: 20 + semantic boosts
    end
    
    SC->>SC: process_exports(&exports)
    loop For each ExportInfo
        SC->>SC: demangle_rust_symbol(name)
        alt Rust symbol
            Note over SC: Use demangled name
        else Non-Rust symbol
            Note over SC: Use original name
        end
        SC->>SC: Detect entry points (main, DllMain, etc.)
        SC->>FS: Create FoundString with Tag::Export
        Note over FS: Base score: 15
    end
    
    SC->>SC: extract_section_names(&sections)
    loop For each SectionInfo
        SC->>FS: Create FoundString from section name
        Note over FS: Score: 10
    end
    
    SC-->>CI: Return Vec<FoundString>
    Note over FS: Ready for ranking and output

## Proposed File Changes

### Cargo.toml(MODIFY)

Add the `rustc-demangle` dependency to support Rust symbol demangling as specified in the requirements. The version should be compatible with the current Rust edition (2024). This dependency is essential for processing Rust export symbols and extracting meaningful function names from mangled symbols.

### src/classification/mod.rs(MODIFY)

Transform this module from a placeholder into the classification module entry point. Declare the `symbols` submodule and re-export key types for public API access. Add module-level documentation explaining the classification system's purpose and how it processes binary metadata into tagged strings. Export the main entry point function `extract_symbol_strings` that will be called by the extraction pipeline.

### src/classification/symbols.rs(NEW)

References: 

- src/types.rs(MODIFY)
- src/container/elf.rs
- src/container/pe.rs

Create the core symbol classification module with the following components:

1. **SymbolClassifier struct**: Main classifier with HashSet-based API pattern collections for crypto APIs (CryptEncrypt, EVP_*, AES_*, crypto_*, etc.), network APIs (socket, connect, bind, listen, accept, send, recv, WSAStartup, WSASocket, curl_*, etc.), and file I/O APIs (CreateFile, CreateFileW, open, fopen, fread, fwrite, ReadFile, WriteFile, etc.). Initialize these sets efficiently, potentially using lazy initialization patterns.

2. **process_imports method**: Convert each `ImportInfo` from `ContainerInfo` into a `FoundString` with:
   - `text`: The import symbol name
   - `encoding`: Ascii (imports are always ASCII)
   - `offset`: 0 (imports don't have file offsets)
   - `rva`: Use the address from ImportInfo if available
   - `section`: Use library name or ".idata" for PE, ".dynsym" for ELF
   - `length`: Calculate from name length
   - `tags`: Start with Tag::Import, then add semantic tags based on API classification
   - `score`: Base score of 20 as specified, with additional boosts for security-relevant APIs
   - `source`: StringSource::ImportName

3. **process_exports method**: Convert each `ExportInfo` into a `FoundString` with:
   - Similar structure to imports but with Tag::Export
   - Attempt Rust symbol demangling using `rustc-demangle::try_demangle`
   - If demangling succeeds, use demangled name as text and add context-specific tags
   - Identify entry points (main, DllMain, _start, WinMain) and add appropriate tags
   - Base score of 15 as specified
   - `source`: StringSource::ExportName

4. **classify_symbol method**: Analyze symbol names and return appropriate semantic tags:
   - Check against crypto_apis set for cryptographic operations
   - Check against network_apis set for network operations
   - Check against file_apis set for file I/O operations
   - Return a Vec<Tag> with all matching classifications

5. **demangle_rust_symbol method**: Use `rustc-demangle::try_demangle` to convert mangled Rust symbols:
   - Return Some(demangled_string) on success
   - Return None for non-Rust symbols or demangling failures
   - Extract context from demangled names (e.g., detect "panic", "main", "alloc" patterns)

6. **extract_section_names function**: Process section names from `ContainerInfo.sections`:
   - Create a `FoundString` for each section name
   - Set score to 10 (high value but lower than imports/exports)
   - Use StringSource::SectionData
   - Add appropriate tags based on section type

Implement comprehensive error handling and ensure all methods are well-documented with examples.

### tests/classification_symbols.rs(NEW)

References: 

- tests/integration_elf.rs
- src/types.rs(MODIFY)

Create comprehensive unit and integration tests for symbol classification:

1. **Import Classification Tests**:
   - `test_crypto_api_detection`: Verify crypto APIs like "CryptEncrypt", "AES_encrypt", "EVP_EncryptInit" are tagged correctly
   - `test_network_api_detection`: Verify network APIs like "socket", "connect", "WSAStartup", "curl_easy_perform" are tagged correctly
   - `test_file_api_detection`: Verify file APIs like "CreateFileW", "fopen", "ReadFile" are tagged correctly
   - `test_import_tag_applied`: Verify Tag::Import is always present
   - `test_import_library_preserved`: Verify library names from ImportInfo are preserved in section field
   - `test_import_base_score`: Verify base score of 20 is applied
   - `test_import_semantic_boost`: Verify additional score boosts for security-relevant APIs

2. **Export Classification Tests**:
   - `test_export_basic_tagging`: Verify Tag::Export is applied to all exports
   - `test_export_entry_point_detection`: Verify "main", "DllMain", "_start", "WinMain" are identified as entry points
   - `test_export_base_score`: Verify base score of 15 is applied

3. **Rust Demangling Tests**:
   - `test_rust_symbol_demangling_success`: Test with real mangled Rust symbols (e.g., "_ZN4core3fmt3num52_$LT$impl$u20$core..fmt..Display$u20$for$u20$i32$GT$3fmt17h")
   - `test_rust_symbol_demangling_preserves_both_forms`: Verify both mangled and demangled forms are accessible
   - `test_rust_panic_detection`: Verify panic-related symbols are tagged appropriately
   - `test_rust_main_detection`: Verify Rust main functions are identified
   - `test_non_rust_symbol_handling`: Verify non-Rust symbols are handled gracefully without demangling

4. **Section Name Tests**:
   - `test_section_name_extraction`: Verify section names are extracted as FoundString objects
   - `test_section_name_scoring`: Verify score of 10 is applied
   - `test_section_name_all_formats`: Test with ELF (.rodata, .text), PE (.rdata, .rsrc), and Mach-O (__TEXT,__cstring) section names

5. **Integration Tests**:
   - `test_extract_symbol_strings_elf`: Use the ELF test fixture from `tests/fixtures/test_binary_elf` and verify complete symbol extraction
   - `test_extract_symbol_strings_pe`: Use PE fixture if available
   - `test_extract_symbol_strings_macho`: Use Mach-O fixture
   - `test_empty_container_info`: Verify graceful handling of ContainerInfo with no imports/exports

Follow the testing patterns established in `tests/integration_elf.rs`, using the insta crate for snapshot testing where appropriate. Each test should be well-documented and include assertions for all relevant fields of FoundString.

### src/types.rs(MODIFY)

Evaluate whether additional Tag variants are needed for the symbol classification system. Based on the requirements and documentation review:

1. Consider adding new Tag variants if not already present:
   - `Crypto` for cryptographic API functions
   - `Network` for network-related API functions
   - `FileIO` for file I/O operations
   - `EntryPoint` for main/DllMain/_start functions

However, review the existing Tag enum carefully. The current tags (Import, Export, etc.) may be sufficient if we use them in combination. If new tags are needed, add them to the enum with appropriate serde rename attributes for JSON serialization consistency. Update any Display or other trait implementations accordingly.

If no new tags are needed (existing tags are sufficient), document this decision in the implementation and use tag combinations to represent semantic categories.

### docs/src/classification.md(MODIFY)

References: 

- src/classification/symbols.rs(NEW)

Update the Symbol Classification section (lines 172-231) with concrete implementation details now that the module is implemented:

1. Update the SymbolClassifier example code to reflect the actual implementation structure
2. Add documentation for the API pattern sets (crypto_apis, network_apis, file_apis) with examples of detected patterns
3. Document the scoring system: base scores (+20 for imports, +15 for exports, +10 for section names) and semantic boosts
4. Add examples of classified symbols with their resulting FoundString representation
5. Document the Rust demangling behavior and how both mangled/demangled forms are handled
6. Add a section on entry point detection with examples
7. Include usage examples showing how to call `extract_symbol_strings` with a ContainerInfo object

Ensure the documentation matches the actual implementation and provides clear guidance for users and future maintainers.

### README.md(MODIFY)

Update the README to reflect the newly implemented symbol classification feature. Add a section describing:

1. Symbol classification capabilities (import/export processing)
2. Semantic API detection (crypto, network, file I/O)
3. Rust symbol demangling support
4. Example output showing classified symbols with tags and scores

Ensure the feature list and status indicators are updated to show that symbol classification is now implemented. Keep the tone consistent with the existing README style.

---

Developer Humor

🔍 The Symbol Classifier speaks:\n> \I demangle Rust, I tag with zest,\n> Crypto and network, I know what's best!\n> Imports get twenty, exports fifteen,\n> The cleanest symbol tags you've ever seen!\n> 🏷️✨

---

Execution Information

Branch: main
Commit: bdd6206

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Tip

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue #20 details
gh issue view 20 --json title,body,labels,assignees,milestone,state

# Get repository information
gh repo view --json name,description,defaultBranch

# Explore the repository structure to understand the project
fd -t f -e py -e md | head -30

Length of output: 2925

---

🏁 Script executed:

#!/bin/bash
# Read relevant documentation
echo "=== Classification Documentation ==="
cat docs/src/classification.md

echo -e "\n=== Binary Formats Documentation ==="
cat docs/src/binary-formats.md

echo -e "\n=== Architecture Documentation ==="
cat docs/src/architecture.md

# Find source files related to classification, imports, exports
echo -e "\n=== Source Structure ==="
fd -t f -e rs | grep -E "(src|lib)" | head -20

Length of output: 32796

---

🏁 Script executed:

#!/bin/bash
# Check classification module implementation
echo "=== Classification Module ==="
cat src/classification/mod.rs

echo -e "\n=== Types Module ==="
cat src/types.rs

# Check if there's existing symbol processing
echo -e "\n=== Looking for symbol-related code ==="
rg -n "symbol|Symbol|import|Import|export|Export" src/ --type rust -C 2 | head -100

# Check test structure
echo -e "\n=== Test Structure ==="
fd -t f "test" -e rs | head -20
ls -la tests/ 2>/dev/null || echo "No tests directory yet"

Length of output: 9971

---

🏁 Script executed:

#!/bin/bash
# Check for requirements documentation
echo "=== Looking for Requirements Documentation ==="
fd -t f "requirement" -e md -e txt
cat docs/src/architecture.md | grep -A 10 "4\."

# Check existing integration tests to understand test patterns
echo -e "\n=== Integration Test Pattern ==="
head -50 tests/integration_elf.rs

# Look for any existing classification or symbol processing code
echo -e "\n=== Check for symbol/classification stubs ==="
rg -n "classify|demangle|mangle" src/ --type rust

# Check concept.md for requirements
echo -e "\n=== Concept Documentation ==="
cat concept.md

Length of output: 11778

---

🏁 Script executed:

#!/bin/bash
# Update the issue with enhanced content
gh issue edit 20 \
  --title "Implement Symbol Classification and Import/Export Tagging" \
  --body "## Summary

Implement the classification layer for import/export symbols and section names, converting parsed binary metadata into tagged, scored FoundString objects for analysis.

## Current State

✅ **Container Parsers Implemented**: All three parsers (ELF, PE, Mach-O) successfully extract import/export metadata:
- \`ImportInfo\`: Symbol names, library names, addresses
- \`ExportInfo\`: Symbol names, addresses, ordinals
- Section metadata with full classification

🚧 **Classification Module Empty**: \`src/classification/mod.rs\` contains only a comment. Need to implement symbol processing logic.

## Requirements

### 4.2: Import Name Identification and Tagging
- Convert \`ImportInfo\` objects into \`FoundString\` with \`Tag::Import\`
- Set \`source: StringSource::ImportName\`
- Apply semantic classification (e.g., crypto APIs, network APIs)
- Boost relevance scores for security-relevant imports

### 4.3: Export Name Identification and Tagging  
- Convert \`ExportInfo\` objects into \`FoundString\` with \`Tag::Export\`
- Set \`source: StringSource::ExportName\`
- Demangle Rust symbols using \`rustc-demangle\`
- Identify entry points and special exports

### 4.4: Section Name Processing and Classification
- Treat section names as high-value strings
- Tag with relevant semantic categories
- Use section names to provide context for other strings

## Proposed Solution

### Implementation Structure

Create \`src/classification/symbols.rs\` module with:

\`\`\`rust
pub struct SymbolClassifier {
    crypto_apis: HashSet<String>,
    network_apis: HashSet<String>,
    file_apis: HashSet<String>,
}

impl SymbolClassifier {
    pub fn process_imports(imports: &[ImportInfo]) -> Vec<FoundString>;
    pub fn process_exports(exports: &[ExportInfo]) -> Vec<FoundString>;
    pub fn classify_symbol(name: &str) -> Vec<Tag>;
    pub fn demangle_rust_symbol(name: &str) -> Option<String>;
}
\`\`\`

### Key Features

1. **Import Processing**
   - Convert each \`ImportInfo\` to \`FoundString\`
   - Base score: +20 points (high value)
   - Additional tags based on API name patterns:
     - Crypto: \`CryptEncrypt\`, \`EVP_*\`, \`crypto_*\`
     - Network: \`socket\`, \`connect\`, \`WSA*\`, \`curl_*\`
     - File I/O: \`CreateFile\`, \`open\`, \`fopen\`
   - Preserve library information in metadata

2. **Export Processing**  
   - Convert each \`ExportInfo\` to \`FoundString\`
   - Attempt Rust symbol demangling
   - Identify special exports:
     - Entry points: \`main\`, \`DllMain\`, \`_start\`
     - Mangled Rust functions
   - Base score: +15 points

3. **Symbol Demangling**
   - Use \`rustc-demangle\` crate for Rust symbols
   - Preserve both mangled and demangled forms
   - Add context-specific tags (\`panic\`, \`alloc\`, etc.)

4. **Section Name Processing**
   - Extract section names from \`SectionInfo\`
   - High relevance score (+10)
   - Use for contextualizing other strings in same section

### API Design

\`\`\`rust
// Main entry point for symbol processing
pub fn extract_symbol_strings(container_info: &ContainerInfo) -> Vec<FoundString> {
    let mut strings = Vec::new();
    
    let classifier = SymbolClassifier::new();
    strings.extend(classifier.process_imports(&container_info.imports));
    strings.extend(classifier.process_exports(&container_info.exports));
    strings.extend(extract_section_names(&container_info.sections));
    
    strings
}
\`\`\`

## Test Requirements

Create \`tests/classification_symbols.rs\` with:

1. **Import Classification Tests**
   - Test crypto API detection (\`CryptEncrypt\`, \`AES_encrypt\`)
   - Test network API detection (\`socket\`, \`WSAStartup\`)
   - Verify Tag::Import applied correctly
   - Check library attribution preserved

2. **Export Classification Tests**
   - Test basic export tagging
   - Test entry point detection (\`main\`, \`DllMain\`)
   - Verify Tag::Export applied

3. **Rust Demangling Tests**
   - Test successful demangling of Rust symbols
   - Verify both forms preserved
   - Test context tag detection (panic, main, etc.)
   - Handle non-Rust symbols gracefully

4. **Section Name Tests**
   - Verify section names extracted as strings
   - Check appropriate scoring applied
   - Test all three formats (ELF, PE, Mach-O)

## Success Criteria

- [ ] \`SymbolClassifier\` implemented in \`src/classification/symbols.rs\`
- [ ] All imports converted to \`FoundString\` with \`Tag::Import\`
- [ ] All exports converted to \`FoundString\` with \`Tag::Export\`  
- [ ] Rust symbol demangling working with \`rustc-demangle\`
- [ ] Semantic API classification (crypto, network, file I/O)
- [ ] Section names processed as high-value strings
- [ ] Unit tests achieving >90% coverage
- [ ] Integration tests for all three formats
- [ ] Documentation with examples

## Dependencies

- ✅ Symbol Processing (container parsers extract symbols)
- 📦 \`rustc-demangle\` crate (add to Cargo.toml)

## Technical Notes

- Use lazy_static for compiled API pattern sets
- Preserve all original metadata (addresses, ordinals, library names)
- Scoring should be additive: base score + semantic boosts
- Handle edge cases: empty names, duplicate symbols, stripped binaries
- Consider memory efficiency with large symbol tables

## Example Output

\`\`\`json
{
  \"text\": \"CryptEncrypt\",
  \"encoding\": \"Ascii\",
  \"offset\": 0,
  \"section\": \".idata\",
  \"tags\": [\"import\", \"crypto\"],
  \"score\": 25,
  \"source\": \"ImportName\"
}
\`\`\`

## References

- Architecture docs: \`docs/src/architecture.md\` (Symbol Classification section)
- Classification docs: \`docs/src/classification.md\` (Symbol Classifier implementation)  
- Concept doc: \`concept.md\` (Demangling requirements)
- Related: Container parsing implementation (✅ complete)"

# Add additional labels
gh issue edit 20 --add-label "priority:medium,needs:implementation"

Length of output: 199

---

🏁 Script executed:

#!/bin/bash
# Check available labels in the repository
echo "=== Available Labels ==="
gh label list --limit 100

# Check if the issue was updated successfully
echo -e "\n=== Verify Issue Update ==="
gh issue view 20 --json title,body,labels | jq -r '.title'

Length of output: 1565

---

🏁 Script executed:

#!/bin/bash
# Add the priority:medium label (it exists in the repo)
gh issue edit 20 --add-label "priority:medium"

# Verify the full issue update
echo "=== Full Issue Details ==="
gh issue view 20 --json title,body,labels,assignees,milestone --jq '{title, assignees: [.assignees[].login], labels: [.labels[].name], milestone: .milestone.title}'

# Show a preview of the updated body
echo -e "\n=== Issue Body Preview (first 500 chars) ==="
gh issue view 20 --json body --jq '.body' | head -c 500
echo "..."

Length of output: 858

---

@unclesp1d3r I've successfully enhanced issue #20 with comprehensive details! Here's what was updated:

✅ Changes Made

Title

Before: Import/Export Classification
After: Implement Symbol Classification and Import/Export Tagging

Enhanced Body Content

Added detailed sections covering:

1. Current State Analysis

   • Container parsers already extract all needed metadata (✅ implemented)
   • Classification module is empty and ready for implementation

2. Requirements Breakdown (4.2, 4.3, 4.4)

   • 4.2: Import name identification and tagging with semantic classification
   • 4.3: Export name identification with Rust symbol demangling
   • 4.4: Section name processing as high-value strings

3. Proposed Solution

   • Complete SymbolClassifier API design
   • Implementation structure for src/classification/symbols.rs
   • Key features with specific scoring algorithms
   • Example code for the main entry point

4. Test Requirements

   • Import classification tests (crypto/network API detection)
   • Export classification tests (entry point detection)
   • Rust demangling tests
   • Section name extraction tests

5. Success Criteria

   • Actionable checklist with 9 measurable outcomes
   • Coverage targets (>90%)
   • Documentation requirements

6. Technical Notes

   • Performance considerations (lazy_static for patterns)
   • Edge case handling (empty names, stripped binaries)
   • Memory efficiency guidance

7. References

   • Links to architecture, classification, and concept documentation
   • Connection to completed container parsing work

Metadata Updates

• ✅ Added priority:medium label
• ✅ Retained all existing labels (area:analyzer, type:enhancement, status:backlog, lang:rust, needs:tests)
• ✅ Still assigned to you
• ✅ Milestone v0.1 preserved

The issue now provides complete implementation guidance with clear technical direction, test requirements, and success criteria. The proposed solution leverages the already-implemented container parsers and focuses on the classification layer that converts raw symbol data into tagged, scored FoundString objects.

View the enhanced issue: #20