VB6 MOD : MDL Device Guard 3.4

[desmomax]

**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.

[glennrocksvb]

Thanks for sharing this free mod.

I just have one clarification. Why use its own SMTP and not re-use the existing SMTP or mail configuration in AdminCP?

[desmomax]

I preferred to keep this solution independent from the vBulletin server. However, I can add the option to choose in the next version

[glennrocksvb]

I see your point. My thought is that if a forum is already using SMTP in its mail settings, administrators would likely reuse those same settings for the mod. If they aren't currently using SMTP and are just using the native PHP mail service on the server, they would need to set up a new SMTP specifically for this mod.

From that perspective, it seems there would still be some additional configuration involved, and I'm not sure there's a significant benefit to separating these settings from the existing mail configuration. That said, this is just my personal view, and I can certainly see that others may have different preferences or use cases.

[desmomax]

## MDL Device Guard

**Version:** 3.5- 2026-06-17

**Major: hybrid email delivery, vBulletin native mail as default.**

### Added
- New email delivery strategy: tries vBulletin's native `vB_Mail::create2()`
API first (no extra config needed if vB mail is working), then falls
back to the optional `mdl_smtp_config.php` (override), then to PHP `mail()`
as last resort.
- New helper `mdl_bootstrap_vb()`: idempotent vBulletin bootstrap reused
by email and thread features.

### Changed
- **`mdl_smtp_config.php` is now OPTIONAL.** Most admins won't need it
anymore — vBulletin's existing SMTP/mail config is reused. The file
is only needed when an isolated SMTP server is desired (e.g. dedicated
alert account separate from forum email).
- Debug log entries now show which method delivered the email:
`vbmail` (native), `smtp` (file override), `mail` (PHP fallback).
- `mdl_smtp_config.php.example` updated with clearer explanation of
when to use this override vs default native vB mail.

### Notes for upgraders from v3.4
- If you currently have `mdl_smtp_config.php` set up, it continues to
work exactly as before (it's the override that takes precedence).
- If you delete `mdl_smtp_config.php`, the engine will automatically
fall back to vBulletin's native mail — useful if you want unified
email handling forum-wide.
- No XML re-import needed (no schema changes).

[desmomax]

UPDATED!!! **Version:** 3.7
**Target platform:** vBulletin 6.x (tested on 6.2.1)
**License:** Free to use, modify and redistribute

Last changelog:
## [3.7] - 2026-06-25

**Bugfix release: smiley artifact in thread + email not enriched.**

### Fixed
- **Smiley artifact in BBCode thread**: dates in the thread body were
formatted as `H:i:s` (e.g. `08:14:35`), which vBulletin's BBCode
engine was parsing as smiley codes (e.g. the `:14:` substring would
render as a clapping-hands emoji). Replaced with `H.i.s` (dots) in
every thread date — clear and smiley-proof.
*Plain-text emails keep `H:i:s` since they're not BBCode-parsed.*


### Changed
- Engine bumped to v7.8.
- `mdl_build_email_it / _en` rewritten with the new enriched layout
(text-based, plain ASCII, aligned columns for readability in plain
text mail clients).

### Notes for upgraders from v3.6
- Replace `mdl_dg_track.php` with v7.8 on the server. No XML re-import
needed. No DB schema changes.
**Target platform:** vBulletin 6.x (tested on 6.2.1)
**License:** Free to use, modify and redistribute

Last changelog:
## [3.6] - 2026-06-25

**Major: enriched staff thread with account history, risk score, and quick links.**

### Added
- **Account history section** for both new and existing accounts:
registration date with relative age, registration IP, post count,
and (for the existing account) last visit timestamp.
- **Existing account email** is now shown — useful for visual comparison
with the new account's email (subtle similarities, plus addressing, etc).
- **Other accounts section** — when the cookie token has been seen with
more than 2 userids in total, all extra userids are listed with their
first-seen date and clickable profile links.
- **Previous alerts cross-reference** — up to 5 prior alerts involving
either the new or existing user, with review status.
- **Risk score 0-100** — automatic risk evaluation with color-coded
label (MINIMO / BASSO / MEDIO / ALTO in IT, MINIMAL / LOW / MEDIUM /
HIGH in EN) computed from these factors:
- Account age (newer = riskier)
- Same registration IP between new and existing
- Existing account dormancy (long dormancy = riskier)
- Existing account post count (low investment = riskier)
- Multiple userids on the same cookie
- Recent prior alerts on the same users
- **Risk factors breakdown** — each contributing factor shown with its
weight, for transparency.
- **Quick action links section** at the bottom (profile, post search)
for both users, so moderators can act quickly.
- New helper functions in the engine: `mdl_enrich_maildata`,
`mdl_fmt_age_it`, `mdl_fmt_age_en`, `mdl_risk_label_it`, `mdl_risk_label_en`.

### Changed
- Engine bumped to v7.7.
- `mdl_build_thread_body_it` / `_en` signatures gained an extra `$url`
parameter (the forum base URL, for link generation).
- The enrichment SQL queries (4 extra SELECTs) only run when an alert
is actually being raised — zero overhead on normal pixel hits.

### Notes for upgraders from v3.5
- No XML changes — just replace `mdl_dg_track.php` with v7.7 on the server.
- No DB schema changes — uses existing tables.
- No new AdminCP settings.