NSKeyedArchiver Decoder (nska)

A modern Python tool for decoding NSKeyedArchiver plist files with beautiful colored output and multiple display formats.

Features

• 🎨 Colored output with rich syntax highlighting
• 🌳 Tree view for hierarchical data visualization
• 📄 JSON output with syntax highlighting
• 🚀 Modern CLI with comprehensive argument parsing
• 🔧 Flexible formatting options
• 📦 Easy installation with pip
• 🔄 Dual format support - handles both NSKeyedArchiver and standard plist files
• 🛡️ Robust error handling with fallback options
• 🔄 Improved NSKeyedUnarchiver - built-in implementation with recursion protection
• 🕵️ Cycle detection - prevents infinite loops from circular references
• 🎛️ Debug mode - detailed logging and error diagnostics
• ⚡ Configurable limits - adjustable recursion depth and safety controls

Installation

1. Install the required dependencies:

pip install -r requirements.txt

Or install individually:

pip install NSKeyedUnArchiver rich

Note: This tool includes an improved NSKeyedUnarchiver implementation that handles complex files with circular references and deep nesting. It falls back to the external investorzilla module if needed, but the built-in version is recommended for better reliability.

2. Make the script executable (optional):

chmod +x main.py

Usage

Basic Usage

Decode a plist file and display it as a colored tree:

python main.py file.plist

Output Formats

Display as JSON with syntax highlighting:

python main.py file.plist --format json

Display as tree structure (default):

python main.py file.plist --format tree

Options

• --format, -f: Choose output format (tree or json)
• --no-color: Disable colored output
• --indent: Set JSON indentation level (default: 2)
• --debug: Enable debug output and verbose error messages
• --max-depth: Set maximum recursion depth for NSKeyedArchiver (default: 2000)

Examples

# Basic tree view with colors
python main.py data.plist

# JSON output with custom indentation
python main.py data.plist --format json --indent 4

# Plain output without colors
python main.py data.plist --no-color

# Works with both NSKeyedArchiver and standard plist files
python main.py regular_plist.plist
python main.py nskeyed_archive.plist

# Enable debug mode for troubleshooting
python main.py complex_file.plist --debug

# Increase recursion limit for very deep structures
python main.py deep_nested.plist --max-depth 5000

# Get help
python main.py --help

Sample Output

Tree Format

📄 data.plist
├── 🔹 $version (dict)
│   ├── $archiver: "NSKeyedArchiver"
│   ├── $objects: (list, 15 items)
│   └── $top: (dict)
└── 🔹 rootObject (dict)
    ├── name: "Example"
    ├── count: 42
    └── enabled: True

JSON Format

{
  "$version": {
    "$archiver": "NSKeyedArchiver",
    "$objects": [...],
    "$top": {...}
  },
  "rootObject": {
    "name": "Example",
    "count": 42,
    "enabled": true
  }
}

Error Handling

The tool provides clear error messages for common issues:

• Missing files
• Invalid plist format
• Decoding errors
• Missing dependencies
• Smart fallback: If NSKeyedArchiver decoding fails, automatically tries standard plist format
• Recursion protection: Prevents infinite loops from circular references
• Cycle detection: Identifies and handles circular object references gracefully
• Debug mode: Provides detailed error diagnostics and stack traces

Supported File Types

• NSKeyedArchiver files - Primary target format with improved handling
  • Complex nested structures
  • Circular references and cycles
  • Deep object hierarchies
  • Core Data model files (.mom)
• Standard plist files - Automatic fallback support
• Both binary and XML plist formats are supported

Requirements

• Python 3.7+
• NSKeyedUnArchiver library (installs as investorzilla module)
• Rich library for colored output

Troubleshooting

Import Errors

1. Ensure NSKeyedUnArchiver is properly installed: pip install NSKeyedUnArchiver
2. The package installs as investorzilla but this is handled automatically
3. For standard plist files, the tool will automatically fall back to built-in plist support

Recursion Issues

1. Use the built-in improved NSKeyedUnarchiver (automatically used when available)
2. Increase recursion limit with --max-depth if needed
3. Enable debug mode with --debug to see detailed error information
4. Look for circular reference indicators in the output

Complex Files

1. Enable debug mode: --debug
2. Increase recursion limit: --max-depth 3000
3. Check for circular references in the tree output
4. Use JSON format for easier analysis of structure

Performance

• Large files may take time to process due to safety checks
• Debug mode adds overhead but provides valuable diagnostics
• Circular reference detection prevents infinite loops but adds processing time

Contributing

Feel free to submit issues and enhancement requests!

License

This project is open source. Feel free to use and modify as needed.