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 vendor-neutral, tool-agnostic standard of 10 principles defining how any AI should be used in digital forensics — not a Crow-Eye feature. Eye is its reference implementation.

GEP vs. the Eye's Operating Rules. The GEP is the standard — what must be upheld. The Eye's Operating Rules are its system-prompt instructions — how it gets answers; each is tagged [Operating · GEP-k] (it upholds principle k) or [Operating] (pure UX/tooling). The rules implement the GEP; they are not the GEP. Read the standard and the full distinction on the GEP page (GEP vs. Operating Rules).

• GEP-1 Evidence Primacy — conclusions only from examined artifacts.
• GEP-2 Traceability — every fact links to a specific source record.
• GEP-3 Specificity & Chronology — exact UTC timestamps, ordered.
• GEP-4 Cross-Corroboration — multiple sources; agreement & conflict reported.
• GEP-5 Premise Verification — human claims are tested, not deferred to.
• GEP-6 Completeness — no silent truncation or omission of evidence; coverage is disclosed (consulted vs. available sources, sample vs. full) and graded per answer (see Result Cache & Coverage).
• GEP-7 Integrity & Non-Repudiation — evidence unmodified; tamper-evident record.
• GEP-8 Transparency & Explainability — reasoning, tools, and data are auditable.
• GEP-9 Human Authority — the investigator decides; actions are attributable.
• GEP-10 Defensibility — objective output structured for independent review.

Context Integrity & Chain of Custody — how the Eye operates

These are Eye's operating mechanisms — the in-product steps that uphold the GEP (especially GEP-6, GEP-7, and GEP-8) during every investigation step.

Protocol Compliance Panel & Live Dashboard

The Eye ships a live Protocol Compliance dashboard so an investigator or reviewer can confirm — per case and per answer — that the Eye actually followed the Ghassan Elsman Protocol. It is read directly from EYE_Logs/ and the live ContextManager state (no separate bookkeeping to drift).

What the panel surfaces

• GEP Compliance dashboard: the forensic-integrity operating rules and live Eye-process rows (Conversation Memory, Recall, Coverage, Result Cache, Semantic Search, Evidence Seal Hash Chain) — each tagged with the GEP principle(s) it upholds.
• GEP Protocol — 10 Principles: a live status for every GEP-1…GEP-10 with an honest basis — verified (rolled up from genuinely-checked mechanisms), structural (always-on guarantee), config (reflects reasoning_config; N-A when a setting is disabled, never a bare PASS), or per-answer.
• Per-Answer GEP Compliance: every answer is graded against all 10 GEP principles (marked N-A where a principle doesn't apply to that turn) and persisted to eye_gep_turns.jsonl.
• Evidence Seals (with a hash-chain VERIFIED / BROKEN banner), Chain-of-Custody Events, Execution Steps, the EYE ↔ LLM Conversation, the Activity Window, and the reasoning trace (why each sub-question / conclusion).

Bridge API (for integrators)

The React panel reads everything through QWebChannel bridge getters you can call directly: get_gep_compliance_status, get_gep_turns, get_payload_seals, get_truncation_events, get_step_history, get_dialogue_history, get_activity_audit, and get_reasoning_turns — each returns a JSON envelope { success, data, error }.

Evidence Sealing, Hash Chains & Self-Healing Guardrail

Traceability to source records means the Eye must never silently truncate what the model sees and must be able to prove exactly what it saw. Three mechanisms enforce this (they uphold GEP-6 Completeness and GEP-7 Integrity & Non-Repudiation — see Compliance).

EvidenceSeal — proving what the model saw

Every payload sent to the model is sealed to eye_payload_seal.jsonl with the SHA-256 of the exact bytes, token count, model + context limit, a truncated flag, the evidence provenance (database:table:rowid, source path, and computed MFT offset = record × 1024), and a tamper-evident prev_seal_hash → seal_hash hash chain. The verify_chain() method re-walks the log and re-computes every link, so altering or removing any record is detectable — the dashboard reports VERIFIED or BROKEN.

TruncationAuditor — the chain-of-custody log

An append-only truncation_audit.log with its own hash chain (and verify_chain()) records every context decision: PRESERVED / SUMMARIZED / TRUNCATED / PINNED / UNPINNED / REFUSED_OVERFLOW / SEAL_FAILED.

Self-healing context guardrail (guarded_generate)

The single choke point for every model call. The usable window is max_ctx − reserve where reserve = min(max(512, 10%·ctx), ctx/2). If a payload would overflow, the Eye self-heals on a per-call copy (the persistent on-disk history is never altered): it summarizes, then slides the oldest non-evidence context — never touching pinned / preserve_evidence / tool-result messages. If the irreducible evidence core still won't fit, it fails hard and refuses rather than drop evidence, handing off to analyze_large_dataset (map-reduce over the whole artifact).

The EYE_Logs Forensic Record (per case)

Every case directory carries an EYE_Logs/ folder — the Eye's complete, machine-readable, independently-reviewable record. A developer can inspect any of:

• eye_payload_seal.jsonl — per-payload SHA-256 seals (hash-chained).
• truncation_audit.log — append-only chain-of-custody events (hash-chained).
• audit_trail.json — machine-readable export of the audit events.
• eye_gep_turns.jsonl — per-answer GEP evaluation (all 10 principles).
• eye_coverage_log.jsonl — per-answer coverage (consulted vs. available, sample vs. full).
• eye_step_log.jsonl — per-step execution timeline.
• eye_dialogue_log.jsonl — full Eye ↔ LLM conversation transcript.
• eye_reasoning_log.jsonl — why each sub-question / why each conclusion + evidence.
• eye_conversation_history.json — persistent chat history (never trimmed by self-heal).
• eye_conversation_archive.jsonl — turns evicted from the window, kept for long-term recall.
• eye_result_cache.jsonl — cached query results for reproducible reuse.
• eye_evidence_index/<model>.jsonl — the per-case semantic evidence index.

Investigation Pipeline

Every question flows through a verifiable, evidence-anchored pipeline. Multi-part questions are decomposed so each part is driven to completion, and the agentic loop keeps gathering evidence until it can answer.

1. Intent Interception: Heuristic check for direct commands (e.g., model switching) and the automatic case-open triage.
2. Forensic Keyword Analysis: Detecting target artifacts (Prefetch, MFT, Amcache, Registry, SRUM, ShimCache, Event Logs).
3. RAG Lookup: Ranked retrieval from the forensic knowledge base (lexical BM25 or semantic embeddings) + relevant earlier conversation.
4. Planning & Question Decomposition: The model splits a multi-part question into a sub-question checklist and turns asserted claims into verify: premises.
5. Per-Sub-Question Context: Each sub-question gets its own targeted knowledge and related evidence — matching Living Report data, pinned evidence, prior findings, conversation recall, and semantic row candidates.
6. Token Balancing (Self-Healing): guarded_generate fits the payload to the model's window — summarize, then slide — never dropping protected evidence; refuses rather than truncate the irreducible core.
7. Agentic Tool Loop: Iterative SQL/search/intelligence tool calls with cycle detection, "keep-going" nudges, and a cross-iteration evidence ledger.
8. Forensic Synthesis (Dual Output): Applying the Ghassan Elsman Protocol to produce both a chat answer and a structured Living Report block.
9. Completion & Coverage: Final payload, action chips, and data viewers to the UI, plus a coverage note (which databases were consulted vs. skipped, and whether any result was a sample) for the human reviewer.

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. Identical queries are served from a per-case result cache (read-only DBs are static).
• analyze_large_dataset: Map-reduce analysis over an entire oversized artifact — every row covered exactly once, each chunk sealed — instead of sampling.
• search_artifacts: Performs text or regex searches across all available databases.
• semantic_search_artifacts: Embedding-based discovery over forensic rows for fuzzy/conceptual questions; returns candidate rows with database:table:rowid provenance to confirm with exact SQL (SQL stays authoritative). Available when an embedding server is configured.
• get_schema: Retrieves table schema information (columns, types) as a fallback mechanism.
• query_correlation_results: Finds time-based or identity-based correlations from the Crow-eye Correlation Engine's results database.
• 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.

Correlation Authoring (GEP-gated)

• correlation_create_wing / correlation_edit_wing: Author or edit Correlation Engine "Wings" (rule templates) — every write requires a stated reason and at least one evidence link, and is stamped with authorship.
• correlation_create_semantic_mapping / correlation_edit_semantic_mapping: Define or edit identity/semantic field mappings. Eye may only edit items it authored.

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.

Ranked retrieval: knowledge is chunked header-aware and ranked by a dependency-free BM25 lexical ranker, or by vector embeddings when an embedding server is configured. After a question is decomposed, each sub-question pulls its own targeted knowledge (sub-question-aware retrieval).

Conversation Memory & Context

Eye keeps the investigation grounded across a long session while staying within the model's context window — and never loses committed evidence.

• Two-stage memory policy: when the window fills, older non-evidence turns are first folded into a rolling summarization buffer, then the sliding window drops the oldest as a last resort. Pinned, evidence-flagged, and tool-result messages are always protected.
• Conversation-recall RAG: turns that age out are archived per-case and retrieved on demand, so a specific earlier detail can still be recalled later — nothing is truly lost when the window fills.
• Living Report evidence in context: the actual data committed to the report (table rows, references, chain-of-custody, timelines) is injected so the model reasons over what's already known. The generic case-open triage sweep is excluded to keep context relevant.
• Per-sub-question knowledge + evidence: each sub-question receives its own targeted knowledge and related evidence (report/pinned data, prior findings, conversation recall, semantic candidates).

The Narrative Map — Persistent Working Memory

The model is stateless, so Eye keeps a per-case Narrative Map: a living claim hierarchy in its own window (mirroring the Compliance window) that is read into every prompt — so the map literally is the Eye's memory. Every card shows the claim being proven, never the raw question: the messy/typo-ridden prompt is distilled into a clean claim and kept only as meta.created_from provenance.

• A four-level claim hierarchy (claims, not questions) that rolls up: Verdict (the user's goal as a claim) ← Main narrative (a sub-question the Eye sets out to prove) ← Sub-narrative (a specific behavior established, e.g. “wrote a Run registry key”) ← Evidence (the tool output that proves the behavior) — trace any verdict back to the artifact rows beneath it.
• It is the memory (bidirectional): injected each turn as a case-overview block plus a per-sub-question slice (investigator notes verbatim). Your edits and notes feed Eye's next answer; Eye's findings push a narrative_map_updated signal so an open map window live-refreshes and pulses the card that changed.
• Sealed & GEP-governed: every change is validated against the write-rules (Reason-Required, Evidence-Link, Eye-Stamped) and appended to a hash-chained audit (narrative_map_audit.jsonl, the EvidenceSeal pattern). A narrative is never “proven” without evidence, and a proven one that loses its last evidence auto-converts to negative — Eye never fabricates a finding.
• An investigation surface: drag cards on a 2-D canvas with an auto-arranged tree; double-click for detail; right-click → Dive deeper to send Eye after more evidence; open any evidence node to load the real source artifact rows. Only the investigator may create 0-evidence needs / absolute narratives.

narrative_map_service.py · NarrativeMap.tsx · bridge getNarrativeMap / commitMapEdit.

The Narrative Map — Under the Hood

How the Narrative Map enforces traceability to source records and produces an auditable, tamper-evident chain: a strict data model, an honesty invariant enforced in code, a single audited mutation path, and a hash-chained chain of custody. (Source: narrative_map_service.py.)

1. The data model

A strict four-level claim hierarchy persisted to <case>/EYE_Logs/narrative_map.json and read fresh every turn by both the map UI and the Eye's prompt. Every node is a claim being proven, never the question that prompted it (the question survives only as meta.created_from):

• Verdict — the user's goal expressed as a single goal-claim (one per case); carries its own lifecycle state (below).
• Main narrative — a decomposed sub-question rendered as a claim the Eye sets out to prove (the reasoning-trace conclusion, or a deterministic _claimify(q) fallback); carries a state.
• Sub-narrative — a specific behavior that establishes the main claim (e.g. “wrote a Run registry key for persistence”); carries a state.
• Evidence — an artifact-backed fact that proves a behavior; lives inside a narrative, or floats free until attached.

Main claims roll up from their behaviors (a main is proven when any behavior is proven); the verdict rolls up from its main claims. If a sub-question yields no behavior breakdown, its main claim takes the evidence directly (a graceful three-level degrade) — still titled as a claim, never the raw question.

2. Narrative states

The Verdict carries a separate lifecycle state (VERDICT_STATES) that tracks the goal-claim as a whole, distinct from the per-narrative states above:

3. Honest by construction

• An Eye narrative may be open with no evidence (investigating), but it can never be proven with zero evidence.
• A proven Eye narrative that loses its last evidence auto-converts to negative — unless it is upheld by at least one proven / absolute child (a main narrative may be proven by its sub-narratives, so it stays traceable to origin).
• Creating an Eye narrative with no evidence is rejected; only the investigator may author 0-evidence needs / absolute narratives.

4. One audited mutation path — the GEP write-rules

Every change — by the Eye or the investigator — flows through a single commit() choke point: validate GEP → stamp authorship → apply → persist → seal. Three write-rules are enforced:

• R9 — Reason-Required (hard): a reasonless mutation is refused and the graph is not touched.
• R10 — Evidence-Link (soft): a narrative needs ≥ 1 evidence ref; the only sanctioned exemption is an investigator absolute / needs — otherwise it is logged partially_satisfied.
• R11 — Eye-Stamped: every Eye write carries an authorship stamp.

Thirteen action types are audited: CREATE, EDIT, STATE_CHANGE, ATTACH, DETACH, MAKE_ABSOLUTE, MAKE_BASE, MARK_NEGATIVE, NOTE, LINK, UNLINK, DELETE, MOVE.

5. How it becomes the Eye's memory

Because the JSON is re-read each turn, any investigator edit or note is automatically in the Eye's next prompt, injected in two tiers:

• Tier A — overview_block(): a compact ## Case Memory block (once per turn) — the verdict plus one line per narrative ([STATE] title — hint · N evidence · 📝note), sorted proven → open → absolute → needs → negative.
• Tier B — relevant_slice(): for each sub-question, expands only the narratives whose keywords overlap — including evidence bullets and investigator notes verbatim, so human guidance actually steers the model.
• Live & bidirectional: an Eye edit emits narrative_map_updated, so an open map window refreshes and pulses the card that changed.

6. Hash-chained audit (chain of custody)

Every commit appends one record to <case>/EYE_Logs/narrative_map_audit.jsonl with the same non-repudiation property as the Evidence Seal:

• Record: seq, ts, action, actor, kind, target, reason, evidence[], gep{r9,r10,r11}, gep_rules_applied, payload_sha256, metadata_sha256, prevHash, hash.
• Chain: hash = SHA-256(prevHash + payload_sha256 + metadata_sha256). The sequence and previous-hash advance only on a successful append — so any tampering breaks the chain on the very next record.

Semantic Retrieval & Embeddings

An optional embedding layer (e.g. nomic-embed-text via a local server) augments retrieval. It is strictly additive — when no embedding server is present, Eye falls back to the always-available BM25 ranker, so cloud and CLI deployments are unaffected.

• Knowledge-base embeddings: vector search over the forensic knowledge base, with embeddings cached on disk so they are not recomputed each launch.
• Evidence semantic index: a per-case index over a curated subset of forensic rows enables semantic_search_artifacts — meaning-based discovery of candidate rows for fuzzy questions ("remote access tools", "download cradle").
• SQL stays authoritative: semantic hits are approximate and never complete. The model confirms every candidate with exact SQL, and uses SQL for any count, enumeration, or timeline — preserving completeness traceable to source records.

Result Cache & Coverage

• Result cache: because case databases are read-only and static, an identical SQL query is reused from a per-case cache instead of being re-run — saving time and tokens, and surfacing "reused prior result".
• Coverage signals: every answer records which databases were actually consulted versus which exist in the case, and whether any result was a sample rather than the full set. This is surfaced for the human reviewer — Eye makes gaps visible rather than silently claiming completeness, because sensitive evidence is always reviewed by a real investigator.

Directory Structure

Configuration Reference (eye_config.json)

Eye's behavior is driven by eye_config.json, validated against eye_config_schema.json and editable from the in-app Settings dialog. The sections a developer tunes:

context_window

• max_total_tokens — the model's usable window (auto-resolved for known cloud models; probed for local servers; this is the fallback).
• token_budget — per-component budgets (conversation_history, system_prompt, tool_results, rag_context, conversation_recall); scaled to the window unless pinned.
• evidence_preservation.confidence_threshold, store_full_payload, max_tool_output_chars.

reasoning

• Decomposition + premise verification: enable_decomposition, max_sub_questions, enable_premise_verification, enable_reasoning_trace, enable_question_memory.
• Generation tuning: answer_temperature, planning_temperature, max_output_tokens, model_retry_max_attempts.
• Retrieval: rag_top_k, rag_min_score, rag_semantic_min_score, rag_subquestion_aware.
• Conversation memory: history_window_turns, enable_summary_buffer, enable_conversation_recall, conversation_recall_top_k.
• Large data: enable_auto_map_reduce, auto_map_reduce_row_threshold, search_max_rows.

embedding (optional)

• enabled — turn on embedding-backed semantic retrieval (off ⇒ the always-available BM25 lexical ranker is used, so Cloud/CLI deployments are unaffected).
• model (default nomic-embed-text), endpoint (Ollama API), timeout.
• index_evidence — build the per-case semantic index that powers semantic_search_artifacts.

What it shows

A vertical timeline of activities, each written as a sentence and tagged so a non-technical reader understands it instantly:

• Who — every activity is attributed to User, Application, or System, or left Unattributed when the evidence does not name an actor. UBA never guesses; the signed-in user is shown as a labelled association, not as proof of who acted.
• What — program launches and runs, files created / edited / renamed / copied / deleted (with full rename name-history chains), folder and document access, USB devices, network activity, sign-ins and sign-outs, account administration, persistence (auto-start programs and services), and more.
• How sure — a severity badge (routine → critical) and a confidence tier (corroborated by an event log, disk-artifact only, presence-only, or inferred), plus an honest caveat when an artifact can also be produced by software rather than the person.
• Proof — every activity links to the exact source records (database, table, row) that justify it. Click for an inline proof summary; double-click to open the full evidence, down to the raw artifact rows.

How it works

A behavior rule engine reads the parsed artifact databases (UserAssist, BAM, Prefetch, ShimCache, AmCache, ShellBags, LNK / Jump Lists, USN Journal, $MFT, Recycle Bin, SRUM, Registry, and the Windows Event Logs) and applies a declarative rule set that correlates on-disk artifacts with event-log entries within strict time windows — for example, tying a UserAssist GUI launch to a Security 4688 process-creation event within a few seconds. Results are written to a derived, indexed store and served to the UBA window over the same QWebChannel bridge the Eye and Timeline windows use. All source databases are opened strictly read-only — the original evidence is never modified.

Honest by design — the Coverage panel

Because Crow-Eye targets any default Windows install, UBA is explicit about what it can and cannot see. A built-in “What we can see” panel lists, for every detection: how it is detected and which artifacts it uses, whether it is fully working, limited (the corroborating Windows log is not enabled, so it runs from disk artifacts at lower certainty), unavailable, or intentionally out of scope (needs optional telemetry such as Sysmon). Absence of a signal is reported as absence of the underlying data — never as a false “nothing happened.”

Using it

Open the case, then launch User Behavior from the toolbar (Ctrl+Shift+B). Filter by user, application, time range, behavior class, or severity; switch between the Activity Story timeline and an Activity Map (hour-of-day heatmap); and open the Coverage view to see exactly how each detection is derived. If a case has no parsed data yet, UBA tells you to parse the computer's artifacts first.

See the case, don't just read it

• An investigation surface — an interactive 2-D canvas with an auto-arranged tree: drag cards, double-click for detail, open any evidence node to load the real source artifact rows, or send the Eye after more proof with Dive deeper.
• It is the Eye's living memory — the map is read into every prompt and updates live as findings land, so what you see always reflects the current state of the investigation.
• Traceable and tamper-evident — every change is governed by write-rules (Reason-Required, Evidence-Link, Eye-Stamped) and appended to a hash-chained audit. A narrative is never marked proven without evidence, and a proven one that loses its last evidence auto-reverts — the Eye never fabricates a finding.

Deep dive: see Narrative Map — Persistent Working Memory and Narrative Map — Under the Hood in the Eye AI section.

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.

Note — the scan feeds the parser for you. Scanning a source is read-only, but every artifact it finds is identified by type and written into the case's scan index as it goes. Parse Artifacts then opens with that discovered set already listed and grouped by category, so you never locate or add files by hand — you choose what to parse (or take everything with Select All) and Crow-Eye parses the found artifacts into the case database.

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: