Technical Documentation

Key Features

• Comprehensive Artifact Collection: Supports Prefetch, Registry, Event Logs, Amcache, Jump Lists, SRUM, MFT, USN Journal, Recycle Bin.
• Timeline Visualization: Advanced timeline view with OpenGL-accelerated rendering.
• Case Management: Organize investigations into cases with persistent configuration.
• Modular Architecture: Easy to extend with new artifact parsers.

System Architecture & Orchestration

Crow Eye is built on a sophisticated multi-layered architecture that prioritizes forensic integrity and real-time responsiveness. The system orchestrates complex data pipelines while maintaining a seamless investigative workspace.

Engine Selection Guide

Directory Structure

Active Development Notice: The Eye Assistant is currently in continuous active development. Users and developers should expect significant changes, architectural optimizations, and new feature integrations in the upcoming releases.

Core Capabilities

Eye consists of a modern React-based GUI embedded inside the PyQt5 application, interacting asynchronously with a Python backend Context Manager.

• Natural Language Investigation: Query forensic artifacts using conversational AI.
• Multi-Source Data Integration: Unified access to Prefetch, MFT, Registry, Event Logs, and more.
• Living Report Workspace: Real-time collaborative documentation with charts and evidence tracking.
• RAG-Enhanced Analysis: Retrieval-Augmented Generation for artifact-specific forensic knowledge.
• Multi-Backend Support: OpenAI, Anthropic, Gemini, Ollama, and LM Studio.
• Human-in-the-Loop: Critical investigative decisions require investigator validation.

Core Architectural Components

System Architecture Map

The Ghassan Elsman Protocol (GEP)

The GEP is a strict set of forensic integrity boundaries enforced during every investigation step.

Investigation Pipeline

The 7-stage processing flow ensures thorough and verifiable analysis.

1. Intent Interception: Heuristic check for direct commands (e.g., model switching).
2. Forensic Keyword Analysis: Identifying target artifacts (Prefetch, MFT, etc.).
3. RAG Lookup: Contextual retrieval from the forensic knowledge base.
4. Token Balancing: Optimization of the context window for history and RAG prompts.
5. Tool Execution: Direct execution of database queries, regex searches, and intelligence lookups.
6. Forensic Synthesis: Applying the Ghassan Elsman Protocol for strictly evidence-anchored reporting.
7. Completion: Delivering the final payload, interactive action chips, and data viewers to the UI.

Eye Tool Arsenal

Eye is equipped with a suite of functional tools to manipulate data, generate reports, and hunt for intelligence.

Investigative & Data Tools

• query_database: Executes raw SQL SELECT queries directly against forensic SQLite databases with automatic TOON compression.
• search_artifacts: Performs text or regex searches across all available databases.
• get_schema: Retrieves table schema information (columns, types) as a fallback mechanism.
• query_correlation_results: Finds time-based or identity-based correlations using Crow-eye's Correlation Engine.
• list_case_files: Secure navigation of the active case directory to discover artifacts.

Reporting & Visualization (The Living Report)

• report_append_section: Adds markdown narrative and synthesis to the report.
• report_add_data_table: Generates interactive data tables for raw forensic evidence.
• report_add_chart: Creates data visualizations (Bar, Line, Pie) for pattern analysis.
• report_add_timeline: Constructs chronological timeline visualizations.
• report_add_heatmap: Generates intensity heatmaps (e.g., login activity by hour/day).
• report_add_chat_transcript: Documents AI reasoning or investigator dialogues.
• report_add_chain_of_custody: Documents evidence handling procedures.
• report_edit_section / report_delete_section: Modifies existing report blocks.
• export_report: Triggers formal export to HTML, PDF, or Markdown.

Threat Intelligence Tools

• query_threat_intel: Queries external intelligence (VirusTotal, AlienVault) for reputation data.
• query_living_off_the_land_intel: Assesses if binaries/drivers are known dual-use tools (LOLBAS/LOLDrivers).
• internet_search: Performs wide-spectrum research for emerging threats or techniques.

Initial Triage Workflow

Upon starting a new case, Eye autonomously executes a "Master Forensic Triage Report", encompassing:

1. System Identity & Network Discovery
2. Authentication & Login Activity
3. Evidence of Execution (Top 10 Apps)
4. Persistence Mechanisms (Auto-Runs)
5. Anti-Forensics & File Lifecycle
6. User Intent (Search & Commands)
7. Connected Hardware (USB Devices)
8. Final Synthesis & Strategy

This ensures the investigator is immediately presented with a comprehensive, actionable overview of the endpoint's state.

Forensic Knowledge Base (RAG)

The Retrieval-Augmented Generation (RAG) service empowers the Eye Assistant with deep, artifact-specific forensic knowledge. Instead of relying on general LLM training data, Eye consults an internal library of markdown documents.

• Artifact Schemas: Detailed breakdowns of database structures (e.g., global_schema_reference.md).
• Forensic Methodology: Step-by-step investigative workflows and best practices.
• Targeted Knowledge: Specific guides for each artifact (e.g., amcache_knowledge.md, prefetch_knowledge.md, usn_knowledge.md) outlining exactly what each field means and how it can be abused.

Directory Structure

1. Main Application (Crow Eye.py)

The main application serves as the entry point and orchestrator for the entire system.

Responsibilities

• Environment Setup: Creates and manages a virtual environment with required dependencies
• UI Initialization: Sets up the PyQt5-based user interface with cyberpunk styling
• Artifact Collection Coordination: Invokes appropriate artifact collectors
• Data Visualization: Displays collected artifacts in tables and UI components
• Case Management: Handles case creation, loading, and configuration

Key Functions

• setup_virtual_environment(): Creates Python virtual environment
• check_and_install_requirements(): Ensures all packages are installed
• validate_dependencies(): Validates dependency functionality
• is_admin(): Checks for administrator privileges
• load_registry_data_from_db(): Master function for loading registry data

2. Styles System (styles.py)

Defines the cyberpunk-themed visual identity of Crow Eye with neon accents and dark backgrounds.

Features

• Custom color palette with neon cyan (#00FFFF) accents
• Dark theme optimized for long forensic sessions
• Consistent styling across all UI components
• Custom table styles with alternating row colors

3. Component Factory (component_factory.py)

Factory pattern for creating consistent UI elements throughout the application.

Created Components

• Styled tables with custom headers
• Search dialogs with filters
• Progress indicators
• Custom buttons and controls

Common Collector Pattern

All collectors follow this pattern:

1. Locate: Find artifact source (files, registry keys, etc.)
2. Parse: Extract binary data into structured information
3. Store: Save results in SQLite databases
4. Export: Generate JSON output for interoperability

1. Prefetch Parser (Prefetch_claw.py)

Parses Windows Prefetch files (.pf) to extract execution history.

Forensic Value

• Program execution history
• Last execution times (up to 8 timestamps)
• Run count
• Files and directories accessed by the program

Supported Versions

• Windows XP/2003 (Version 17)
• Windows Vista/7 (Version 23)
• Windows 8/8.1/2012 (Version 26)
• Windows 10/11 (Versions 30-31)

2. Registry Parser (Regclaw.py)

Extracts forensic artifacts from live Windows Registry hives.

Artifacts Collected

• USB Devices & Storage
• UserAssist (ROT-13 decoded)
• Shellbags (folder access)
• Recent Documents
• Network Lists
• Run/RunOnce keys
• Installed Programs
• Services
• BAM/DAM (Background Activity Moderator)

3. Offline Registry Parser (offline_RegClaw.py)

Parses offline registry hives without requiring live system access.

Key Features

• Hive Support: SYSTEM, SOFTWARE, SAM, SECURITY, NTUSER.DAT
• Path Independence: No reliance on current system's registry API
• Cross-Analysis: Analyze hives from different Windows versions

4. Amcache Parser (amcacheparser.py)

Parses Amcache.hve to identify application execution history.

Database Tables

• InventoryApplication
• InventoryApplicationFile
• InventoryDriverBinary
• DeviceCensus

5. Event Log Parser (WinLog_Claw.py)

Parses Windows Event Log files (.evtx).

Forensic Value

• User logon/logoff events
• Process creation (Event ID 4688)
• Service installations
• System events

6. Jump Lists & LNK Parser (A_CJL_LNK_Claw.py)

Parses Jump Lists and LNK (shortcut) files.

Forensic Value

• Recently accessed files
• Application usage patterns
• File paths and network shares
• Timestamps of file access

7. SRUM Parser (SRUM_Claw.py)

Parses System Resource Usage Monitor database.

Forensic Value

• Application runtime and resource usage
• Network connectivity data
• Energy usage statistics

8. MFT Parser (MFT_Claw.py)

Parses the Master File Table from NTFS file systems.

Forensic Value

• Complete file system timeline
• File creation, modification, access times
• Deleted file recovery
• File attributes and permissions

9. USN Journal Parser (USN_Claw.py)

Parses the Update Sequence Number Journal.

Forensic Value

• File system change tracking
• File creation, deletion, renaming events
• Detailed change reasons

10. Recycle Bin Parser (recyclebin_claw.py)

Parses Recycle Bin artifacts.

Forensic Value

• Deleted file metadata
• Original file paths
• Deletion timestamps
• File sizes

11. Shimcache Parser (shimcash_claw.py)

Parses the Windows Application Compatibility Cache (Shimcache) to track executable files that have been present on the system.

Forensic Value

• Execution history (even if the file is deleted)
• Full file paths
• Last modification timestamps
• Execution flags and status

Crow-claw: Advanced Collection Engine

Crow-claw is the high-fidelity collection core of Crow-Eye. It is designed to bypass operational system locks and provide deep access to hidden or protected forensic artifacts.

Core Components

• VSS Health Diagnostics: Automated volume consistency checks via vss_health_checker.py.
• Error Classifier: Advanced error handling (error_classifier.py) to distinguish between access denials and corrupted data.
• Multi-Strategy Collection: Dynamically switches between Standard, Shadow, and Raw access depending on the forensic context.

Forensic Image Parsing Engine

The Forensics Image Parsing module provides a robust, extensible architecture designed to analyze and extract artifacts from diverse forensic containers. By leveraging the Strategy Design Pattern and the dissect framework, it abstracts image complexity into a unified filesystem interface.

Core Architectural Components

The Parsing Pipeline

1. Detection: Cascading format checks via can_handle() electing the appropriate strategy.
2. Mounting: Transparent mounting of containers and resolution of split segments.
3. Discovery: Automated partition probing and creation of PartitionInfo metadata.
4. Traversal: Mapping offset addresses to mount specific NTFS/FAT32 volumes.
5. Extraction: Streaming artifact data while preserving forensic MAC timestamps.

Offline Artifact Importer

The Offline Importer subsystem allows investigators to process raw forensic artifacts that have been extracted from target machines or acquired via third-party tools. It provides a robust GUI for batch processing and validation.

Core Capabilities

• Automated Discovery: Scans directories to automatically identify artifact types (Prefetch, EVTX, Registry Hives) using artifact_type_detector.py.
• Batch Processing: Orchestrates multiple offline parsers concurrently using parser_invoker.py.
• Validation & Indexing: Validates file integrity before parsing and builds a comprehensive scan index.
• Standalone GUI: Provides a dedicated interface (offline_importer_gui.py) for managing imports outside of the live collection workflow.

Hybrid Architecture (React + Python)

The timeline bridges a robust Python data-processing backend with a modern, responsive React frontend hosted within a PyQt5 QWebEngineView.

Core Data Orchestration

Optimization Strategies

• Time-Sliced Querying: Prevents UI blocking by sampling and chunking data for different zoom levels.
• Event Aggregation: Condenses raw events into high-level representations (e.g., system sessions) when viewed at macro scales.
• Progressive Loading: Asynchronously fetches data as the investigator pans through the temporal viewport.

Investigation Workflow

1. Initialization: TimelineDialog instantiates the bridge and loads the React build.
2. Temporal Mapping: UI queries getTimeBounds() to map the absolute forensic scope of the case.
3. Contextual Querying: As the analyst zooms, specific swimlanes (e.g., MFT, Network, Execution) request localized time-slices.
4. Correlation: The correlation_engine.py identifies proximity-based relationships between isolated system events.

Intelligence Engine (intelligence_engine.py)

The core logic that orchestrates link gathering and enrichment. It transforms anonymous IDs into human-readable investigative context.

Knowledge Architecture

• Rule Framework: Modular rules located in the rules/ directory define how different artifacts relate to each other.
• Enrichment Database: High-speed IO (io/database.py) for managing the dynamic mapping state and persistent link history.
• Intelligence IO: Handles the import/export of intelligence data for sharing across investigation teams.

Database Architecture

Crow Eye uses SQLite databases for storing parsed artifacts:

• Case Databases: One database per case
• Artifact Tables: Separate tables for each artifact type
• Indexes: Optimized for timestamp and text searches

Key Components

• database_manager.py: Connection and transaction management
• base_loader.py: Base class for data loaders
• registry_loader.py: Registry-specific data loading
• mft_loader.py: MFT data loading with virtual tables
• usn_loader.py: USN Journal data loading
• search_engine.py: Full-text search across artifacts
• index_manager.py: Database index optimization

Search Capabilities

• Full-text search across all artifacts
• Timestamp range filtering
• Regular expression support
• Multi-field queries
• Search history tracking

Component Factory Pattern

The component_factory.py module creates consistent UI elements:

• Styled tables with custom headers
• Search and filter dialogs
• Progress indicators
• Custom buttons and controls

Key Dialogs

• case_dialog.py: Case creation and management
• search_filter_dialog.py: Advanced search interface
• row_detail_dialog.py: Detailed artifact view
• Loading_dialog.py: Custom loading animations

Virtual Tables

For large datasets (MFT, USN), Crow Eye uses virtual tables:

• On-demand data loading
• Smooth scrolling for millions of records
• Memory-efficient rendering
• Pagination controls

General Documentation

Correlation Engine Documentation

The Correlation Engine is the most actively developed subsystem, with over 10,000 lines of documentation: