9.7 KiB
9.7 KiB
Cross-Site Request Forgery (CSRF) Prevention Reference
Overview
CSRF attacks trick authenticated users into performing unintended actions by exploiting the browser's automatic credential transmission. The attack works because browsers automatically include cookies with requests to a domain, regardless of the request's origin.
Attack Scenario
<!-- Attacker's page -->
<img src="https://bank.com/transfer?to=attacker&amount=10000">
<!-- Or form submission -->
<form action="https://bank.com/transfer" method="POST" id="evil">
<input name="to" value="attacker">
<input name="amount" value="10000">
</form>
<script>document.getElementById('evil').submit();</script>
When a logged-in user visits the attacker's page, their browser makes the request with their session cookie.
Primary Defenses
1. Synchronizer Token Pattern
Generate and validate a unique token per session.
import secrets
# Generate token on session creation
def create_csrf_token(session_id):
token = secrets.token_urlsafe(32)
store_csrf_token(session_id, token)
return token
# Include in forms
def render_form():
token = get_csrf_token(session.id)
return f'''
<form method="POST">
<input type="hidden" name="csrf_token" value="{token}">
<!-- form fields -->
</form>
'''
# Validate on submission
def validate_csrf():
submitted_token = request.form.get('csrf_token')
stored_token = get_csrf_token(session.id)
if not submitted_token or not secrets.compare_digest(submitted_token, stored_token):
raise CSRFValidationError()
2. Double Submit Cookie Pattern (Stateless)
Use a cryptographically signed token that doesn't require server-side storage.
import hmac
import hashlib
import time
SECRET_KEY = os.environ['CSRF_SECRET']
def generate_csrf_token(session_id):
"""Generate signed token tied to session."""
timestamp = int(time.time())
message = f"{session_id}:{timestamp}"
signature = hmac.new(
SECRET_KEY.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return f"{timestamp}:{signature}"
def validate_csrf_token(token, session_id):
"""Validate token matches session and isn't expired."""
try:
timestamp, signature = token.split(':')
timestamp = int(timestamp)
# Check expiry (1 hour)
if time.time() - timestamp > 3600:
return False
# Verify signature
message = f"{session_id}:{timestamp}"
expected = hmac.new(
SECRET_KEY.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return secrets.compare_digest(signature, expected)
except:
return False
3. SameSite Cookie Attribute
# Modern browsers respect SameSite attribute
response.set_cookie(
'session_id',
value=session_id,
samesite='Lax', # Or 'Strict' for maximum protection
secure=True,
httponly=True
)
SameSite Values:
| Value | Behavior |
|---|---|
| Strict | Never sent cross-site |
| Lax | Sent only with safe methods (GET) on top-level navigation |
| None | Always sent (requires Secure) |
4. Custom Request Headers
For AJAX/API requests, require a custom header that can't be set cross-origin without CORS.
// Client
fetch('/api/transfer', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': getCSRFToken() // Or any custom header
},
body: JSON.stringify(data)
});
# Server
@app.before_request
def verify_csrf_header():
if request.method in ('POST', 'PUT', 'DELETE', 'PATCH'):
token = request.headers.get('X-CSRF-Token')
if not validate_csrf_token(token):
return jsonify({'error': 'CSRF validation failed'}), 403
Framework Implementations
Django
# Enabled by default via middleware
MIDDLEWARE = [
'django.middleware.csrf.CsrfViewMiddleware',
...
]
# In templates
<form method="POST">
{% csrf_token %}
...
</form>
# For AJAX
<script>
const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;
fetch('/api/endpoint', {
method: 'POST',
headers: {'X-CSRFToken': csrftoken},
...
});
</script>
Flask
from flask_wtf.csrf import CSRFProtect
csrf = CSRFProtect(app)
# In templates
<form method="POST">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
...
</form>
# Exempt specific routes if needed (be careful!)
@csrf.exempt
@app.route('/webhook', methods=['POST'])
def webhook():
pass
Express.js
const csrf = require('csurf');
const csrfProtection = csrf({ cookie: true });
app.use(csrfProtection);
app.get('/form', (req, res) => {
res.render('form', { csrfToken: req.csrfToken() });
});
// In template
<form method="POST">
<input type="hidden" name="_csrf" value="<%= csrfToken %>">
...
</form>
Origin and Referer Validation
As a supplementary defense:
def verify_origin():
"""Verify request origin matches expected domain."""
origin = request.headers.get('Origin')
referer = request.headers.get('Referer')
# Prefer Origin header
if origin:
if not is_trusted_origin(origin):
return False
return True
# Fall back to Referer
if referer:
parsed = urlparse(referer)
if not is_trusted_origin(f"{parsed.scheme}://{parsed.netloc}"):
return False
return True
# No origin info - could be same-origin or direct request
# Decision depends on security requirements
return True # Or False for strict validation
def is_trusted_origin(origin):
TRUSTED = {'https://example.com', 'https://admin.example.com'}
return origin in TRUSTED
Fetch Metadata Headers
Modern browsers send additional headers that indicate request context:
def check_fetch_metadata():
"""Use Fetch Metadata headers for CSRF protection."""
sec_fetch_site = request.headers.get('Sec-Fetch-Site')
sec_fetch_mode = request.headers.get('Sec-Fetch-Mode')
# Allow same-origin requests
if sec_fetch_site == 'same-origin':
return True
# Allow navigation requests (clicking links)
if sec_fetch_site == 'none' and sec_fetch_mode == 'navigate':
return True
# Block cross-origin state-changing requests
if request.method in ('POST', 'PUT', 'DELETE', 'PATCH'):
if sec_fetch_site in ('cross-site', 'same-site'):
return False
return True
Client-Side CSRF
Modern variant where JavaScript code uses attacker-controlled input:
// VULNERABLE: URL fragment used in request
const param = window.location.hash.substring(1);
fetch(`/api/action?${param}`, { method: 'POST' });
// Attack: https://example.com#action=delete&target=all
// SAFE: Validate before use
const allowedActions = ['view', 'refresh'];
const param = window.location.hash.substring(1);
const parsed = new URLSearchParams(param);
if (allowedActions.includes(parsed.get('action'))) {
fetch(`/api/action?${param}`, { method: 'POST' });
}
Common Mistakes
1. GET Requests for State Changes
# VULNERABLE: State change via GET
@app.route('/delete/<id>')
def delete_item(id):
Item.delete(id) # Attacker: <img src="/delete/123">
# SAFE: Use POST for state changes
@app.route('/delete/<id>', methods=['POST'])
@csrf_required
def delete_item(id):
Item.delete(id)
2. CORS Misconfiguration
# VULNERABLE: Allows any origin with credentials
@app.after_request
def add_cors(response):
response.headers['Access-Control-Allow-Origin'] = request.headers.get('Origin')
response.headers['Access-Control-Allow-Credentials'] = 'true'
return response
# SAFE: Explicit allowlist
ALLOWED_ORIGINS = {'https://trusted.com'}
@app.after_request
def add_cors(response):
origin = request.headers.get('Origin')
if origin in ALLOWED_ORIGINS:
response.headers['Access-Control-Allow-Origin'] = origin
response.headers['Access-Control-Allow-Credentials'] = 'true'
return response
3. Token in URL
<!-- VULNERABLE: Token exposed in URL (logged, cached, referer) -->
<a href="/action?csrf_token=abc123">Do Action</a>
<!-- SAFE: Token in form -->
<form method="POST" action="/action">
<input type="hidden" name="csrf_token" value="abc123">
<button type="submit">Do Action</button>
</form>
Grep Patterns for Detection
# Missing CSRF protection
grep -rn "@app\.route.*POST\|@router\.post" --include="*.py" | grep -v "csrf"
# State-changing GET requests
grep -rn "\.delete\|\.update\|\.create" --include="*.py" | grep "GET"
# CORS wildcards
grep -rn "Access-Control-Allow-Origin.*\*" --include="*.py"
# Framework CSRF disabled
grep -rn "csrf_exempt\|WTF_CSRF_ENABLED.*False\|csrf.*disable" --include="*.py"
Testing Checklist
- All state-changing requests require POST/PUT/DELETE
- CSRF tokens included in all forms
- CSRF tokens validated on submission
- SameSite cookie attribute set (Lax or Strict)
- Custom headers required for API requests
- Origin/Referer validated as secondary defense
- Fetch Metadata headers checked where supported
- CORS properly configured (no wildcard with credentials)
- Token not exposed in URL/logs
- GET requests never change state