mevislobo2006/threatripperOffline heuristic analyzer that scores suspicious SMS, chat messages and links for scam and phishing indicators, explaining each warning sign with awareness guides and a quiz.
A cyber security awareness platform. Paste a suspicious SMS, email, chat message or link and it tells you which scam techniques it spotted, why each one matters, and what to do next.
Live demo: https://threatripper.onrender.com (Render free tier — the first visit after inactivity may take a minute to wake up.)
It is a teaching tool, not a security product. There is no antivirus engine, no malware scanning, no sender verification and no domain reputation service. Links are never opened.
Purpose and scope. Threatripper is a defensive, educational tool for detecting scam indicators in text. It does not contain malware, exploit code, phishing kits, credential lists or any offensive capability, and it never makes network requests. All example messages and domains in the repository use fictional, reserved
.examplenames and exist only to demonstrate detection logic.Use it only to protect yourself and others. Misuse is contrary to the project's purpose; report fraud through official channels (see Limitations).
Four pages, no build step, no JavaScript framework, no CDN:
| Page | Path | Purpose |
|---|---|---|
| Analyse | / | Paste a message or link, get a scored, explained verdict |
| Awareness | /awareness.html | Seven scam-type guides plus reporting advice |
| Quiz | /quiz.html | Twelve scenarios graded server-side with explanations |
| History | /history.html | Your recent analyses, with identifiers already redacted |
The analysis is deliberately explainable rather than authoritative. Every point on the scale maps to a named rule with a severity, a confidence and a sentence explaining why it matters. The interface shows the whole calculation, including the combination bonuses, so the output can be argued with instead of merely trusted.
What it does not do:
Requires Python 3.11 or newer.
git clone <your-repo-url> threatripper
cd threatripper
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Use "python3 -m pip", not a bare "pip": on a hardened distro (Kali, Debian,
# Fedora) pip may be an externally managed system binary that is blocked by
# PEP 668, and a bare "pip" will not resolve to the venv.
python3 -m pip install -r requirements.txt
python3 -m uvicorn backend.main:app --reload
Open http://127.0.0.1:8000.
The whole product — API, rule catalogue, database and web interface — runs from that
one process on one origin. Interactive API docs are at /docs, the raw OpenAPI schema
at /openapi.json.
To run the tests:
python3 -m pip install -r requirements-dev.txt
python3 -m pytest
The same analysis runs from a terminal. This is a second front end, not a second
implementation: every rule, score, explanation and recommended action comes from
the same AnalysisService the web app uses, so the two cannot disagree about
what is dangerous.
No server, no port, no network — useful when the message you are looking at is the incident.
# Analyse a pasted message
./threatripper.sh "URGENT: your account will be closed, share the OTP"
# Or pipe it in, which is the natural way to use it
pbpaste | ./threatripper.sh
# A bare link
./threatripper.sh "http://verify-account.example/login"
# The API payload, for scripts
./threatripper.sh "share your OTP" --json | jq .result.risk_level
# Only fail when it is serious
./threatripper.sh --fail-on critical "see you tomorrow" ; echo $? # 0
./threatripper.sh --fail-on critical "your bank account will be suspended in 24 hours, verify at http://bank-verify.example/login and share the OTP" ; echo $? # 1
# Stored history, shared with the web app
./threatripper.sh history
./threatripper.sh history --level critical --json
# Analyse without keeping any record
./threatripper.sh "share your OTP" --no-store
A red THREATRIPPER banner is printed at the start of an interactive run, drawn
in the ANSI Shadow face. It goes to stderr and is skipped for --json and
whenever the output is piped or redirected, so it never lands in a log or breaks
a pipeline. --no-color keeps the banner but drops the colour.
Every glyph in ANSI Shadow is an East Asian ambiguous-width character, so on
some terminals — typically a CJK locale, or a window narrower than 78 columns —
the rows render at different widths and the letters shear apart. In that case the
banner quietly falls back to a pure-ASCII face. Override the choice with
--banner shadow|ascii|none:
./threatripper.sh --banner shadow "message" # force the block letters
./threatripper.sh --banner ascii "message" # force the terminal-safe face
./threatripper.sh --banner none "message" # no banner at all
Like the web app, an analysis is added to the shared history by default —
the same redacted preview, never the raw text. Pass --no-store to analyse
without keeping a record.
./threatripper.sh analyze --help and ./threatripper.sh history --help list every
option. The launcher prefers the project's .venv interpreter and resolves its
own location, so it works from any directory and with the virtualenv activated or
not. python3 -m backend.cli is equivalent.
A terminal tool gets used in scripts, so "did this find something?" has to be answerable without parsing prose.
| Code | Meaning |
|---|---|
0 | Nothing found, at or below the --fail-on threshold |
1 | Something was found at or above the threshold |
2 | The command line was wrong |
3 | There was nothing to analyse, or the analysis could not run |
The threshold defaults to suspicious. Pass --fail-on with any band
(low, suspicious, medium, high, critical) to change it.
# Fail a deploy pipeline only on a serious finding
./threatripper.sh --fail-on critical "$MESSAGE" || echo "review this message"
A usage error deliberately never shares a code with a finding, so a script can tell "this message is dangerous" from "you typed the flag wrong". An unrecognised risk band also exits non-zero, rather than reporting all clear.
| Score | Level | Meaning |
|---|---|---|
| 0–20 | LOW | Few or no scam indicators. Not a guarantee of safety. |
| 21–40 | SUSPICIOUS | Some questionable characteristics. Verify independently. |
| 41–60 | MEDIUM | Multiple scam signals. Do not act on this message. |
| 61–80 | HIGH | Strong fraud indicators. Treat as hostile. |
| 81–100 | CRITICAL | Very strong indicators of an active fraud attempt. |