PhishGuard Inbox: private, local-first email triage for freelancers

The problem

Freelancers and small teams regularly receive invoices, document shares, account notices, and payment requests without having a security team to review them. A suspicious email can be hard to judge quickly, especially when it creates urgency or uses a lookalike sender or link.

What I built

PhishGuard Inbox is a local-first email triage app. Paste an email or upload an .eml file, and it extracts links, domains, selected sender details, and attachment metadata. Deterministic Python checks flag common warning signs and show their evidence. A locally hosted Gemma model, served through Ollama, adds an explanation and a cautious next step. The app can also create a JSON report that omits the full email body and attachment contents.

The project includes 22 fictional sample emails spanning phishing attempts and routine messages, so people can try the workflow without using real inbox data.

Who it is for

The first intended users are freelancers and small teams who want a quick second look at an unexpected payment request, login warning, document share, or other message. This is an early product hypothesis; I have not yet validated willingness to pay with users.

Demo

• Demo video or walkthrough:https://phishguard-zctfym5bmf6mklsmpvur2a.streamlit.app/
• Source code: https://github.com/Mstr-Creta/PhishGuard

The current app runs locally with Python, Streamlit, and Ollama. A public Streamlit Cloud link is not available for this local-only version: the app is configured to use a loopback Ollama service on the same computer. A recorded walkthrough is the most accurate demo unless the app is later adapted for a hosted inference setup.

For a short recording, load sample email, run the analysis, show the extracted link and evidence, then download the JSON report. Explain that the model and rules provide triage assistance, not a verdict users should trust without checking.

Why open innovation matters here

Running an open-weight model locally makes the inference path inspectable and avoids sending email text to a hosted LLM provider. It also avoids a per-request cloud model fee for the local workflow. That matters for a small tool aimed at independent professionals, where recurring inference costs and handling client email data are both practical concerns.

Local processing is not a guarantee of security, and this prototype has not been independently audited. The model can misunderstand a message, and rules can miss attacks or flag legitimate email. Users should verify sensitive requests through a contact method they already trust.

How it works

1. Streamlit accepts pasted text or an .eml upload.
2. The parser extracts message text, headers, links, domains, and attachment metadata in memory.
3. Deterministic checks score visible signals and keep their evidence available.
4. Ollama runs the selected local model to explain the findings and suggest a safe next step.
5. The downloadable report excludes the full email body and attachment contents.

Built with

Python, Streamlit, Ollama, and Gemma 3 1B. The default model is gemma3:1b; qwen2.5:1.5b-instruct is an optional alternative.

Try it locally

See the setup instructions in the GitHub README below. The sample messages are synthetic and use reserved .test domains.

Current limitations

• This is a prototype, not an antivirus product or proof that a message is safe or malicious.
• The heuristics and model have not been calibrated against a representative, labeled email dataset.
• The sample emails are illustrative and do not establish accuracy.
• The current local-only Ollama configuration does not provide a public hosted demo.
• No user testing or willingness-to-pay validation has been completed yet.

Challenge fit

PhishGuard Inbox explores the Side Hustle prompt by applying an open-weight model to a specific workflow for freelancers and small teams. Whether people would pay for it remains to be tested with actual users.

#hf26challenge #python #ai #security

# PhishGuard Inbox

Local-first email triage for freelancers and small teams. Paste an email or upload an `.eml` file to inspect links, sender signals, attachments, and common social-engineering patterns. A local Ollama model explains the evidence and suggests a cautious next step.

> PhishGuard is triage assistance. It cannot prove that a message is safe or malicious. Verify sensitive requests through a contact method you already trust.

## Features

- Parse pasted email text and `.eml` files in memory
- Extract URLs, domains, selected header fields, and attachment metadata
- Flag common signals such as urgency, payment or credential requests, URL mismatches, shorteners, and risky attachments
- Show deterministic findings and their evidence alongside a local model explanation
- Download a JSON report without the full email body or attachment contents
- Browse 22 fictional sample emails across phishing and routine message categories

## How it works

The app parses the message, applies transparent Python checks, and sends selected email content to the local Ollama service for an explanation. The app is configured for loopback Ollama addresses; it does not use a cloud LLM API or perform DNS lookups. Uploaded `.eml` files are read in memory, and attachment contents are not opened or saved.

## Requirements

- Python 3.11 or newer
- [Ollama](https://ollama.com/download)
- About 16 GB system RAM is recommended for the target setup; model performance depends on the computer

## Run locally on Windows

Open PowerShell in the project folder:

powershell
py -3 -m venv .venv
..venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env
ollama pull gemma3:1b
streamlit run app.py

Ollama's Windows app normally runs in the background. If the app reports that Ollama is unavailable, open Ollama and retry. The optional alternative model is `qwen2.5:1.5b-instruct`:

powershell
ollama pull qwen2.5:1.5b-instruct

For macOS or Linux, create and activate a Python virtual environment with your platform's commands, install `requirements.txt`, pull `gemma3:1b` with Ollama, and run `streamlit run app.py`.

## Sample walkthrough

1. Open **Sample Emails**.
2. Select a fictional phishing message and choose **Load sample in Analyze Email**.
3. Open **Analyze Email** and select **Analyze locally**.
4. Review the evidence, extracted links, model explanation, and JSON report.

The examples are synthetic and use reserved `.test` domains.

## Privacy notes

The default Streamlit address is `127.0.0.1`. Email text is sent to the local Ollama process for analysis, not to a cloud LLM service. The model request contains selected headers, a body excerpt capped at 6,000 characters, URLs, domains, attachment metadata, and deterministic findings. Reports do not include the full email body or attachment contents.

## Limitations

PhishGuard is an experimental triage tool. Rules can miss attacks or flag legitimate messages, and a small local model can misunderstand an email. The included examples are not a benchmark and do not demonstrate real-world accuracy. Do not use the output as the sole basis for payments, account changes, or sharing sensitive information.

The current Ollama setup is local-only. Deploying this app to Streamlit Community Cloud will not connect it to Ollama running on your personal computer. A hosted deployment requires a separately designed inference setup and corresponding privacy/security review.

## Project status

Early MVP. Accuracy evaluation, user research, accessibility review, and a public hosted demo are future work.

## License

[Add your chosen license and include its `LICENSE` file before describing this project as open source.]

---