react-behavior-guard 🛡️

A production-ready React library to detect suspicious behavioral patterns in online exams, assessments, or secure web apps and generate a real-time risk score.

Features

• ⚡️ Lightweight & Tree-shakable: Built with Vite library mode for minimal bundle size.
• 🔒 Tab/Focus Tracking: Tracks tab switches, window blur, and visibility changes.
• ✂️ Clipboard Guard: Detects copy and paste events.
• 🖱️ Interaction Monitor: Tracks rapid click bursts and mouse movement out of window.
• ⏳ Inactivity Detection: Detects idle time and penalizes accordingly.
• 🛡️ Risk Scoring: Automatically calculates a risk score (0–100) based on severity.

Installation

npm install react-behavior-guard
# or
yarn add react-behavior-guard

Usage Example

import React from 'react';
import { useBehaviorGuard } from 'react-behavior-guard';

function ExamPortal() {
  // Initialize with custom strictness levels
  const { riskScore, warnings, analytics } = useBehaviorGuard({
    trackTabSwitch: true,
    penaltyTabSwitch: 25,    // Custom penalty for tab switching
    penaltyCopyPaste: 50,    // High penalty for clipboard actions
    idleTimeoutMs: 15000     // 15 seconds inactivity threshold
  });

  return (
    <div style={{ padding: '20px' }}>
      <h1>Secure Online Exam</h1>
      
      <div style={{ 
        padding: '10px', 
        borderRadius: '8px',
        color: 'white',
        backgroundColor: riskScore > 60 ? '#ef4444' : '#10b981' 
      }}>
        Current Risk Score: **{riskScore} / 100**
      </div>
      
      <h3>Activity Logs</h3>
      <ul>
        {warnings.map((msg, i) => <li key={i}>{msg}</li>)}
      </ul>
    </div>
  );
}

export default ExamPortal;

API Reference

useBehaviorGuard(options)

Option	Type	Default	Description
trackTabSwitch	boolean	true	Tracks when user switches tabs or minimizes window.
trackMouseActivity	boolean	true	Tracks if the mouse leaves the browser window area.
trackCopyPaste	boolean	true	Monitors clipboard copy and paste actions.
trackRapidClick	boolean	true	Detects suspicious rapid clicking (click bursts).
trackIdleTime	boolean	true	Penalizes if user is inactive for a set duration.
idleTimeoutMs	number	30000	Inactivity threshold in milliseconds.

Analytics Object

The hook returns an analytics object containing:

• tabSwitches: Total number of focus/visibility losses.
• copyPasteCount: Number of clipboard events.
• rapidClicks: Number of rapid click incidents.
• idleIncidents: Number of inactivity timeouts.
• mouseLeaveCount: Number of times the mouse left the window.

API Reference

useBehaviorGuard(options)

Option	Type	Default	Description
trackTabSwitch	boolean	true	Tracks when user switches tabs or minimizes window.
trackMouseActivity	boolean	true	Tracks if the mouse leaves the browser window area.
trackCopyPaste	boolean	true	Monitors clipboard copy and paste actions.
trackRapidClick	boolean	true	Detects suspicious rapid clicking (click bursts).
trackIdleTime	boolean	true	Penalizes if user is inactive for a set duration.
idleTimeoutMs	number	30000	Inactivity threshold in milliseconds.

Analytics Object

The hook returns an analytics object containing:

• tabSwitches: Total number of focus/visibility losses.
• copyPasteCount: Number of clipboard events.
• rapidClicks: Number of rapid click incidents.
• idleIncidents: Number of inactivity timeouts.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a PR.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Developer

Developed with ❤️ by Ayush Rai (@ayushraistudio)

License

Distributed under the MIT License. See LICENSE for more information.