Methodology

This page explains how CustosEye works: what data it collects, how it processes that data, and what assumptions or limitations you should be aware of.

Purpose and Goals

CustosEye is designed to give you visibility into what's happening on your system without requiring cloud services or sending data anywhere. It monitors processes, network activity, and file integrity, then presents this information in a simple web dashboard so you can understand what's running and what's changed.

What Data CustosEye Uses

CustosEye collects three types of data from your system:

Process information: running processes, their executable paths, file hashes, code signatures, parent processes, and whether they're running as services or with elevated privileges
Network activity: listening ports, active network connections, and which processes are making connections
File integrity data: for files you choose to monitor, CustosEye computes SHA-256 hashes or tracks modification time and size to detect changes

All of this data stays on your machine. Nothing is sent to external servers or cloud services.

How Data is Processed

CustosEye processes data in several stages:

1. Collection

Three monitoring agents run continuously in the background, publishing events to an event bus:

Process monitor: Scans running processes periodically, tracking executable paths, file hashes, code signatures, parent processes, memory usage, command lines, and whether processes are running as services or with elevated privileges
Network scanner: Captures listening ports and active network connections, identifying which processes are making connections
Integrity checker: Compares watched files against their baseline hashes (SHA-256) or metadata (mtime+size) every split second for faster detection

2. Trust Scoring (CSC v2)

Each process is evaluated using a trust scoring engine (CSC v2) that considers multiple signals:

Path context: System directories are trusted, temp/downloads are suspicious
Code signing: Valid signatures boost trust, especially from known publishers
Name heuristics: High entropy names, hex-like strings, misspellings of system processes reduce trust
File characteristics: Very new or tiny binaries outside system dirs are flagged
Network behavior: Listening on ports (especially risky ones) is suspicious
Parent context: Processes launched by script interpreters get penalized
Elevation/service: Elevated processes or services from user directories are highly suspicious
Prevalence: Processes seen frequently on your machine earn trust over time (with time decay)

These signals are combined into a score, which is then mapped to a categorical verdict: trusted, caution, suspicious, malicious, or unknown. The engine also assigns a class (like "system", "service", "dev_tool", "game", "utility") to help categorize processes. The engine produces confidence scores and human-readable reasons for each verdict.

3. Rules Engine

The rules engine (data/rules.json) applies severity levels (Info, Warning, Critical) and contextual reasons to events. Rules are evaluated in order, the first match wins. Rules can match on:

Source type (process, network, integrity)
Process names or executable paths
Listening ports
Remote connections
And more

Rules hot-reload automatically when you edit the file. The engine also deduplicates events within a short window to reduce noise while preserving important state changes.

4. Event Processing and Storage

The dashboard subscribes to the event bus and processes events in a background thread. Events get:

Tagged with severity levels by the rules engine
Scored by the CSC trust engine (for process events)
Deduplicated to reduce noise
Stored in a ring buffer (oldest events drop when full)

For file integrity events, the dashboard computes diffs when changes are detected. It uses chunk-based hashing to find what changed, extracts text from various file types (text files, Office documents, PDFs), and performs character/word/line-level diffs. Baseline storage optionally stores full file snapshots, auto-pruning to stay under size limits.

5. Presentation

Processed events are displayed in the web dashboard (accessible at http://127.0.0.1:8765/ with authentication required). The dashboard includes:

Live Events tab: Real-time stream with filters by level (Info, Warning, Critical), search by process name or path, pause/resume, and export to CSV, JSON, JSONL, or XLSX
Process Tree tab: Hierarchical view of all running processes showing parent-child relationships, trust verdicts, and process classes. Search and expand/collapse nodes
Integrity tab: Manage files you want to monitor, add files with SHA-256 or mtime+size rules, view diffs when changes are detected
About tab: Version information, build details, buffer size, and runtime stats

Architecture Diagram: 100%

Use mouse wheel to zoom, click and drag to pan. Shows data flow: Collection → Trust Scoring → Rules Engine → Event Processing → Dashboard

Assumptions and Limitations

CustosEye makes several assumptions and has known limitations:

Local-only operation: CustosEye doesn't use threat intelligence feeds or cloud-based reputation services. Trust scores are based entirely on local signals and your system's history.
Heuristic-based scoring: The trust scoring engine uses heuristics and local prevalence, not behavioral analysis or machine learning. It's designed to be fast and explainable, but may miss sophisticated threats that don't match known patterns.
No real-time blocking: CustosEye is a monitoring tool, not an active security product. It reports what it sees but doesn't block or quarantine processes.
Windows focus: Currently designed for Windows 10 or 11. Process and network monitoring uses Windows-specific APIs and may not work on other platforms.
File integrity modes: The "mtime+size" mode is faster but less secure than SHA-256 hashing. It might miss changes that don't affect file size or modification time.
Prevalence learning: The trust engine learns from what it sees on your machine, but this means it may be less accurate on a fresh system or when new software is first installed.

Privacy and Data Handling

All data collected by CustosEye stays on your machine. No information is sent to external servers. The dashboard runs locally on your computer, and all processing happens in memory or in local files. For more details on privacy and data handling, see our Privacy Policy.