FENDER - Forensic Extraction of Navigational Data & Event Records

FENDER is a powerful tool for extracting GPS location data from vehicle telematics binary files. It supports multiple vehicle manufacturers and provides an easy-to-use interface for forensic investigators and researchers.

Feedback

Your input helps make FENDER better! Please share bugs, feature requests, or suggestions by creating a GitHub Issue. Include the diagnostic details in your test file, as well as your logs/fender.log file.

I would also appreciate any assistance with analyzing QNX systems, as all of my attempts have failed thusfar. If you have experience in this, please contact me and we can work on adding it to FENDER!

Simple Guide

Quick Start

Windows Users

Download the latest release from the releases page.
Double-click FENDER.exe to run the application.
Select your decoder type from the left panel.
Drag and drop your binary file or click to browse.
Click "Process File" to extract GPS data.
Results will be saved as an XLSX file in the same directory.

Python Users

# Install dependencies  
pip install -r requirements.txt

# Run the GUI  
python main.py

# Run in CLI mode  
python main.py --cli

Supported Vehicles

OnStar Gen 10+ - Extracts GPS data from OnStar NAND dumps (.CE0 files)
Toyota TL19 - Extracts GPS data from Toyota infotainment systems (.CE0 files)
Honda Telematics - Extracts GPS data from Honda Android eMMC images (.USER files)
Mercedes-Benz - Extracts GPS data from Mercedes-Benz database files (.db files)
BMW NBT-HDD - Extracts GPS data from BMW NBT-HDD folder structure (folder)
Stellantis - Extracts GPS data from a folder holding Stellantis log files (folder)
Denso - Extracts GPS, speed, and bluetooth data from Denso and Acura Android eMMC images (.001 files)

Features

🚗 Multi-manufacturer support with modular decoder architecture
📍 Extracts latitude, longitude, and timestamps
📊 Exports data to XLSX, JSON, and KML formats for analysis
🖱️ Drag-and-drop file support
💻 Both GUI and command-line interfaces
🔌 Plugin architecture for easy decoder additions

System Requirements

Windows 10/11 (for .exe release)
Python 3.8+ (for source code)
4GB RAM minimum
500MB free disk space

Advanced Guide

Architecture Overview

FENDER uses a modular plugin architecture that allows for easy addition of new decoder types:

FENDER/  
├── main.py                # Main application entry point
├── src/                   # Source code modules
│   ├── core/             # Core components
│   │   └── base_decoder.py    # Abstract base class  
│   ├── gui/              # GUI components  
│   │   └── main_window.py     # Main GUI application
│   ├── cli/              # CLI components
│   │   └── cli_interface.py   # Command-line interface
│   └── utils/            # Utility modules
│       ├── file_operations.py
│       └── system_info.py
├── decoders/             # Decoder plugins directory  
│   ├── __init__.py  
│   ├── onstar_decoder.py  
│   ├── toyota_decoder.py  
│   ├── honda_decoder.py  
│   ├── mercedes_decoder.py  
│   ├── bmw_decoder.py
│   ├── denso_decoder.py    
│   └── stellantis_decoder.py  
└── requirements.txt

Core Components

DecoderRegistry: Auto-discovers and manages available decoders
BaseDecoder: Abstract class defining the decoder interface
VehicleGPSDecoder: Main GUI application using tkinter
GPSEntry: Standard data structure for GPS points

Module Structure

This section provides detailed information about the modular architecture and components:

1. `main.py`

Purpose: Main entry point for the application
Contents:
- Logging setup
- Command line argument parsing
- Application initialization
- Import and execution of GUI or CLI modes

2. `main_window.py`

Purpose: GUI components and user interface
Contents:
- VehicleGPSDecoder class - Main GUI application
- CustomRadiobutton and CustomToggleButton classes - Custom UI widgets
- GUI setup, styling, event handling
- File processing workflow for GUI mode
- Drag-and-drop functionality
- Progress reporting and error handling

3. `cli_interface.py`

Purpose: Command-line interface logic
Contents:
- DecoderRegistry class - Manages available decoders
- run_cli() function - Main CLI workflow
- User interaction for decoder/format selection
- CLI-specific processing and output
- Helper functions for CLI operation

4. `file_operations.py`

Purpose: File handling and export operations
Contents:
- File validation and security functions
- Export format writers (Excel, JSON, KML)
- Secure file operations (temp files, copying, etc.)
- Duplicate entry filtering
- File path sanitization and validation

5. `system_info.py`

Purpose: System information gathering
Contents:
- Hardware and OS information collection
- Decoder integrity verification
- Network connectivity checks
- Permission validation
- Extraction metadata generation

Technical Details

Plugin Architecture

The application automatically discovers decoders at runtime:

Scans the decoders/ directory for *_decoder.py files
Imports modules and finds classes inheriting from BaseDecoder
Registers decoders in the registry
Makes them available in the GUI/CLI

Decoder Specifications

OnStar Decoder

File Format: OnStar NAND dumps (.CE0 files)
Data Location: GPS data stored as text within binary
Extraction Method: Pattern matching for GPS keywords
Key patterns:

gps_tow= - GPS time of week (milliseconds)
gps_week= - GPS week number
lat= - Latitude in hex format
lon= - Longitude in hex format
utc_year=, utc_month=, etc. - UTC timestamp components

Coordinate Format:

Stored as 16-byte hex strings
Decoded as little-endian doubles
Divided by 10,000,000 for decimal degrees

Toyota Decoder

File Format: Toyota TL19 NAND dumps (.CE0 files)
Data Location: Structured binary format with markers
Extraction Method: Binary pattern matching with offsets
Key markers:

loc.position - Base location marker
Various longitude markers (e.g., ong6, ongi5)
Latitude marker: latitud,
Multiple timestamp markers

Data Structure:

Fixed offsets from markers
Timestamps stored as Unix milliseconds
Coordinates as ASCII strings in binary

Honda Decoder

File Format: Honda Android eMMC images (.USER files)
Data Location: SQLite database in Android userdata partition
Extraction Method: Filesystem extraction using pytsk3
Process:

Find userdata partition (GPT or ext4)
Extract filesystem using TSK
Locate crm.db in Honda telematics app data
Query eco_logs table for GPS data

Database Schema:

start_pos_lat, start_pos_lon - Starting coordinates
finish_pos_lat, finish_pos_lon - Ending coordinates
start_pos_time, finish_pos_time - Timestamps

Mercedes-Benz Decoder

File Format: Mercedes-Benz log files and folders
Data Location: Text-based log files in various locations
Extraction Method: Folder-based recursive search and pattern matching
Process:

Recursively scan folders for relevant log files
Parse log files for GPS coordinate patterns
Extract timestamp and location data using regex patterns
Convert coordinate formats to standard decimal degrees

Key Log Patterns:

Navigation system location logs
Telematics service position reports
COMAND system diagnostic logs
Mercedes ME app synchronization data

Data Format:

Coordinates stored in various formats (decimal degrees, DMS)
Timestamps typically in ISO format or local system time
Additional vehicle status information often available in context

Stellantis Decoder

File Format: Log files in persistent storage folders
Data Location: Debug logs, service logs, and navigation logs
Extraction Method: Recursive file search with multi-pattern matching
Key patterns:

SAL_SDARS_FUEL - Navigation destination coordinates
NW_SOS - Emergency call position data
SAL_KONA_NAVI - Navigation system coordinates
GetCurrentLocAddressResponse - Location service responses
JSR179InterfaceImpl - Low-level positioning with speed data
NaviTelematicsDataRequest - Telematics position reports

Extraction Process:

Scan folder structure for log files matching predefined patterns
Parse files using regex patterns to extract GPS coordinates
Extract timestamps from log entries
Validate coordinates and convert to standard format
Sort entries chronologically

Data Format:

Coordinates stored as decimal degrees in text format
Timestamps in various formats (MM/DD/YYYY HH:MM:SS.mmm or YYYY.MM.DD HH:MM:SS,mmm)
Some patterns include additional data like speed and heading

Denso Decoder

File Format: Denso and Acura Android eMMC images (.001, .bin, .CE0 files)
Data Location: JSON-formatted telemetry data embedded in binary files
Extraction Method: Binary pattern matching with JSON parsing
Key patterns:

Navigation.Location - GPS coordinates with accuracy and velocity data
Frame.VehicleSpeed - Vehicle speed in kilometers per hour
Phone.BluetoothConnection - Bluetooth device connection events

Extraction Process:

Scan binary file for JSON telemetry record boundaries
Extract records using regex pattern matching for timestamp and tag fields
Parse JSON-formatted data from binary context
Categorize data by event type (location, speed, bluetooth)
Convert timestamps from ISO format to Unix epoch and UTC
Validate GPS coordinates and filter invalid entries

JSON Record Structure:

timestamp - ISO format timestamp (e.g., 2023-12-15T14:30:25.123Z)
tag - Event type identifier (Navigation.Location, Frame.VehicleSpeed, Phone.BluetoothConnection)
value - Event-specific data payload containing coordinates, speed, or device information

GPS Data Format:

Coordinates stored as decimal degrees in JSON coordinate object
Additional fields: accuracy, speed, bearing, fixTime
Speed data includes kilometersPerHour field
Bluetooth data includes deviceName, deviceId, deviceAddress, and connection state

Output Structure:

The decoder creates separate data categories for comprehensive analysis:

Location data with GPS coordinates and navigation details
Speed data with vehicle velocity measurements
Bluetooth data with device connection logs and states

BMW NBT-HDD Decoder

File Format: BMW NBT-HDD folder structure with SQLite database
Data Location: trails.sqlite database in NBT-HDD/p2/nav/ directory
Extraction Method: Database extraction and binary path decoding
Process:

Search for NBT-HDD folder structure in dropped folder/path
Locate trails.sqlite database at expected path: NBT-HDD/p2/nav/trails.sqlite
Query Trails table for navigation trail records
Decode binary path data to extract GPS coordinates
Convert timestamps from Unix format to UTC

Database Schema:

TrailId - Unique identifier for each navigation trail
BeginTime, EndTime - Unix timestamps for trail start/end
Path - Binary blob containing encoded GPS coordinates and events

Path Binary Format:

Similar to Mercedes-Benz NTG5*2 format
GPS coordinates encoded as 32-bit integers
Formula: decoded_value = encoded_value * 180 / 2147483647
Multiple GPS events per trail with elevation data

Expected Folder Structure:

Users should drag and drop the NBT-HDD folder, which contains:

NBT-HDD/
├── p2/
│   └── nav/
│       └── trails.sqlite
└── [other system folders]

Installation from Source

Windows

# Clone repository  
git clone https://github.com/BitEU/fender.git  
cd fender

# Install dependencies  
pip install -r requirements.txt

# Run application  
python main.py

Linux/macOS

# Clone repository  
git clone https://github.com/BitEU/fender.git  
cd fender

# Install dependencies  
pip install -r requirements.txt

# Install system dependencies for pytsk3  
# Ubuntu/Debian:  
sudo apt-get install libtsk-dev

# macOS:  
brew install sleuthkit

# Install pytsk3  
pip install pytsk3

# Run application  
python main.py

Building Executables

Windows Executable with PyInstaller

# Run build.bat
build.bat

# Output will be in dist/main_.exe

Decoder Development

See the Development Tutorial for detailed instructions on creating new decoders.

Key Methods to Implement

get_name() - Decoder display name
get_supported_extensions() - File extensions list
extract_gps_data() - Main extraction logic
get_xlsx_headers() - Column headers for output
format_entry_for_xlsx() - Format GPS data for Excel

Data Formats

GPSEntry Structure

@dataclass  
class GPSEntry:  
    lat: float              # Latitude in decimal degrees  
    long: float             # Longitude in decimal degrees  
    timestamp: str          # ISO format timestamp  
    extra_data: Dict[str, Any]  # Decoder-specific metadata

XLSX Output Format

Each decoder can define custom columns, but typically includes:

Latitude/Longitude coordinates
Timestamp information
Decoder-specific metadata
Hex representations (for debugging and data verification)

Troubleshooting

Common Issues

"No decoders found" error

Ensure decoders/ directory exists
Check that decoder files end with _decoder.py
Verify Python path includes the application directory

Honda decoder not working

Install pytsk3 library
Ensure you have a valid Android eMMC image
Check that the image contains a userdata partition

Large file processing

Files over 4GB may require 64-bit Python
Ensure sufficient RAM (8GB+ recommended for large files)
Consider using CLI mode for better performance

Windows Defender warnings

Add exception for FENDER.exe
Or build from source yourself

Todo

Add QNX support
Plotting points on an interactive map
Include more data than just timestamps and geolocation
Batch processing
Implement anomoly detection to flag any rows that arent in line eith the rest of the data
Make this program compliant with leading guidelines (ISO 27037? NIST 800-86?)
- NIST 800-86
  - Need more contextual reporting (offsets, file paths, etc)
Improve unit testing
Input sanitization
Memory efficient processing
Make test files publically available

Scoreboard

This is the current tally of vehicles supported by FENDER. This contains the most common vehicles in the United States.

Fully supported vehicles:

Toyota Group
- Toyota
- Lexus
Honda Motor Co
- Honda
- Acura
General Motors
- GMC
- Chevrolet
- Buick
- Cadillac

Vehicles with partial (parse from file/folder, not disk image) support:

Mercedes-Benz
BMW Group
- BMW
- Mini
Stellantis
- Chrystler
- Dodge
- Ram
- Jeep
- Fiat

Currently unsupported:

Nissan Motor Corp
- Nissan
- Infiniti
Hyundai Group
- Hyundai
- Kia
Ford Motor Company
- Ford
- Lincoln
Volkswagen Group
- Volkswagen
- Porsche
- Audi
Volvo
Tesla

Contributing

Fork the repository
Create a feature branch
Add your decoder to decoders/
Include test files for validation. If you are unable to publically supply them due to sensitive content or an ongoing investigation, please contact [email protected].
Submit a pull request

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
decoders		decoders
docs		docs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
FENDER.pyproj		FENDER.pyproj
LICENSE		LICENSE
build.bat		build.bat
main.py		main.py
readme.md		readme.md
requirements.txt		requirements.txt

License

BitEU/FENDER

Folders and files

Latest commit

History

Repository files navigation