Metadata-Version: 2.4
Name: flask-honeypot
Version: 0.1.0
Summary: A comprehensive honeypot framework with admin dashboard
Author-email: Carter <support@certgames.com>
License: MIT
Project-URL: Homepage, https://github.com/CarterPerez-dev/honeypot-framework
Project-URL: Repository, https://github.com/CarterPerez-dev/honeypot-framework
Keywords: flask,honeypot,security,react,admin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=2.2.0
Requires-Dist: flask-cors>=3.0.0
Requires-Dist: flask-session[redis]>=0.4.0
Requires-Dist: redis>=4.3.0
Requires-Dist: pymongo>=4.0.0
Requires-Dist: geoip2>=4.5.0
Requires-Dist: python-dotenv>=0.20.0
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: user-agents>=2.2.0
Requires-Dist: python-socketio[client]>=5.7.0
Requires-Dist: gevent>=21.12.0
Requires-Dist: gunicorn>=20.1.0
Requires-Dist: werkzeug>=2.2.0
Requires-Dist: ipaddress>=1.0.0
Requires-Dist: requests>=2.27.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: black>=22.10.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# 🍯 Flask-Honeypot Framework

```
 ██████╗ ██████╗ ████████╗     ██╗  ██╗ ██████╗ ███╗   ██╗███████╗██╗   ██╗██████╗  ██████╗ ████████╗██╗
██╔════╝ ██╔═══██╗╚══██╔══╝     ██║  ██║██╔═══██╗████╗  ██║██╔════╝╚██╗ ██╔╝██╔══██╗██╔═══██╗╚══██╔══╝██║
██║  ███╗██║   ██║   ██║        ███████║██║   ██║██╔██╗ ██║█████╗   ╚████╔╝ ██████╔╝██║   ██║   ██║   ██║
██║   ██║██║   ██║   ██║        ██╔══██║██║   ██║██║╚██╗██║██╔══╝    ╚██╔╝  ██╔═══╝ ██║   ██║   ██║   ╚═╝
╚██████╔╝╚██████╔╝   ██║        ██║  ██║╚██████╔╝██║ ╚████║███████╗   ██║   ██║     ╚██████╔╝   ██║   ██╗
 ╚═════╝  ╚═════╝    ╚═╝        ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝   ╚═╝   ╚═╝      ╚═════╝    ╚═╝   ╚═╝
 ```

<p align="center">
  <strong>A comprehensive honeypot system for detecting, trapping, and analyzing unauthorized access attempts</strong>
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-installation">Installation</a> •
  <a href="#-configuration">Configuration</a> •
  <a href="#-technical-overview">Technical Overview</a> •
  <a href="#-honeypot-traps">Honeypot Traps</a> •
  <a href="#-admin-dashboard">Admin Dashboard</a> •
  <a href="#-integration">Integration</a> •
  <a href="#-docker-deployment">Docker Deployment</a> •
  <a href="#-security-considerations">Security</a> •
  <a href="#-license">License</a>
</p>

## 🔍 Features

Flask-Honeypot is a security monitoring tool designed to detect and analyze unauthorized access attempts by creating convincing decoys that attract and trap potential attackers.

- **Multiple honeypot trap types** - 20+ pre-built decoys including admin panels, WordPress, phpMyAdmin, file managers, and more
- **Interactive deceptive elements** - Clickable buttons, forms, fake file downloads, and simulated errors to keep attackers engaged
- **Rich attacker profiling** - Collect IPs, user agents, GeoIP data, ASN info, and behavioral patterns
- **Real-time Tor/proxy detection** - Identify attackers attempting to hide their true location
- **Advanced security analytics** - Visual dashboards showing attack patterns, geographic distribution, and threat levels
- **Auto-blocking capabilities** - Rate limiting and IP blocking with configurable thresholds
- **Detailed interaction logging** - Every click, form submission, and interaction attempt is recorded
- **Containerized deployment** - Quick setup with Docker and docker-compose
- **Scalable architecture** - MongoDB for storage and Redis for session management
- **MaxMind GeoIP integration** - Optional geographic and ASN tracking

## 🚀 Quick Start

### The fastest way to deploy (Docker):

```bash
# Clone the repository
git clone https://github.com/CarterPerez-dev/honeypot-framework.git
cd honeypot-framework

# Run the setup script
./setup_honeypot.sh

# Start the honeypot
docker-compose up --build -d
```

That's it! Your honeypot is now running. Access the admin dashboard at:
```
http://your-server/honey/login
```

Use the admin password from your `.env` file (generated by the setup script).

## 📦 Installation

### Option 1: Docker Deployment (Recommended for Production)

1. Clone the repository:
```bash
git clone https://github.com/CarterPerez-dev/honeypot-framework.git
cd honeypot-framework
```

2. Run the setup script:
```bash
./setup_honeypot.sh
```

This script will:
- Check dependencies (Python, Docker, Docker Compose)
- Create a Python virtual environment
- Install Flask-Honeypot
- Generate a secure configuration in `.env`
- Prompt for optional MaxMind license key

3. Start the honeypot:
```bash
docker-compose up -d
```

### Option 2: Python Package Installation

If you want to integrate the honeypot into an existing Flask application:

```bash
pip install flask-honeypot
```

Then in your Python code:

```python
from honeypot import create_honeypot_app

app = create_honeypot_app()

if __name__ == "__main__":
    app.run()
```

### Requirements

- Python 3.8+
- MongoDB 4.0+
- Redis 5.0+ (for session management)
- Docker & Docker Compose (for containerized deployment)
- (Optional) MaxMind GeoIP database license key

## ⚙️ Configuration

Configuration options can be set via:
1. Environment variables
2. The `.env` file
3. Direct parameters to `create_honeypot_app()`

### Key Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `SECRET_KEY` | Secret key for sessions | Randomly generated |
| `MONGO_URI` | MongoDB connection URI | `mongodb://localhost:27017/honeypot` |
| `REDIS_HOST` | Redis host | `localhost` |
| `REDIS_PORT` | Redis port | `6379` |
| `REDIS_PASSWORD` | Redis password | `None` |
| `HONEYPOT_ADMIN_PASSWORD` | Admin dashboard password | Required |
| `HONEYPOT_RATE_LIMIT` | Max requests per period | `15` |
| `HONEYPOT_RATE_PERIOD` | Rate limit period in seconds | `60` |
| `MAXMIND_LICENSE_KEY` | MaxMind GeoIP license key | `None` |
| `HONEYPOT_DATA_DIRECTORY` | Directory for data storage | `/app/data` |
| `FLASK_ENV` | Environment (`development`/`production`) | `production` |

Example `.env` file:
```
SECRET_KEY="f926dfdd9fffdafedd195ab8b30e60aa8157736475be9646c41b9b1994e47089"
MONGO_USER="supersecretstrongpassword123!"
MONGO_PASSWORD="Bigstrongpasswordyea112"
REDIS_PASSWORD="Ih9zfuUrgoxnir5qz"
HONEYPOT_ADMIN_PASSWORD="2WW6TUhgfdu3BkuApLA"
HONEYPOT_RATE_LIMIT=5
HONEYPOT_RATE_PERIOD=60
FLASK_ENV=production
HONEYPOT_DATA_DIRECTORY=/app/data
```

## 🔬 Technical Overview

Flask-Honeypot uses a Flask backend to serve deceptive content that appears legitimate to attackers while logging all interactions for security analysis.

### Structure

```bash
.
├── LICENSE
├── MANIFEST.in
├── README.md
├── examples
│   ├── App-js.py
│   ├── enhanced_admin_security.py
│   └── example_flask_integration.py
├── honeypot
│   ├── __init__.py
│   ├── _version.py
│   ├── backend
│   │   ├── __init__.py
│   │   ├── app.py
│   │   ├── helpers
│   │   │   ├── __init__.py
│   │   │   ├── db_utils.py
│   │   │   ├── geoip_manager.py
│   │   │   ├── proxy_detector.py
│   │   │   └── unhackable.py
│   │   ├── middleware
│   │   │   ├── __init__.py
│   │   │   └── csrf_protection.py
│   │   ├── routes
│   │   │   ├── __init__.py
│   │   │   ├── admin.py
│   │   │   ├── honeypot.py
│   │   │   ├── honeypot_pages.py
│   │   │   └── honeypot_routes.py
│   │   └── templates
│   │       ├── honeypot
│   │       │   ├── admin-dashboard.html
│   │       │   ├── admin-login.html
│   │       │   ├── cloud-dashboard.html
│   │       │   ├── cms-dashboard.html
│   │       │   ├── cpanel-dashboard.html
│   │       │   ├── database-dashboard.html
│   │       │   ├── debug-console.html
│   │       │   ├── devops-dashboard.html
│   │       │   ├── ecommerce-dashboard.html
│   │       │   ├── filesharing-dashboard.html
│   │       │   ├── forum-dashboard.html
│   │       │   ├── framework-dashboard.html
│   │       │   ├── generic-login.html
│   │       │   ├── generic-page.html
│   │       │   ├── iot-dashboard.html
│   │       │   ├── mail-dashboard.html
│   │       │   ├── mobile-api.html
│   │       │   ├── monitoring-dashboard.html
│   │       │   ├── phpmyadmin-dashboard.html
│   │       │   ├── remote-access-dashboard.html
│   │       │   ├── shell.html
│   │       │   └── wp-dashboard.html
│   │       └── redirection
│   │           ├── step1.html
│   │           ├── step10.html
│   │           ├── step11.html
│   │           ├── step12.html
│   │           ├── step13.html
│   │           ├── step14.html
│   │           ├── step15.html
│   │           ├── step2.html
│   │           ├── step3.html
│   │           ├── step4.html
│   │           ├── step5.html
│   │           ├── step6.html
│   │           ├── step7.html
│   │           ├── step8.html
│   │           └── step9.html
│   ├── cli.py
│   ├── config
│   │   ├── __init__.py
│   │   └── settings.py
│   ├── database
│   │   ├── models.py
│   │   ├── mongo-init.js
│   │   └── mongodb.py
│   ├── deploy_templates
│   │   ├── Dockerfile.backend.template
│   │   ├── Dockerfile.nginx.template
│   │   ├── __init__.py
│   │   ├── dev-nginx.conf.template
│   │   ├── docker-compose.dev.yml.template
│   │   ├── docker-compose.yml.template
│   │   ├── dot_env.example
│   │   └── nginx
│   │       ├── nginx.conf.template
│   │       └── sites-enabled
│   │           └── proxy.conf.template
│   ├── frontend
│   │   ├── README.md
│   │   ├── package-lock.json
│   │   ├── package.json
│   │   └── src
│   │       ├── App.js
│   │       ├── components
│   │       │   ├── JsonSyntaxHighlighter.js
│   │       │   ├── LoadingPlaceholder.js
│   │       │   └── csrfHelper.js
│   │       ├── index.css
│   │       ├── index.js
│   │       ├── reportWebVitals.js
│   │       ├── static
│   │       │   ├── css
│   │       │   │   ├── HoneypotTab.css
│   │       │   │   ├── HtmlInteractionsTab.css
│   │       │   │   ├── JsonSyntaxHighlighter.css
│   │       │   │   ├── LoadingPlaceholder.css
│   │       │   │   ├── admin.css
│   │       │   │   └── login.css
│   │       │   ├── js
│   │       │   │   ├── admin.js
│   │       │   │   └── login.js
│   │       │   └── tabs
│   │       │       ├── HoneypotTab.js
│   │       │       ├── HtmlInteractionsTab.js
│   │       │       └── OverviewTab.js
│   │       └── utils
│   │           └── dateUtils.js
│   └── utils
│       └── generate_config.py
├── mongo-init.js
├── pyproject.toml
└── setup_honeypot.sh
```

### Core Components

- **Flask Backend**: Serves honeypot pages and logs interactions
- **MongoDB**: Stores interaction data, attacker profiles, and logs
- **Redis**: Manages secure sessions for the admin interface
- **GeoIP Detection**: Identifies attacker locations (requires MaxMind)
- **Proxy Detector**: Identifies Tor exit nodes and known proxies

### How It Works

1. When an attacker visits a honeypot URL (like `/admin` or `/wp-login.php`), they see a realistic-looking page
2. The system logs detailed information about the visitor
3. As they interact with the page (clicking buttons, submitting forms), each action is recorded
4. Security staff can monitor these interactions through the admin dashboard
5. Repeated suspicious behavior can trigger automatic blocking

## 🕸️ Honeypot Traps

The framework includes many deceptive pages designed to look like common targets:

### Admin Panels

- **Generic Admin Dashboards**: Look like typical login portals
- **WordPress Admin**: Fake WP-Admin login and dashboard
- **phpMyAdmin**: Simulated database administration panel
- **cPanel**: Fake hosting control panel

### Example: Admin Dashboard Trap

The admin dashboard honeypot includes:
- Fake login forms that collect credentials
- Simulated database management interfaces
- Interactive elements that appear to provide system access
- Deceptive file upload/download capabilities
- Fake terminal access that records command attempts
-more details
Here's what attackers might see:

```
pictures here
```

Each interaction is timestamped, geolocated, and stored for analysis.

### Additional Trap Types

- **Database Admin**: MySQL, MongoDB, Redis interfaces
- **File Managers**: Cloud storage and file sharing
- **Email Systems**: Webmail interfaces
- **CMS Systems**: Joomla, Drupal, and other CMS platforms
- **E-commerce**: Shopify, WooCommerce admin panels
- **Network Devices**: Router configuration panels
- **Remote Access**: SSH, RDP, VNC interfaces
- **Development Tools**: Jenkins, GitLab, etc.
- **API Endpoints**: Simulated REST APIs

## 📊 Admin Dashboard

The admin dashboard provides security staff with detailed insights:

- **Overview**: Summary of recent activity
- **Detailed Stats**: In-depth analysis of attack patterns
- **Geographic View**: Map showing attack origins
- **Threat Analysis**: Categorization of attack types
- **Raw Logs**: Complete interaction records
- **System Health**: Monitoring of honeypot operation
-more here

## 🔄 Integration

### Integration with Existing Flask Applications

```python
from flask import Flask
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from honeypot import create_honeypot_app

# Create your main application
main_app = Flask(__name__)

@main_app.route('/')
def index():
    return "My secure application"

# Create the honeypot application
honeypot_app = create_honeypot_app()

# Mount the honeypot at a specific URL prefix
application = DispatcherMiddleware(main_app, {
    '/security': honeypot_app  # Maps to /security/* URLs
})

# For direct Flask execution
if __name__ == "__main__":
    # Create a WSGI app wrapper
    from werkzeug.serving import run_simple
    run_simple('localhost', 5000, application, use_reloader=True)
```

### Advanced Integration

For more advanced integration options (such as selective blueprint registration or frontend integration), see the `examples/` directory.

## 🐳 Docker Deployment

For production deployments, use the Docker configuration:

```bash
# Generate deployment files (if you haven't run setup_honeypot.sh)
python -m honeypot.cli init

# Start in production mode
docker-compose up --build -d

# For development mode with hot reloading
docker-compose -f docker-compose.dev.yml up --build -d
```

The Docker deployment includes:
- Nginx web server
- Flask backend
- MongoDB database
- Redis for session management

## 🔐 Security Considerations

### Admin Security

- **Access Restriction**: Limit admin dashboard access to trusted IPs
- **Strong Authentication**: Use complex passwords for the admin interface
- **HTTPS**: Always use SSL/TLS in production, refer to documentation for HTTPS
- **Regular Rotation**: Change admin credentials frequently
- **VPN Access**: Consider placing the admin interface behind a VPN

### Honeypot Placement

- **Segregation**: Run honeypots on separate infrastructure from production systems
- **Firewall Rules**: Implement strict firewall rules for honeypot traffic
- **Resource Limits**: Prevent honeypots from being used for further attacks
- **Legal Compliance**: Ensure your honeypot deployment complies with local laws

### Enhanced Security Module

For additional security, consider using the enhanced security module (refer to examples documentation):

```python
from honeypot import create_honeypot_app
from examples.enhanced_admin_security import setup_enhanced_security

app = create_honeypot_app()
app = setup_enhanced_security(app)
```

This provides:
- IP whitelisting
- Enhanced brute force protection
- Security headers
- Advanced session protection

## 📖 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

```
 ╭─────────────────────────────────────────────────────────────────╮
 │       🐝   Flask-Honeypot Framework - Catch attackers red-handed!   🐝       │
 ╰─────────────────────────────────────────────────────────────────╯
```

For questions, contributions, or support, please open an issue on GitHub.
