The Search space, Entropy, and Estimated time tiles show how configuration choices impact the attacker timeline and how defenses stretch out each attempt.

Defenses

Each toggle under "Defenses" modifies the simulated timing model:

• Rate limit (attempts/sec): A ceiling on how fast guesses are tried. The slider runs from 10 to 2000 attempts/sec, and the display shows the live value. Lower rates stretch out the attack and make metrics like ETA go up.
• Captcha challenge: When enabled, the demo applies a 2.5× penalty to the rate limit to emulate human verification delays. This models any challenge-response barrier that slows a brute-force script.
• Lockout after failed attempts: Turns on the lockout logic. The simulation pauses for Lockout seconds every Lockout threshold attempts, demonstrating how account lockouts can choke automation.
• Lockout threshold: How many guesses the attacker can make before the account locks out. Lower thresholds are stricter; higher thresholds give more room but still introduce penalties.
• Lockout seconds: The duration of each lockout period. Combine a short threshold with a long lockout to show how even a few wrong guesses can stall an attacker for minutes.
• Jitter (%): Adds randomness to the attempts-per-second rate to model network latency, throttling, or inconsistent backoff. Higher jitter introduces more visible variability in the chart and makes ETA estimates bounce around, illustrating how unpredictability frustrates attackers.

Web demo features

• Interactive brute-force simulation with real-time metrics
• Simulated defenses: rate limiting, lockout, captcha, jitter
• Configurable PIN policy (length + charset)
• Estimated time-to-crack and entropy
• Downloadable JSON report
• Optional local API mode
• Responsive, accessible UI

Run modes & API

• Run via API: This button is intentionally disabled until you toggle "Use local API (Flask)". The payload mirrors the settings (PIN length, charset, rate limits, captcha, lockout, etc.), which demonstrates how a server-backed workflow could work.
• API endpoint: Defaults to http://127.0.0.1:5000/api/bruteforce. There is no server bundled with the repo—this field is purely illustrative so you can experiment with your own Flask or FastAPI service if you build one.
• Event log: Every major action—simulation start, lockout trigger, PIN found, API success/failure—drops a timestamped entry into the log. It keeps the last 40 entries so you can scroll through a run and see what the simulation is thinking.
• Download report: Exports a JSON summary of the settings, results (attempts, elapsed seconds, attempts/sec, found/not), and estimate data. Great for sharing on a security whiteboard or pairing it with a lesson plan.

How the simulation works (short)

1. Build a search space from PIN length and charset.
2. Enumerate candidates in a deterministic order.
3. Compare the guess to a locally generated PIN.
4. Track attempts, rate, and estimated time.
5. Apply defenses (rate limit, lockout, captcha) to the timing model.

This mirrors how brute-force attacks scale without ever touching a real system.

Tests and development

Install dev dependencies:

python -m pip install -r requirements-dev.txt

Run the smoke tests that make sure the hero UI, buttons, and script stay wired up:

pytest tests/test_ui_assets.py

Security and ethics

This repo is for learning defensive security only. Unauthorized access attempts are illegal and unethical. Use this project to understand risks and build better protections, not to attack systems.

License

MIT — see LICENSE.