Scan Browser

Enterprise-grade browser diagnostics and device fingerprinting platform

Features • Installation • Documentation • API Reference • Contributing

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Installation
• Configuration
• Usage
• API Reference
• Data Model
• Admin Dashboard
• Security
• Deployment
• Screenshots
• Contributing
• License

🎯 Overview

Scan Browser is a production-ready diagnostics platform that captures comprehensive browser and device telemetry including engine identification, hardware specifications, network characteristics, battery status, and geolocation data. Built with enterprise-grade security and scalability in mind, it features compressed storage, real-time analytics, and an intuitive admin dashboard.

Key Highlights

• Real-time Diagnostics: Instant browser and device profiling with sub-second response times
• Geospatial Visualization: Interactive mapping with Leaflet.js for location-based insights
• Compressed Storage: Gzip-compressed MongoDB storage reducing data footprint by 70%+
• Dual Persistence: MongoDB primary storage with flat-file JSON mirroring for redundancy
• Analytics Dashboard: Comprehensive admin interface with geo-hotspots and distribution metrics
• Production Hardened: Rate limiting, CORS protection, and health monitoring built-in

✨ Features

Core Capabilities

• 🔍 Deep Scan Engine - One-click comprehensive device profiling
• 🗺️ Geolocation Mapping - Real-time coordinate visualization with Leaflet
• 💾 Smart Caching - Local persistence with 20-minute session retention
• 📊 Analytics Suite - Geo-hotspots, IP distribution, and browser analytics
• 🔐 Security Hardened - Rate limiting, CORS controls, and input validation
• 📈 Scalable Storage - Gzip compression with MongoDB + JSON file mirroring
• ⚡ Zero Build Frontend - CDN-based dependencies for instant deployment
• 🏥 Health Monitoring - Built-in health checks for production monitoring

🏗️ Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│                 │         │                  │         │                 │
│  Static HTML/   │◄───────►│   Express API    │◄───────►│    MongoDB      │
│  CSS/JS Client  │  HTTP   │  (Node.js)       │  Async  │   (Primary)     │
│  + Leaflet.js   │         │  - Rate Limiting │         │                 │
│                 │         │  - CORS          │         └─────────────────┘
└─────────────────┘         │  - Compression   │                   │
                            │                  │                   │
                            └──────────────────┘                   │
                                     │                             │
                                     ▼                             │
                            ┌──────────────────┐                  │
                            │   logs.json      │◄─────────────────┘
                            │   (Mirror)       │    Sync Write
                            └──────────────────┘

Request Flow

1. Client initiates scan via browser API calls
2. Express middleware validates and rate-limits requests
3. Payload compressed with gzip (70%+ size reduction)
4. Dual-write to MongoDB and local JSON file
5. Real-time analytics aggregation
6. Admin dashboard queries aggregated statistics

🛠️ Tech Stack

Frontend

• HTML5/CSS3/ES6+ - Modern web standards
• Leaflet.js - Interactive mapping library
• Font Awesome - Icon library via CDN
• Vanilla JavaScript - Zero framework dependencies

Backend

• Node.js 18+ - JavaScript runtime
• Express 4.x - Web application framework
• Mongoose - MongoDB ODM with schema validation
• express-rate-limit - Request throttling
• cors - Cross-origin resource sharing
• zlib - Native compression
• dotenv - Environment configuration

Database & Storage

• MongoDB 5.0+ - Primary document store
• JSON Files - Redundant flat-file storage

📦 Installation

Prerequisites

• Node.js 18.x or higher
• MongoDB 5.0+ (local or Atlas)
• npm or yarn package manager

Quick Start

# Clone repository
git clone https://github.com/yourusername/scan-browser.git
cd scan-browser

# Backend setup
cd backend
npm install
cp .env.example .env
# Edit .env with your MongoDB credentials
npm run dev

# Frontend setup (new terminal)
cd ../frontend
npx serve
# Or use Python: python -m http.server 8001

Detailed Installation

1. Clone the repository

   git clone https://github.com/yourusername/scan-browser.git
   cd scan-browser

2. Install backend dependencies

   cd backend
   npm install

3. Configure environment variables

   cp .env.example .env

   See Configuration section for details.

4. Start the backend server

   # Development mode (with hot reload)
   npm run dev
   
   # Production mode
   npm start

5. Serve the frontend

   # Option 1: Using npx
   cd ../frontend
   npx serve
   
   # Option 2: Using Python
   python -m http.server 8001
   
   # Option 3: Using any static file server

6. Access the application

   • Main app: http://localhost:8001
   • Admin dashboard: http://localhost:8001/Admin.html
   • API health: http://localhost:4000/health

⚙️ Configuration

Create a .env file in the backend/ directory:

# Database Configuration
MONGODB_URI=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>?retryWrites=true&w=majority
DB_NAME=browser_scan

# Server Configuration
PORT=4000
NODE_ENV=development

# CORS Configuration (optional)
ALLOWED_ORIGINS=http://localhost:8001,http://localhost:3000

# Rate Limiting (optional)
RATE_LIMIT_WINDOW_MS=600000
RATE_LIMIT_MAX_REQUESTS=100

Frontend Configuration

Update the API endpoints in your frontend files:

frontend/script.js

const BACKEND_URL = 'http://localhost:4000/receive';

frontend/Admin.html

const API_BASE = 'http://localhost:4000/api/admin';

Environment Variables

Variable	Description	Default	Required
MONGODB_URI	MongoDB connection string	-	Yes
DB_NAME	Database name	browser_scan	Yes
PORT	Server port	4000	No
NODE_ENV	Environment mode	development	No
ALLOWED_ORIGINS	CORS allowed origins	* (dev)	No

🚀 Usage

Running the Scan

1. Open the application in your browser
2. Click the "Start Scan" button
3. Grant geolocation permission (optional)
4. View real-time results including:
   • Browser and engine details
   • Hardware specifications
   • Network information
   • Battery status
   • Geolocation coordinates (if permitted)
   • Interactive map visualization

Accessing Analytics

1. Navigate to /Admin.html
2. View comprehensive analytics:
   • Total request counts
   • Browser distribution charts
   • Geographic hotspots
   • IP address distribution
   • Recent scan logs

Local Storage

Scan results are automatically cached for 20 minutes, allowing quick access to recent scans without re-running diagnostics.

📡 API Reference

Base URL: http://localhost:4000

Endpoints

POST /receive

Capture and store scan payload.

Request Body:

{
  "browser": "Chrome 120.0.0",
  "cores": 8,
  "memory": "16 GB",
  "latitude": "28.6139",
  "longitude": "77.2090",
  "battery": "87%",
  "connection": "4g",
  "timestamp": "2025-12-30T12:34:56.000Z"
}

Success Response (200):

{
  "status": "captured",
  "message": "Logged to DB and local storage."
}

Error Response (429):

{
  "error": "Too many requests, please try again later."
}

---

GET /api/admin/stats

Retrieve aggregate statistics.

Success Response (200):

{
  "totalRequests": 1523,
  "browsers": [
    { "_id": "Chrome", "count": 890 },
    { "_id": "Firefox", "count": 423 },
    { "_id": "Safari", "count": 210 }
  ]
}

---

GET /api/admin/analytics

Get detailed analytics data.

Success Response (200):

{
  "geoHotspots": [
    {
      "_id": { "lat": "28.61", "lng": "77.20" },
      "count": 145
    }
  ],
  "ipDistribution": [
    { "_id": "203.0.113.42", "count": 67 },
    { "_id": "198.51.100.23", "count": 45 }
  ]
}

---

GET /api/admin/logs

Fetch all stored logs with decompressed payloads.

Success Response (200):

[
  {
    "_id": "65a1b2c3d4e5f6789",
    "payload": {
      "browser": "Chrome",
      "cores": 8,
      "memory": "16 GB"
    },
    "ip": "203.0.113.42",
    "browser": "Chrome",
    "receivedAt": "2025-12-30T12:34:56.000Z"
  }
]

---

GET /health

Health check endpoint for monitoring.

Success Response (200):

{
  "status": "healthy",
  "timestamp": "2025-12-30T12:34:56.000Z"
}

Rate Limiting

All endpoints are rate-limited to 100 requests per 10 minutes per IP address. Exceeding this limit returns a 429 Too Many Requests response.

📊 Data Model

Log Schema

{
  payload: Buffer,           // gzip-compressed JSON (required)
  ip: String,                // Client IP address
  browser: String,           // Browser identifier
  isCompressed: Boolean,     // Compression flag (default: true)
  receivedAt: Date,          // Timestamp (default: Date.now)
  createdAt: Date,           // Auto-generated by Mongoose
  updatedAt: Date            // Auto-generated by Mongoose
}

Compression Details

• Algorithm: gzip (zlib)
• Compression Ratio: Typically 70-85% size reduction
• Decompression: Transparent on retrieval via /api/admin/logs

Indexes

• receivedAt: Descending (optimizes recent log queries)
• browser: Ascending (optimizes aggregation queries)
• ip: Ascending (optimizes IP-based analytics)

📈 Admin Dashboard

The admin dashboard provides comprehensive analytics and monitoring capabilities.

Features

• Real-time Statistics: Total requests and browser distribution
• Geographic Heatmap: Visual representation of scan locations
• IP Distribution: Top IP addresses by request count
• Recent Logs: Paginated view of latest scans
• Responsive Design: Mobile-friendly interface

Access

Navigate to /Admin.html or http://localhost:8001/Admin.html

Configuration

Update the API base URL in Admin.html:

const API_BASE = 'http://localhost:4000/api/admin';

🔐 Security

Implemented Security Measures

Rate Limiting

• Window: 10 minutes (600,000ms)
• Max Requests: 100 per IP
• Strategy: Rolling window with IP-based tracking

CORS Configuration

• Development: Permissive (*) for local testing
• Production: Strict allowlist (e.g., https://scan-browser.vercel.app)
• Methods: GET, POST
• Headers: Content-Type, Authorization

Input Validation

• Schema validation via Mongoose
• Type checking on all endpoints
• Sanitization of user inputs

Data Protection

• Compression prevents payload tampering visibility
• IP logging for audit trails
• No sensitive data stored in plaintext

Best Practices

1. Always set NODE_ENV=production in production environments
2. Use environment variables for sensitive configuration
3. Enable MongoDB authentication and use strong credentials
4. Regularly update dependencies to patch vulnerabilities
5. Monitor rate limit hits for potential abuse patterns
6. Implement SSL/TLS for production deployments

Security Checklist

• MongoDB credentials secured in environment variables
• Production CORS origins configured
• Rate limiting enabled
• SSL certificate installed (production)
• Regular dependency audits (npm audit)
• Logs monitored for suspicious activity

🚢 Deployment

Environment Setup

1. Set production environment variables

   NODE_ENV=production
   MONGODB_URI=<your-production-mongodb-uri>
   PORT=4000

2. Update frontend API URLs

   • Set BACKEND_URL in script.js to your production API
   • Set API_BASE in Admin.html to your production API

3. Configure CORS

   • Update allowlist in server.js to match your frontend domain

Platform-Specific Guides

Vercel (Frontend)

# Install Vercel CLI
npm i -g vercel

# Deploy from frontend directory
cd frontend
vercel --prod

Render (Backend)

1. Create new Web Service
2. Connect your GitHub repository
3. Configure:
   • Build Command: cd backend && npm install
   • Start Command: cd backend && npm start
4. Add environment variables in Render dashboard

MongoDB Atlas

1. Create cluster at mongodb.com/atlas
2. Configure network access (allow your server IPs)
3. Create database user
4. Copy connection string to MONGODB_URI

Production Checklist

• Environment variables configured
• Frontend API URLs updated
• CORS origins configured for production domain
• MongoDB connection tested
• Health endpoint accessible
• Rate limiting verified
• SSL/TLS certificate installed
• Monitoring and logging configured

Monitoring

Use the /health endpoint for uptime monitoring:

curl https://your-api-domain.com/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-12-30T12:34:56.000Z"
}

📸 Screenshots

Home Screen

Interactive Map & Results

Admin Dashboard

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Test thoroughly
5. Commit with conventional commits

   git commit -m "feat: add amazing feature"

6. Push to your fork

   git push origin feature/amazing-feature

7. Open a Pull Request

Commit Convention

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Code Style

• Follow existing code formatting
• Use meaningful variable names
• Comment complex logic
• Write descriptive commit messages
• Update documentation for new features

⬆ Back to Top

Made with ❤️ by the Scan Browser Team

Report Bug • Request Feature