279 lines
7.1 KiB
Markdown
279 lines
7.1 KiB
Markdown
# API Security & Rate Limiting
|
|
|
|
## Overview
|
|
|
|
AtlasOS implements comprehensive API security measures including rate limiting, security headers, CORS protection, and request validation to protect the API from abuse and attacks.
|
|
|
|
## Rate Limiting
|
|
|
|
### Token Bucket Algorithm
|
|
|
|
The rate limiter uses a token bucket algorithm:
|
|
- **Default Rate**: 100 requests per minute per client
|
|
- **Window**: 60 seconds
|
|
- **Token Refill**: Tokens are refilled based on elapsed time
|
|
- **Per-Client**: Rate limiting is applied per IP address or user ID
|
|
|
|
### Rate Limit Headers
|
|
|
|
All responses include rate limit headers:
|
|
|
|
```
|
|
X-RateLimit-Limit: 100
|
|
X-RateLimit-Window: 60
|
|
```
|
|
|
|
### Rate Limit Exceeded
|
|
|
|
When rate limit is exceeded, the API returns:
|
|
|
|
```json
|
|
{
|
|
"code": "SERVICE_UNAVAILABLE",
|
|
"message": "rate limit exceeded",
|
|
"details": "too many requests, please try again later"
|
|
}
|
|
```
|
|
|
|
**HTTP Status**: `429 Too Many Requests`
|
|
|
|
### Client Identification
|
|
|
|
Rate limiting uses different keys based on authentication:
|
|
|
|
- **Authenticated Users**: `user:{user_id}` - More granular per-user limiting
|
|
- **Unauthenticated**: `ip:{ip_address}` - IP-based limiting
|
|
|
|
### Public Endpoints
|
|
|
|
Public endpoints (login, health checks) are excluded from rate limiting to ensure availability.
|
|
|
|
## Security Headers
|
|
|
|
All responses include security headers:
|
|
|
|
### X-Content-Type-Options
|
|
- **Value**: `nosniff`
|
|
- **Purpose**: Prevents MIME type sniffing
|
|
|
|
### X-Frame-Options
|
|
- **Value**: `DENY`
|
|
- **Purpose**: Prevents clickjacking attacks
|
|
|
|
### X-XSS-Protection
|
|
- **Value**: `1; mode=block`
|
|
- **Purpose**: Enables XSS filtering in browsers
|
|
|
|
### Referrer-Policy
|
|
- **Value**: `strict-origin-when-cross-origin`
|
|
- **Purpose**: Controls referrer information
|
|
|
|
### Permissions-Policy
|
|
- **Value**: `geolocation=(), microphone=(), camera=()`
|
|
- **Purpose**: Disables unnecessary browser features
|
|
|
|
### Strict-Transport-Security (HSTS)
|
|
- **Value**: `max-age=31536000; includeSubDomains`
|
|
- **Purpose**: Forces HTTPS connections (only on HTTPS)
|
|
- **Note**: Only added when request is over TLS
|
|
|
|
### Content-Security-Policy (CSP)
|
|
- **Value**: `default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data:; font-src 'self' https://cdn.jsdelivr.net; connect-src 'self';`
|
|
- **Purpose**: Restricts resource loading to prevent XSS
|
|
|
|
## CORS (Cross-Origin Resource Sharing)
|
|
|
|
### Allowed Origins
|
|
|
|
By default, the following origins are allowed:
|
|
|
|
- `http://localhost:8080`
|
|
- `http://localhost:3000`
|
|
- `http://127.0.0.1:8080`
|
|
- Same-origin requests (no Origin header)
|
|
|
|
### CORS Headers
|
|
|
|
When a request comes from an allowed origin:
|
|
|
|
```
|
|
Access-Control-Allow-Origin: http://localhost:8080
|
|
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
|
|
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
|
|
Access-Control-Allow-Credentials: true
|
|
Access-Control-Max-Age: 3600
|
|
```
|
|
|
|
### Preflight Requests
|
|
|
|
OPTIONS requests are handled automatically:
|
|
|
|
- **Status**: `204 No Content`
|
|
- **Headers**: All CORS headers included
|
|
- **Purpose**: Browser preflight checks
|
|
|
|
## Request Size Limits
|
|
|
|
### Maximum Request Body Size
|
|
|
|
- **Limit**: 10 MB (10,485,760 bytes)
|
|
- **Enforcement**: Automatic via `http.MaxBytesReader`
|
|
- **Error**: Returns `413 Request Entity Too Large` if exceeded
|
|
|
|
### Content-Type Validation
|
|
|
|
POST, PUT, and PATCH requests must include a valid `Content-Type` header:
|
|
|
|
**Allowed Types:**
|
|
- `application/json`
|
|
- `application/x-www-form-urlencoded`
|
|
- `multipart/form-data`
|
|
|
|
**Error Response:**
|
|
```json
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"message": "Content-Type must be application/json"
|
|
}
|
|
```
|
|
|
|
## Middleware Chain Order
|
|
|
|
Security middleware is applied in the following order (outer to inner):
|
|
|
|
1. **CORS** - Handles preflight requests
|
|
2. **Security Headers** - Adds security headers
|
|
3. **Request Size Limit** - Enforces 10MB limit
|
|
4. **Content-Type Validation** - Validates request content type
|
|
5. **Rate Limiting** - Enforces rate limits
|
|
6. **Error Recovery** - Catches panics
|
|
7. **Request ID** - Generates request IDs
|
|
8. **Logging** - Logs requests
|
|
9. **Audit** - Records audit logs
|
|
10. **Authentication** - Validates JWT tokens
|
|
11. **Routes** - Handles requests
|
|
|
|
## Public Endpoints
|
|
|
|
The following endpoints are excluded from certain security checks:
|
|
|
|
- `/api/v1/auth/login` - Rate limiting, Content-Type validation
|
|
- `/api/v1/auth/logout` - Rate limiting, Content-Type validation
|
|
- `/healthz` - Rate limiting, Content-Type validation
|
|
- `/metrics` - Rate limiting, Content-Type validation
|
|
- `/api/docs` - Rate limiting, Content-Type validation
|
|
- `/api/openapi.yaml` - Rate limiting, Content-Type validation
|
|
|
|
## Best Practices
|
|
|
|
### For API Consumers
|
|
|
|
1. **Respect Rate Limits**: Implement exponential backoff when rate limited
|
|
2. **Use Authentication**: Authenticated users get better rate limits
|
|
3. **Include Content-Type**: Always include `Content-Type: application/json`
|
|
4. **Handle Errors**: Check for `429` status and retry after delay
|
|
5. **Request Size**: Keep request bodies under 10MB
|
|
|
|
### For Administrators
|
|
|
|
1. **Monitor Rate Limits**: Check logs for rate limit violations
|
|
2. **Adjust Limits**: Modify rate limit values in code if needed
|
|
3. **CORS Configuration**: Update allowed origins for production
|
|
4. **HTTPS**: Always use HTTPS in production for HSTS
|
|
5. **Security Headers**: Review CSP policy for your use case
|
|
|
|
## Configuration
|
|
|
|
### Rate Limiting
|
|
|
|
Rate limits are currently hardcoded but can be configured:
|
|
|
|
```go
|
|
// In rate_limit.go
|
|
rateLimiter := NewRateLimiter(100, time.Minute) // 100 req/min
|
|
```
|
|
|
|
### CORS Origins
|
|
|
|
Update allowed origins in `security_middleware.go`:
|
|
|
|
```go
|
|
allowedOrigins := []string{
|
|
"https://yourdomain.com",
|
|
"https://app.yourdomain.com",
|
|
}
|
|
```
|
|
|
|
### Request Size Limit
|
|
|
|
Modify in `app.go`:
|
|
|
|
```go
|
|
a.requestSizeMiddleware(10*1024*1024) // 10MB
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
### Rate Limit Exceeded
|
|
|
|
```json
|
|
{
|
|
"code": "SERVICE_UNAVAILABLE",
|
|
"message": "rate limit exceeded",
|
|
"details": "too many requests, please try again later"
|
|
}
|
|
```
|
|
|
|
**Status**: `429 Too Many Requests`
|
|
|
|
### Request Too Large
|
|
|
|
```json
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"message": "request body too large"
|
|
}
|
|
```
|
|
|
|
**Status**: `413 Request Entity Too Large`
|
|
|
|
### Invalid Content-Type
|
|
|
|
```json
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"message": "Content-Type must be application/json"
|
|
}
|
|
```
|
|
|
|
**Status**: `400 Bad Request`
|
|
|
|
## Monitoring
|
|
|
|
### Rate Limit Metrics
|
|
|
|
Monitor rate limit violations:
|
|
|
|
- Check audit logs for rate limit events
|
|
- Monitor `429` status codes in access logs
|
|
- Track rate limit headers in responses
|
|
|
|
### Security Events
|
|
|
|
Monitor for security-related events:
|
|
|
|
- Invalid Content-Type headers
|
|
- Request size violations
|
|
- CORS violations (check server logs)
|
|
- Authentication failures
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Configurable Rate Limits**: Environment variable configuration
|
|
2. **Per-Endpoint Limits**: Different limits for different endpoints
|
|
3. **IP Whitelisting**: Bypass rate limits for trusted IPs
|
|
4. **Rate Limit Metrics**: Prometheus metrics for rate limiting
|
|
5. **Distributed Rate Limiting**: Redis-based for multi-instance deployments
|
|
6. **Advanced CORS**: Configurable CORS via environment variables
|
|
7. **Request Timeout**: Configurable request timeout limits
|