API Reference

This page documents the complete API for django-honeyguard.

Models

HoneyGuard models for logging honeypot detections.

class django_honeyguard.models.TimingIssue(*values)

Bases: TextChoices

TOO_FAST = 'too_fast'

TOO_SLOW = 'too_slow'

VALID = 'valid'

class django_honeyguard.models.RequestMethod(*values)

Bases: TextChoices

GET = 'GET'

POST = 'POST'

class django_honeyguard.models.HoneyGuardLog(*args, **kwargs)

Bases: Model

Log entry for honeypot detection events.

ip_address

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

path

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

username

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

password

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

user_agent

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

referer

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

accept_language

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

accept_encoding

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

method

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

honeypot_triggered

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

timing_issue

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

elapsed_time

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

raw_metadata

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

created_at

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

updated_at

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property is_bot

Check if this appears to be bot activity.

property risk_score

Calculate a simple risk score based on detection flags.

Returns:

Risk score between 0 and 100

Return type:

int

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

get_method_display(*, field=<django.db.models.fields.CharField: method>)

get_next_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)

get_next_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=True, **kwargs)

get_previous_by_created_at(*, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)

get_previous_by_updated_at(*, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=False, **kwargs)

get_timing_issue_display(*, field=<django.db.models.fields.CharField: timing_issue>)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

Views

Views for fake admin pages (honeypots).

class django_honeyguard.views.FakeAdminView(*args: Any, **kwargs: Any)

Bases: FormView

Base view for fake admin pages that act as honeypots.

success_url = '/'

error_message = 'Authentication failed.'

get_error_message() → str

Get error message to display to user.

Override in subclasses to provide specific error messages.

Returns:

Error message text

Return type:

str

__init__(*args: Any, **kwargs: Any) → None

Initialize the view with a TimestampSigner.

dispatch(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponse

Store signed render time for timing detection.

get_initial() → Dict[str, Any]

Get initial form data including signed render time.

get(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponse

Handle GET requests - optionally trigger honeypot detection.

post(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponse

Handle POST requests - always show error message.

form_valid(form: BaseForm) → HttpResponse

Handle valid form submission - always trigger honeypot detection.

form_invalid(form: BaseForm) → HttpResponse

Handle invalid form submission - still trigger honeypot detection.

process_honeypot_trigger(request: HttpRequest, form_data: Dict[str, Any] | None = None) → None

Process honeypot trigger and send signal.

class django_honeyguard.views.FakeDjangoAdminView(*args: Any, **kwargs: Any)

Bases: FakeAdminView

Fake Django admin login page honeypot.

form_class

alias of FakeDjangoLoginForm

template_name = 'django_honeyguard/django_admin_login.html'

get_error_message() → str

Return Django admin error message.

class django_honeyguard.views.FakeWPAdminView(*args: Any, **kwargs: Any)

Bases: FakeAdminView

Fake WordPress admin login page honeypot.

form_class

alias of FakeWordPressLoginForm

template_name = 'django_honeyguard/wp_admin_login.html'

get_error_message() → str

Return WordPress admin error message.

Forms

class django_honeyguard.forms.BaseFakeLoginForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None, bound_field_class=None)

Bases: Form

username_required_message = 'This field is required.'

password_required_message = 'This field is required.'

is_honeypot_triggered() → bool

Check if the honeypot field was filled (indicating bot activity).

clean_username() → str

Clean and validate username field.

clean_password() → str

Clean and validate password field.

base_fields = {'hp': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>}

declared_fields = {'hp': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>}

property media

Return all media required to render the widgets on this form.

class django_honeyguard.forms.FakeDjangoLoginForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None, bound_field_class=None)

Bases: BaseFakeLoginForm

Fake login form with hidden honeypot field to detect bots.

base_fields = {'hp': <django.forms.fields.CharField object>, 'password': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}

declared_fields = {'hp': <django.forms.fields.CharField object>, 'password': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}

property media

Return all media required to render the widgets on this form.

class django_honeyguard.forms.FakeWordPressLoginForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None, bound_field_class=None)

Bases: BaseFakeLoginForm

Fake WordPress login form with WordPress-specific attributes.

username_required_message = 'The username field is empty.'

password_required_message = 'The password field is empty.'

base_fields = {'hp': <django.forms.fields.CharField object>, 'password': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}

declared_fields = {'hp': <django.forms.fields.CharField object>, 'password': <django.forms.fields.CharField object>, 'render_time': <django.forms.fields.CharField object>, 'username': <django.forms.fields.CharField object>}

property media

Return all media required to render the widgets on this form.

Services

Business logic for HoneyGuard honeypot triggers.

class django_honeyguard.services.HoneyGuardService(request: HttpRequest, data: Dict[str, Any] | None = None)

Bases: object

Encapsulates core business logic for honeypot event processing.

__init__(request: HttpRequest, data: Dict[str, Any] | None = None) → None

log_trigger() → None

Log honeypot trigger to the database.

log_to_console() → None

Log honeypot trigger details to console or file.

send_email_alert() → None

Send email alert to configured recipients.

This method handles email sending with proper error handling. Email failures will not raise exceptions by default to prevent disrupting the honeypot detection flow.

Signals

honeypot_triggered Signal

Signal emitted when honeypot is triggered.

Arguments:

• sender - The sender class

• request - Django HttpRequest object

• data - Dictionary with attack data including: * ip_address * path * username * password (sanitized) * honeypot_triggered * timing_issue * elapsed_time * risk_score

Example:

from django_honeyguard.signals import honeypot_triggered
from django.dispatch import receiver

@receiver(honeypot_triggered)
def my_handler(sender, request, data, **kwargs):
    print(f"Attack from {data['ip_address']}")

Utilities

Utility functions for django-honeyguard.

django_honeyguard.utils.get_client_ip(request: HttpRequest) → str

Extract the client’s IP address, honoring X-Forwarded-For if present.

Parameters:

request – Django HttpRequest object

Returns:

Client IP address

Return type:

str

django_honeyguard.utils.sanitize_password(password: str) → str

Sanitize password by replacing it with asterisks.

django_honeyguard.utils.get_request_metadata(request: HttpRequest) → Dict[str, str]

Collect request metadata for logging and alerting.

Parameters:

request – Django HttpRequest object

Returns:

Dictionary containing request metadata

Return type:

dict

django_honeyguard.utils.check_timing_attack(render_time: str | None) → Tuple[str, float]

Check if form submission timing is suspicious.

Parameters:

render_time – ISO format created_at when form was rendered, or None

Returns:

(timing_issue, elapsed_time) where timing_issue is a TimingIssue choice

and elapsed_time is in seconds

Return type:

tuple

Configuration

Configuration management for django-honeyguard.

django_honeyguard.conf.validate_email_recipients(value: Any, setting_name: str) → Tuple[List[str], str]

Validate EMAIL_RECIPIENTS setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

Returns:

(validated_value, error_message)

Return type:

tuple

Raises:

ImproperlyConfigured – If value is invalid and cannot be fixed

django_honeyguard.conf.validate_positive_number(value: Any, setting_name: str, min_value: float = 0.0) → Tuple[float, str]

Validate a positive number setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

• min_value – Minimum allowed value

Returns:

(validated_value, error_message)

Return type:

tuple

Raises:

ImproperlyConfigured – If value is invalid

django_honeyguard.conf.validate_positive_integer(value: Any, setting_name: str, min_value: int = 1) → Tuple[int, str]

Validate a positive integer setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

• min_value – Minimum allowed value

Returns:

(validated_value, error_message)

Return type:

tuple

Raises:

ImproperlyConfigured – If value is invalid

django_honeyguard.conf.validate_boolean(value: Any, setting_name: str) → Tuple[bool, str]

Validate a boolean setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

Returns:

(validated_value, error_message)

Return type:

tuple

django_honeyguard.conf.validate_log_level(value: Any, setting_name: str) → Tuple[str, str]

Validate LOG_LEVEL setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

Returns:

(validated_value, error_message)

Return type:

tuple

Raises:

ImproperlyConfigured – If value is invalid

django_honeyguard.conf.validate_string(value: Any, setting_name: str) → Tuple[str, str]

Validate a string setting.

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

Returns:

(validated_value, error_message)

Return type:

tuple

django_honeyguard.conf.validate_optional_string(value: Any, setting_name: str) → Tuple[Any, str]

Validate an optional string setting (can be None or string).

Parameters:

• value – Setting value to validate

• setting_name – Name of the setting

Returns:

(validated_value, error_message)

Return type:

tuple

django_honeyguard.conf.validate_timing_fast(value: Any, setting_name: str) → Tuple[float, str]

Validate TIMING_TOO_FAST_THRESHOLD.

django_honeyguard.conf.validate_timing_slow(value: Any, setting_name: str) → Tuple[float, str]

Validate TIMING_TOO_SLOW_THRESHOLD.

django_honeyguard.conf.validate_username_length(value: Any, setting_name: str) → Tuple[int, str]

Validate username length settings.

class django_honeyguard.conf.Settings

Settings management for django-honeyguard.

Allows settings to be configured either through: 1. A HONEYGUARD dictionary in Django settings 2. Individual HONEYGUARD_* settings

Settings are lazily loaded and cached for performance.

__getattr__(name: str) → Any

Get a setting value by name.

Parameters:

name – Setting name (without HONEYGUARD_ prefix)

Returns:

Setting value from Django settings or default

Raises:

AttributeError – If setting name is not valid

change_setting(setting: str, value: Any, enter: bool, **kwargs: Any) → None

Handle Django setting changes via setting_changed signal.

Parameters:

• setting – Django setting name that changed

• value – New value of the setting

• enter – True if setting is being added/changed, False if removed

• **kwargs – Additional signal arguments

reset() → None

Reset all cached settings to force reload from Django settings.

Admin

Enhanced Django admin interface for HoneyGuard logs.

class django_honeyguard.admin.HoneyGuardLogAdmin(model, admin_site)

Enhanced admin interface for HoneyGuard logs.

list_display = ('created_at', 'method', 'ip_address', 'path', 'username_display', 'risk_score_display', 'timing_issue', 'honeypot_triggered')

list_filter = ('created_at', 'path', 'method', 'timing_issue', 'honeypot_triggered')

search_fields = ('ip_address', 'username', 'password', 'user_agent', 'path', 'referer')

date_hierarchy = 'created_at'

readonly_fields = ('created_at', 'updated_at', 'risk_score_field', 'request_summary')

list_per_page = 50

ordering = ['-created_at']

fieldsets = (('Request Information', {'fields': ('ip_address', 'path', 'method', 'created_at', 'updated_at')}), ('Authentication Attempt', {'fields': ('username', 'password')}), ('Detection Flags', {'classes': ('collapse',), 'fields': ('honeypot_triggered', 'timing_issue', 'elapsed_time', 'risk_score_field')}), ('Request Metadata', {'classes': ('collapse',), 'fields': ('user_agent', 'referer', 'accept_language', 'accept_encoding', 'request_summary', 'raw_metadata')}))

actions = ['export_to_csv', 'archive_old_logs']

username_display(obj: HoneyGuardLog) → str

Display username with truncation.

risk_score_display(obj: HoneyGuardLog) → str

Display risk score with color coding.

risk_score_field(obj: HoneyGuardLog) → int

Display risk score value for detail view.

request_summary(obj: HoneyGuardLog) → str

Display formatted request summary.

export_to_csv(request: Any, queryset: QuerySet) → HttpResponse

Export selected logs to CSV format.

archive_old_logs(request: Any, queryset: QuerySet) → None

Archive logs older than 90 days.

property media

Loggers

Logging utilities for django-honeyguard.

class django_honeyguard.loggers.HoneyGuardLogger(name: str)

Custom logger wrapper that respects HoneyGuard settings.

This logger checks ENABLE_CONSOLE_LOGGING before actually logging, and respects the configured LOG_LEVEL.

__init__(name: str) → None

Initialize logger with given name.

Parameters:

name – Logger name (usually __name__)

debug(msg: str, *args: Any, **kwargs: Any) → None

Log debug message if enabled.

info(msg: str, *args: Any, **kwargs: Any) → None

Log info message if enabled.

warning(msg: str, *args: Any, **kwargs: Any) → None

Log warning message if enabled.

error(msg: str, *args: Any, **kwargs: Any) → None

Log error message if enabled.

critical(msg: str, *args: Any, **kwargs: Any) → None

Log critical message if enabled.

django_honeyguard.loggers.get_logger(name: str) → HoneyGuardLogger

Get a HoneyGuard logger instance.

Parameters:

name – Logger name (usually __name__)

Returns:

Logger instance that respects HoneyGuard settings

Return type:

HoneyGuardLogger