🛡️ WALRUS

Web Application for Learning, Reporting, and Understanding Security

An AI-powered, gamified, multilingual cybersecurity education & threat-detection platform built for India

Features · Tech Stack · Installation · API Docs · Deployment · Contributing

📌 Overview

WALRUS is a full-stack cybersecurity platform designed to address India's rapidly growing digital fraud crisis:

📊 60% increase in cybercrime cases (2023) · ₹10,319 crore lost to digital fraud (2022) · 70% of Indians have been scammed

The platform tackles this through three pillars:

Pillar	What it does
🤖 AI Protection	Real-time scam detection across text, URLs, emails, and images
🎮 Gamified Learning	Interactive cybersecurity modules with quizzes, streaks, and leaderboards
🌐 Community	Scam reporting, shared experiences, and moderated discussion forums

Fully localized in English, Hindi (हिंदी), and Kannada (ಕನ್ನಡ) — making digital safety accessible to every Indian.

✨ Features

🔍 AI-Powered Scam Analyzer

Analyzes text, URLs, emails, and phone numbers in real-time
Supports image OCR — upload a screenshot, extract text, detect threats
Hugging Face AI integration (BART models) with pattern-based fallback
Returns a threat score (0–10) with detailed reasoning
Anonymous usage — no account required for basic checks

🎮 Gamified Learning System

5 comprehensive modules covering phishing, malware, social engineering, and more
Progressive difficulty: beginner → advanced
Points, levels, streaks, achievements, and leaderboards
Immediate quiz feedback to reinforce learning

⏰ Time Machine — Interactive Scenarios

Explore cybersecurity threats across 3 eras: 2015, 2025, and 2035
Decision-based storylines that teach consequences
Case studies and prevention guides for each era
Immersive UI with time-travel animations

👥 Community & Reporting

Submit detailed scam reports with PDF export
Discussion forums with topics, comments, and moderation
Admin panel: user management, analytics, content moderation
Status tracking for filed reports

🌐 Multilingual Support

870+ translation keys per language
Real-time language switching (no page reload)
Persistent preference stored in localStorage
Culturally adapted translations for Indian context

🚀 Tech Stack

Frontend

Technology	Version	Purpose
React	18.3	UI framework
TypeScript	5.5	Type safety
Vite	5.4	Build tooling
Tailwind CSS	3.4	Styling
React Router DOM	7.9	Routing
react-i18next	—	Internationalization
Recharts	3.2	Analytics charts
GSAP	3.13	Animations
Rive	—	Interactive animations
Lucide React	—	Icons

Backend

Technology	Version	Purpose
Node.js	v18+	Runtime
Express.js	5.x	HTTP server
MongoDB + Mongoose	8.x	Database
Firebase Admin SDK	—	Auth verification
Helmet.js	—	Security headers
Multer	—	File uploads
Tesseract.js	—	OCR processing
Puppeteer	—	URL scraping
jsPDF	—	PDF generation

AI & External Services

Service	Use
Hugging Face API (`facebook/bart-large-mnli`)	Text & URL classification
Hugging Face API (`facebook/bart-large-cnn`)	Summary generation
Google Safe Browsing API (optional)	URL threat intelligence
Gemini API (optional)	Advanced summaries
Firebase Authentication	User auth (frontend)
Cloudflare URL Scanner	URL intelligence

📁 Project Structure

cyberawareness/
├── src/                        # React + TypeScript frontend
│   ├── admin/                  # Admin panel components
│   ├── components/
│   │   └── timeMachine/        # Time Machine feature
│   ├── contexts/               # Auth & Theme contexts
│   ├── i18n/locales/           # en.json, hi.json, kn.json
│   ├── pages/                  # Page-level components
│   ├── routes/                 # React Router config
│   ├── services/               # API service layer
│   └── utils/                  # Helper functions
│
├── server/                     # Express.js backend
│   ├── config/                 # Validation rules, DB config
│   ├── middleware/             # Security middleware stack
│   ├── models/                 # Mongoose schemas
│   ├── routes/                 # 70+ REST API endpoints
│   ├── services/               # Business logic (AI analyzer, etc.)
│   └── test/                   # Backend test suites
│
├── api/                        # Vercel serverless functions
├── public/                     # Static assets
├── md/                         # Additional documentation
│
├── .env.example                # Environment variable template
├── vercel.json                 # Vercel deployment config
├── render.yaml                 # Render deployment config
├── firestore.rules             # Firestore security rules
├── start_server.py             # Python dev server manager
└── package.json

📦 Installation

Prerequisites

Node.js v18+
npm or yarn
MongoDB (local or Atlas)
Firebase project with Authentication enabled
Hugging Face API key (get one here)
Python 3 (optional, for the dev server manager)

Step 1 — Clone

git clone https://github.com/NITHINKR06/cyberawareness.git
cd cyberawareness

Step 2 — Install Dependencies

npm run install:all   # Installs frontend + backend dependencies

# Or separately:
npm install           # Frontend
cd server && npm install  # Backend

Step 3 — Configure Environment

cp .env.example .env

Open .env and fill in the following:

# ── Database ─────────────────────────────────────────────
MONGODB_URI=mongodb://localhost:27017/walrus_db
MONGODB_DBNAME=walrus_db

# ── Security ─────────────────────────────────────────────
JWT_SECRET=your-super-secret-jwt-key
SESSION_SECRET=your-session-secret-key

# ── Server ───────────────────────────────────────────────
PORT=5000
NODE_ENV=development

# ── Firebase (Frontend) ───────────────────────────────────
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=

# ── Firebase Admin (Backend) ──────────────────────────────
FIREBASE_ADMIN_PROJECT_ID=
FIREBASE_ADMIN_CLIENT_EMAIL=
FIREBASE_ADMIN_PRIVATE_KEY=   # Include -----BEGIN/END PRIVATE KEY-----

# ── AI Analysis ───────────────────────────────────────────
HUGGINGFACE_API_KEY=

# Optional: Override default AI models
HUGGINGFACE_TEXT_MODEL=facebook/bart-large-mnli
HUGGINGFACE_URL_MODEL=facebook/bart-large-mnli
HUGGINGFACE_SUMMARY_MODEL=facebook/bart-large-cnn

# Optional: Additional AI enhancements
GOOGLE_SAFE_BROWSING_API_KEY=
GEMINI_API_KEY=

Step 4 — Firebase Setup

Create a project at Firebase Console
Enable Authentication → Email/Password provider
Create a Firestore database
Copy your web app config → .env (VITE_FIREBASE_*)
Go to Project Settings → Service Accounts → Generate new private key
Extract values into FIREBASE_ADMIN_* env vars
Deploy Firestore rules: firebase deploy --only firestore:rules

Step 5 — Run

# Development (frontend + backend together)
npm run dev:all

# Or separately:
npm run dev          # Frontend  → http://localhost:5173
npm run server:dev   # Backend   → http://localhost:5000

# Using the Python server manager (recommended)
python start_server.py           # Start both
python start_server.py status    # Check status
python start_server.py stop all  # Stop both

The Python manager handles port conflict detection, concurrent output, and graceful shutdown on Ctrl+C.

📖 Usage

User Roles

Role	Access
Anonymous	Scam Analyzer (text only), public community posts, Time Machine
Registered	Full Analyzer, learning modules with progress, reports, community, leaderboard, sandbox
Admin	All of the above + user management, content moderation, analytics dashboard

Core Workflows

Scam Check:   Input text / URL / image  →  AI analysis  →  Threat score + recommendations
Learning:     Select module  →  Study content  →  Take quiz  →  Earn points & achievements
Reporting:    Fill report form  →  Submit  →  Export PDF  →  Track status
Time Machine: Choose era  →  Interactive storyline  →  Decision-based learning

📚 API Reference

All API endpoints are prefixed with /api. Endpoints marked 🔒 require a valid Firebase token in the Authorization: Bearer <token> header. Endpoints marked 👑 require admin role.

Auth

GET  /api/auth/test          Health check
GET  /api/auth/profile  🔒   Get user profile
PUT  /api/auth/profile  🔒   Update user profile

POST /register and POST /login are deprecated — use Firebase Auth directly.

Scam Analyzer

POST /api/analyzer/analyze         Analyze content (text: public · URL: 🔒)
GET  /api/analyzer/history    🔒   Get analysis history
GET  /api/analyzer/session/:id 🔒  Get specific session
GET  /api/analyzer/configuration   Get analyzer config

Community

GET    /api/community/posts          List posts (paginated)
POST   /api/community/posts     🔒   Create post
GET    /api/community/posts/:id      Get post
PUT    /api/community/posts/:id 🔒   Update post
DELETE /api/community/posts/:id 🔒   Delete post
GET    /api/community/comments/:id   Get comments
POST   /api/community/comments  🔒   Add comment
GET    /api/community/topics         List topics
POST   /api/community/topics   👑    Create topic

Reports

POST   /api/reports          🔒  Submit report
GET    /api/reports          🔒  List user reports
GET    /api/reports/:id      🔒  Get report
PUT    /api/reports/:id      🔒  Update report
DELETE /api/reports/:id      🔒  Delete report
GET    /api/reports/export/:id 🔒 Export as PDF

Time Machine Scenarios

GET  /api/scenarios              All scenarios
GET  /api/scenarios/:era         By era (2015 | 2025 | 2035)
GET  /api/scenarios/id/:id       Single scenario

OCR

POST /api/ocr/analyze   Extract text from image (PNG, JPG, JPEG)

Admin 👑

GET    /api/admin/stats                System statistics
GET    /api/admin/analytics            Detailed analytics
GET    /api/admin/users                List users
PUT    /api/admin/users/:id            Update user
POST   /api/admin/users/:id/ban        Ban/unban user
DELETE /api/admin/users/:id            Delete user
GET    /api/admin/posts                All posts
PUT    /api/admin/posts/:id            Moderate post
DELETE /api/admin/posts/:id            Delete post
GET    /api/admin/reports              All reports
PUT    /api/admin/reports/:id          Update report status
GET    /api/admin/scams                Scam database
POST   /api/admin/scams                Add scam entry
PUT    /api/admin/scams/:id            Update entry
DELETE /api/admin/scams/:id            Delete entry

🚀 Deployment

Vercel (Recommended)

npm i -g vercel
vercel          # Preview deploy
vercel --prod   # Production deploy

Frontend is a static Vite build
Backend runs as a serverless catch-all (api/[...path].js)
Set all environment variables in the Vercel dashboard
See vercel.json for routing and header config

Render

# Set these in the Render dashboard:
# MONGODB_URI, FIREBASE_ADMIN_*, HUGGINGFACE_API_KEY, JWT_SECRET, SESSION_SECRET

Built-in keep-alive to prevent server sleep
MongoDB connection retry logic included
See md/RENDER_DEPLOYMENT.md for full guide

Manual / PM2

npm run build              # Build frontend
npm install -g pm2
pm2 start server/server.js --name walrus
pm2 save && pm2 startup

🧪 Testing

npm run test:all              # Run all test suites
npm run test:validation       # Input validation tests
npm run test:security         # Security middleware tests
npm run test:quick            # Quick security smoke test
npm run test:server           # Server security test
npm run test:manual           # Manual testing guide

Coverage areas: input sanitization · XSS/CSRF/NoSQL injection · API security · auth & authorization

🛡️ Security Architecture

Layer	Mechanism
Authentication	Firebase Auth (frontend) + Firebase Admin SDK (backend)
Authorization	Role-based access control (user / admin)
Input Validation	Server-side validation + sanitization
XSS Protection	`isomorphic-dompurify`
CSRF Protection	Custom CSRF token middleware
NoSQL Injection	Custom MongoDB query sanitizer
Rate Limiting	`express-rate-limit` per endpoint
Security Headers	`helmet.js` with Content Security Policy
Password Hashing	`bcrypt` with salt rounds
Sessions	`express-session` with secure cookie config

🔧 Troubleshooting

MongoDB won't connect

sudo systemctl status mongod   # Check status
sudo systemctl start mongod    # Start if stopped

Verify MONGODB_URI in .env is correct. For Atlas, ensure your IP is whitelisted.

Firebase auth errors

Double-check all VITE_FIREBASE_* values match your Firebase project
Ensure Email/Password auth provider is enabled
Verify FIREBASE_ADMIN_PRIVATE_KEY includes the full -----BEGIN/END PRIVATE KEY----- delimiters
Check Firestore security rules match firestore.rules

Port already in use

kill -9 $(lsof -ti:5000)   # Kill backend port
kill -9 $(lsof -ti:5173)   # Kill frontend port

Build errors / dependency issues

rm -rf node_modules package-lock.json
npm install
npm run typecheck   # Check TypeScript errors

🤝 Contributing

Contributions are welcome from educators, security researchers, designers, and full-stack engineers.

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/cyberawareness.git

# 2. Create a branch
git checkout -b feature/your-feature-name

# 3. Make changes and test
npm run test:all

# 4. Commit and push
git commit -m "feat: describe your change"
git push origin feature/your-feature-name

# 5. Open a Pull Request

Code standards: TypeScript throughout · ESLint config enforced · tests required for new features · update docs when changing behavior · never commit real secrets

Safe exploration areas:

src/ — React/Vite frontend (Time Machine, learning modules, i18n)
server/ — Express services (scam analysis, reporting, admin)
api/ — Vercel-ready serverless endpoints

📄 Additional Documentation

File	Description
`md/DEPLOYMENT_README.md`	Multi-platform deployment guide (Vercel, Render, Heroku, AWS)
`md/RENDER_DEPLOYMENT.md`	Step-by-step Render.com guide
`md/LOCALAZY_SETUP.md`	Translation management with Localazy

📜 License

Distributed under the MIT License.

🙏 Acknowledgments

Built on the shoulders of great open-source work — React, Express.js, MongoDB, Firebase, Tailwind CSS, Hugging Face, Tesseract.js, and Lucide Icons.

Built with ❤️ for a safer digital India

WALRUS — Empowering citizens with cybersecurity knowledge and protection

⬆ Back to top

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
api		api
assests		assests
public		public
server		server
src		src
.env.example		.env.example
.env.production.example		.env.production.example
.gitignore		.gitignore
README.md		README.md
Upgrade plan walrus cyberawareness.md		Upgrade plan walrus cyberawareness.md
app.json		app.json
eng.traineddata		eng.traineddata
eslint.config.js		eslint.config.js
firestore.rules		firestore.rules
index.html		index.html
localazy.json.template		localazy.json.template
package.json		package.json
postcss.config.js		postcss.config.js
render.yaml		render.yaml
start_server.py		start_server.py
tailwind.config.js		tailwind.config.js
testing.txt		testing.txt
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel-headers.json		vercel-headers.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation