Advanced form validation and protection utility that intelligently detects and blocks automated bot submissions while maintaining a seamless experience for legitimate users.
- Smart Honeypot Fields - Context-aware invisible fields that attract bots
- Behavioral Analysis - Tracks mouse movements, typing patterns, and interaction sequences
- Timing Analysis - Detects suspiciously fast or robotic form completion
- Browser Fingerprinting - Identifies headless browsers and automation tools
- Flexible Integration - Works with any form, framework, or CMS
- Zero Friction - Invisible to legitimate users
- Configurable Scoring - Adjustable sensitivity levels
npm install form-guardianJust add a data attribute to your forms:
<script src="form-guardian.js" data-auto-init="true"></script>
<form data-bot-protection="true" data-min-time="5000">
<input type="text" name="name" required>
<input type="email" name="email" required>
<textarea name="message"></textarea>
<button type="submit">Send</button>
</form>import FormGuardian from 'form-guardian';
const guardian = new FormGuardian({
debug: true,
scoreThreshold: 70
});
// Protect specific forms
guardian.protect('#contact-form', {
minFillTime: 8000,
onSubmit: (data) => {
if (!data.blocked) {
// Process legitimate submission
console.log('Valid submission:', data.formData);
}
},
onBlock: (reason, score) => {
console.log('Blocked submission:', reason, score);
}
});import { useEffect } from 'react';
import FormGuardian from 'form-guardian';
function ContactForm() {
useEffect(() => {
const guardian = new FormGuardian();
guardian.protect('#contact-form');
return () => guardian.destroy();
}, []);
return (
<form id="contact-form">
<input name="name" type="text" placeholder="Your Name" />
<input name="email" type="email" placeholder="Your Email" />
<textarea name="message" placeholder="Your Message"></textarea>
<button type="submit">Send Message</button>
</form>
);
}<template>
<form ref="contactForm">
<input name="name" type="text" placeholder="Your Name" />
<input name="email" type="email" placeholder="Your Email" />
<textarea name="message" placeholder="Your Message"></textarea>
<button type="submit">Send Message</button>
</form>
</template>
<script>
import FormGuardian from 'form-guardian';
export default {
mounted() {
this.guardian = new FormGuardian();
this.guardian.protect(this.$refs.contactForm);
},
beforeDestroy() {
this.guardian?.destroy();
}
}
</script>const guardian = new FormGuardian({
autoInit: true, // Auto-protect forms with data attributes
debug: false, // Enable console logging
globalMinTime: 3000, // Default minimum fill time (ms)
globalMaxTime: 300000, // Default maximum fill time (ms)
defaultHoneypots: 2, // Number of honeypot fields to inject
scoreThreshold: 70, // Block threshold (0-100)
endpoint: '/api/verify' // Optional server-side validation endpoint
});guardian.register('my-form', {
minFillTime: 8000, // Minimum time to fill form
maxFillTime: 600000, // Maximum time before timing out
behaviorTracking: true, // Track mouse/keyboard behavior
fingerprintTracking: true, // Browser fingerprinting
honeypotFields: ['backup_email', 'website'], // Custom honeypot field names
onSubmit: (data) => {
// Handle valid submissions
console.log('Form data:', data.formData);
console.log('Analysis score:', data.score);
},
onBlock: (reason, score) => {
// Handle blocked submissions
console.log('Blocked:', reason);
// Maybe show CAPTCHA or additional verification
}
});Invisible form fields that bots typically fill but humans cannot see:
<!-- These are automatically injected and hidden -->
<input type="email" name="email_confirmation" style="display: none;">
<input type="url" name="website_url" style="position: absolute; left: -9999px;">- Too Fast: Form completed in under 3 seconds (configurable)
- Too Slow: Form abandoned for hours then suddenly submitted
- Robotic Patterns: Perfectly regular typing intervals
- No Mouse Movement: Bots often don't simulate mouse movement
- No Keyboard Input: Copy-paste only behavior
- Unnatural Field Order: Bots may fill fields programmatically
- Missing Focus Events: Real users focus on fields before typing
- Webdriver Detection: Automation tools leave traces
- Headless Browsers: Missing window properties
- Suspicious User Agents: Bot-like browser signatures
Form Guardian uses a 0-100 scoring system:
- 0-30: Likely human (allow submission)
- 31-70: Suspicious (consider additional verification)
- 71-100: Likely bot (block submission)
Scores are cumulative based on multiple detection methods:
- Honeypot interaction: +80 points
- No mouse movement: +40 points
- Too fast completion: +50 points
- Webdriver detected: +60 points
const express = require('express');
const app = express();
app.post('/contact', (req, res) => {
const { _guardian_score, _guardian_reasons, ...formData } = req.body;
if (_guardian_score > 70) {
return res.status(400).json({
error: 'Submission blocked',
reason: _guardian_reasons
});
}
// Process legitimate submission
processContactForm(formData);
res.json({ success: true });
});<?php
if ($_POST['_guardian_score'] > 70) {
http_response_code(400);
echo json_encode(['error' => 'Submission blocked']);
exit;
}
// Process form data
$clean_data = array_filter($_POST, function($key) {
return !str_starts_with($key, '_guardian_');
}, ARRAY_FILTER_USE_KEY);
processForm($clean_data);
?>// Analyze a form without submitting
const analysis = await guardian.analyzeForm('my-form');
console.log('Current score:', analysis.score);
console.log('Detected issues:', analysis.reasons);
if (analysis.score > 50) {
// Show CAPTCHA or additional verification
showCaptcha();
}const guardian = new FormGuardian({
debug: true,
onSubmit: (data) => {
// Send analytics to your server
fetch('/api/form-analytics', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
score: data.score,
reasons: data.reasons,
blocked: data.blocked,
formId: 'contact-form'
})
});
}
});// Start with basic protection, add features based on bot activity
let currentThreshold = 70;
guardian.protect('#form', {
scoreThreshold: currentThreshold,
onBlock: (reason, score) => {
// If getting a lot of bots, tighten security
if (score > 90) {
currentThreshold = 60; // Lower threshold = stricter
guardian.updateConfig('form', { scoreThreshold: currentThreshold });
}
}
});- Chrome/Edge 60+
- Firefox 55+
- Safari 12+
- Mobile browsers (iOS Safari, Chrome Mobile)
Q: Will this block legitimate users? A: Form Guardian is designed to be invisible to real users. The scoring system requires multiple suspicious signals before blocking.
Q: Can sophisticated bots bypass this? A: While no solution is 100% foolproof, Form Guardian uses multiple detection layers that make it very difficult for automated tools to bypass.
Q: Does this work with AJAX forms? A: Yes! Form Guardian works with any form submission method - traditional posts, AJAX, fetch, etc.
Q: What about accessibility? A: Honeypot fields are properly hidden with ARIA attributes and don't interfere with screen readers or keyboard navigation.
MIT License - see LICENSE file for details.
Contributions welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.