SecureGate.js

Version: 1.0.0
Author: Yousef M. Y. Al Sabbah
License: MIT
Repository: https://github.com/Yosef-AlSabbah/SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams

Overview

SecureGate.js is a lightweight, framework-agnostic JavaScript library designed to protect web-based examination systems from unauthorized access via emulators, virtual machines, and sandboxes. The library combines advanced device detection with motion-based verification to ensure exam integrity on legitimate mobile devices.

Key Features

• Virtual Machine Detection: Identifies and blocks access from virtual machines, emulators, and sandboxes using WebGL renderer analysis
• Motion-Based Verification: Requires users to perform figure-8 motion patterns on mobile devices for authentication
• Submit Protection: Prevents form submission until successful verification is completed
• Persistent Verification: Maintains verification status across sessions with configurable time-to-live
• Anti-Tampering: Detects and reports suspicious behavior with forced re-verification
• Framework Agnostic: Works with any LMS or web application through a flexible reporter interface
• Zero Dependencies: Pure JavaScript implementation with no external runtime dependencies
• Modular Architecture: Clean separation of concerns for maintainability and extensibility
• Environment Configuration: Supports environment variables for deployment flexibility

Table of Contents

1. Installation
2. Quick Start
3. Configuration
4. Reporter System
5. API Reference
6. Browser Support
7. Security Considerations
8. Contributing
9. License

Installation

NPM Installation

npm install securegate.js

Manual Installation

1. Clone the repository:

git clone https://github.com/Yosef-AlSabbah/SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams.git
cd SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams

2. Install dependencies and build:

npm install
npm run build

3. Include the built file in your project:

<script type="module" src="path/to/dist/securegate.min.js"></script>

Quick Start

Basic Implementation

1. Include the verification curtain HTML (from templates/curtain.html) at the beginning of your page body

2. Include the SecureGate.js script:

<script type="module" src="dist/securegate.min.js"></script>

3. Your exam content will be automatically protected

With Custom Reporter

<script type="module">
  import SecureGate from './dist/securegate.min.js';
  import { HTTPReporter } from './dist/securegate.min.js';
  
  // Configure custom reporter
  const reporter = new HTTPReporter('https://your-server.com/api/violations', {
    headers: {
      'Authorization': 'Bearer your-token'
    }
  });
  
  SecureGate.setReporter(reporter);
</script>

Configuration

Environment Variables

Create a .env file in your project root (see .env.example):

# Verification persistence (milliseconds)
VERIFIED_TTL_MS=7200000

# Force verification duration (milliseconds)
FORCE_TTL_MS=86400000

# Timer duration (seconds)
TIMER_DURATION=12

# Maximum failed attempts
MAX_FAILS=5

# Motion detection thresholds
MOTION_SPREAD_THRESHOLD=15
MOTION_HIGH_INCREMENT=2.3

# VM detection patterns (comma-separated)
VM_PATTERNS=swift,llvmpipe,virtual,vmware,hyper,box,emu

Runtime Configuration

Override configuration at runtime:

window.SecureGateConfig = {
  TIMER_DURATION: 15,
  MAX_FAILS: 3,
  MOTION_SPREAD_THRESHOLD: 10
};

Reporter System

SecureGate.js uses a flexible reporter system to handle security violation reporting. This allows integration with any backend system.

Built-in Reporters

Console Reporter (Development)

import { ConsoleReporter } from 'securegate.js';
SecureGate.setReporter(new ConsoleReporter());

HTTP Reporter (REST API)

import { HTTPReporter } from 'securegate.js';

const reporter = new HTTPReporter('https://api.example.com/violations', {
  headers: {
    'Authorization': 'Bearer token',
    'X-API-Key': 'your-key'
  },
  transform: (report) => ({
    attempt_id: report.attemptId,
    type: report.violationType,
    timestamp: report.timestamp
  })
});

SecureGate.setReporter(reporter);

XHR Reporter (Legacy Support)

import { XHRReporter } from 'securegate.js';

const reporter = new XHRReporter('https://api.example.com/violations', {
  method: 'POST',
  contentType: 'application/json'
});

SecureGate.setReporter(reporter);

Callback Reporter (Custom Logic)

import { CallbackReporter } from 'securegate.js';

const reporter = new CallbackReporter(async (report) => {
  // Custom reporting logic
  console.log('Violation detected:', report);
  await fetch('/api/log', {
    method: 'POST',
    body: JSON.stringify(report)
  });
  return true;
});

SecureGate.setReporter(reporter);

Multi Reporter (Multiple Destinations)

import { MultiReporter, ConsoleReporter, HTTPReporter } from 'securegate.js';

const reporter = new MultiReporter([
  new ConsoleReporter(),
  new HTTPReporter('https://primary.example.com/api'),
  new HTTPReporter('https://backup.example.com/api')
]);

SecureGate.setReporter(reporter);

Creating Custom Reporters

Extend the BaseReporter class:

import { BaseReporter } from 'securegate.js';

class CustomReporter extends BaseReporter {
  async report(report) {
    // Implement your reporting logic
    console.log('Custom report:', report);
    
    // Return true for success, false for failure
    return true;
  }
  
  isAvailable() {
    // Return true if reporter can be used
    return true;
  }
}

SecureGate.setReporter(new CustomReporter());

Report Data Structure

interface ViolationReport {
  attemptId: number;           // Unique exam attempt identifier
  sessionKey: string;          // Session authentication key
  violationCount: number;      // Number of violations
  violationType: string;       // Type: 'VM_DETECTED', 'TAMPERING', etc.
  timestamp: number;           // Unix timestamp (milliseconds)
  duration: number;            // Duration in seconds
  metadata: {
    isOffline: string;         // Offline status code
    userAgent: string;         // Browser user agent
    timestamp: number;         // Unix timestamp (seconds)
  };
}

API Reference

Main Module

import SecureGate from 'securegate.js';

// Start SecureGate manually
SecureGate.start();

// Get version
console.log(SecureGate.version); // "1.0.0"

// Set custom reporter
SecureGate.setReporter(reporterInstance);

// Access reporter classes
const { HTTPReporter } = await SecureGate.reporters.HTTPReporter();

Configuration API

// Runtime configuration
window.SecureGateConfig = {
  TIMER_DURATION: 15,
  MAX_FAILS: 3
};

// Custom reporter
window.SecureGateReporter = customReporterInstance;

Browser Support

Browser	Desktop	Mobile
Chrome	Blocked*	Supported
Firefox	Blocked*	Supported
Safari	Blocked*	Supported**
Edge	Blocked*	Supported
Mobile Chrome	N/A	Supported
Mobile Safari	N/A	Supported**

*Desktop browsers are intentionally blocked to prevent VM/emulator access
**iOS 13+ requires user permission for DeviceOrientation API

Requirements

• ES6+ JavaScript support
• WebGL support (for VM detection)
• DeviceOrientation API (for mobile verification)
• LocalStorage support (for persistence)

Security Considerations

Important Limitations

SecureGate.js is a client-side security measure and has inherent limitations:

1. Client-Side Nature: Determined attackers with sufficient technical skills may potentially bypass client-side JavaScript controls
2. Not a Complete Solution: Must be combined with server-side validation and monitoring
3. Browser Variations: Detection efficacy may vary across different browsers and devices
4. Evolving Threats: New virtualization technologies may not be immediately detected

Defense in Depth Strategy

For maximum security, combine SecureGate.js with:

• Server-side monitoring and behavioral analytics
• Video proctoring systems
• Network traffic analysis and anomaly detection
• Time-based access restrictions
• IP address tracking and geolocation
• Browser fingerprinting
• Multi-factor authentication

Best Practices

1. Regular Updates: Maintain the latest version for improved detection capabilities
2. Log Monitoring: Implement regular review of violation reports
3. Comprehensive Testing: Test on all target devices and browsers before deployment
4. User Communication: Clearly inform users about system requirements
5. Fallback Procedures: Provide alternative assessment methods when necessary
6. Legal Compliance: Ensure compliance with privacy regulations and institutional policies

Contributing

Contributions are welcome. Please review the following documents before contributing:

• Contributing Guidelines
• Contributor License Agreement
• Security Policy

Development Setup

git clone https://github.com/Yosef-AlSabbah/SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams.git
cd SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams
npm install
npm run build

License

This project is licensed under the MIT License. See the LICENSE file for details.

All contributors must agree to the Contributor License Agreement which grants the project owner relicensing rights while allowing open-source use under MIT terms.

Author

Yousef M. Y. Al Sabbah

Repository: https://github.com/Yosef-AlSabbah/SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams

Version History

See CHANGELOG.md for detailed version history and release notes.

Support

• Issues: https://github.com/Yosef-AlSabbah/SecureGate.js-Anti-Emulator-VM-Sandbox-Motion-Verification-for-Web-Exams/issues
• Documentation: See docs/ directory
• Security: See SECURITY.md

---

Copyright (c) 2025 Yousef M. Y. Al Sabbah. Licensed under MIT License.