Table of Contents
Request Throttling
TetherX uses multiple layers of protection to prevent abuse, brute-force attacks, and malicious requests. This article documents all rate limiting and blocking mechanisms.
Security Layers
Protection is applied at three levels:
- Nginx - Infrastructure-level blocking for known attack patterns
- Rack::Attack - Application-level rate limiting and attack detection
- Rails Controllers - Endpoint-specific rate limits for sensitive actions
Rate Limits
General Web Requests
| Endpoint | Limit | Period | Response |
|---|---|---|---|
| Web pages | 3,000 requests | 5 minutes | HTTP 429 |
| Login attempts | 10 requests | 5 minutes | HTTP 429 |
| Password resets | 5 requests | 5 minutes | HTTP 429 |
Excluded from general limit: Assets, live view, WebSocket connections, and API endpoints have separate handling.
API Rate Limits
| API Version | Limit | Period | Response |
|---|---|---|---|
| Public API (v3p) | 100 requests | 1 minute | HTTP 429 |
| Webhooks | 60 requests | 1 minute | HTTP 429 |
Tip: The private API (v3) is designed for TetherBoxes and authenticated users. TetherBox communication uses a pre-authenticated MQTT connection with message queuing, allowing requests to backlog gracefully during high load rather than being rejected.
Attack Blocking
Immediate Blocks (HTTP 444)
These patterns are blocked immediately with a connection close:
- SQL Injection in Host Header - Keywords like
union,select,drop,exec,sleep( - Invalid Host Characters - Characters outside
a-z,0-9,.,-,: - Path Traversal - Patterns like
..,/etc/passwd,/proc/self - CMS Admin Paths - Requests to
wp-admin,phpmyadmin,admin.php - Malicious Script Extensions - Files ending in
.php,.asp,.jsp,.cgi
Fail2Ban-Style Backoff
Repeated suspicious requests trigger an exponential ban:
- Trigger: 5 suspicious requests within 10 minutes
- Ban Duration: 5 minutes per IP address
- Tracked Patterns: Path traversal, SQL injection, invalid host characters
Per-User Access Restrictions
Administrators can lock a user's access to specific IP addresses. When enabled, the user can only access TetherX from the listed IPs - all other addresses are blocked.
- Location: Users → Edit User → Permissions → CCTV → Restrict Access from Specific IP(s)
- Format: Comma-separated list of IP addresses
- Effect: User is blocked from ALL access unless connecting from a listed IP
- Response when blocked: HTTP 403 Forbidden
Warning: This is a security restriction, not a whitelist. Enabling this feature locks the user out of all IP addresses except those explicitly listed. Users cannot modify their own IP restrictions.
Infrastructure Blocking
Bot Blocking
Known bots are blocked at the nginx level to reduce noise:
- YandexBot, Googlebot, Bingbot
- DuckDuckBot, BaiduSpider
- AhrefsBot, SemrushBot
SSH Protection
Server SSH access is protected by fail2ban:
- Trigger: 10 failed attempts within 10 minutes
- Ban Duration: 10 minutes per IP address
Error Responses
HTTP 429 - Rate Limit Exceeded
When throttled, you receive a JSON response with retry information:
{
"error": "Rate limit exceeded",
"ip": "203.0.113.1",
"throttle": "req/ip",
"count": 3001,
"limit": 3000,
"retry_after": 300
}
The Retry-After header indicates seconds until the limit resets.
HTTP 444 - Connection Closed
Attack patterns receive an immediate connection close with no response body. This minimises information disclosure to attackers.
HTTP 403 - IP Restricted
Users with IP restrictions accessing from unauthorised addresses receive:
"IP restricted"
Common Questions
Why am I getting 429 errors?
Your IP has exceeded the rate limit. Wait for the period specified in retry_after before retrying. If you need higher limits for legitimate use cases, contact support.
Can I get higher API limits?
The public API has fixed limits. If you have a legitimate use case requiring higher limits, contact support to discuss your requirements.