Metadata-Version: 2.4
Name: ghostcanary
Version: 0.2.0
Summary: Endpoint security monitor — watches your system and screams when something changes.
Author: Adam Thomas
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/adam-scott-thomas/ghostcanary
Project-URL: Repository, https://github.com/adam-scott-thomas/ghostcanary
Project-URL: Issues, https://github.com/adam-scott-thomas/ghostcanary/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml
Requires-Dist: filelock
Provides-Extra: ui
Requires-Dist: pillow; extra == "ui"
Provides-Extra: full
Requires-Dist: pillow; extra == "full"
Requires-Dist: psutil; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pillow; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install ghostcanary
```

With desktop UI support (Pillow for mascot images):

```bash
pip install ghostcanary[ui]
```

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

```bash
pip install ghostcanary[full]
```

## Quick Start

### Run the scanner

```bash
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

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

### Run the daemon (manages scanner + UI)

```bash
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

```python
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
