This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle
ScamShield: I Built a Local AI Scam Detector for Freelancers
Freelancing offers flexibility, but finding legitimate clients isn't always easy.
A job offer might look professional while asking for an upfront registration fee. A client might request an unusual payment transfer. Sometimes, the warning signs are subtle enough that a new freelancer doesn't know what to look for.
I wanted to build something practical to help freelancers pause, identify warning signs, and make more informed decisions before accepting an offer.
That's why I built ScamShield, a local AI-assisted freelance scam screening tool.
What I built
ScamShield lets users paste a freelance job offer, client message, or payment request and receive a structured analysis.
The current MVP includes:
- Risk classification: LOW, MEDIUM, HIGH, or CRITICAL.
- Risk scoring: A score from 0 to 100 based on detected warning signs.
- Evidence-based findings: Matched text excerpts, rule identifiers, severity levels, and explanations.
- AI explanations: Additional context generated by a locally running Qwen3 model.
- Missing information: Details that the message doesn't establish, such as contract terms or independently verifiable company information.
- Recommended next steps: Practical suggestions based on the detected indicators.
- A web interface: A responsive frontend with example messages, character counting, and a structured analysis report.
The goal isn't to declare every suspicious message fraudulent. It's to help users understand what deserves closer inspection.
How it works
The most important architectural decision was to keep risk assessment separate from AI-generated explanations.
Here's the basic flow:
- A user submits a message through the web interface.
- The FastAPI backend validates the input.
- A deterministic Python rules engine searches for known warning signs.
- The engine calculates the risk score and classification.
- If findings exist, the optional local AI component explains those existing findings.
- The frontend displays the evidence, score, recommendations, and AI explanation.
The AI model does not determine the risk score, invent verified findings, or change the original severity ratings.
This separation makes the output easier to inspect and test.
Why open-source AI matters here
ScamShield uses Qwen3 4B through Ollama, allowing the explanation model to run locally instead of depending on a hosted AI API.
That matters for a tool that handles potentially sensitive client messages and job offers.
A local-first approach offers several advantages:
- Privacy: Message content can remain on the user's machine during local analysis.
- Control: The model can be replaced or reconfigured without redesigning the entire application.
- Accessibility: Users can experiment without requiring a paid hosted-model API.
- Transparency: Deterministic rules remain responsible for risk scoring, while AI provides supplementary explanations.
Local inference still requires suitable hardware and the model must be downloaded first. Running locally does not automatically make every component secure, but it gives users more control over where their data is processed.
Technology stack
- Backend: Python, FastAPI, Pydantic
- Frontend: HTML, CSS, JavaScript
- AI inference: Ollama with Qwen3 4B
- Testing: pytest, FastAPI TestClient, mocked AI responses
- Development environment: Local Windows environment
Testing and reliability
I implemented automated tests for the rule-based analyzer, API endpoints, and Ollama client.
The latest full test run completed with 29 tests passing.
The tests cover input validation, risk classification, finding validation, malformed model responses, timeouts, HTTP errors, and preservation of the original findings. API tests also cover successful AI explanations, fallback behavior when Ollama fails, and skipping AI calls when no findings exist.
These tests verify expected application behavior; they are not proof that the tool can detect every type of scam.
Who could use it?
ScamShield is designed for freelancers, students looking for their first remote opportunity, and independent contractors who regularly receive unfamiliar job offers.
A future version could include configurable detection rules, additional message patterns, and more comprehensive evaluation against a curated collection of legitimate and suspicious offers.
For now, it is an MVP demonstrating how deterministic security checks and local AI explanations can work together.
Try the project
-
GitHub repository:
ScamShield 🛡️
Protect Your Freelance Journey. Spot Scams Before They Strike.
ScamShield is an open-source, AI-assisted screening tool that helps freelancers assess suspicious job offers, client messages, and payment requests before responding. It looks for warning signs, shows the evidence behind its assessment, and suggests practical next steps.
Important: ScamShield is a decision-support tool, not a guarantee that a message is safe or fraudulent. Always verify clients and companies independently.
Contents
- Why ScamShield?
- Features
- How It Works
- Technology Stack
- Project Structure
- Requirements
- Installation and Setup
- Run the Application
- Run the Tests
- Example Scenarios
- AI, Privacy, and Limitations
- Roadmap
- Contributing
- License
Why ScamShield?
Freelancers and people starting their careers can encounter fake job offers, upfront registration fees, suspicious payment requests, impersonation, and pressure to share sensitive information. These messages can be difficult to evaluate, especially for people who are new to freelance work.
ScamShield makes the assessment more understandable by surfacing…
To run the project locally, install the Python dependencies, start the FastAPI backend, and serve the frontend. For AI explanations, install Ollama, download the configured Qwen3 model, and make sure the local Ollama service is running.
The project is still under development. Its findings depend on the available detection rules, and a low score does not establish that an offer is safe.
What I learned
Building ScamShield taught me that adding an AI model isn't the same as building a reliable AI-assisted application.
The surrounding system matters: input validation, structured outputs, error handling, tests, and clear limitations all influence whether users can trust what they see.
My biggest takeaway is that AI should help explain security evidence, not replace the logic responsible for establishing it.
That is the principle I want to continue following as ScamShield grows.
Conclusion
ScamShield is my attempt to turn a real problem faced by freelancers into a practical, locally runnable cybersecurity tool.
By combining deterministic detection with open-weight AI, it aims to make suspicious freelance offers easier to understand without requiring users to send their messages to a hosted AI service.
This is an early version, not a definitive scam detector. But it's a working foundation that I can test, improve, and develop further.
Thanks for reading!
Top comments (0)