Introduction

Welcome to the Crow Eye project! We appreciate your interest in contributing. This guide will help you get started with contributing to our Windows forensic investigation tool.

Our Vision: Crow-Eye aims to democratize digital forensics, making it accessible to everyone—from concerned parents to professional investigators and businesses.

System Architecture

graph LR subgraph User_Interface ["🖥️ User Interface"] style User_Interface fill:#1E293B,stroke:#3B82F6,stroke-width:2px MainUI["Main Window
(Crow Eye.py)"] Timeline["Timeline View
(timeline/)"] Factory["Component Factory
(ui/)"] end subgraph Collectors ["📦 Artifact Collectors"] style Collectors fill:#1E293B,stroke:#8B5CF6,stroke-width:2px Prefetch["Prefetch"] Registry["Registry"] Amcache["Amcache"] EventLog["Event Logs"] JumpList["Jump Lists"] end subgraph Data_Layer ["💾 Data Layer"] style Data_Layer fill:#0B1220,stroke:#10B981,stroke-width:2px BaseLoader["Base Loader"] DataMgr["Data Manager"] SQLite[("SQLite DBs")] end subgraph Utils ["🔧 Utilities"] style Utils fill:#334155,stroke:#F59E0B,stroke-width:2px ErrorHandler["Error Handler"] FileUtils["File Utils"] SearchUtils["Search Utils"] end MainUI --> Collectors MainUI --> Timeline MainUI --> Factory Collectors --> Data_Layer Timeline --> Data_Layer MainUI --> Utils Collectors --> Utils Timeline --> Utils Data_Layer --> SQLite classDef uiClass fill:#1E293B,stroke:#3B82F6,color:#E2E8F0 classDef collectorClass fill:#1E293B,stroke:#8B5CF6,color:#E2E8F0 classDef dataClass fill:#0B1220,stroke:#10B981,color:#E2E8F0 classDef utilClass fill:#334155,stroke:#F59E0B,color:#E2E8F0 class MainUI,Timeline,Factory uiClass class Prefetch,Registry,Amcache,EventLog,JumpList collectorClass class BaseLoader,DataMgr,SQLite dataClass class ErrorHandler,FileUtils,SearchUtils utilClass

🖥️ UI Layer

PyQt5-based interface with cyberpunk styling

📦 Collectors

Specialized parsers for Windows forensic artifacts

💾 Data Layer

SQLite-based storage with optimized querying

🔧 Utilities

Reusable helper functions for common tasks

⚙️ Correlation Engine

Advanced forensic analysis system with dual-engine architecture (Time-Based and Identity-Based) for finding temporal and semantic relationships between artifacts

Correlation Engine Components

The Correlation Engine is organized into 7 main directories:

  • engine/ - Core correlation logic with Time-Based and Identity-Based engines
  • feather/ - Data normalization and import from forensic artifacts
  • wings/ - Correlation rule definitions and validation
  • config/ - Configuration management and semantic mappings
  • pipeline/ - Workflow orchestration and automation
  • gui/ - User interface for pipeline management and results visualization
  • integration/ - Bridge between Crow-Eye and Correlation Engine

Contribution Decision Tree

Use this flowchart to quickly determine where your contribution should go and what steps to follow:

flowchart TD Start["🚀 I want to contribute"] --> Type{What type of
contribution?} Type -->|New Artifact Parser| Artifact["📦 Add to Artifacts_Collectors/"] Type -->|UI Enhancement| UI["🖥️ Add to ui/"] Type -->|Bug Fix| Bug["🐛 Find relevant module"] Type -->|Documentation| Docs["📝 Update .md files"] Type -->|Timeline Feature| TL["⏱️ Add to timeline/"] Artifact --> Parser["1️⃣ Create *_claw.py file"] Parser --> DataClass["2️⃣ Define @dataclass structures"] DataClass --> ParseFunc["3️⃣ Implement parse() function"] ParseFunc --> DBFunc["4️⃣ Add save_to_sqlite()"] DBFunc --> IntegrateMain["5️⃣ Integrate with Crow Eye.py"] UI --> Factory["Use ComponentFactory"] Factory --> Style["Follow cyberpunk theme
(styles.py)"] Style --> UITest["Test UI responsiveness"] TL --> TLArch["Review timeline/ARCHITECTURE.md"] TLArch --> TLLayer{Which layer?} TLLayer -->|Data| TLData["timeline/data/"] TLLayer -->|Rendering| TLRender["timeline/rendering/"] TLLayer -->|UI| TLUI["timeline/*.py dialogs"] Bug --> TestCase["1️⃣ Write test case"] TestCase --> FixIssue["2️⃣ Fix the issue"] FixIssue --> VerifyFix["3️⃣ Verify fix works"] Docs --> ReviewDocs["Review existing docs"] ReviewDocs --> UpdateDocs["Update relevant sections"] UpdateDocs --> CheckLinks["Verify all links work"] IntegrateMain --> PR["📤 Create Pull Request"] UITest --> PR TLData --> PR TLRender --> PR TLUI --> PR VerifyFix --> PR CheckLinks --> PR PR --> CodeReview["👀 Code Review"] CodeReview --> Changes{Changes
requested?} Changes -->|Yes| MakeChanges["Make requested changes"] MakeChanges --> CodeReview Changes -->|No| Merge["✅ Merge to main"] style Start fill:#0F172A,stroke:#00FFFF,stroke-width:3px,color:#E2E8F0 style Merge fill:#10B981,stroke:#059669,stroke-width:3px,color:#E2E8F0 style PR fill:#8B5CF6,stroke:#7C3AED,stroke-width:2px,color:#E2E8F0 style Type fill:#1E293B,stroke:#3B82F6,stroke-width:2px,color:#E2E8F0 style CodeReview fill:#F59E0B,stroke:#D97706,stroke-width:2px,color:#0F172A classDef artifactClass fill:#1E293B,stroke:#8B5CF6,color:#E2E8F0 classDef uiClass fill:#1E293B,stroke:#3B82F6,color:#E2E8F0 classDef bugClass fill:#7F1D1D,stroke:#DC2626,color:#E2E8F0 classDef docClass fill:#065F46,stroke:#10B981,color:#E2E8F0 classDef timelineClass fill:#1E293B,stroke:#F59E0B,color:#E2E8F0 class Artifact,Parser,DataClass,ParseFunc,DBFunc,IntegrateMain artifactClass class UI,Factory,Style,UITest uiClass class Bug,TestCase,FixIssue,VerifyFix bugClass class Docs,ReviewDocs,UpdateDocs,CheckLinks docClass class TL,TLArch,TLLayer,TLData,TLRender,TLUI timelineClass

📦 New Artifact Parser

Adding support for a new Windows artifact → Follow the Artifact Parser path

🖥️ UI Enhancement

Improving the user interface → Follow the UI Enhancement path

🐛 Bug Fix

Fixing a bug → Follow the Bug Fix path

📝 Documentation

Improving documentation → Follow the Documentation path

Getting Started

Development Environment Setup

Prerequisites:

  • Python 3.12.4 or higher
  • Git
  • Windows operating system (recommended for testing artifacts)

Setting Up

  1. Fork and Clone 
    git clone https://github.com/Ghassan-elsman/Crow-Eye.git
cd Crow-Eye
  2. Run the Application

    Simply run the main script. The application handles environment setup automatically.

    python "Crow Eye.py"

    Automatic Setup Process:

    • The script checks for a crow_eye_venv virtual environment
    • If missing, it creates one automatically
    • It installs all required dependencies
    • Finally, it restarts itself within the virtual environment

    Note: Run as administrator to ensure access to all system artifacts during live analysis.

Troubleshooting

  • Python Version: Ensure you are using Python 3.12.4+
  • Path Issues: Run from the root directory
  • Permission Errors: Run terminal as Administrator
  • Dependency Conflicts: Delete crow_eye_venv folder and restart

Contribution Guidelines

Types of Contributions

✨ Feature Enhancements

Adding new features or improving existing ones. We welcome new artifact parsers and UI improvements.

🐛 Bug Fixes

Fixing issues in existing functionality. Every bug fix makes Crow Eye more reliable.

📝 Documentation

Improving or adding documentation. Clear documentation is key to our mission.

🧪 Testing

Adding or improving tests to ensure code quality and reliability.

Coding Standards

  • Follow PEP 8 guidelines
  • Use meaningful variable and function names
  • Add docstrings to all functions and classes
  • Keep functions focused on a single responsibility
  • Use type hints where possible

Pull Request Process

  1. Create a branch for your feature (git checkout -b feature/name)
  2. Make changes and test thoroughly
  3. Commit with clear messages (feat: add new parser)
  4. Push to your fork and submit a Pull Request

Pull Request Workflow

flowchart LR Fork[Fork Repository] --> Clone[Clone to Local] Clone --> Branch[Create Feature Branch] Branch --> Code[Write Code] Code --> Test[Test Changes] Test --> TestPass{Tests Pass?} TestPass -->|No| Fix[Fix Issues] Fix --> Test TestPass -->|Yes| Commit[Commit Changes] Commit --> Push[Push to Fork] Push --> PR[Create Pull Request] PR --> Review[Code Review] Review --> ReviewOK{Approved?} ReviewOK -->|Changes Requested| Update[Update Code] Update --> Push ReviewOK -->|Approved| Merge[Merge to Main] Merge --> Done([Complete]) style Fork fill:#3B82F6,stroke:#2563EB,color:#fff style Done fill:#10B981,stroke:#059669,color:#fff style TestPass fill:#F59E0B,stroke:#D97706,color:#fff style ReviewOK fill:#F59E0B,stroke:#D97706,color:#fff style Merge fill:#10B981,stroke:#059669,color:#fff

Commit Message Guidelines

Use the following format:

<type>: <subject>

<body>

Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Adding or modifying tests
  • chore: Build process or auxiliary tool changes

Testing

Manual Testing

When testing your changes, please verify:

  • Test with different Windows versions (7/10/11)
  • Verify artifact parsing with known test files
  • Check UI rendering on different screen sizes
  • Validate database operations and data integrity
  • Test error handling with malformed or corrupted files

Contributing to Correlation Engine

The Correlation Engine is a sophisticated system for finding temporal and semantic relationships between forensic artifacts. Contributing to this component requires understanding of its architecture.

For detailed technical documentation: View Correlation Engine Documentation

Key Areas for Contribution

🔧 Engine Development

Improve Time-Based or Identity-Based correlation engines

  • Optimize correlation algorithms
  • Enhance scoring mechanisms
  • Add new correlation strategies

📦 Feather Parsers

Add support for new forensic artifact types

  • Create new artifact parsers
  • Add column mappings
  • Implement data transformations

🎯 Wing Configurations

Create new correlation rule templates

  • Define correlation rules
  • Set time windows
  • Configure filters

🖥️ GUI Components

Enhance visualization and user interface

  • Improve results visualization
  • Add new timeline features
  • Enhance pipeline management

Correlation Engine Contribution Workflow

Identify Component

Determine which correlation engine component you want to contribute to (Engine, Feather, Wing, GUI)

Review Documentation

Read the correlation engine documentation and understand the architecture

Set Up Development Environment

Clone the repository and set up the correlation engine development environment

Implement Changes

Make your changes following the coding standards and architecture patterns

Test Thoroughly

Test with multiple artifact types and correlation scenarios

Submit Pull Request

Create a PR with clear description of changes and test results

Getting Started with Correlation Engine Development

  1. Understand the Dual-Engine Architecture: Learn about Time-Based and Identity-Based engines
  2. Review the Directory Structure: Familiarize yourself with the 7 main directories
  3. Study Existing Code: Look at existing parsers, wings, and correlation logic
  4. Start Small: Begin with small improvements or bug fixes
  5. Ask Questions: Reach out if you need clarification on architecture or design decisions

Roadmap & Future Development

Planned enhancements for Crow Eye:

  • Enhanced LNK file and Jump list structure parsing
  • Advanced visualization of artifact timelines
  • Reporting functionality for exporting findings
  • Timeline Visualization feature (in progress)
  • Correlation engine to correlate Windows Artifacts
  • Enhanced search dialog with advanced filtering
  • AI integration for analysis assistance

We welcome contributions in these areas, as well as new ideas for improving the project!

Get in Touch

Have questions? Feel free to reach out:

Community Guidelines:

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Maintain a welcoming environment for all contributors