VishGuard

Social-engineering pattern detection and enforced out-of-band verification — for the deepfake-vishing era.

Scope — read this first

VishGuard does not detect synthetic/deepfake audio. Real audio deepfake detection requires models trained on large synthetic-speech datasets — a research-lab-scale problem, not something to casually claim in a portfolio project.

What it does instead is arguably more durable: it detects the behavioral pattern that vishing and CEO-fraud attacks share, regardless of whether the voice behind them is real, spoofed, or AI-generated — urgency, authority impersonation, secrecy, threats, and requests for sensitive actions. That pattern doesn't change as generative audio quality improves, which is exactly why detection alone isn't the point here — enforcement is.

How it works

1. pattern_detector.py — scans a call/message transcript for five categories of social-engineering markers (urgency, authority claims, secrecy/isolation, threats, sensitive-action requests) and produces a weighted Low/Medium/High risk score.
2. verification_workflow.py — the actual mitigation. Any Medium/High risk request is gated behind a verification code that must be confirmed through a channel separate from the one the request arrived on (e.g. calling back a known extension) — never by asking the original caller to confirm it themselves, which would defeat the point. Every step, pass or fail, is logged for audit.

Proof, not just claims

python tests/test_pattern_detection.py

✅ PASS — benign_it_ticket_update.txt: risk=Low (score=0)
✅ PASS — benign_scheduling_call.txt: risk=Low (score=0)
✅ PASS — vishing_ceo_fraud.txt: risk=Medium (score=45, categories=['urgency', 'sensitive_action_requested'])
✅ PASS — vishing_it_support.txt: risk=Medium (score=35, categories=['urgency', 'threat_consequence'])

4/4 transcripts correctly classified.

Two real vishing transcript patterns (CEO wire-fraud, fake IT-support account-lockout) correctly flagged, two benign calls correctly left alone — checking for false positives is as important as catching true ones.

Running it

Command line:

git clone https://github.com/Aditya-Sec/VishGuard.git
cd VishGuard
python cli.py tests/sample_transcripts/vishing_ceo_fraud.txt

Web UI:

pip install -r requirements.txt
python app.py
# open http://127.0.0.1:5000

Paste a transcript (or click one of the built-in samples), see the risk score and matched categories, then try both verification paths — same-call confirmation is always blocked, only an out-of-band callback approves the action.

No dependencies beyond the Python standard library for the core detector/workflow — Flask is only needed for the optional web UI.

License

MIT — see LICENSE.