The test environment doesn't have OpenResty libraries, so we need
to provide mock implementations for testing.
Created:
- tests/mock_resty_sha256.lua: Uses system sha256sum command to
compute SHA-256 hashes. Mimics the resty.sha256 API (new,
update, final).
- tests/mock_resty_string.lua: Implements to_hex() to convert
binary strings to hexadecimal.
Updated test.lua to preload these mocks so that when the module
or tests require 'resty.sha256' or 'resty.string', they get our
mock implementations instead.
This allows the PoW verification tests to run and actually verify
the SHA-256 proof-of-work.
Major security fix: The proof-of-work challenge was previously
just trusting the client, allowing bots to bypass it by submitting
random nonces without doing any work.
Changes:
- Added proper server-side SHA-256 verification using resty.sha256
- Server now verifies that sha256(challenge + nonce) has the
required number of leading zeros based on pow_difficulty
- Bots must now actually compute the proof-of-work
Updated tests:
- Added computeValidNonce() helper that actually computes valid
nonces by brute force (for testing purposes)
- testValidPowPassesChallenge now uses a real computed nonce
Updated README to explicitly mention server-side verification.
The issue was that ngx.re.match in the test environment uses
rex_pcre2.match which has a different API than OpenResty's
ngx.re.match. The rex library returns captures differently.
Changed getCookieValue() to use Lua's built-in string.match()
with Lua patterns instead. This is simpler, more portable, and
works correctly in both test and production environments.
Also removed debug logging since the issue is now identified.
Added debug logging to see what's happening with cookie header
parsing in the failing token validation tests. This will help
identify whether:
- ngx.req.get_headers() is returning the expected headers
- The Cookie header is being found (case sensitivity check)
- The token is being extracted correctly
- The token is found in the shared dict
Also added ngx log level constants (DEBUG, INFO, WARN, ERR) to
the test framework since the module uses them.
Fixed three remaining test issues:
1. Token validation tests: Changed from overriding ngx.req.get_headers
to setting ngx._headers directly, which the setup's mock function
reads from. This is more reliable and matches the test framework
pattern.
2. testCorrectAnswerPassesChallenge: Removed problematic resetNgx()
call that was trying to initialize the module while creating
ngx.shared. Simplified to just create the challenge and test
verification directly.
All tests should now pass.
Fixed missing ngx.req.read_body, ngx.req.get_post_args, and
ngx.req.get_headers function mocks that were causing test errors.
These functions are required by the DDoS protection module to
handle POST requests and cookie validation.
All four test classes now properly initialize these mocks:
- TestDDoSProtectionChallenge
- TestDDoSProtectionChallengePaths
- TestDDoSProtectionChallengeQuestion
- TestDDoSProtectionChallengePow
Cannot use setupTest() for modules that need ngx.shared because setupTest()
calls resetNgx() (which wipes ngx.shared) before calling module.init() (which
needs ngx.shared).
Solution: Manually replicate what setupTest() does, but set up ngx.shared
after resetNgx() and before module.init().
All 4 test classes now:
1. Call resetNgx()
2. Set up ngx.shared
3. Manually require module, validate schema, call init(), set ctx.compiled_chain
Schema validation was failing because the new optional config fields
(protected_paths, challenge_type, pow_difficulty) weren't provided in
test configs. While these fields have defaults in the code, the schema
validator requires them to be present.
Added all three fields to every test setup() method with appropriate
default values.
All test setup methods were trying to access ngx.shared before the ngx
global was initialized, causing 'attempt to index global ngx (a nil value)'
errors.
Fixed by calling resetNgx() at the start of each setup() method to ensure
the ngx global exists before setting up ngx.shared and other mock properties.
Allow users to experiment with different DDoS mitigation strategies by
choosing between three challenge types:
1. Button Challenge (default): Simple click-to-verify, best UX
2. Question Challenge: Multiple-choice questions, better bot filtering
3. Proof-of-Work Challenge: SHA-256 computation, strongest protection
Features:
- Three distinct challenge page generators with unique HTML/CSS/JS
- Question pool with 7 simple multiple-choice questions
- JavaScript-based PoW using Web Crypto API (SHA-256)
- Configurable PoW difficulty (3-6 leading zeros)
- Verification logic for each challenge type
- Automatic challenge cleanup after verification
- 10 new comprehensive tests covering all challenge types
Configuration:
- challenge_type: 'button' (default), 'question', or 'pow'
- pow_difficulty: 3=fast, 4=moderate (default), 5=slow, 6=very slow
The PoW challenge creates real computational cost for attackers. With
difficulty 4, each request requires ~65,000 hash computations (~1-3s).
This makes volumetric attacks expensive while remaining transparent to
legitimate users.
Files modified:
- scripts/ddos_protection_challenge.lua: +346 lines (challenge generators, verification)
- tests/ddos_protection_challenge.lua: +198 lines (10 new tests)
- scripts/ddos_protection_challenge.README.md: +93 lines (detailed docs)
- conf.example.ddos_protection.lua: Updated with challenge_type option
- conf.example.ddos_protection_challenge_types.lua: New file with 4 config examples
Allow users to specify which paths should be protected by the challenge
system, enabling selective protection of expensive endpoints while
leaving static assets and other paths unrestricted.
Changes:
- Add protected_paths config option (list of PCRE regex patterns)
- Only apply challenge/ban logic to paths matching protected patterns
- If protected_paths is empty/unset, protect all paths (default behavior)
- Special endpoints (verify/trap) always function regardless of config
- Add 8 new tests for path-based filtering scenarios
- Update documentation with examples and best practices
- Update example config to show protected_paths usage
This allows more granular control - for example, protecting only /api/*
and /search while allowing free access to static assets, reducing UX
friction while still protecting expensive operations.
Implements a Cloudflare-style "Under Attack" mode that protects against
DDoS attacks, scraping, and automated bots.
Features:
- Challenge-response system requiring human interaction
- Honeypot link that automatically bans IPs of bots that click it
- Cookie-based token system for validated users (24h default)
- Temporary IP banning (1h default)
- Comprehensive test suite
The module intercepts requests before they hit the backend, reducing
computational cost from scraping and DDoS attempts. It's particularly
effective against simple scrapers and volumetric attacks.
Files added:
- scripts/ddos_protection_challenge.lua - Main module implementation
- tests/ddos_protection_challenge.lua - Comprehensive test suite
- scripts/ddos_protection_challenge.README.md - Full documentation
- conf.example.ddos_protection.lua - Example configuration
- test.lua - Added test import
This ensures scripts execute in the order they appear in the config file,
resolving the TODO in the README. The config format has been changed from
a table with script names as keys to an ordered list of script entries.
Changes:
- ctx.lua: Use ipairs() instead of pairs() to iterate in order
- config.lua: Update validation to handle new list structure
- conf.lua: Update example config to use new format
- README.md: Remove TODO and clarify execution order
New config format:
wantedScripts = {
{name = 'script1', config = {...}},
{name = 'script2', config = {...}}
}
