TruthShield Lite

Privacy-first AI scam, phishing, fake job offer, and suspicious document analyzer.

TruthShield Lite is a database-free full-stack project. Each scan is stored as a local artifact folder under storage/scans, making the system easy to inspect, demo, export, and extend.

What It Does

• Accepts pasted suspicious text, job offers, emails, or messages.
• Optionally accepts an uploaded image, screenshot, or document-like file.
• Provides investigation modes for scam text, fake jobs, suspicious URLs, and AI media.
• Samples video frames and runs a pretrained AI-image classifier when optional AI dependencies are installed.
• Combines average frame likelihood, top suspicious frames, strong-frame ratio, and consistent mild-suspicion signals.
• Adds multimodal context agents for OCR text, speech transcript, public-figure misuse, health claims, money scams, and identity/link risk.
• Displays the six most suspicious frames with timestamps and per-frame likelihoods.
• Shows risk category meters, highlighted evidence, local scan history, and a threat watchlist.
• Extracts text/security features.
• Produces an ML-style risk score.
• Produces a DL-style visual risk estimate for uploaded files.
• Retrieves relevant safety knowledge from a local RAG-style knowledge base.
• Generates a Markdown risk report and a dashboard result.

Tech Stack

• Frontend: HTML, CSS, vanilla JavaScript
• Backend: Python standard library HTTP server
• Storage: local JSON and Markdown files
• AI tiers:
  • Classical ML tier: feature extraction + risk model in backend/engine/ml_model.py
  • Deep Learning tier: visual risk analyzer stub in backend/engine/dl_model.py
  • Multimodal media tier: OCR/audio/persona context agents in backend/engine/media_context_detector.py
  • Generative AI tier: local RAG-style report generation in backend/engine/rag_engine.py and report_generator.py

This starter intentionally avoids external dependencies so it runs anywhere. Later, replace the heuristic modules with Scikit-learn, PyTorch, OCR, and a real LLM.

Run

From the project root:

cd truthshield-lite
python backend/app.py

Open:

http://localhost:8000

Enable Frame-Based AI Media Detection

The basic app remains dependency-free. To enable video frame analysis, run once:

./scripts/install-ai.ps1

Or install manually:

python -m pip install -r requirements-ai.txt

OCR is supported as an optional extra when your Torch/TorchVision environment is compatible:

python -m pip install -r requirements-ocr.txt

Then restart TruthShield:

python -B backend/app.py

The first image/video or audio scan downloads the configured Hugging Face model and can take longer. Later scans reuse the local model cache.

The default model is umm-maybe/AI-image-detector. Override it with:

$env:TRUTHSHIELD_AI_MODEL="your-compatible-image-classification-model"
python -B backend/app.py

This produces an AI-generation likelihood, not proof that media is fake. Animation, CGI, heavy compression, and unseen generators can still cause incorrect results.

OCR and audio transcription are optional. If easyocr or audio extraction dependencies are unavailable, TruthShield still runs and marks that agent as unavailable instead of crashing. On Windows/Anaconda, install OCR only in a clean environment if TorchVision version conflicts appear.

Single-File Runnable Edition

For users who want the whole demo in one file:

python -B truthshield_compiled.py

This launches the same app at:

http://localhost:8000

The single-file edition bundles the frontend, backend routes, scanner logic, local knowledge base, and report generator into truthshield_compiled.py.

Project Structure

truthshield-lite/
  truthshield_compiled.py
  backend/
    app.py
    engine/
      dl_model.py
      feature_extractor.py
      ml_model.py
      rag_engine.py
      report_generator.py
      storage.py
  frontend/
    index.html
    styles.css
    app.js
  docs/
    01-project-overview.md
    02-architecture.md
    03-runbook.md
    04-upgrade-roadmap.md
  knowledge_base/
    scam_patterns.json
  storage/
    scans/
  scripts/
    run.ps1

Next Upgrade Path

1. Replace ml_model.py with a Scikit-learn pipeline trained on SMS spam, phishing, and fake job datasets.
2. Replace dl_model.py with a PyTorch CNN for fake screenshot / AI-image / manipulated document detection.
3. Replace rag_engine.py with ChromaDB embeddings over cybersecurity PDFs.
4. Replace report_generator.py with an LLM call that generates richer explanations from retrieved context.

Documentation Order

Read these files in order:

1. docs/01-project-overview.md
2. docs/02-architecture.md
3. docs/03-runbook.md
4. docs/04-upgrade-roadmap.md