GhostPort: a friendly haunting that teaches Nmap with local Gemma

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

What I Built

A cybersecurity command can look like a magic spell when you are starting out:

nmap -sV -p 22,80,443 localhost

The flags are short. The assumptions behind them are not. Does -p open a port? Does an open port mean someone got in? Does -sn scan quietly, or does it ask a different question altogether?

GhostPort is a haunted Nmap classroom for beginners. You follow four small lessons, read a command piece by piece, answer a question, and ask a ghostly Gemma tutor when something is still unclear.

The theme is literal: there is a ghost in the browser, but it is there to help explain the machine. A dim moon, drifting mist and candle-orange accents give the classroom its Halloween atmosphere. The explanations remain readable, and reduced-motion preferences are respected.

The scope is deliberately small. GhostPort interprets commands; it never executes them or contacts their targets. All lesson examples use localhost.

Demo

Live app: https://ghostport.onrender.com/

Open a lesson, change its command if you like, and choose Reveal meaning. The token-by-token notes work immediately. Select Wake the ghost to load the local Gemma tutor, then ask a question.

The first model download is large—approximately 1.5 GB—and needs a compatible WebGPU browser and around 2 GB of GPU memory. The model is cached for later visits. A compatible recent Chrome or Edge browser is recommended. Written lessons and quizzes remain available if the model cannot run on your hardware.

A quick path through the app:

1. Read nmap localhost and learn that a command describes a request, not a finding.
2. Add -p 22,80,443 to select ports. It does not open them.
3. Add -sV to attempt service and version identification.
4. Try -sn to discover responsive hosts without a port scan.

Quiz completion is saved in the browser, and Reset field notes lets you practice again.

Code

Public repository: https://github.com/Mochi-coder-star/ghostport

The repository includes the application, an MIT license for the original code, a local preview server, tests and a Render Blueprint. Gemma and the other third-party components retain their own licenses and terms.

How I Built It

The application is static HTML, CSS and JavaScript. Render serves the frontend. WebLLM 0.2.87 runs Google's open-weight Gemma 2 2B, using the MLC quantized build gemma-2-2b-it-q4f16_1-MLC, on the visitor's GPU.

There are two complementary explanations:

• Reference notes: a deterministic parser recognizes the supported command options and links their explanations to Nmap's official documentation.
• The ghost: Gemma receives those notes with the learner's question and produces a short explanation and analogy.

Unsupported flags produce an explicit message rather than a guessed explanation. This is a beginner guide, not a complete Nmap command validator.

Command → parser → referenced field notes
                         ↓
Question + field notes → local Gemma → targeted reference check → reply
Quiz completion → browser localStorage

Gemma 2 expects its instructions in a user turn, so the runtime receives a single user-role message containing the tutor instructions, reference facts and question. The model does not get tools that can execute a command.

The ghost got something wrong

One of the most useful tests was a failure. When asked about -sn, Gemma correctly said it did not scan ports, but also incorrectly claimed it checked the operating system and network type.

That would be a poor lesson for someone who came here to learn.

I added a small, targeted reference check for this observed error. If a host-discovery reply brings in operating-system or service-version claims, the displayed answer uses the precise lesson definition instead. A second check replaces unlocked-door analogies: a listening service can still require authentication.

The model's streamed output is buffered until that check finishes. These checks catch particular mistakes; they do not verify every possible answer. The original referenced notes stay visible throughout.

There are nine passing automated tests covering supported lessons, argument parsing, invalid inputs, flag conflicts, Gemma prompt construction, the observed response errors and the local server's file boundaries. The browser checks included real Gemma inference, cached loading, quizzes and wide/narrow layouts.

I also tried smaller Qwen models early in the build. The smallest response was too vague to teach from. Switching to Gemma gave the project a relevant partner integration, but did not remove the need to test its answers.

Why Does Open Innovation Matter?

For a cybersecurity learning tool, I want the learner to be able to ask about a command without sending that command to a hosted model.

Gemma's open weights and WebLLM make that architecture possible: the model comes to the browser, and the command and question are processed on the learner's device. There is no inference API key to paste into the frontend and no application server handling chat prompts.

This is not a claim that the page makes no network requests. Loading the app, runtime, model and fonts requires downloads. Offline operation has not been verified. The distinction is that those asset downloads do not contain the learner's commands or chat questions.

The source is also small enough to inspect. The parser, prompt, model identifier and reference checks are all ordinary JavaScript. Someone can change the lesson wording, test another open-weight model or improve the checks without rebuilding a proprietary backend.

Prize Categories

• Best Use of Gemma: Gemma powers the interactive local tutor, grounded in the current command's reference notes.
• Best Use of Render: Render hosts the deployed classroom frontend at the live demo URL above.

References and Credits

• Nmap Reference Guide, including port states, port selection, service detection and host discovery.
• Google's Gemma 2 documentation and Gemma Terms of Use.
• WebLLM and the MLC Gemma model build.
• Render Static Sites documentation.
• ListingLift, by @aniruddhaadak, provided a useful community account of local Gemma's factual limitations and targeted checks; GhostPort's code is original.

AI disclosure: I supplied the project concept and direction, including the Nmap teaching focus and visual feedback. Codex generated most of the implementation, ran the checks and authored this article on my behalf. The entry is disclosed as AI-authored; no human teaching outcomes or user testimonials are claimed.