GhostWatch: Making the Ghost in Your Machine Visible — with Local AI

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 4, Theme: Ghost in the Machine.

---

What I Built

GhostWatch is an open-source, local-first AI investigation tool that helps you understand unusual computer activity through a clear timeline, evidence-backed findings, and plain-language explanations — without sending a single byte to a cloud API.

Your computer is constantly doing things in the background: processes starting, log entries being written, system events firing. Most of it is normal. Some of it isn't. But raw logs and process lists are unreadable noise for most people.

GhostWatch turns that noise into a transparent investigation report: what happened, what looks unusual, what the evidence supports, and what remains unknown.

praveen-pravi6B / ghostwatch

Local-first AI investigation tool for unusual computer activity. Hacktoberfest 2026.

GhostWatch

Local-first AI investigation tool for unusual computer activity.

GhostWatch collects process snapshots and OS log events, applies deterministic rules to identify interesting sequences, then asks a locally-running open-weight model to explain what the evidence shows — without sending a single byte to a cloud API.

Hacktoberfest 2026 — Ghost in the Machine challenge entry

---

What it does

1. Collects process snapshots (via psutil) and OS log events (journalctl on Linux, log show on macOS).
2. Normalises everything into a shared event schema and stores it in a local SQLite database.
3. Applies rules deterministically: temp-directory processes, interpreter download patterns, hidden process names, high-severity log entries.
4. Redacts sensitive fields (tokens, passwords, API keys) before any AI inference.
5. Asks a local Ollama model to explain the evidence, express uncertainty, and suggest manual follow-up steps.
6. Displays deterministic findings and AI explanations separately — facts stay facts.

GhostWatch is a lightweight investigator, not…

View on GitHub

---

The Theme Connection

The ghost in the machine is a perfect metaphor for what GhostWatch does. Your computer runs dozens of background processes you never see: processes launched from temporary directories, interpreters making network connections, privilege escalations happening in /tmp. This activity is the literal ghost in the machine — invisible, difficult to interpret, and easy to miss.

GhostWatch makes it visible. And it keeps the analysis on your own machine.

---

Demo

Activity timeline — real macOS process data

28 new processes observed since the last snapshot. The incremental collector only shows what changed, not the whole system every time.

AI investigation — qwen2.5:1.5b running locally

The AI correctly identifies gh as GitHub CLI, wdk as Automox remote management, and mdmdmclient as macOS MDM — all from local inference with no internet connection.

---

How It Works

The pipeline is deliberately simple and auditable:

1. Collect native OS telemetry via psutil and journalctl / log show
2. Normalize everything into a shared Pydantic v2 event schema
3. Store locally in SQLite with deduplication
4. Apply deterministic rules — no AI involved yet
5. Redact credentials and tokens before building the prompt
6. Ask the local model to explain the evidence
7. Display rule findings and AI output in separate UI sections

Deterministic rules come first. Four rules in the MVP:

Rule	What it flags
PROC_TEMP_DIR	Process launched from /tmp, /var/tmp, or Downloads
PROC_HIDDEN_NAME	Process name starts with a dot
INTERP_NETWORK_CMDLINE	Python/bash/ruby with network URLs in command line
HIGH_SEVERITY_LOG	Log entries already rated high by the OS

The AI explains findings in plain language — it cannot override severity or declare the system compromised. That separation stays enforced in the UI.

---

Stack

Layer	Technology
Backend	Python 3.11 + FastAPI
Validation	Pydantic v2
Storage	SQLite via aiosqlite
Process data	psutil
Linux logs	journalctl --output=json
macOS logs	log show --style=json
Local AI	Ollama with qwen2.5:1.5b
Dashboard	Vue 3 + Vite

---

Why Local Open-Weight AI

System logs contain sensitive information: process names, command-line arguments, usernames, file paths, error messages. Sending this to a hosted AI service means your logs leave your machine, a third-party retains them, and you have no control over what happens next.

With an open-weight model running in Ollama, none of that happens. The model runs at 127.0.0.1. The API is bound to localhost. GhostWatch validates the configured URL at startup and refuses to connect to anything that is not a local address:

def __init__(self, base_url: str, model: str, timeout: float = 120.0) -> None:
    if not base_url.startswith(("http://127.0.0.1", "http://localhost")):
        raise ValueError(
            f"AI base_url must be a localhost address, got: {base_url!r}. "
            "GhostWatch never connects to remote AI endpoints."
        )

This is not a config flag. It is enforced in code. You can read it. You can fork it.

This is what open-source AI makes possible: you can inspect the guarantee, not just trust a privacy policy.

---

Redaction Before Inference

Even with a local model, log content can contain credentials — tokens, passwords, API keys embedded in command-line arguments. GhostWatch redacts before building the prompt:

_SECRET_PATTERNS = [
    re.compile(r"(?i)(password|passwd|secret|token|api[_-]?key)\s*[=:]\s*\S+"),
    re.compile(r"Bearer\s+[A-Za-z0-9\-._~+/]+=*"),
    re.compile(r"sk-[A-Za-z0-9]{20,}"),
]

Dict keys are also checked by name. An api_key field gets its value replaced regardless of what the value looks like. The original events in SQLite are never modified; redaction happens on a copy immediately before the AI request is built.

---

Running It

git clone https://github.com/praveen-pravi6B/ghostwatch
cd ghostwatch
bash scripts/setup_dev.sh

# Sample mode — no privileges required
GHOSTWATCH_SAMPLE_MODE=true .venv/bin/ghostwatch

# In a second terminal
cd frontend && npm run dev
# Open http://localhost:5173

For AI explanations:

ollama pull qwen2.5:1.5b
GHOSTWATCH_MODEL=qwen2.5:1.5b GHOSTWATCH_SAMPLE_MODE=true .venv/bin/ghostwatch

Live mode on real OS telemetry:

GHOSTWATCH_MODEL=qwen2.5:1.5b .venv/bin/ghostwatch

---

Build Session

Here is the full Claude Code session where GhostWatch was built — from an empty directory to a working MVP in two days:

Building GhostWatch: Local-First AI Security Investigation Tool from Scratch

You

@GhostWatch_Planner.md — build this from scratch. Today is October 29, Hacktoberfest 2026 Ghost in the Machine challenge, deadline October 31.

Agent

No ghostwatch directory exists yet — starting from scratch. Building Day 1 foundation and Day 2 collection in one pass.

▸ create_project_structure mkdir -p ghostwatch/{ghostwatch/{api,core,collectors,platforms/{linux,macos},...

Input

mkdir -p ghostwatch/{ghostwatch/{api,core,collectors,platforms/{linux,macos},ai,storage},frontend,tests/fixtures,docs,scripts}

Output

Project skeleton created

▸ write_schema ghostwatch/core/schema.py

Input

ghostwatch/core/schema.py

Output

GhostEvent Pydantic v2 model with EventSource, Severity, AvailabilityStatus, ProcessInfo, RuleFinding. UTC timestamp enforcement, empty summary rejection.

▸ write_storage ghostwatch/storage/database.py

Input

ghostwatch/storage/database.py

Output

aiosqlite EventStore with INSERT OR IGNORE deduplication, chronological ordering, source filtering

▸ write_rules ghostwatch/core/rules.py

Input

ghostwatch/core/rules.py

Output

4 deterministic rules: PROC_TEMP_DIR, PROC_HIDDEN_NAME, INTERP_NETWORK_CMDLINE, HIGH_SEVERITY_LOG. Registry pattern with @rule decorator.

▸ write_redaction ghostwatch/core/redact.py

Input

ghostwatch/core/redact.py

Output

Redacts tokens, passwords, API keys from cmdline and evidence dicts. Key-name aware — api_key field replaced regardless of value pattern. Original events never mutated.

▸ write_platform_adapters linux/journal.py + macos/unified_log.py

Input

linux/journal.py + macos/unified_log.py

Output

journalctl --output=json bounded adapter. log show --style=json adapter with privacy redaction tracking. Both handle: command missing, permission denied, timeout, malformed JSON.

▸ write_ai_client ghostwatch/ai/local_model.py

Input

ghostwatch/ai/local_model.py

Output

OllamaClient using /v1/chat/completions (OpenAI-compatible, works with Ollama and llama.cpp). Localhost-only enforcement in __init__. Schema-validated AIResponse. Graceful timeout handling.

▸ write_api ghostwatch/api/routes.py + main.py

Input

ghostwatch/api/routes.py + main.py

Output

FastAPI: /collect, /events, /investigate, /status, DELETE /events. CORS localhost-only. Sample mode loads fixture events. Binds to 127.0.0.1 only.

You

run tests

Agent

▸ run_tests .venv/bin/pytest tests/ -v

Input

.venv/bin/pytest tests/ -v

Output

40 passed in 0.51s

▸ run_lint .venv/bin/ruff check ghostwatch/ tests/

Input

.venv/bin/ruff check ghostwatch/ tests/

Output

All checks passed!

40/40 tests passing, Ruff clean. All platform detection, adapter mocking, redaction, rules, schema, and storage tests green.

You

frontend vue js

Agent

Switching from Astro+React to Vue 3 + Vite. Building the dashboard.

▸ write_frontend frontend/src/

Input

frontend/src/

Output

App.vue: two-column layout, event state management. StatusBar.vue: Ollama/platform/model pills. ToolBar.vue: Collect/Investigate/Clear with loading states. EventCard.vue: severity badge, amber rule findings, process info. InvestigationPanel.vue: rule list, AI explanation, uncertainty, next steps, evidence chips. useApi.js composable with Vite proxy to :8765.

▸ build_check npm run build

Input

npm run build

Output

dist/index.html 0.55kB | dist/assets/index.js 80.50kB | built in 1.22s

You

start it up — run ollama — use qwen2.5:1.5b

Agent

▸ install_ollama brew install --cask ollama

Input

brew install --cask ollama

Output

ollama-app 0.40.13 successfully installed

▸ pull_model ollama pull qwen2.5:1.5b

Input

ollama pull qwen2.5:1.5b

Output

success — 1GB model downloaded

▸ start_api GHOSTWATCH_MODEL=qwen2.5:1.5b .venv/bin/ghostwatch

Input

GHOSTWATCH_MODEL=qwen2.5:1.5b .venv/bin/ghostwatch

Output

Uvicorn running on http://127.0.0.1:8765 | ollama_available: true | model: qwen2.5:1.5b

Both servers running. UI at http://localhost:5173, API at :8765. Ollama ready with qwen2.5:1.5b.

You

run without sample mode — show real macOS data

Agent

▸ collect_real POST /api/collect (live mode)

Input

POST /api/collect (live mode)

Output

200 events: Unified Log entries + process snapshots from real macOS

▸ investigate POST /api/investigate

Input

POST /api/investigate

Output

ai_available: true | AI explains: gh=GitHub CLI, wdk=Automox remote management, mdmdmclient=macOS MDM | uncertainty disclosed | suggested manual checks listed

Live investigation working. qwen2.5:1.5b correctly identifies real processes on the system and discloses uncertainty appropriately.

You

validate first — run all acceptance criteria

Agent

Running all 12 acceptance criteria from the planner.

▸ validate_platform_detection macOS → UnifiedLogAdapter, Linux → JournalAdapter, unsupported → None

Input

macOS → UnifiedLogAdapter, Linux → JournalAdapter, unsupported → None

Output

✓ All 3 platform paths correct

▸ validate_schema sample_events.json against GhostEvent

Input

sample_events.json against GhostEvent

Output

✓ 4/4 fixtures valid

▸ validate_ordering SQLite list_events ORDER BY timestamp DESC

Input

SQLite list_events ORDER BY timestamp DESC

Output

✓ Chronological order confirmed

▸ validate_rules Same input × 5 runs

Input

Same input × 5 runs

Output

✓ Deterministic: ['PROC_TEMP_DIR', 'PROC_HIDDEN_NAME']

▸ validate_redaction Bearer sk-abc... in cmdline

Input

Bearer sk-abc... in cmdline

Output

✓ Token stripped from copy, original unchanged

▸ validate_offline Ollama at dead port 19999

Input

Ollama at dead port 19999

Output

✓ ai_available: false | 4 rule findings still returned | clear error message

▸ validate_localhost OllamaClient('https://api.openai.com', 'gpt-4')

Input

OllamaClient('https://api.openai.com', 'gpt-4')

Output

✓ ValueError raised at init — remote URL rejected

▸ validate_no_cloud grep cloud domains in source

Input

grep cloud domains in source

Output

✓ No cloud API endpoints found

▸ validate_no_exec grep os.system/subprocess in ghostwatch/

Input

grep os.system/subprocess in ghostwatch/

Output

✓ No shell execution of AI output

▸ validate_tests .venv/bin/pytest tests/ -q

Input

.venv/bin/pytest tests/ -q

Output

✓ 40 passed

▸ validate_lint .venv/bin/ruff check

Input

.venv/bin/ruff check

Output

✓ All checks passed

All 12 acceptance criteria pass. Ready for submission.

You

let's finish and draft dev.to submission today

Agent

Drafted DEV post, created GitHub repo praveen-pravi6B/ghostwatch, set up branch ruleset with admin bypass, pushed all commits as praveen-pravi6B, added LICENSE/CONTRIBUTING/issue templates/PR template/dependabot/CI matching pixelbreak repo structure.

▸ create_dev_draft title: GhostWatch: Making the Ghost in Your Machine Visible — with Local AI |...

Input

title: GhostWatch: Making the Ghost in Your Machine Visible — with Local AI | tags: hf26challenge, python, ai, opensource

Output

Draft created at dev.to/praveen_kumar_50c9892727f — edit_url returned

14 of 10 messages

---

Limitations

GhostWatch is a lightweight investigator, not a security product.

• Process polling misses short-lived processes. A process that starts and exits between two snapshots will not appear.
• macOS Unified Logging applies privacy redactions. Some fields appear as private. GhostWatch notes this in the capability status.
• journalctl requires systemd. Non-systemd Linux distributions see the journal listed as unavailable.
• No kernel-level tracing. No eBPF, no kernel module, no EDR. Lightweight observer only.
• Small models make small mistakes. qwen2.5:1.5b is fast on CPU but not infallible. Deterministic rules are the authority on severity, not the AI.

---

Why Open Innovation Matters Here

Security tooling is one of the last places you should trust a black box.

If a tool explains why a process looks suspicious, you should be able to read the rules that produced that finding. If a tool redacts credentials before AI inference, you should be able to verify that it actually does. If a tool claims it does not send your logs anywhere, you should be able to confirm that in the source.

GhostWatch works with the internet off. It works when hosted services change their pricing. It works in environments where sending system logs to a third party is simply not acceptable.

That is not a marketing claim. It is the architecture.

---

What's Next

• Live collection loop with configurable intervals
• More detection rules: unusual parent-child relationships, processes on unexpected ports
• Ubuntu CI matrix
• Baseline snapshots to flag new processes not seen in a previous run

---

Built with Python, FastAPI, Vue 3, Pydantic v2, psutil, aiosqlite, and Ollama. Tested on macOS. Sample mode works without OS privileges or a running Ollama instance. 40 tests, Ruff clean.