## django-honeyguard [![pypi version][1]][2] [![rtd][3]][4]
[![license][5]][6] [![python version][7]][2] [![django version][8]][9] [![build][10]][11]
📖 Documentation: https://django-honeyguard.readthedocs.io
HoneyGuard is a reusable Django app that provides fake admin login pages (honeypots) for Django and WordPress, logs suspicious requests, detects timing anomalies, and optionally sends alerts. Protect your real admin by wasting attackers’ time and gathering intelligence safely.
### Features
- Live timing detection (too-fast/too-slow submissions)
- Hidden honeypot field detection
- Fake login pages for Django Admin and WordPress
- Comprehensive logging with risk scores
- Pluggable signal to integrate custom handlers
- Optional email alerts and console logging
- URL include or drop-in views usage
- Strict settings validation at startup
### Preview
The package ships with templates for:
- `django_honeyguard/django_admin_login.html` (fake Django admin)
- `django_honeyguard/wp_admin_login.html` (fake WordPress admin)
Include the URLs and visit `/admin/` or `/wp-admin.php` to see the honeypots in action.
### Requirements
- Django >= 5.0.0
- Python >= 3.10
### Installation
Install from PyPI:
```bash
pip install django-honeyguard
```
Add the app to `INSTALLED_APPS`:
```python
# settings.py
INSTALLED_APPS = [
# ...
"django_honeyguard",
]
```
Include the URLs (Option A), or wire views directly (Option B):
```python
# urls.py
from django.urls import include, path
urlpatterns = [
# Option A: include both fake admin pages
path("", include("django_honeyguard.urls")),
# Option B: use individual views
# from django_honeyguard.views import FakeDjangoAdminView, FakeWPAdminView
# path("admin/", FakeDjangoAdminView.as_view()),
# path("wp-admin.php", FakeWPAdminView.as_view()),
]
```
Run migrations (creates log table):
```bash
python manage.py migrate
```
### Settings (settings.py)
You can configure HoneyGuard via a `HONEYGUARD` dictionary or individual `HONEYGUARD_*` settings. Defaults shown below:
```python
HONEYGUARD = {
# Email alerts
"EMAIL_RECIPIENTS": [],
"EMAIL_SUBJECT_PREFIX": "🚨 Honeypot Alert",
"EMAIL_FROM": None, # Uses Django DEFAULT_FROM_EMAIL if None
"EMAIL_FAIL_SILENTLY": True, # Do not crash on email errors
# Timing detection (seconds)
"TIMING_TOO_FAST_THRESHOLD": 2.0,
"TIMING_TOO_SLOW_THRESHOLD": 600.0,
# Logging
"ENABLE_CONSOLE_LOGGING": True,
"LOG_LEVEL": "WARNING", # DEBUG, INFO, WARNING, ERROR, CRITICAL
# Detection behavior
"ENABLE_GET_METHOD_DETECTION": False, # Detect on GET as well as POST
# Field limits
"MAX_USERNAME_LENGTH": 150,
"MAX_PASSWORD_LENGTH": 128,
"WORDPRESS_USERNAME_MAX_LENGTH": 60,
"WORDPRESS_PASSWORD_MAX_LENGTH": 255,
# Error messages (shown on fake pages)
"DJANGO_ERROR_MESSAGE": (
"Please enter a correct username and password. Note that both fields"
" may be case-sensitive."
),
"WORDPRESS_ERROR_MESSAGE": (
"<strong>Error:</strong> The password you entered for the username is incorrect."
),
}
```
### Usage
- Visit `/admin/` for the fake Django admin login page
- Visit `/wp-admin.php` for the fake WordPress login page
- Submissions and suspicious GETs will be logged via the `honeypot_triggered` signal
Listen to the `honeypot_triggered` signal to add custom behaviors:
```python
from django_honeyguard.signals import honeypot_triggered
from django.dispatch import receiver
@receiver(honeypot_triggered)
def my_handler(sender, request, data, **kwargs):
# data contains ip_address, path, username, timing info, risk_score, etc.
pass
```
### Documentation
Complete documentation is available at: https://django-honeyguard.readthedocs.io/
Running the docs locally:
```bash
git clone https://github.com/alihtt/django-honeyguard.git
cd django-honeyguard
python -m venv .venv && source .venv/bin/activate
pip install -r docs/requirements.txt
cd docs && make html
# open _build/html/index.html in your browser
```
### Notes
- This package does not replace Django’s real authentication; it provides decoy pages and logging.
- Always secure your real admin at a non-obvious URL and behind proper authentication and rate limiting.
[1]: https://img.shields.io/pypi/v/django-honeyguard.svg
[2]: https://pypi.org/project/django-honeyguard/
[3]: https://readthedocs.org/projects/django-honeyguard/badge/?version=latest
[4]: https://django-honeyguard.readthedocs.io/en/latest/
[5]: https://img.shields.io/badge/license-BSD--3--Clause-blue
[6]: https://github.com/alihtt/django-honeyguard/blob/main/LICENSE
[7]: https://img.shields.io/pypi/pyversions/django-honeyguard.svg
[8]: https://img.shields.io/badge/Django-%3E%3D%205.0.0-green.svg
[9]: https://www.djangoproject.com
[10]: https://img.shields.io/github/actions/workflow/status/alihtt/django-honeyguard/tests.yml?branch=main
[11]: https://github.com/alihtt/django-honeyguard/actions
Raw data
{
"_id": null,
"home_page": null,
"name": "django-honeyguard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "admin, django, honeypot, security, wordpress, wp-admin",
"author": null,
"author_email": "Ali Hatami <aliht.workspace@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/4e/85480b60e9fb9d968e67faff92c287b6a5eaf10510e4dddb9aa6570e575e/django_honeyguard-1.0.0.tar.gz",
"platform": null,
"description": "## django-honeyguard [![pypi version][1]][2] [![rtd][3]][4]\n\n[![license][5]][6] [![python version][7]][2] [![django version][8]][9] [![build][10]][11]\n\n\ud83d\udcd6 Documentation: https://django-honeyguard.readthedocs.io\n\nHoneyGuard is a reusable Django app that provides fake admin login pages (honeypots) for Django and WordPress, logs suspicious requests, detects timing anomalies, and optionally sends alerts. Protect your real admin by wasting attackers\u2019 time and gathering intelligence safely.\n\n\n### Features\n\n- Live timing detection (too-fast/too-slow submissions)\n- Hidden honeypot field detection\n- Fake login pages for Django Admin and WordPress\n- Comprehensive logging with risk scores\n- Pluggable signal to integrate custom handlers\n- Optional email alerts and console logging\n- URL include or drop-in views usage\n- Strict settings validation at startup\n\n\n### Preview\n\nThe package ships with templates for:\n- `django_honeyguard/django_admin_login.html` (fake Django admin)\n- `django_honeyguard/wp_admin_login.html` (fake WordPress admin)\n\nInclude the URLs and visit `/admin/` or `/wp-admin.php` to see the honeypots in action.\n\n\n### Requirements\n\n- Django >= 5.0.0\n- Python >= 3.10\n\n\n### Installation\n\nInstall from PyPI:\n\n```bash\npip install django-honeyguard\n```\n\nAdd the app to `INSTALLED_APPS`:\n\n```python\n# settings.py\nINSTALLED_APPS = [\n # ...\n \"django_honeyguard\",\n]\n```\n\nInclude the URLs (Option A), or wire views directly (Option B):\n\n```python\n# urls.py\nfrom django.urls import include, path\n\nurlpatterns = [\n # Option A: include both fake admin pages\n path(\"\", include(\"django_honeyguard.urls\")),\n\n # Option B: use individual views\n # from django_honeyguard.views import FakeDjangoAdminView, FakeWPAdminView\n # path(\"admin/\", FakeDjangoAdminView.as_view()),\n # path(\"wp-admin.php\", FakeWPAdminView.as_view()),\n]\n```\n\nRun migrations (creates log table):\n\n```bash\npython manage.py migrate\n```\n\n\n### Settings (settings.py)\n\nYou can configure HoneyGuard via a `HONEYGUARD` dictionary or individual `HONEYGUARD_*` settings. Defaults shown below:\n\n```python\nHONEYGUARD = {\n # Email alerts\n \"EMAIL_RECIPIENTS\": [],\n \"EMAIL_SUBJECT_PREFIX\": \"\ud83d\udea8 Honeypot Alert\",\n \"EMAIL_FROM\": None, # Uses Django DEFAULT_FROM_EMAIL if None\n \"EMAIL_FAIL_SILENTLY\": True, # Do not crash on email errors\n\n # Timing detection (seconds)\n \"TIMING_TOO_FAST_THRESHOLD\": 2.0,\n \"TIMING_TOO_SLOW_THRESHOLD\": 600.0,\n\n # Logging\n \"ENABLE_CONSOLE_LOGGING\": True,\n \"LOG_LEVEL\": \"WARNING\", # DEBUG, INFO, WARNING, ERROR, CRITICAL\n\n # Detection behavior\n \"ENABLE_GET_METHOD_DETECTION\": False, # Detect on GET as well as POST\n\n # Field limits\n \"MAX_USERNAME_LENGTH\": 150,\n \"MAX_PASSWORD_LENGTH\": 128,\n \"WORDPRESS_USERNAME_MAX_LENGTH\": 60,\n \"WORDPRESS_PASSWORD_MAX_LENGTH\": 255,\n\n # Error messages (shown on fake pages)\n \"DJANGO_ERROR_MESSAGE\": (\n \"Please enter a correct username and password. Note that both fields\"\n \" may be case-sensitive.\"\n ),\n \"WORDPRESS_ERROR_MESSAGE\": (\n \"<strong>Error:</strong> The password you entered for the username is incorrect.\"\n ),\n}\n```\n\n\n### Usage\n\n- Visit `/admin/` for the fake Django admin login page\n- Visit `/wp-admin.php` for the fake WordPress login page\n- Submissions and suspicious GETs will be logged via the `honeypot_triggered` signal\n\nListen to the `honeypot_triggered` signal to add custom behaviors:\n\n```python\nfrom django_honeyguard.signals import honeypot_triggered\nfrom django.dispatch import receiver\n\n@receiver(honeypot_triggered)\ndef my_handler(sender, request, data, **kwargs):\n # data contains ip_address, path, username, timing info, risk_score, etc.\n pass\n```\n\n\n### Documentation\n\nComplete documentation is available at: https://django-honeyguard.readthedocs.io/\n\nRunning the docs locally:\n\n```bash\ngit clone https://github.com/alihtt/django-honeyguard.git\ncd django-honeyguard\npython -m venv .venv && source .venv/bin/activate\npip install -r docs/requirements.txt\ncd docs && make html\n# open _build/html/index.html in your browser\n```\n\n\n### Notes\n\n- This package does not replace Django\u2019s real authentication; it provides decoy pages and logging.\n- Always secure your real admin at a non-obvious URL and behind proper authentication and rate limiting.\n\n\n[1]: https://img.shields.io/pypi/v/django-honeyguard.svg\n[2]: https://pypi.org/project/django-honeyguard/\n[3]: https://readthedocs.org/projects/django-honeyguard/badge/?version=latest\n[4]: https://django-honeyguard.readthedocs.io/en/latest/\n[5]: https://img.shields.io/badge/license-BSD--3--Clause-blue\n[6]: https://github.com/alihtt/django-honeyguard/blob/main/LICENSE\n[7]: https://img.shields.io/pypi/pyversions/django-honeyguard.svg\n[8]: https://img.shields.io/badge/Django-%3E%3D%205.0.0-green.svg\n[9]: https://www.djangoproject.com\n[10]: https://img.shields.io/github/actions/workflow/status/alihtt/django-honeyguard/tests.yml?branch=main\n[11]: https://github.com/alihtt/django-honeyguard/actions\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Reusable Django app providing multi-CMS honeypot login traps with DB logging and email alerts.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/alihtt/django-honeyguard/issues",
"Changelog": "https://github.com/alihtt/django-honeyguard/blob/main/CHANGES.rst",
"Documentation": "https://django-honeyguard.readthedocs.io/en/main/",
"Homepage": "https://github.com/alihtt/django-honeyguard/tree/main",
"Source Code": "https://github.com/alihtt/django-honeyguard"
},
"split_keywords": [
"admin",
" django",
" honeypot",
" security",
" wordpress",
" wp-admin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b29c3f551edeecd18533e6c85d394570b5f12f732e589fb6d3827c3d8ccd2353",
"md5": "4fdc50de0a637d70a49b4c79937697b4",
"sha256": "beafbbd0f40a1978be908b0cc477f13cd27a04df56f755f4a24c3f39b4dd7ee8"
},
"downloads": -1,
"filename": "django_honeyguard-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4fdc50de0a637d70a49b4c79937697b4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 131435,
"upload_time": "2025-11-03T11:25:25",
"upload_time_iso_8601": "2025-11-03T11:25:25.880821Z",
"url": "https://files.pythonhosted.org/packages/b2/9c/3f551edeecd18533e6c85d394570b5f12f732e589fb6d3827c3d8ccd2353/django_honeyguard-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d54e85480b60e9fb9d968e67faff92c287b6a5eaf10510e4dddb9aa6570e575e",
"md5": "dde98113c64d12e610ded1d643f72591",
"sha256": "14f26ca798bc441c899ea7f8439420b7f45bc330eb105269b7ac8780d10530e4"
},
"downloads": -1,
"filename": "django_honeyguard-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dde98113c64d12e610ded1d643f72591",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 63790,
"upload_time": "2025-11-03T11:25:27",
"upload_time_iso_8601": "2025-11-03T11:25:27.276534Z",
"url": "https://files.pythonhosted.org/packages/d5/4e/85480b60e9fb9d968e67faff92c287b6a5eaf10510e4dddb9aa6570e575e/django_honeyguard-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 11:25:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alihtt",
"github_project": "django-honeyguard",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "django-honeyguard"
}
JSON
