Fuzz test APIs with malformed inputs and edge cases
Generates comprehensive fuzz tests for REST APIs to discover security vulnerabilities, crashes, and edge cases.
/plugin marketplace add jeremylongshore/claude-code-plugins-plus/plugin install api-fuzzer@claude-code-plugins-plusAutomated fuzz testing for REST APIs to discover vulnerabilities, crashes, and unexpected behavior through malformed inputs, boundary values, and random payloads. This command generates comprehensive fuzz test suites targeting injection attacks, input validation failures, and edge cases.
Why fuzz testing matters:
Alternatives considered:
This approach balances: Automation, coverage, security focus, and integration with CI/CD.
Use API fuzzing when:
Don't use when:
Identify Attack Surface
Generate Fuzz Inputs
Execute Fuzz Tests
Analyze Results
Remediate and Retest
// tests/api-fuzzer.test.js
const axios = require('axios');
const API_BASE = process.env.API_URL || 'http://localhost:3000';
// Fuzz input generators
const fuzzInputs = {
// String mutations
strings: [
'', // Empty
null,
undefined,
' ', // Whitespace
'A'.repeat(10000), // Very long
'A'.repeat(1000000), // Extremely long
'<script>alert(1)</script>', // XSS
'<img src=x onerror=alert(1)>', // XSS variant
'${7*7}', // Template injection
'{{7*7}}', // Template injection variant
'\x00', // Null byte
'\n\r\t', // Control characters
'../../etc/passwd', // Path traversal
'../../../etc/passwd', // Path traversal variant
'\\x41\\x42\\x43', // Hex encoding
],
// SQL injection payloads
sqlInjection: [
"' OR '1'='1",
"' OR '1'='1' --",
"' OR '1'='1' /*",
"1; DROP TABLE users--",
"1' UNION SELECT NULL, NULL--",
"admin'--",
"' OR 1=1--",
"1' ORDER BY 10--", // Column enumeration
],
// Number mutations
numbers: [
0,
-1,
1,
999999999999999999, // Large positive
-999999999999999999, // Large negative
Infinity,
-Infinity,
NaN,
Number.MAX_SAFE_INTEGER,
Number.MIN_SAFE_INTEGER,
Number.MAX_VALUE,
Number.MIN_VALUE,
3.14159265358979323846, // Floating point
],
// Boolean mutations
booleans: [
true,
false,
'true',
'false',
1,
0,
'yes',
'no',
],
// Object/Array mutations
structures: [
{},
[],
{ __proto__: { polluted: true } }, // Prototype pollution
{ constructor: { prototype: { polluted: true } } },
[[[[[]]]]]], // Deeply nested
new Array(10000).fill('x'), // Large array
],
// Special characters
special: [
'!@#$%^&*()',
'"><script>alert(1)</script>',
'%00', // URL-encoded null byte
'%0A', // URL-encoded newline
'\\', // Backslash
'/', // Forward slash
'..\\..\\..\\', // Windows path traversal
],
};
describe('API Fuzz Testing', () => {
describe('POST /api/users - Create User', () => {
it('handles malformed string inputs gracefully', async () => {
for (const input of fuzzInputs.strings) {
try {
const response = await axios.post(`${API_BASE}/api/users`, {
name: input,
email: 'test@example.com',
}, { validateStatus: () => true }); // Accept all status codes
// Should not crash (500) or hang
expect(response.status).not.toBe(500);
expect(response.status).toBeLessThan(500);
// Should return proper error for invalid input
if (response.status >= 400) {
expect(response.data).toHaveProperty('error');
}
} catch (error) {
// Network errors are acceptable (timeouts, connection refused)
if (error.code !== 'ECONNABORTED' && error.code !== 'ECONNREFUSED') {
throw error;
}
}
}
});
it('prevents SQL injection', async () => {
for (const payload of fuzzInputs.sqlInjection) {
const response = await axios.post(`${API_BASE}/api/users`, {
name: payload,
email: payload,
}, { validateStatus: () => true });
// Should not execute SQL
expect(response.status).not.toBe(200);
expect(response.status).toBe(400); // Should be validation error
// Should not leak database errors
if (response.data.error) {
expect(response.data.error.toLowerCase()).not.toMatch(/sql|database|query/);
}
}
});
it('handles numeric boundary values', async () => {
for (const input of fuzzInputs.numbers) {
const response = await axios.post(`${API_BASE}/api/users`, {
age: input,
name: 'Test User',
email: 'test@example.com',
}, { validateStatus: () => true });
expect(response.status).not.toBe(500);
// Should validate range
if (input < 0 || input > 150) {
expect(response.status).toBe(400);
}
}
});
it('validates deeply nested objects', async () => {
for (const input of fuzzInputs.structures) {
const response = await axios.post(`${API_BASE}/api/users`, {
metadata: input,
name: 'Test',
email: 'test@example.com',
}, { validateStatus: () => true });
expect(response.status).not.toBe(500);
}
});
});
describe('GET /api/users/:id - Get User', () => {
it('handles malformed ID parameters', async () => {
const idInputs = [
...fuzzInputs.strings,
...fuzzInputs.sqlInjection,
...fuzzInputs.special,
];
for (const input of idInputs) {
const response = await axios.get(
`${API_BASE}/api/users/${encodeURIComponent(input)}`,
{ validateStatus: () => true }
);
expect(response.status).not.toBe(500);
// Should be 400 (bad request) or 404 (not found)
expect([400, 404]).toContain(response.status);
}
});
});
describe('Query Parameter Fuzzing', () => {
it('handles malformed query parameters', async () => {
for (const input of fuzzInputs.strings) {
const response = await axios.get(`${API_BASE}/api/users`, {
params: { search: input },
validateStatus: () => true,
});
expect(response.status).not.toBe(500);
}
});
it('prevents injection via query params', async () => {
for (const payload of fuzzInputs.sqlInjection) {
const response = await axios.get(`${API_BASE}/api/users`, {
params: { filter: payload },
validateStatus: () => true,
});
expect(response.status).not.toBe(500);
// Should not return all users or execute SQL
if (response.status === 200) {
expect(response.data.length).toBe(0); // No results for invalid filter
}
}
});
});
});
# tests/test_api_fuzzer.py
import pytest
import requests
from typing import Any, List
import string
import random
API_BASE = "http://localhost:3000"
class FuzzInputGenerator:
"""Generate various fuzz inputs for API testing"""
@staticmethod
def string_mutations() -> List[Any]:
return [
"", # Empty
None,
" ", # Whitespace
"A" * 10000, # Very long
"<script>alert(1)</script>", # XSS
"${7*7}", # Template injection
"../../etc/passwd", # Path traversal
"\x00", # Null byte
]
@staticmethod
def sql_injection_payloads() -> List[str]:
return [
"' OR '1'='1",
"' OR '1'='1' --",
"1; DROP TABLE users--",
"admin'--",
]
@staticmethod
def number_mutations() -> List[Any]:
return [
0, -1, 999999999999999999,
-999999999999999999,
float('inf'), float('-inf'),
]
@staticmethod
def generate_random_string(length: int = 100) -> str:
"""Generate random string with special characters"""
chars = string.ascii_letters + string.digits + string.punctuation
return ''.join(random.choice(chars) for _ in range(length))
class TestAPIFuzzing:
"""Comprehensive API fuzz tests"""
def test_string_input_handling(self):
"""Test API handles malformed string inputs"""
for input_value in FuzzInputGenerator.string_mutations():
response = requests.post(
f"{API_BASE}/api/users",
json={"name": input_value, "email": "test@example.com"},
timeout=5
)
# Should not crash (500)
assert response.status_code < 500, \
f"Server error with input: {repr(input_value)}"
# Should return proper error for invalid input
if response.status_code >= 400:
assert "error" in response.json()
def test_sql_injection_prevention(self):
"""Test API prevents SQL injection"""
for payload in FuzzInputGenerator.sql_injection_payloads():
response = requests.post(
f"{API_BASE}/api/users",
json={"name": payload, "email": payload},
timeout=5
)
# Should reject malicious input
assert response.status_code != 200, \
f"Accepted SQL injection: {payload}"
# Should not leak database errors
if response.status_code >= 400:
error_text = response.text.lower()
assert "sql" not in error_text
assert "database" not in error_text
def test_numeric_boundary_values(self):
"""Test numeric input boundaries"""
for value in FuzzInputGenerator.number_mutations():
response = requests.post(
f"{API_BASE}/api/users",
json={
"name": "Test User",
"email": "test@example.com",
"age": value
},
timeout=5
)
assert response.status_code < 500
def test_random_fuzzing(self):
"""Random fuzz testing with generated inputs"""
for _ in range(100): # 100 random tests
random_data = {
"name": FuzzInputGenerator.generate_random_string(random.randint(1, 1000)),
"email": FuzzInputGenerator.generate_random_string(20),
"age": random.randint(-1000, 1000),
}
response = requests.post(
f"{API_BASE}/api/users",
json=random_data,
timeout=5
)
# Should handle gracefully
assert response.status_code < 500
def test_header_injection(self):
"""Test header injection vulnerabilities"""
malicious_headers = {
"X-Forwarded-For": "' OR '1'='1",
"User-Agent": "<script>alert(1)</script>",
"Referer": "javascript:alert(1)",
}
response = requests.get(
f"{API_BASE}/api/users",
headers=malicious_headers,
timeout=5
)
assert response.status_code < 500
// .github/workflows/fuzz-tests.yml
name: API Fuzz Testing
on: [push, pull_request]
jobs:
fuzz:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Start API server
run: npm run start:test &
- name: Wait for API
run: npx wait-on http://localhost:3000/health
- name: Run fuzz tests
run: npm run test:fuzz
- name: Upload fuzz report
if: failure()
uses: actions/upload-artifact@v2
with:
name: fuzz-report
path: ./fuzz-report.html
// fuzzer/openapi-fuzzer.js
const SwaggerParser = require('@apidevtools/swagger-parser');
const axios = require('axios');
async function fuzzFromOpenAPI(specPath) {
const api = await SwaggerParser.validate(specPath);
for (const [path, methods] of Object.entries(api.paths)) {
for (const [method, operation] of Object.entries(methods)) {
if (method === 'get' || method === 'post') {
console.log(`Fuzzing ${method.toUpperCase()} ${path}`);
// Generate fuzz inputs based on parameters
const fuzzInputs = generateFuzzInputs(operation.parameters);
for (const input of fuzzInputs) {
const response = await axios[method](
`${api.servers[0].url}${path}`,
input,
{ validateStatus: () => true }
);
if (response.status === 500) {
console.error(`CRASH FOUND: ${method} ${path}`, input);
}
}
}
}
}
}
function generateFuzzInputs(parameters) {
// Generate based on parameter schemas
return [
/* fuzz inputs */
];
}
fuzzFromOpenAPI('./openapi.yaml');
# fuzzer/continuous_fuzzer.py
import requests
import random
import json
from datetime import datetime
class ContinuousFuzzer:
"""Continuously fuzz API endpoints with mutations"""
def __init__(self, base_url: str, endpoints: list):
self.base_url = base_url
self.endpoints = endpoints
self.crashes = []
def mutate_string(self, s: str) -> str:
"""Mutate string with random changes"""
mutations = [
lambda x: x + chr(random.randint(0, 255)), # Append random char
lambda x: x[:len(x)//2], # Truncate
lambda x: x * 100, # Repeat
lambda x: x.replace('a', '<script>'), # XSS injection
lambda x: x + "' OR '1'='1", # SQL injection
]
return random.choice(mutations)(s)
def fuzz_endpoint(self, endpoint: str, method: str = "POST"):
"""Fuzz single endpoint"""
seed_data = {"name": "test", "email": "test@test.com"}
for _ in range(1000): # 1000 iterations
# Mutate seed data
fuzzed_data = {}
for key, value in seed_data.items():
if isinstance(value, str):
fuzzed_data[key] = self.mutate_string(value)
else:
fuzzed_data[key] = value
# Send request
try:
response = requests.request(
method,
f"{self.base_url}{endpoint}",
json=fuzzed_data,
timeout=5
)
# Detect crashes
if response.status_code == 500:
self.crashes.append({
"endpoint": endpoint,
"input": fuzzed_data,
"response": response.text,
"timestamp": datetime.now().isoformat()
})
except requests.exceptions.Timeout:
# Potential hang/DoS
self.crashes.append({
"endpoint": endpoint,
"input": fuzzed_data,
"error": "timeout",
"timestamp": datetime.now().isoformat()
})
def run(self, duration_minutes: int = 60):
"""Run continuous fuzzing"""
import time
start_time = time.time()
while (time.time() - start_time) < (duration_minutes * 60):
endpoint = random.choice(self.endpoints)
self.fuzz_endpoint(endpoint)
# Save crash report
with open('crash_report.json', 'w') as f:
json.dump(self.crashes, f, indent=2)
print(f"Found {len(self.crashes)} crashes")
# Usage
fuzzer = ContinuousFuzzer(
base_url="http://localhost:3000",
endpoints=["/api/users", "/api/orders", "/api/products"]
)
fuzzer.run(duration_minutes=60)
Common issues and solutions:
Problem: Fuzzer overwhelms API with requests
Problem: False positives (valid errors reported as crashes)
Problem: Fuzzer credentials get rate-limited or blocked
Problem: Fuzzing breaks production data
Problem: Can't reproduce crashes
// fuzzer.config.js
module.exports = {
target: {
baseUrl: process.env.API_URL || 'http://localhost:3000',
endpoints: [
{ path: '/api/users', method: 'POST' },
{ path: '/api/users/:id', method: 'GET' },
{ path: '/api/orders', method: 'POST' },
],
},
authentication: {
type: 'bearer', // 'bearer' | 'basic' | 'apiKey'
token: process.env.TEST_API_TOKEN,
},
fuzzing: {
iterations: 1000, // Tests per endpoint
timeout: 5000, // Request timeout (ms)
delay: 100, // Delay between requests (ms)
concurrent: 5, // Concurrent requests
},
inputs: {
strings: true, // Enable string fuzzing
numbers: true, // Enable number fuzzing
sqlInjection: true, // Enable SQL injection tests
xss: true, // Enable XSS tests
customPayloads: [ // Custom payloads
'{{7*7}}',
'${7*7}',
],
},
reporting: {
output: './fuzz-report.html',
verbose: false,
onCrash: (crash) => {
console.error('CRASH:', crash);
// Send alert (Slack, PagerDuty, etc.)
},
},
skipEndpoints: [
'/api/health', // Skip health checks
'/api/metrics', // Skip metrics
],
};
DO:
DON'T:
TIPS:
/scan-api-security - Comprehensive security scanning/validate-schemas - Schema validation testing/run-load-test - Performance testing under load/generate-rest-api - Generate APIs with built-in validation/implement-error-handling - Proper error handling to prevent info leaksOptimization strategies:
Security checklist:
Fuzzer hangs or times out:
No crashes found:
Too many false positives:
Can't reproduce crashes: