Skip to content

docs: Clarify cool-off mechanisms and document AXES_USE_ATTEMPT_EXPIRATION#1400

Open
rodrigobnogueira wants to merge 5 commits intojazzband:masterfrom
rodrigobnogueira:docs/1383-document-cooloff-time
Open

docs: Clarify cool-off mechanisms and document AXES_USE_ATTEMPT_EXPIRATION#1400
rodrigobnogueira wants to merge 5 commits intojazzband:masterfrom
rodrigobnogueira:docs/1383-document-cooloff-time

Conversation

@rodrigobnogueira
Copy link

What does this PR do?

This PR addresses issue #1383 where users found the AXES_COOLOFF_TIME behavior confusing and lacked documentation on how to set a "number of failed login attempts per xx minutes" lockout rule.

Changes:

  • Converted grid table to list-table: The settings.py table in docs/4_configuration.rst was a fragile grid table making it hard to maintain. It has been converted to a clean Sphinx .. list-table::.
  • Documented AXES_USE_ATTEMPT_EXPIRATION: This setting, when combined with AXES_COOLOFF_TIME, enables the "rolling window" behavior the reporter was looking for (e.g., 3 attempts per 15 minutes). Added it to the configuration docs.
  • Clarified Lockout Configuration Behaviors:
    • AXES_FAILURE_LIMIT: Clarified it's the limit before the request is considered locked.
    • AXES_COOLOFF_TIME: Explicitly stated None means permanent lockout until manual reset/deletion, and gave type examples (timedelta recommended).
    • AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT: Emphasized that any new failed attempt while locked resets the timer to now() + cool_off, meaning repeated brute-force attempts continuously extend the lockout period.
  • Added Lockout configuration heading: Grouped the configuration table under a clear heading to help users find security policies quickly.

Fixes #1383

Before submitting

  • This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
  • Did you make sure to update the documentation with your changes?
  • Did you write any new necessary tests?

Copy link
Member

@aleksihakli aleksihakli left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commenting on reformatting the table coding.

This kind of reformat is a valid approach, but please note that it requires a complete reread of the documentation and testing at RTD website since our documentation is located there. Just adding the necessary documentation in one PR and suggesting reformatting in another would be more polite considering the maintainers' time in open-source projects.

@rodrigobnogueira
Copy link
Author

Thanks @aleksihakli .
I removed the broad table reformat and kept only the docs changes needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AXES_COOLOFF_TIME is undocumented

2 participants