ghostcanary 0.1.0

Endpoint security monitor — watches your system and screams when something changes.

ghostcanary

Endpoint security monitor. Watches your system and screams when something changes.

A loud, visible desktop canary. Not an EDR. Not a blocker. Just a watcher that talks.

What It Monitors

• Kernel drivers - new loads, disappearances
• Windows services - new services, state changes
• Processes - new process names, suspicious parent-child relationships, encoded PowerShell, download cradles
• Network connections - new outbound destinations, new listening ports, connection spikes, beaconing detection
• DNS cache - new resolutions, suspicious/DGA-like domains
• Registry autoruns - Run/RunOnce key changes
• Scheduled tasks - new tasks, removed tasks
• File system - new executables in monitored paths, startup folder modifications, System32 changes
• DLLs - unusual load paths, unsigned DLLs in signed processes
• Named pipes - new pipe creation (common C2 channel)
• WMI subscriptions - event subscription creation
• COM objects - hijack detection
• Event logs - gaps, cleared logs

Cross-platform: Windows (full support), Linux and macOS (core monitoring via psutil fallback).

Install

pip install ghostcanary

With desktop UI support (Pillow for mascot images):

pip install ghostcanary[ui]

With all optional dependencies (psutil for deeper process/network monitoring):

pip install ghostcanary[full]

Quick Start

Run the scanner

ghostcanary-scan                    # Continuous scanning (30s interval)
ghostcanary-scan --interval 10      # Faster scanning
ghostcanary-scan --once             # Single scan and exit
ghostcanary-scan --list-logs        # List monitored Windows Event Logs

Run the desktop UI

ghostcanary-ui                      # Floating desktop mascot with speech bubbles
ghostcanary-ui --test               # Show a test bubble and exit

Run the daemon (manages scanner + UI)

ghostcanary-daemon run              # Start both scanner and UI, auto-restart on crash
ghostcanary-daemon install          # Add to Windows startup (requires admin)
ghostcanary-daemon uninstall        # Remove from Windows startup
ghostcanary-daemon status           # Check if running/installed
ghostcanary-daemon stop             # Stop the daemon

How It Works

1. Edge Parser scans system surfaces on a configurable interval
2. Compares current state against a SQLite-backed baseline
3. Emits typed signals with severity levels (INFO, WARN, ALERT, CRITICAL)
4. Canary UI picks up signals and displays speech bubbles on your desktop
5. Notification Center provides filterable history of all signals

No inference. No correlation. No blocking. Just facts.

Configuration

On first run, a config.yaml is created in the package directory with defaults. Key sections:

• scan - interval, parallel workers
• baseline - aging, frequency tracking, anomaly threshold
• network - spike detection, beaconing parameters
• beaconing - trusted processes/destinations, scoring thresholds
• process - suspicious parent/child relationships
• alert - sound, snooze, rate limiting
• ui - color mode, theme

Using as a Library

import ghostcanary

# Check version
print(ghostcanary.__version__)

# Access signal types
print(ghostcanary.SignalTypes.NEW_KERNEL_DRIVER)

# Create a signal
sig = ghostcanary.Signal.create(
    signal_type=ghostcanary.SignalTypes.NEW_KERNEL_DRIVER,
    source_surface="CustomMonitor",
    artifacts={"name": "suspicious.sys"},
    severity=ghostcanary.Severity.CRITICAL,
    category=ghostcanary.Category.KERNEL,
)

# Store in the signals database
db = ghostcanary.get_signals_db()
db.store(sig)

# Query signals
recent = db.get_recent(limit=10)

Signal Flow

System State (drivers, services, processes, network, ...)
    |
    v
Edge Parser (scan surfaces, compare baseline, emit signals)
    |
    v
signals.json (file-based queue) + signals.db (SQLite history)
    |
    v
Canary UI (poll queue, translate signal, show bubble)

Design Principles

1. No inference - only detects changes, never interprets them
2. No correlation - each surface is independent
3. No blocking - observes, never prevents
4. Local only - everything stays on this machine
5. Expendable - raw logs exist elsewhere, these files can be deleted
6. Visible - canary is always on screen, not hidden
7. Loud - every signal gets a bubble
8. Factual - dry tone, no alarm, no "attack" language

License

MIT