# Bot Lockout

A lightweight WordPress plugin that protects your site from AI scrapers and bad bots using cryptographic JavaScript challenges.

**License**: GPL v3 or later  
**License URI**: https://www.gnu.org/licenses/gpl-3.0.html

## Description

Bot Lockout is a security plugin that implements a lightweight cryptographic challenge system to distinguish between real browsers and automated bots. Unlike traditional CAPTCHA systems, it uses JavaScript-based cryptographic operations that are easy for humans but difficult for most bots to solve.

### Key Features

- **Lightweight Protection**: Uses minimal resources and doesn't impact site performance
- **Cryptographic Challenges**: SHA-256 hashing with date and user agent binding
- **Smart Whitelisting**: Allow trusted bots (Google, Bing, etc.) and IP addresses
- **Flexible Configuration**: Exclude specific pages and customize block messages
- **Comprehensive Logging**: Track blocked attempts for analysis
- **Custom Styling**: Add custom CSS to match your site's design
- **Daily Token Expiration**: Prevents long-term bypass attempts

### How It Works

1. **Initial Request**: When a visitor accesses your site, the plugin checks for a valid challenge token
2. **JavaScript Challenge**: If no token exists, a cryptographic challenge is presented
3. **Token Generation**: The challenge combines the current date with the user agent string and creates a SHA-256 hash
4. **Secure Storage**: The hash is base64 encoded, truncated, and stored as a secure cookie
5. **Validation**: Subsequent requests are validated against the stored token

### Security Features

- **Cryptographically Secure**: Uses SHA-256 hashing algorithm
- **Time-Bound**: Tokens expire daily to prevent long-term bypass
- **Browser-Specific**: User agent binding prevents token sharing
- **Secure Cookies**: Implements proper cookie security settings
- **Whitelist Support**: Allow trusted services and IP addresses

## Security Advisory

Bot Lockout is one layer in a broader security strategy, not a silver bullet.

While Bot Lockout is designed to deter automated bots and AI scrapers through cryptographic JavaScript challenges, no single solution can offer complete protection. Web scraping technologies continue to evolve, and determined actors may find ways to bypass front-end defenses.

This plugin should be used as part of a multi-layered approach to website security. For best results, we recommend combining Bot Lockout with additional tools such as server-level firewalls, rate limiting, CAPTCHA systems, behavior-based threat detection, and CDN-level bot mitigation.

Kognetiks makes no guarantee that this plugin will block all unwanted bot traffic. It is intended as a proactive, lightweight defense mechanism—not a comprehensive security system. Users are responsible for evaluating their own threat model and deploying appropriate complementary protections.

## Installation

### Single Site Installation

#### From WordPress Plugin Directory (Recommended)

1. Go to **Plugins > Add New** in your WordPress admin
2. Search for "Bot Lockout"
3. Click **Install Now** and then **Activate**

#### Manual Installation

1. Download the plugin ZIP file
2. Go to **Plugins > Add New > Upload Plugin** in your WordPress admin
3. Choose the ZIP file and click **Install Now**
4. Click **Activate Plugin**

#### FTP Installation

1. Extract the plugin files
2. Upload the `bot-lockout` folder to `/wp-content/plugins/`
3. Go to **Plugins** in your WordPress admin
4. Find "Bot Lockout" and click **Activate**

### Multi-Site Installation

Bot Lockout supports WordPress Multi-Site installations with both network-wide and site-specific configurations.

#### Network Activation (Recommended)

1. Go to **My Sites > Network Admin > Plugins** in your WordPress admin
2. Find "Bot Lockout" and click **Network Activate**
3. Configure settings at **My Sites > Network Admin > Settings > Bot Lockout**

#### Site-Specific Activation

1. Go to **My Sites > Network Admin > Plugins** in your WordPress admin
2. Find "Bot Lockout" and click **Enable** for specific sites
3. Configure settings at **Settings > Bot Lockout** on each individual site

#### Configuration Options

- **Network-Wide Settings**: When network activated, settings apply to all sites
- **Site-Specific Settings**: When activated per site, each site has independent settings
- **Mixed Configuration**: You can have network-wide defaults with site-specific overrides

## Configuration

### Single Site Configuration

1. Go to **Settings > Bot Lockout** in your WordPress admin
2. Enable the plugin by checking "Enable Bot Lockout Protection"
3. Customize the block message that appears to blocked requests
4. Set the challenge timeout (default: 24 hours)

### Multi-Site Configuration

#### Network-Wide Settings

1. Go to **My Sites > Network Admin > Settings > Bot Lockout**
2. Configure settings that will apply to all sites in the network
3. These settings serve as defaults for all sites

#### Site-Specific Settings

1. Go to **Settings > Bot Lockout** on any individual site
2. Configure settings specific to that site
3. These settings override network-wide defaults

### Allowed User Agents

Add user agent strings for trusted bots and services:

- `Googlebot` - Google Search
- `Bingbot` - Bing Search
- `DuckDuckBot` - DuckDuckGo
- `Slurp` - Yahoo Search
- `Baiduspider` - Baidu Search

### Excluded Pages

Specify pages or paths that should be excluded from protection:

- `/api/` - API endpoints
- `/feed/` - RSS feeds
- `/sitemap.xml` - Sitemap files
- `/robots.txt` - Robots file

### IP Whitelist

Add IP addresses that should bypass the challenge:

- Your office IP address
- Trusted service IPs
- Development server IPs

### Custom CSS

Add custom CSS to style the block message or other elements:

```css
.bot-lockout-block {
    background: #f0f0f0;
    padding: 20px;
    border-radius: 5px;
    text-align: center;
    font-family: Arial, sans-serif;
}
```

## Testing

The plugin includes a built-in test tool:

1. Go to **Settings > Bot Lockout**
2. Scroll to the "Test Challenge" section
3. Enter a user agent string (your browser's user agent is auto-filled)
4. The generated token will be automatically calculated
5. Click "Test Challenge" to verify the system works correctly

## Performance Impact

Bot Lockout is designed to be lightweight and fast:

- **JavaScript Challenge**: Runs only once per day per browser
- **Minimal Server Processing**: Efficient cookie-based validation
- **No Database Queries**: Normal operation doesn't require database access
- **Small File Size**: Minimal plugin footprint

## Troubleshooting

### Common Issues

**Plugin blocks legitimate users**
- Check if JavaScript is enabled in the browser
- Verify the user agent is not in the allowed list
- Check if the IP is whitelisted
- Ensure the page is not in the excluded pages list

**Plugin doesn't block bots**
- Verify the plugin is enabled
- Check that the page is not excluded
- Ensure the user agent is not whitelisted
- Test the challenge manually

**Performance issues**
- Disable logging if not needed
- Reduce the number of whitelisted items
- Check for conflicts with other security plugins

### Multi-Site Specific Issues

**Settings not applying to all sites**
- Ensure the plugin is network activated
- Check if you're configuring network-wide settings
- Verify site-specific settings aren't overriding network defaults

**Inconsistent behavior across sites**
- Check if the plugin is activated on all sites
- Verify settings are configured correctly for each site
- Ensure network-wide settings are properly set

**Network admin access issues**
- Verify you have `manage_network_options` capability
- Check if you're logged in as a super admin
- Ensure the plugin is properly network activated

### Debug Mode

Enable WordPress debug mode to see detailed error messages:

```php
// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

## Security Considerations

- **Not a Complete Solution**: Bot Lockout is one layer of protection, not a complete security solution
- **JavaScript Required**: Users with JavaScript disabled will be blocked
- **Cookie Dependencies**: Users who clear cookies will need to complete the challenge again
- **Regular Updates**: Keep the plugin updated for the latest security improvements

## Support

### Documentation

- [Plugin Homepage](https://wordpress.org/plugins/bot-lockout/)
- [FAQ](https://wordpress.org/plugins/bot-lockout/faq/)
- [Support Forum](https://wordpress.org/support/plugin/bot-lockout/)

### Reporting Issues

If you encounter a bug or have a feature request:

1. Check the [existing issues](https://wordpress.org/support/plugin/bot-lockout/)
2. Create a new support topic with:
   - WordPress version
   - Plugin version
   - Detailed description of the issue
   - Steps to reproduce
   - Error messages (if any)

## Development

### Requirements

- WordPress 5.0 or higher
- PHP 7.4 or higher
- Modern browser with JavaScript support

### Building from Source

1. Clone the repository
2. Install dependencies: `npm install`
3. Build assets: `npm run build`
4. Test the plugin

### Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Changelog

### 1.0.0
- Initial release
- JavaScript cryptographic challenges
- Admin settings interface
- Whitelist support
- Logging functionality
- Custom CSS support
- Test challenge tool

## License

This plugin is licensed under the GPL v3 or later.

```
Copyright (C) 2025 Stephen Howell

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
```

## Credits

- **Developer**: Kogentiks