VishGuard Final Submission

This ZIP contains two runnable projects:

• VishGuardAndroid/ (Android app)
• vishguard-laptop/ (Python laptop backend)

Use this README only. It has complete step-by-step setup and run commands.

1) What This Prototype Does

VishGuard detects a vishing incident in progress by combining:

1. Laptop call intelligence (mic -> speech-to-text -> scam risk analysis)
2. Phone security events (OTP/reset/login notifications)

The Android app correlates these and raises an on-phone warning with incident timeline.

2) Tested Environment

• macOS (Apple Silicon)
• Android phone (USB debugging enabled)
• Android Studio installed
• Python 3.9+

3) One-Time Setup

3.1 Laptop Python setup

cd vishguard-laptop
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-mic.txt

3.2 Hugging Face token (required for LLM mode)

Use a valid HF token with inference access.

export HF_TOKEN="YOUR_HF_TOKEN"
export HUGGINGFACE_HUB_TOKEN="$HF_TOKEN"
export HF_MODEL="meta-llama/Meta-Llama-3-8B-Instruct"

3.3 Build/install Android app

1. Open Android Studio
2. Open folder: VishGuardAndroid
3. Let Gradle sync
4. Connect Android phone by USB
5. Press Run (green triangle) to install app

4) Every Demo Run (Start Here)

Open 2 terminal windows.

Terminal A: start laptop backend

cd vishguard-laptop
source .venv/bin/activate
export HF_TOKEN="YOUR_HF_TOKEN"
export HUGGINGFACE_HUB_TOKEN="$HF_TOKEN"
export HF_MODEL="meta-llama/Meta-Llama-3-8B-Instruct"
python3 main.py --serve --host 0.0.0.0 --port 8000

Terminal B: enable adb + USB reverse tunnel

export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export PATH="$ANDROID_SDK_ROOT/platform-tools:$PATH"
adb devices
adb reverse --remove-all
adb reverse tcp:8000 tcp:8000
adb reverse --list

Expected: tcp:8000 tcp:8000

5) App Configuration on Phone

Open VishGuard app:

1. Tap Automation Settings
2. Set laptop URL to exactly:
   • http://127.0.0.1:8000
3. Save settings
4. Ensure Auto-sync ON
5. Tap Enable Notification Access and grant access to VishGuard

6) Quick LLM Health Check (optional but recommended)

In Terminal B:

curl -X POST "http://127.0.0.1:8000/analyze_text" \
  -H "Content-Type: application/json" \
  --data-raw '{"text":"This is bank fraud team. Share OTP now. Account will be blocked.","mode":"llm_hf"}'

Expected: JSON response with scam risk fields.

7) Demo Flow (Judge Run)

1. Keep Terminal A server running.
2. Keep USB cable connected.
3. Start/answer call on Android phone and enable speaker.
4. Place phone near laptop mic.
5. Speak scam-like script for ~45-75 seconds.
6. During call, send an OTP-style message to the same phone.
7. End call.
8. Show app dashboard + timeline:
   • CALL_INTEL events
   • OTP_EVENT / reset/login events if triggered
   • escalated ATO risk and warning UI

8) Common Issues

"Failed to connect to /127.0.0.1:8000"

URL saved incorrectly. It must include protocol:

• http://127.0.0.1:8000

Then rerun:

adb reverse --remove-all
adb reverse tcp:8000 tcp:8000

adb: command not found

Run:

export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export PATH="$ANDROID_SDK_ROOT/platform-tools:$PATH"

No transcript captured

• Check laptop backend is running
• Keep phone near laptop mic
• Make sure call is on speaker
• Verify app Auto-sync is ON

9) Project Structure

• VishGuardAndroid/ Android source (Kotlin/Compose)
• vishguard-laptop/ Python API + transcription + analysis