This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
What I Built
I built GhostShell: The Haunted AI Terminal 👻 — a local-first, open-source cybersecurity assistant and terminal simulator that creates the experience of a sentient digital entity living inside your computer terminal.
Developers frequently copy-paste shell commands from forums, StackOverflow, or LLMs without realizing that commands like rm -rf /, chmod -R 777, or curl | bash can destroy filesystems, wipe disks, or leak private SSH credentials. Furthermore, sending private commands, directory paths, and environment secrets to cloud AI APIs poses serious privacy and security risks.
GhostShell solves this by embodying a protective, slightly spooky AI companion named Ghost with three core modes:
🛡️ Security Guardian: A deterministic command safety auditor across Linux Bash, Windows PowerShell, Windows CMD, and macOS. It checks commands for destructive flags, privilege escalation, and credential exposure, classifying them into CRITICAL, HIGH, MEDIUM, LOW, SAFE, and REVIEW REQUIRED. Crucially, GhostShell treats commands purely as text and NEVER executes them.
🔮 Terminal Ghost: An interactive, witty terminal assistant that explains commands (like pwd, chmod 755 vs 777, git rebase vs merge) in beginner-friendly terms without cloud dependence.
📜 Haunted Archives: A cyber-horror generator that produces fictional incident post-mortems, abandoned terminal logs, and interactive Choose-Your-Own-Adventure (CYOA) stories from forgotten mainframes and midnight datacenters.
Demo
Code
GhostShell: The Haunted AI Terminal 👻
A digital ghost haunting your local computer terminal — combining open-weight AI, deterministic cybersecurity command auditing, and spooky interactive storytelling.
1. Project Overview
GhostShell is a local-first, open-source cybersecurity assistant and terminal simulator built for the "Ghost in the Machine" challenge. It embodies a sentient, witty, and technically astute digital entity named Ghost that inhabits your terminal to:
- Demystify terminal commands for beginners and seasoned developers alike.
- Audit commands for dangerous patterns (recursive deletions, disk wipes, fork bombs, privilege escalation, secret leaks, pipe-to-shell attacks) using a deterministic security engine.
- Provide safe alternatives before dangerous operations can damage real systems.
- Generate cyber horror stories and fictional incident logs from forgotten servers and haunted networks.
- Run 100% offline and locally, keeping developer commands and prompts strictly on your own hardware.
2. Problem Statement
Modern software developers frequently copy terminal commands from StackOverflow, GitHub issues, LLMs…
How I Built It
GhostShell was built around a hybrid local architecture that guarantees safety, offline resilience, and zero data waste:
Local Model Runtime (Ollama Integration):
Integrates directly with Ollama
via local loopback (http://127.0.0.1:11434) to power conversational reasoning using open-weight models such as Qwen 2.5 (3B) and Llama 3.2 (1B).
Live runtime detection detects model health and allows dynamic in-browser model switching without restarting the server.
Built-in Server-Side Request Forgery (SSRF) defense restricts endpoints strictly to local loopback addresses (127.0.0.1, localhost).
Spectral Heuristic Engine (0 MB Data / Low-Bandwidth Mode):
For users with bandwidth limitations or without local LLMs, GhostShell features a custom built-in heuristic knowledge core (ghostshell/spectral_engine.py).
It answers shell queries, synthesizes spooky Ghost explanations, and procedurally generates horror incident reports with 0 MB of internet data download required.
Deterministic Safety Analyzer (ghostshell/command_analyzer.py & risk_rules.py):
Built with deterministic regular expressions, tokenization, and quote-aware chaining parsers.
Strictly separates rule-based invariants from AI prose: the LLM is prohibited from overriding or downplaying confirmed security risks.
Zero execution sandbox: commands are never passed to eval(), exec(), or subshells.
Web Stack & Testing:
Backend: Python 3.10+ and Flask 3.0 with strict security headers (CSP, nosniff, SAMEORIGIN).
Frontend: Semantic HTML5, CSS3 Custom Properties, and vanilla JavaScript (zero heavy frameworks, zero external tracking pixels).
Verification: An extensive test suite with 88 automated tests using pytest covering dangerous commands, misleading whitespace, shell chaining, and REST API limits.
Why Does Open Innovation Matter?
Open innovation and open-weight AI are not just nice-to-have features for GhostShell—they are essential to its mission:
Confidentiality of Developer Secrets: Terminal activity contains proprietary code paths, usernames, environment variables (AWS_SECRET_ACCESS_KEY, DATABASE_URL), and private SSH keys. Piping these into proprietary cloud AI services risks severe data leakage and compliance violations. Open-source local models guarantee that sensitive infrastructure data never leaves the developer's laptop.
Deterministic Trust & Transparency: Closed commercial AI APIs are black boxes whose safety alignments can change overnight or hallucinate away dangerous operations. With open-source code and local open-weight models, developers can inspect every line of the risk rulebook and reproduce exact audit outcomes.
Accessibility & Offline Independence: Developers working on trains, airplanes, air-gapped security bunkers, or in regions with metered data can run GhostShell without cloud subscriptions, credit cards, or token quotas.
My Agent Session
During the development session, the agentic pairing workflow helped accelerate several key milestones:
Architected the multi-platform static command analyzer, parsing chained commands (&&, ;, |) and unclosed quotes.
Diagnosed and fixed a Windows-specific console encoding defect where sys.stdout defaulted to cp1252, ensuring smooth cross-platform execution.
Designed the fail-safe asset delivery system with embedded CSS fallbacks to eliminate flash of unstyled content across varied local browser environments.
Implemented the zero-download Spectral Heuristic Engine so users can enjoy the full terminal assistant experience even without downloading gigabytes of model weights.
Wrote and validated the 88-test automated verification suite with pytest.
The Spirit of It
There is a distinct feeling every developer remembers: sitting alone in a dark room late at night, staring into the glow of a terminal, running a command, and experiencing that heart-stopping second of dread: "Did I just delete the production database or wipe my root partition?"
GhostShell captures that exact moment of tech lore. The terminal flickers with nostalgic phosphor scanlines, a digital ghost watches over your keystrokes, and the instant you accidentally type rm -rf / or an unsafe remote pipe, the ghost's spectral eyes flash crimson, warning:
"🚨 CRITICAL RISK! Mortal, stay your hand! This command recursively deletes files starting from the filesystem root. The ghost protects your machine!"
It turns cybersecurity education from a dry manual into an atmospheric, unforgettable pairing experience
Prize Categories
Best Use of Ollama
Top comments (0)