**Version:** 3.4
**Target platform:** vBulletin 6.x (tested on 6.2.1)
**License:** Free to use, modify and redistribute
## 1. Requirements
- vBulletin 6.x installed and working
- PHP 7.4 or higher (tested up to PHP 8.3)
- MySQL 5.7 or higher with vBulletin table prefix (empty prefix is fine)
- FTP/SFTP access to the forum document root
- AdminCP access with permissions to install products
- For emails: Gmail account with app password, or any reachable SMTP server
- For auto-posting: an existing staff-only channel and an admin user ID
to use as author for the alert threads
MDL Device Guard is a silent multi-account detection system for vBulletin 6
forums. It tracks devices via a persistent SHA-256 cookie and detects when
two or more accounts share the same physical device, even after multiple
login/logout cycles.
### Key features
- **Cookie-based device fingerprint**: 64-character SHA-256 token in the
user's browser, persists across login/logout (does not use `bb` prefix,
so vBulletin's cookie-cleanup doesn't touch it).
- **IP + UserAgent fallback**: when the cookie is missing or blocked,
matches on IP + UserAgent within a 24h window.
- **Smart first-login detection**: alerts fire the first time a (token,
userid) pair is seen — covers fresh registrations AND dormant accounts
that wake up on a device already known to another user.
- **Real-time email notifications via SMTP**: bilingual (Italian/English)
email sent to the configured webmaster based on the recipient's language.
- **Automatic staff forum thread**: every alert auto-publishes a richly
formatted thread in a configurable staff-only channel, attributed to a
configurable admin user. Moderators subscribed to that channel get
notifications automatically.
- **Standalone PHP engine**: does NOT bootstrap the full vBulletin
framework on every page hit (uses direct mysqli), so it's fast and stable.
The vB framework is loaded only when an alert fires (rare event).
- **Native vBulletin product**: installs via standard AdminCP product
import. Exposes 6 configurable options.
### Detection logic
```
USER LOADS PAGE -> PIXEL FIRES -> mdl_dg_track.php
|
| identify user via session table
| read or generate cookie token (mdl_dg_tk)
|
v
FIRST TIME this (token, userid) pair seen?
|
|--YES--> any other userid using same token?
| |
| YES --> ALERT (cookie match) + email + staff thread
| NO --> any other userid with same IP+UA in last 24h?
| |
| YES --> ALERT (ip+ua match) + email + staff thread
| NO --> just save fingerprint (no alert)
|
|--NO--> already known, just update last_seen
```
# Package contents
```
mdl_device_guard_v3.4/
├── README.md this file
├── CHANGELOG.md version history
├── docs/
│ ├── INSTALLATION_IT.md Italian installation manual
│ ├── INSTALLATION_EN.md English installation manual
│ └── ARCHITECTURE.md technical design notes
├── server-files/
│ ├── mdl_dg_track.php core engine
│ └── mdl_smtp_config.php.example SMTP config template
├── vbulletin/
│ ├── product-mdl_device_guard-IT.xml Italian product XML
│ └── product-mdl_device_guard-EN.xml English product XML
└── utilities/
├── mdl_dg_diag.php installation diagnostics
├── mdl_dg_check.php log/fingerprint inspector
├── mdl_dg_reset.php manual tables truncate
└── mdl_smtp_test.php standalone SMTP tester
```
## Quick start
1. Upload `server-files/mdl_dg_track.php` to your forum document root.
2. Configure SMTP: copy `mdl_smtp_config.php.example` to `mdl_smtp_config.php`,
edit credentials, chmod 600.
3. Import the matching XML (`-IT.xml` or `-EN.xml`) via AdminCP →
Products & Hooks → Manage Products → Import.
4. Empty caches: AdminCP → Maintenance → Empty Caches → check all → Run.
5. Rebuild styles: AdminCP → Styles & Templates → Maintenance →
Rebuild Style Information.
6. Configure 6 options in AdminCP → Settings → MDL Device Guard.
7. Done. The system tracks devices automatically.
## Testing notes
This mod has been extensively production-tested on an
Italian-language vBulletin 6.2.1 forum (ilbraccoitaliano.net) over multiple
weeks. The English code paths (English emails, English threads, English
AdminCP labels via the EN.xml) have been reviewed for correctness but not
yet field-tested on an English-language forum. If you install it on an
English-language vBulletin and notice anything off, please report back —
the fixes are typically minor BBCode/translation tweaks.
Attached Files
