diff --git a/learn/security/api-input-validation-injection-prevention.md b/learn/security/api-input-validation-injection-prevention.md new file mode 100644 index 00000000..eea94964 --- /dev/null +++ b/learn/security/api-input-validation-injection-prevention.md @@ -0,0 +1,24 @@ +--- +title: Input Validation and Injection Prevention +description: Prevent API injection attacks and mass assignment vulnerabilities using OpenAPI schema validation and automated governance. +seo: + title: Input Validation and Injection Prevention + description: Prevent API injection attacks and mass assignment vulnerabilities using OpenAPI schema validation and automated governance. +--- + +# Input Validation and Injection Prevention + +*This comprehensive guide is coming soon and will cover:* + +## What You'll Learn + +- **SQL Injection Prevention**: Parameterized queries and input sanitization +- **Mass Assignment Protection**: Schema-based validation and field filtering +- **OpenAPI Validation**: Schema constraints and automated enforcement +- **OWASP API Security**: Addressing Top 10 injection vulnerabilities +- **Real-World Examples**: Code samples in Node.js with security patterns +- **Automated Governance**: CI/CD validation rules and policy enforcement + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/api-rate-limiting-abuse-prevention.md b/learn/security/api-rate-limiting-abuse-prevention.md new file mode 100644 index 00000000..b781a387 --- /dev/null +++ b/learn/security/api-rate-limiting-abuse-prevention.md @@ -0,0 +1,726 @@ +--- +title: Rate Limiting and Abuse Prevention +description: Implement API rate limiting strategies to prevent DoS attacks, brute force attempts, and business logic abuse. +seo: + title: Rate Limiting and Abuse Prevention + description: Implement API rate limiting strategies to prevent DoS attacks, brute force attempts, and business logic abuse. +--- + +# Rate limiting and abuse prevention for APIs + +--- + +## Key takeaways + +A single client, whether intentionally malicious or simply due to a bug in its code, can send a massive number of requests to an API in a short period. This can overwhelm the server, degrading performance for all other users or even causing the service to crash. Rate limiting is the primary defense against this scenario. + +**In this guide, you'll learn:** +- [How to implement rate limiting](#documenting-rate-limits-in-openapi) as a security and reliability control +- [OpenAPI x-rateLimit extensions](#documenting-rate-limits-in-openapi) and documentation strategies +- [Rate limiting algorithms and implementation patterns](#rate-limiting-implementation-approaches) +- [Client-side exponential backoff](#client-side-exponential-backoff) and error handling +- [Real-world lessons from the Facebook phone number scraping incident](#attack-example-facebook-phone-number-scraping-2019) +- [Advanced techniques and monitoring approaches](#rate-limiting-monitoring-and-observability) + +--- + +## Quick start guide + +Ready to implement effective rate limiting? Follow these steps: + +1. **Document rate limits:** Add [OpenAPI x-rateLimit extensions](#documenting-rate-limits-in-openapi) to your API specifications +2. **Choose an algorithm:** Select from [Token Bucket, Sliding Window, or Fixed Window](#rate-limiting-implementation-approaches) based on your needs +3. **Implement multi-tier limits:** Set up global, per-endpoint, and per-client [rate limiting configurations](#advanced-rate-limiting-techniques) +4. **Set up monitoring:** Implement [metrics collection and alerting](#rate-limiting-monitoring-and-observability) to detect attacks +5. **Test and tune:** Use the [implementation strategy framework](#rate-limiting-strategy-framework) to prioritize critical endpoints and validate limits + +**Next Steps:** Now that you have rate limiting protection in place, learn about [Authentication and Authorization with OpenAPI](authentication-authorization-openapi) to implement comprehensive access control for your APIs. + +--- + +## The library card principle + +> **The Library Card**: A library card allows a patron to check out a maximum of ten books per month. Once that limit is reached, the system will not allow any more checkouts until the next month begins, regardless of how many times the patron asks. + +**Rate limiting** applies this same principle to an API. It establishes a policy that restricts the number of requests a single client can make within a specific time window (e.g., 100 requests per minute). + +## Why rate limiting is critical for API security + +Rate limiting is a critical control for both security and reliability, directly mitigating several OWASP API Security Top 10 risks: + +1. **Security:** It thwarts Denial-of-Service (DoS) attacks by preventing traffic floods, addressing OWASP API4:2023 - Unrestricted Resource Consumption. It also makes brute-force attacks against [authentication endpoints](authentication-authorization-openapi) much slower and less effective, reducing the risk of credential stuffing attacks. + +2. **Business Logic Abuse:** It helps mitigate abuse by preventing bots from scraping data or manipulating business flows, addressing OWASP API6:2023 - Unrestricted Access to Sensitive Business Flows. + +3. **Reliability and Fair Usage:** It ensures that the API remains stable and responsive for all users by preventing any single client from monopolizing server resources. + +## Documenting rate limits in OpenAPI + +While OpenAPI 3.1 doesn't include native rate-limiting objects, extension properties (prefixed with `x-`) provide a standard mechanism. The best practice is defining custom `x-rateLimit` extensions at the operation level. + +**Note:** Rate limits are typically dynamic in production environments, with different limits for different clients based on service tiers, contracts, or usage patterns. The OpenAPI specification documents the baseline policy, while implementation systems apply client-specific variations. + +```yaml {% title="openapi.yaml" %} +paths: + /auth/login: + post: + summary: User Login + tags: [Authentication] + # Define rate-limiting policy for this sensitive endpoint # [!code highlight] + x-rateLimit: + limit: 5 # [!code highlight] Strict limit for auth endpoints + window: "1m" # [!code highlight] Short time window + scope: "ip_address" # [!code highlight] IP-based rate limiting + description: "Limits login attempts to 5 per minute per IP to prevent brute-force attacks." + responses: + '200': + description: "Successful login." + # Document the 429 response with proper headers # [!code highlight] + '429': + description: "Too Many Requests. Rate limit exceeded." + headers: + Retry-After: # [!code highlight] Required for proper client behavior + schema: + type: integer + description: "Seconds to wait before making a new request." + X-RateLimit-Limit: # [!code highlight] Inform clients of limits + schema: + type: integer + description: "Maximum requests permitted in the window." + X-RateLimit-Remaining: # [!code highlight] Help clients pace requests + schema: + type: integer + description: "Requests remaining in current window." +``` + +### Automated governance for rate limiting + +API governance tools can enforce rules that ensure [authentication endpoints](authentication-authorization-openapi) always have rate limiting policies defined. + +This approach provides dual benefits: modern API documentation tools automatically display rate limiting extensions in generated documentation, making policies transparent to API consumers, while governance rules ensure sensitive endpoints never lack rate-limiting policies. + +> **🔧 Implementation Guide**: See our [Automated Security Validation Walkthrough](automated-security-validation-walkthrough) for step-by-step instructions on implementing rate limiting validation rules, including 429 response validation and header consistency checks. + +## Rate limiting implementation approaches + +Choose the rate limiting algorithm that best fits your traffic patterns and precision requirements: + +{% tabs %} + {% tab label="Token Bucket" %} + +### Token bucket algorithm + +**Best for:** APIs that need to handle legitimate traffic spikes + +**How it works:** +- Tokens are added to a bucket at a steady rate (refill rate) +- Each request consumes one token from the bucket +- If bucket is empty, requests are rejected or queued +- Allows burst traffic up to bucket capacity + +**Pros:** +- **Flexible burst handling**: Accommodates legitimate traffic spikes +- **Smooth long-term limiting**: Maintains steady average rate +- **User-friendly**: Doesn't penalize users for occasional bursts + +**Cons:** +- **Implementation complexity**: Requires token state management +- **Memory overhead**: Need to track bucket state per client +- **Distributed challenges**: Synchronizing token state across servers + +**Implementation example:** +```javascript {% title="token-bucket.js - Secure Rate Limiting Algorithm" %} +class TokenBucket { + constructor(capacity, refillRate) { + // STEP 1: Initialize bucket parameters + this.capacity = capacity; // Max burst size (e.g., 100 requests) + this.tokens = capacity; // Start with full bucket (allows immediate bursts) + this.refillRate = refillRate; // Steady rate (e.g., 10 requests/second) + this.lastRefill = Date.now(); // Track when we last added tokens + } + + // STEP 2: Process incoming request - the main security enforcement point + consume(tokens = 1) { + // First, add any tokens we've earned since last request + this.refill(); // CRITICAL: Always refill before checking + + // STEP 3: Security decision - allow or block the request + if (this.tokens >= tokens) { + this.tokens -= tokens; // Consume tokens for this request + return true; // ✅ REQUEST ALLOWED - user under limit + } + + // STEP 4: Rate limit exceeded - implement security response + console.warn(`Rate limit exceeded. Tokens available: ${this.tokens}, requested: ${tokens}`); + return false; // ❌ BLOCK REQUEST - user over limit + } + + // STEP 5: Token refill logic - implements the "steady rate" behavior + refill() { + const now = Date.now(); + const timePassed = (now - this.lastRefill) / 1000; // Convert to seconds + + // Calculate tokens earned: time × rate + const tokensToAdd = Math.floor(timePassed * this.refillRate); // Floor prevents fractional tokens + + if (tokensToAdd > 0) { + // Add tokens but never exceed capacity (prevents bucket overflow) + this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd); + this.lastRefill = now; // Update timestamp for next calculation + + console.debug(`Added ${tokensToAdd} tokens. Current: ${this.tokens}/${this.capacity}`); + } + } + + // STEP 6: Utility methods for monitoring and debugging + getStatus() { + this.refill(); // Ensure current state + return { + tokens: this.tokens, // Available tokens right now + capacity: this.capacity, // Maximum burst size + utilizationPercent: ((this.capacity - this.tokens) / this.capacity * 100).toFixed(1) + }; + } +} + +// EXAMPLE USAGE: Protect login endpoint from brute force +const loginRateLimit = new TokenBucket(5, 0.1); // 5 attempts, refill 1 every 10 seconds + +// In your API endpoint: +app.post('/auth/login', (req, res) => { + const clientId = req.ip || req.headers['x-client-id']; // Identify the client + + if (!loginRateLimit.consume()) { + return res.status(429).json({ // HTTP 429 = Too Many Requests + error: 'Rate limit exceeded', + retryAfter: Math.ceil((1 / loginRateLimit.refillRate)) // Tell client when to retry + }); + } + + // Process login attempt... // Only reached if under rate limit +}); +``` + + {% /tab %} + {% tab label="Sliding Window" %} + +### Sliding window algorithm + +**Best for:** APIs requiring exact rate limiting precision + +**How it works:** +- Tracks exact timestamps of requests within a rolling time window +- Continuously slides the window forward with each request +- Provides most accurate rate limiting without boundary conditions + +**Pros:** +- **Maximum accuracy**: No boundary condition exploits +- **Precise enforcement**: Exact request counting within time windows +- **Fair distribution**: Prevents gaming of window boundaries + +**Cons:** +- **Memory intensive**: Stores timestamp for each request +- **Complex implementation**: Requires efficient data structures +- **Distributed complexity**: Hard to synchronize across multiple servers + +**Implementation example:** +```javascript {% title="sliding-window.js" %} +class SlidingWindowRateLimit { + constructor(maxRequests, windowSeconds) { + this.maxRequests = maxRequests; // [!code highlight] Maximum requests allowed + this.windowSeconds = windowSeconds; // [!code highlight] Time window in seconds + this.requests = []; // [!code highlight] Store request timestamps + } + + isAllowed() { + const now = Date.now(); + const windowMs = this.windowSeconds * 1000; + + // Remove requests outside current window // [!code highlight] + while (this.requests.length > 0 && this.requests[0] <= now - windowMs) { + this.requests.shift(); // [!code highlight] Clean old timestamps + } + + // Check if we're under the limit + if (this.requests.length < this.maxRequests) { + this.requests.push(now); // [!code highlight] Record this request + return true; // [!code highlight] Request allowed + } + + return false; // [!code error] Rate limit exceeded + } + + // Utility method to get current status + getStatus() { + const now = Date.now(); + const windowMs = this.windowSeconds * 1000; + + // Clean old requests first + while (this.requests.length > 0 && this.requests[0] <= now - windowMs) { + this.requests.shift(); + } + + return { + currentRequests: this.requests.length, + maxRequests: this.maxRequests, + remaining: this.maxRequests - this.requests.length, + windowSeconds: this.windowSeconds + }; + } +} +``` + + {% /tab %} + {% tab label="Fixed Window" %} + +### Fixed window algorithm + +**Best for:** Simple use cases with easy implementation requirements + +**How it works:** +- Divides time into fixed intervals (e.g., per minute, per hour) +- Counts requests within each fixed window +- Resets counter at the start of each new window + +**Pros:** +- **Simple implementation**: Easy to understand and code +- **Low memory usage**: Only need counter per time window +- **Distributed-friendly**: Easy to implement with shared counters + +**Cons:** +- **Boundary condition abuse**: 2x rate limit possible at window edges +- **Traffic spikes**: All requests could arrive at start of window +- **Less user-friendly**: Sudden cutoffs can impact user experience + +**Implementation example:** +```javascript {% title="fixed-window.js" %} +class FixedWindowRateLimit { + constructor(maxRequests, windowMs) { + this.maxRequests = maxRequests; // [!code highlight] Maximum requests per window + this.windowMs = windowMs; // [!code highlight] Window duration in milliseconds + this.counter = new Map(); // [!code highlight] Request counters by client + this.windowStart = new Map(); // [!code highlight] Window start times + } + + isAllowed(clientId) { + const now = Date.now(); + const windowStart = this.windowStart.get(clientId); + + // Check if we're in a new window // [!code highlight] + if (!windowStart || (now - windowStart) >= this.windowMs) { + this.windowStart.set(clientId, now); // [!code highlight] Start new window + this.counter.set(clientId, 1); // [!code highlight] Reset counter + return true; // [!code highlight] Request allowed + } + + // Check current window limit + const currentCount = this.counter.get(clientId) || 0; + if (currentCount < this.maxRequests) { + this.counter.set(clientId, currentCount + 1); // [!code highlight] Increment counter + return true; // [!code highlight] Request allowed + } + + return false; // [!code error] Rate limit exceeded + } + + // Utility method to get window status for a client + getWindowStatus(clientId) { + const now = Date.now(); + const windowStart = this.windowStart.get(clientId); + const currentCount = this.counter.get(clientId) || 0; + + if (!windowStart) { + return { + requests: 0, + maxRequests: this.maxRequests, + remaining: this.maxRequests, + timeUntilReset: this.windowMs + }; + } + + const timeElapsed = now - windowStart; + const timeUntilReset = Math.max(0, this.windowMs - timeElapsed); + + return { + requests: currentCount, + maxRequests: this.maxRequests, + remaining: Math.max(0, this.maxRequests - currentCount), + timeUntilReset + }; + } +} +``` + + {% /tab %} +{% /tabs %} + +## Advanced rate limiting techniques + +### Multi-tier rate limiting configuration + +```yaml {% title="Kong configuration" %} +plugins: +- name: rate-limiting + config: + minute: 100 # 100 requests per minute per IP + hour: 1000 # 1000 requests per hour per IP + policy: redis # Use Redis for distributed rate limiting + fault_tolerant: true + hide_client_headers: false + +# Per-endpoint overrides +- name: rate-limiting + route: auth-endpoints + config: + minute: 5 # Stricter limits for auth endpoints + hour: 20 + policy: redis +``` + +### Client-side exponential backoff + +```javascript +class APIClient { + async makeRequest(url, options, retries = 3) { + try { + const response = await fetch(url, options); + + if (response.status === 429) { + const retryAfter = response.headers.get('Retry-After'); + const delay = retryAfter ? parseInt(retryAfter) * 1000 : + Math.pow(2, 4 - retries) * 1000; // Exponential backoff + + if (retries > 0) { + await new Promise(resolve => setTimeout(resolve, delay)); + return this.makeRequest(url, options, retries - 1); + } + + throw new Error('Rate limit exceeded'); + } + + return response; + } catch (error) { + throw error; + } + } +} +``` + +As a complementary practice, the client-side responsibility of implementing exponential backoff should also be noted. When an API client receives a rate-limiting error (e.g., HTTP 429 Too Many Requests), it should wait for an exponentially increasing period of time between retries. This prevents clients from overwhelming the server and helps the system recover gracefully from load spikes. + +> **Tip:** Combine per-IP and per-account quotas and require exponential backoff on clients. + +## Attack example: Facebook phone number scraping (2019) + +In 2019, malicious actors exploited a vulnerability in Facebook's contact importer feature to scrape the personal data of over 530 million users. The API endpoint itself was not technically "broken"—it performed its intended function of matching phone numbers to user profiles. The vulnerability was the absence of adequate rate limiting and business rule enforcement. + +Attackers used automated scripts to submit massive lists of phone numbers, and the API dutifully returned the corresponding user profiles, allowing them to build a massive database of personal information. + +This incident highlights a different type of API attack, moving from exploiting technical flaws to abusing business logic at scale. It elevates rate limiting from an infrastructure protection mechanism to also being a tool for enforcing business rules. The `x-rateLimit` extension in OpenAPI is a form of declarative security policy. + +```mermaid +sequenceDiagram + participant B as Botnet/Script + participant API as Contact Import API + + loop Enumerate phone numbers + B->>API: Batch upload numbers + API-->>B: Matched user IDs/profile data + end + Note over B,API: Missing per-account/IP limits and anomaly detection +``` + +*Sequence diagram showing how attackers used Facebook's contact import API to scrape phone numbers at scale, exploiting missing rate limits and velocity checks to harvest personal data.* + +Why this matters: Rate limiting, velocity checks, and behavior analytics are core defenses against scraping and credential-stuffing at scale. + +## Rate limiting monitoring and observability + +Choose your monitoring approach based on your security operations needs: + +{% tabs %} + {% tab label="Metrics Collection (JavaScript)" %} + +### Rate limiting metrics collection + +```javascript +// Track rate limiting metrics for security analysis +class RateLimitMetrics { + constructor() { + this.blockedRequests = new Map(); // [!code highlight] Count blocked requests by client + this.totalRequests = new Map(); // [!code highlight] Count total requests by client + this.suspiciousPatterns = new Map(); // [!code highlight] Track attack patterns + } + + recordRequest(clientId, blocked = false, endpoint = null) { + // Initialize counters if client is new + if (!this.totalRequests.has(clientId)) { + this.totalRequests.set(clientId, 0); + this.blockedRequests.set(clientId, 0); + this.suspiciousPatterns.set(clientId, []); + } + + this.totalRequests.set(clientId, this.totalRequests.get(clientId) + 1); // [!code highlight] Increment request counter + + if (blocked) { + this.blockedRequests.set(clientId, this.blockedRequests.get(clientId) + 1); // [!code highlight] Track blocked request + + // Track suspicious patterns // [!code highlight] + const patterns = this.suspiciousPatterns.get(clientId); + patterns.push({ + timestamp: Date.now(), // [!code highlight] When attack occurred + endpoint: endpoint, // [!code highlight] Which endpoint targeted + blocked: true // [!code highlight] Request was blocked + }); + this.suspiciousPatterns.set(clientId, patterns); + } + } + + getBlockRate(clientId) { + const total = this.totalRequests.get(clientId) || 0; + const blocked = this.blockedRequests.get(clientId) || 0; + return total > 0 ? (blocked / total) * 100 : 0; + } + + getAttackIndicators(clientId, windowMinutes = 5) { + // Detect rapid repeated attempts that might indicate an attack + const patterns = this.suspiciousPatterns.get(clientId) || []; + const recentBlocks = patterns.filter(event => // [!code highlight] Filter recent blocked requests + Date.now() - event.timestamp < windowMinutes * 60 * 1000 + ); + return recentBlocks.length; // [!code highlight] Return attack indicator count + } +} +``` + +**How metrics collection works:** +- **Request tracking**: Counts all requests and blocked requests per client +- **Pattern detection**: Records timestamps and endpoints for blocked requests +- **Attack indicators**: Identifies rapid repeated attempts within time windows +- **Block rate calculation**: Calculates percentage of requests blocked per client + +{% /tab %} +{% tab label="Alerting Configuration (Prometheus)" %} + +### Alerting configuration + +```yaml {% title="prometheus-alerts.yml" %} +groups: +- name: rate_limiting_alerts + rules: + - alert: HighRateLimitBlocks + expr: rate(rate_limit_blocked_total[5m]) > 10 + for: 2m + labels: + severity: warning + annotations: + summary: "High rate of blocked requests detected" + description: "{{ $value }} requests per second being blocked" + + - alert: SuspiciousRateLimitPattern + expr: rate_limit_block_rate > 80 # [!code highlight] 80% block rate threshold + for: 1m # [!code highlight] Alert after 1 minute + labels: + severity: critical # [!code error] Critical security alert + annotations: + summary: "Possible DDoS or brute force attack" + description: "Client {{ $labels.client_id }} has {{ $value }}% blocked rate" +``` + +**How alerting works:** +- **HighRateLimitBlocks**: Monitors overall rate of blocked requests across system +- **SuspiciousRateLimitPattern**: Detects clients with abnormally high block rates +- **Threshold-based**: Configurable thresholds trigger security team notifications +- **Context-aware**: Provides client IDs and block rates for investigation + +{% /tab %} +{% /tabs %} + +### Rate limiting troubleshooting + +**Common Issues and Solutions:** + +* **Counting the wrong thing** — per-IP only; add per-account and per-token limits +* **Same limits for every endpoint** — tighten auth and write endpoints separately +* **No Retry-After header** — clients can't back off predictably +* **Stateless limits in distributed systems** — use Redis or gateway-native stores +* **Legitimate bursts blocked** — implement token bucket algorithm for flexibility + +**Quick Diagnostic Commands:** + +```bash +# Observe 429 behavior and headers +curl -i https://api.example.com/login | grep -E 'HTTP/|Retry-After|X-RateLimit' + +# Simulate burst to verify rate limiting +hey -z 10s -q 50 -c 50 https://api.example.com/api/resource + +# Test different client patterns +for i in {1..10}; do + curl -H "Authorization: Bearer $TOKEN" https://api.example.com/api/data + sleep 1 +done +``` + +### Advanced rate limiting patterns + +**Adaptive Rate Limiting:** +```javascript +// Adjust limits based on server health +class AdaptiveRateLimit { + constructor() { + this.baseLimit = 100; + this.currentLimit = 100; + this.healthThreshold = 0.8; + } + + adjustLimit(serverLoad, errorRate) { + if (serverLoad > this.healthThreshold || errorRate > 0.1) { + this.currentLimit = Math.max(10, this.currentLimit * 0.8); + } else if (serverLoad < 0.5 && errorRate < 0.01) { + this.currentLimit = Math.min(this.baseLimit, this.currentLimit * 1.1); + } + } +} +``` + +**Geographic Rate Limiting:** +```yaml {% title="nginx-rate-limit.conf" %} +# Different limits based on geographic regions +geo $rate_limit_zone { + default $binary_remote_addr; + # More restrictive limits for high-risk regions + ~^192\.168\. $binary_remote_addr_strict; + ~^10\. $binary_remote_addr_internal; +} + +limit_req_zone $rate_limit_zone zone=general:10m rate=100r/m; +limit_req_zone $binary_remote_addr_strict zone=restricted:10m rate=20r/m; +limit_req_zone $binary_remote_addr_internal zone=internal:10m rate=1000r/m; +``` + +> Rate Limiting Best Practice: "Rate limiting on auth endpoints is non-negotiable. We set 5/min per IP and per account, and alert when bypass attempts appear." + +## Frequently asked questions + +### Why is rate limiting important for API security? +Rate limiting prevents denial-of-service attacks, brute-force authentication attempts, and data scraping. It ensures fair resource usage among legitimate users while blocking malicious automation. Without rate limits, a single bad actor can overwhelm your API infrastructure. See the [Facebook phone number scraping incident](#attack-example-facebook-phone-number-scraping-2019) for a real-world example. + +### What's the difference between rate limiting and throttling? +Rate limiting sets hard limits on request volume (e.g., 100 requests per minute), rejecting excess requests with 429 status codes. Throttling typically involves slowing down or queuing requests rather than rejecting them outright. Rate limiting is more common for APIs as it provides clearer client feedback. + +### Should rate limits be per-IP, per-user, or both? +Implement multiple layers: per-IP limits prevent DDoS attacks from single sources, per-user limits enforce fair usage policies, and per-API-key limits support tiered service levels. Combine all three for comprehensive protection against different attack patterns. See [advanced rate limiting patterns](#advanced-rate-limiting-patterns) for implementation guidance. + +### How do I handle legitimate traffic spikes? +Use [token bucket algorithms](#rate-limiting-implementation-approaches) that allow controlled bursts within overall rate limits. Consider implementing adaptive rate limiting that adjusts limits based on server health. For predictable spikes, provide rate limit increase APIs or temporary exemption mechanisms for verified clients. + +### What rate limiting algorithm should I choose? +- **[Token Bucket](#rate-limiting-implementation-approaches)**: Best for APIs needing burst flexibility +- **[Sliding Window](#rate-limiting-implementation-approaches)**: Most accurate but memory intensive +- **[Fixed Window](#rate-limiting-implementation-approaches)**: Simple but allows boundary condition abuse + +Choose based on your accuracy requirements, traffic patterns, and implementation complexity tolerance. See our [implementation approaches](#rate-limiting-implementation-approaches) for detailed comparisons. + +### How do I communicate rate limits to API consumers? +Document limits in [OpenAPI specifications using x-rateLimit extensions](#documenting-rate-limits-in-openapi), include rate limit headers in responses (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`), provide clear error messages with 429 responses, and maintain public documentation about your rate limiting policies. + +## Rate limiting strategy framework + +### Implementation priority + +1. **Critical Endpoints First** + - Authentication endpoints: 5-10 requests per minute per IP + - Password reset: 3 requests per hour per email + - Account creation: 5 requests per hour per IP + - Payment processing: Strict limits based on business rules + +2. **Resource-Intensive Operations** + - Search endpoints: Higher limits but monitor query complexity + - File uploads: Size-based and frequency-based limits + - Data export: Very restrictive limits with queuing + +3. **General API Access** + - Read operations: Generous limits for good user experience + - Write operations: More restrictive than reads + - Administrative endpoints: Very restrictive with strong authentication + +### Rate limit testing strategy + +```javascript +// Rate limit testing framework +async function testRateLimit(url, requestsCount, windowSeconds) { + /** + * Test rate limiting behavior + * @param {string} url - API endpoint to test + * @param {number} requestsCount - Number of concurrent requests to send + * @param {number} windowSeconds - Expected rate limit window + */ + const startTime = Date.now(); + let successfulRequests = 0; + let blockedRequests = 0; + + // Create array of request promises + const requests = Array.from({ length: requestsCount }, () => makeRequest(url)); + + // Execute all requests concurrently + const responses = await Promise.allSettled(requests); + + // Analyze responses + for (const result of responses) { + if (result.status === 'rejected') { + console.warn('Request failed:', result.reason.message); + continue; + } + + const response = result.value; + if (response.status === 200) { + successfulRequests++; + } else if (response.status === 429) { + blockedRequests++; + } + } + + const elapsed = (Date.now() - startTime) / 1000; // Convert to seconds + console.log('Rate limit test results:'); + console.log(`Successful: ${successfulRequests}, Blocked: ${blockedRequests}`); + console.log(`Effective rate: ${(successfulRequests / elapsed).toFixed(2)} req/sec`); + + return { + successful: successfulRequests, + blocked: blockedRequests, + total: requestsCount, + elapsedSeconds: elapsed, + effectiveRate: successfulRequests / elapsed + }; +} + +async function makeRequest(url) { + try { + const response = await fetch(url, { + method: 'GET', + headers: { + 'User-Agent': 'rate-limit-tester/1.0' + } + }); + return response; + } catch (error) { + throw new Error(`Request failed: ${error.message}`); + } +} + +// Example usage: +// await testRateLimit('https://api.example.com/users', 50, 60); +``` + +## Resources and next steps + +### Essential Standards +- OWASP API Security Top 10 - Comprehensive guide including unrestricted resource consumption (API4:2023) and business logic abuse (API6:2023) +- RFC 6585 - HTTP status code 429 (Too Many Requests) specification + +### Related Security Topics +- [API Input Validation and Injection Prevention](api-input-validation-injection-prevention) - Protect APIs from malicious data +- [Authentication and Authorization with OpenAPI](authentication-authorization-openapi) - Implement secure access control +- [API TLS Encryption and HTTPS Best Practices](api-tls-encryption-https-best-practices) - Secure data in transit +- [API Security by Design: Complete Guide](/learn/security) - Overview of all API security domains \ No newline at end of file diff --git a/learn/security/api-tls-encryption-https-best-practices.md b/learn/security/api-tls-encryption-https-best-practices.md new file mode 100644 index 00000000..ca0ff727 --- /dev/null +++ b/learn/security/api-tls-encryption-https-best-practices.md @@ -0,0 +1,24 @@ +--- +title: TLS Encryption and HTTPS Best Practices for APIs +description: Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement using OpenAPI security contracts. +seo: + title: TLS Encryption and HTTPS Best Practices for APIs + description: Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement using OpenAPI security contracts. +--- + +# TLS encryption and HTTPS best practices for APIs + +*This comprehensive guide is coming soon and will cover:* + +## What you'll learn + +- **TLS 1.3 Configuration**: Modern encryption standards and cipher suite selection +- **Certificate Management**: Best practices for SSL/TLS certificate lifecycle +- **OpenAPI Security Contracts**: Enforcing HTTPS-only APIs through specifications +- **Mutual TLS (mTLS)**: Service-to-service cryptographic authentication +- **Real-World Examples**: Configuration examples for Nginx and Express.js +- **Automated Governance**: CI/CD integration for transport security validation + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/authentication-authorization-openapi.md b/learn/security/authentication-authorization-openapi.md new file mode 100644 index 00000000..38074779 --- /dev/null +++ b/learn/security/authentication-authorization-openapi.md @@ -0,0 +1,24 @@ +--- +title: Authentication and Authorization with OpenAPI +description: Implement secure access control using OpenAPI security schemes and modern authentication patterns. +seo: + title: Authentication and Authorization with OpenAPI + description: Implement secure access control using OpenAPI security schemes and modern authentication patterns. +--- + +# Authentication and authorization with OpenAPI + +*This comprehensive guide is coming soon and will cover:* + +## What you'll learn + +- **Authentication Methods**: JWT, OAuth2, API Keys, and Mutual TLS patterns +- **Authorization Strategies**: RBAC, scope-based access, and fine-grained permissions +- **OpenAPI Security Schemes**: Specification-driven access control definitions +- **Token Management**: Validation, expiration, and refresh strategies +- **Real-World Examples**: Implementation patterns with detailed code samples +- **Monitoring & Observability**: Auth failure analysis and security metrics + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/index.md b/learn/security/index.md new file mode 100644 index 00000000..ac824743 --- /dev/null +++ b/learn/security/index.md @@ -0,0 +1,254 @@ +--- +title: "API Security by Design: Framework and Fundamentals" +description: Build secure APIs from the ground up using OpenAPI security contracts and automated governance. +seo: + title: "API Security by Design: Framework and Fundamentals" + description: Build secure APIs from the ground up using OpenAPI security contracts and automated governance. +--- + +# API Security by Design: Framework and Fundamentals + +_Build secure APIs from the ground up using OpenAPI security contracts and automated governance._ + +--- + +## Key takeaways + +Many teams discover security vulnerabilities after they're already in production, but it doesn't have to be that way! + +This comprehensive guide shows you how to turn your OpenAPI specification into a security contract that actually gets enforced. You'll learn to implement TLS encryption, input validation, rate limiting policies, and access control. By the time you're done, you'll know how to catch security issues during the design phase instead of scrambling to fix them once they're in production. + +**What you'll learn:** +- Transform your OpenAPI specs into executable security policies +- Automate security enforcement in your CI/CD pipeline +- Reduce vulnerability discovery time (from months to minutes in some cases) +- Build APIs that are secure by design upfront + +--- + +## From reactive patching to proactive API security + +High-profile data breaches frequently trace back to insecure APIs, exposing a fundamental flaw in traditional security approaches. The conventional method—identifying and patching vulnerabilities in production—is reactive, costly, and ultimately inadequate. In its typical form, this paradigm treats security as an afterthought. + +Shifting security practices to the left in the development lifecycle, known as the "shift-left" imperative, addresses this by integrating security into the earliest stages of design and development. This proactive model prevents vulnerabilities from being introduced in the first place, rather than attempting to remediate them under pressure in production environments. + +### OpenAPI as your security contract + +The core of this strategy is treating your OpenAPI specification not merely as documentation, but as an executable security contract. This contract declaratively defines a set of security requirements, constraints, and policies before any application code is written. It becomes the single source of truth that dictates how an API must behave to be considered secure, effectively implementing a "policy-as-code" approach for APIs. + +However, a contract, much like a law, is only as strong as its enforcement. This is where automated governance and linting tools provide value by transforming your contract into dynamic, automated guardrails that validate security requirements at every stage of development. When integrated into a Continuous Integration/Continuous Deployment (CI/CD) pipeline, this automated governance acts as a gatekeeper, failing builds that violate the security contract and requiring fixes before deployment. + +## The four pillars of API security + +Building secure APIs doesn't have to feel like playing whack-a-mole with vulnerabilities. Once you shift from reactive patching to proactive design, you'll wonder why you ever did it any other way. Let's explore how to make security an automatic part of your API development process. + +```mermaid +graph TD + A["🏛️ Secure API Foundation"] --> B["🔐 TLS Encryption
Data in Transit"] + A --> C["✅ Input Validation
Schema Contracts"] + A --> D["⚡ Rate Limiting
Abuse Prevention"] + A --> E["🔑 Access Control
Auth & Authorization"] + + B --> F["• HTTPS Enforcement
• Certificate Management
• Strong Cipher Suites"] + C --> G["• JSON Schema Rules
• Type Validation
• Length Constraints"] + D --> H["• x-rateLimit Extensions
• 429 Response Headers
• Multi-tier Limits"] + E --> I["• Security Schemes
• JWT/OAuth2
• Scope Management"] + + J["📄 OpenAPI 3.1
Specification"] --> A + K["⚙️ Automated
Governance"] --> A + + style A fill:#e8f5e8 + style B fill:#e3f2fd + style C fill:#fff3e0 + style D fill:#fce4ec + style E fill:#f1f8e9 + style J fill:#e1f5fe + style K fill:#f3e5f5 +``` + +*Architecture diagram showing the four essential areas of API security (TLS encryption, input validation, rate limiting, access control) supported by OpenAPI specifications and automated governance tools.* + +## Deep dive guides + +Each security domain requires specific knowledge and implementation techniques. Choose the guide that matches your current focus: + +### API TLS encryption and HTTPS best practices +**What you'll learn:** Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement. + +**Key topics:** +- TLS 1.3 implementation and cipher suite selection +- OpenAPI server URL security contracts +- Mutual TLS (mTLS) for service-to-service communication +- Real-world case study: Heartbleed vulnerability and lessons learned +- Automated governance for transport security + +**Perfect for:** Infrastructure teams, DevOps engineers, and security architects + +--- + +### API input validation and injection prevention +**What you'll learn:** Stop injection attacks using OpenAPI schema validation and automated governance rules. + +**Key topics:** +- JSON Schema security constraints and validation patterns +- Mass assignment attack prevention +- SQL injection and OGNL injection defense strategies +- Real-world case study: Equifax breach analysis +- Automated validation governance and linting + +**Perfect for:** Backend developers, security engineers, and API architects + +--- + +### API rate limiting and abuse prevention +**What you'll learn:** Prevent DoS attacks, brute force attempts, and business logic abuse through strategic rate limiting. + +**Key topics:** +- Rate limiting algorithms and implementation patterns +- OpenAPI x-rateLimit extensions and documentation +- Multi-tier rate limiting strategies +- Real-world case study: Facebook phone number scraping incident +- Client-side backoff and error handling + +**Perfect for:** API product managers, DevOps teams, and security operations + +--- + +### Authentication and authorization with OpenAPI +**What you'll learn:** Implement secure access control using OpenAPI security schemes and modern authentication patterns. + +**Key topics:** +- OpenAPI security schemes (JWT, OAuth2, API Keys, mTLS) +- Authentication vs authorization flow patterns +- Scope-based access control and permission systems +- Security scheme governance and automation +- Token validation and session management + +**Perfect for:** Identity and access management teams, full-stack developers, and security engineers + +## Understanding design-time vs runtime security + +It's important to understand that OpenAPI-based security governance operates at **design-time**, not runtime. This governance approach excels at preventing configuration errors, missing security controls, and specification inconsistencies before they reach production. That said, it cannot prevent runtime vulnerabilities in the underlying implementation. + +### API security implementation timeline + +```mermaid +timeline + title API Security Implementation Timeline + + section Design Phase + OpenAPI Spec : Security schemes defined + : Input validation rules + : Rate limiting policies + + section Build Phase + Code Generation : Security middleware + : Validation logic + CI/CD Pipeline : Governance checks + : Security linting + + section Runtime Phase + Production : TLS termination + : Authentication + : Rate limiting + : Input validation + Monitoring : Attack detection + : Performance metrics +``` + +*Timeline showing how API security spans from design-time specification through build automation to runtime enforcement, with different security controls applied at each phase.* + +**Design-time security governance prevents:** +- Accidentally public endpoints (missing security requirements) +- Insecure server configurations (HTTP instead of HTTPS) +- Missing input validation constraints +- Inconsistent rate limiting policies +- Data leakage through unused components + +**Runtime security still requires:** +- Patch management for frameworks and libraries (like the Heartbleed OpenSSL vulnerability) +- Secure coding practices and parameterized queries +- Infrastructure security monitoring and alerting +- Penetration testing and vulnerability scanning + +True "secure by design" requires both: design-time contracts enforced through OpenAPI governance *and* runtime security posture management as part of a comprehensive DevSecOps practice. + +## API security maturity model + +Implementing comprehensive API security is a journey. Organizations typically progress through distinct maturity levels as they build more sophisticated security practices: + +```mermaid +graph TD + A[Level 0: Basic] --> B[Level 1: Structured] --> C[Level 2: Automated] --> D[Level 3: Proactive] + + A --> A1[Manual reviews
Basic HTTPS
Simple auth] + B --> B1[OpenAPI specs
Schema validation
Rate limiting] + C --> C1[Automated governance
CI/CD integration
Policy enforcement] + D --> D1[Threat modeling
Zero-trust architecture
Continuous monitoring] + + style A fill:#ffcdd2 + style B fill:#fff59d + style C fill:#c8e6c9 + style D fill:#a5d6a7 +``` + +*API security maturity progression showing the evolution from basic manual practices to proactive, automated security governance with comprehensive threat detection and prevention.* + +**Level 0 - Basic Security:** +- Manual code reviews for obvious security issues +- HTTPS enabled but not enforced through specifications +- Basic authentication (API keys or simple passwords) +- Ad-hoc security practices without consistent standards + +**Level 1 - Structured Security:** +- OpenAPI specifications document all APIs with security requirements +- Schema-based input validation prevents basic injection attacks +- Rate limiting implemented on authentication and sensitive endpoints +- Consistent security patterns across API teams + +**Level 2 - Automated Security:** +- Automated governance tools enforce security standards in CI/CD pipelines +- Security policies defined as code and validated automatically +- Breaking changes to security configurations fail builds +- Security metrics tracked and monitored systematically + +**Level 3 - Proactive Security:** +- Comprehensive threat modeling integrated into the design process +- Zero-trust architecture with mutual TLS for service-to-service communication +- Continuous security monitoring with behavioral analysis and anomaly detection +- Security feedback loops drive iterative improvements to governance policies + +Most organizations find that advancing one level at a time provides the most sustainable improvement path. The techniques covered in this guide primarily support progression from Level 0 to Level 2, with Level 3 requiring additional infrastructure and organizational maturity. + +## Frequently asked questions + +### What is design-first API security? +Design-first API security means defining security requirements in your OpenAPI specification before writing code, then using automated governance tools to enforce those requirements throughout the development lifecycle. This prevents vulnerabilities from reaching production rather than patching them after discovery. + +### How does OpenAPI prevent injection attacks? +OpenAPI specifications define precise data schemas with type validation, format constraints, and length limits. When enforced by governance tools, these schemas automatically reject malformed inputs that could contain injection payloads, stopping attacks before they reach your application logic. + +### Why is rate limiting important for API security? +Rate limiting prevents denial-of-service attacks, brute-force authentication attempts, and data scraping. It ensures fair resource usage among legitimate users while blocking malicious automation. Without rate limits, a single bad actor can overwhelm your API infrastructure. + +### Can I implement all four security areas with just OpenAPI? +Yes, OpenAPI 3.1 supports all four security areas: TLS enforcement through server URLs, input validation via JSON schemas, rate limiting through extensions like `x-rateLimit`, and access control via security schemes. Combined with governance automation, your specification becomes an executable security contract. + +### What's the difference between authentication and authorization in APIs? +Authentication verifies *who* the user is (like checking an ID card), while authorization determines *what* they can do (like checking permissions). Both are essential for API security, and OpenAPI provides security schemes to define and enforce both concepts through your specification. + +## Resources + +### Security standards and guidelines +- OWASP API Security Top 10 - Comprehensive vulnerability guide including injection attacks (API3:2023), resource consumption (API4:2023), and business logic abuse (API6:2023) +- NIST SP 800-52 Rev. 2 - Official guidelines for secure TLS implementation and configuration requirements +- IETF RFC 8446 - TLS 1.3 protocol specification and security requirements + +### Practical implementation tools +- Mozilla SSL Configuration Generator - Generate secure, up-to-date TLS configurations for various web servers and security levels +- OpenAPI Generator - Code generation tool for creating secure client SDKs and server stubs from OpenAPI specifications +- OpenAPI Specification - Official OpenAPI 3.1 specification including security scheme definitions + +### DevSecOps and API governance +- OWASP API Security Project - Community-driven API security best practices and threat modeling +- OpenAPI Security Schemes - Official specification for defining authentication and authorization in OpenAPI \ No newline at end of file diff --git a/learn/security/sidebars.yaml b/learn/security/sidebars.yaml new file mode 100644 index 00000000..c97575e2 --- /dev/null +++ b/learn/security/sidebars.yaml @@ -0,0 +1,5 @@ +- page: ./index.md +- page: ./api-tls-encryption-https-best-practices.md +- page: ./api-input-validation-injection-prevention.md +- page: ./api-rate-limiting-abuse-prevention.md +- page: ./authentication-authorization-openapi.md diff --git a/pages/learning-center/cards.ts b/pages/learning-center/cards.ts index 61ccb907..818b4989 100644 --- a/pages/learning-center/cards.ts +++ b/pages/learning-center/cards.ts @@ -95,22 +95,24 @@ export const cards = [ { title: 'Tools for API Testing in 2025', link: '/learn/testing/tools-for-api-testing-in-2025' }, ], }, - // { - // id: 7, - // key: 'api-security', - // title: 'API Security', - // description: - // 'Gain insights into securing your APIs with essential resources, tools, and best practices to protect your applications.', - // thumbnail: apiSecurityThumbnail, - // moreItems: ' more topics', - // landingPage: '/', - // items: [ - // { title: 'Introduction to API Security', link: '' }, - // { title: 'Common API Vulnerabilities', link: '' }, - // { title: 'Implementing Authentication and Authorization examples', link: '' }, - // { title: 'Best Practices for Securing APIs', link: '' }, - // ], - // }, + { + id: 6, + key: 'api-security', + title: 'API Security', + description: + 'Gain insights into securing your APIs with essential resources, tools, and best practices to protect your applications.', + thumbnail: apiSecurityThumbnail, + moreItems: '2 more topics', + landingPage: '/learn/security', + items: [ + { title: 'API Security by Design: Complete Guide', link: '/learn/security' }, + { title: 'API TLS Encryption and HTTPS Best Practices', link: '/learn/security/api-tls-encryption-https-best-practices' }, + { title: 'API Input Validation and Injection Prevention', link: '/learn/security/api-input-validation-injection-prevention' }, + { title: 'API Rate Limiting and Abuse Prevention', link: '/learn/security/api-rate-limiting-abuse-prevention' }, + { title: 'Authentication and Authorization with OpenAPI', link: '/learn/security/authentication-authorization-openapi' }, + { title: 'Automated Security Validation - Interactive Walkthrough', link: '/learn/security/automated-security-validation-walkthrough' }, + ], + }, // { // id: 8, // key: 'graphql', diff --git a/redocly.yaml b/redocly.yaml index f21a8ad0..aef95e5c 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -11,6 +11,7 @@ redirects: ignore: - '.github' - 'learn/arazzo/_filesets/**' + - 'learn/security/_filesets/**' - '**/code-walkthrough-files/**' - docs/realm/.templates