@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/security-review/references/cryptography.md

@@ -0,0 +1,329 @@
+# Cryptographic Security Reference
+
+## Core Principles
+
+1. **Avoid storing sensitive data** when possible - the best protection is not having the data
+2. **Use established libraries** - never implement cryptographic algorithms yourself
+3. **Use modern algorithms** - avoid deprecated algorithms even if they seem convenient
+4. **Manage keys securely** - key management is often harder than encryption itself
+
+## Encryption Algorithms
+
+### Symmetric Encryption
+
+**Recommended:**
+- **AES-256-GCM** (preferred) - Provides encryption + authentication
+- **AES-128-GCM** - Acceptable minimum
+- **ChaCha20-Poly1305** - Good alternative, especially on systems without AES hardware
+
+**Avoid:**
+- DES, 3DES - Deprecated, insufficient key length
+- RC4 - Broken
+- AES-ECB - Reveals patterns in data
+- AES-CBC without authentication - Vulnerable to padding oracle attacks
+
+### Cipher Modes
+
+| Mode | Use Case | Notes |
+|------|----------|-------|
+| **GCM** | General purpose | Authenticated encryption (preferred) |
+| **CCM** | Constrained environments | Authenticated encryption |
+| **CTR + HMAC** | When GCM unavailable | Encrypt-then-MAC pattern |
+| **CBC** | Legacy only | Requires separate MAC |
+| **ECB** | Never for data | Reveals patterns |
+
+```python
+# VULNERABLE: ECB mode
+from Crypto.Cipher import AES
+cipher = AES.new(key, AES.MODE_ECB)
+
+# SAFE: GCM mode
+cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+ciphertext, tag = cipher.encrypt_and_digest(plaintext)
+```
+
+### Asymmetric Encryption
+
+**Recommended:**
+- **ECC with Curve25519** (preferred for key exchange)
+- **RSA-2048** minimum (RSA-4096 for long-term)
+- **ECDSA with P-256** or Ed25519 for signatures
+
+**Avoid:**
+- RSA < 2048 bits
+- DSA
+- ECDSA with weak curves
+
+---
+
+## Secure Random Number Generation
+
+### Cryptographically Secure PRNGs (CSPRNG)
+
+| Language | Safe | Unsafe |
+|----------|------|--------|
+| **Python** | `secrets`, `os.urandom()` | `random` module |
+| **JavaScript** | `crypto.randomBytes()`, `crypto.randomUUID()` | `Math.random()` |
+| **Java** | `SecureRandom`, `UUID.randomUUID()` | `Math.random()`, `java.util.Random` |
+| **PHP** | `random_bytes()`, `random_int()` | `rand()`, `mt_rand()`, `uniqid()` |
+| **.NET** | `RandomNumberGenerator` | `Random()` |
+| **Go** | `crypto/rand` | `math/rand` |
+| **Ruby** | `SecureRandom` | `rand()` |
+
+```python
+# VULNERABLE: Predictable random
+import random
+token = ''.join(random.choices(string.ascii_letters, k=32))
+
+# SAFE: Cryptographically secure
+import secrets
+token = secrets.token_urlsafe(32)
+```
+
+### UUID Considerations
+
+- **UUID v1**: NOT random - contains timestamp and MAC address
+- **UUID v4**: Depends on implementation - verify CSPRNG usage
+- **ULID**: Time-sortable but predictable time component
+
+```python
+# Check if UUID v4 is actually random
+import uuid
+# uuid.uuid4() uses os.urandom() in Python - SAFE
+token = str(uuid.uuid4())
+```
+
+---
+
+## Key Management
+
+### Key Generation
+
+```python
+# VULNERABLE: Key from password directly
+key = password.encode()
+
+# SAFE: Key derivation function
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+kdf = PBKDF2HMAC(
+    algorithm=hashes.SHA256(),
+    length=32,
+    salt=salt,
+    iterations=600000,
+)
+key = kdf.derive(password.encode())
+```
+
+### Key Storage
+
+**Do:**
+- Use Hardware Security Modules (HSM)
+- Use cloud key management (AWS KMS, Azure Key Vault, GCP KMS)
+- Use dedicated secrets managers (HashiCorp Vault)
+- Store keys separately from encrypted data
+
+**Don't:**
+- Hardcode keys in source code
+- Commit keys to version control
+- Store keys in environment variables (can leak)
+- Store keys in plaintext files
+
+```python
+# VULNERABLE: Hardcoded key
+KEY = b'super_secret_key_12345'
+
+# VULNERABLE: Key in code as base64
+KEY = base64.b64decode('c3VwZXJfc2VjcmV0X2tleQ==')
+
+# SAFE: Load from secure source
+KEY = secrets_manager.get_secret('encryption_key')
+```
+
+### Key Rotation
+
+**When to rotate:**
+- Key compromise (immediate)
+- Cryptoperiod expiration (time-based)
+- After encrypting 2^35 bytes (for 64-bit block ciphers)
+- Algorithm deprecation
+
+**Rotation strategies:**
+
+1. **Re-encryption** (preferred): Decrypt with old key, re-encrypt with new
+2. **Versioning**: Tag encrypted items with key version, maintain multiple keys
+
+### Envelope Encryption
+
+```python
+# Two-key structure:
+# - Data Encryption Key (DEK): Encrypts actual data
+# - Key Encryption Key (KEK): Encrypts the DEK
+
+def encrypt_with_envelope(plaintext, kek):
+    # Generate random DEK
+    dek = secrets.token_bytes(32)
+
+    # Encrypt data with DEK
+    cipher = AES.new(dek, AES.MODE_GCM)
+    ciphertext, tag = cipher.encrypt_and_digest(plaintext)
+
+    # Encrypt DEK with KEK
+    kek_cipher = AES.new(kek, AES.MODE_GCM)
+    encrypted_dek, dek_tag = kek_cipher.encrypt_and_digest(dek)
+
+    # Store encrypted_dek with ciphertext
+    return {
+        'ciphertext': ciphertext,
+        'tag': tag,
+        'encrypted_dek': encrypted_dek,
+        'dek_tag': dek_tag,
+        'nonce': cipher.nonce,
+        'dek_nonce': kek_cipher.nonce
+    }
+```
+
+---
+
+## Hashing
+
+### Password Hashing
+
+See `authentication.md` for password-specific hashing.
+
+### General Purpose Hashing
+
+| Use Case | Algorithm |
+|----------|-----------|
+| Integrity verification | SHA-256 or SHA-3 |
+| HMAC | HMAC-SHA-256 |
+| Key derivation | HKDF, PBKDF2 |
+| Content addressing | SHA-256 |
+
+**Avoid for new systems:**
+- MD5 (broken)
+- SHA-1 (deprecated)
+
+```python
+# For integrity/checksums
+import hashlib
+digest = hashlib.sha256(data).hexdigest()
+
+# For authentication (HMAC)
+import hmac
+mac = hmac.new(key, data, hashlib.sha256).digest()
+```
+
+---
+
+## Common Vulnerabilities
+
+### Weak Algorithm Usage
+
+```python
+# VULNERABLE: MD5 for security purposes
+import hashlib
+checksum = hashlib.md5(data).hexdigest()
+
+# VULNERABLE: SHA1 for signatures
+signature = hashlib.sha1(data + secret).hexdigest()
+
+# SAFE: SHA-256
+checksum = hashlib.sha256(data).hexdigest()
+```
+
+### Insufficient Key Size
+
+```python
+# VULNERABLE: Short key
+key = b'short_key'  # 9 bytes
+
+# SAFE: Adequate key length
+key = secrets.token_bytes(32)  # 256 bits
+```
+
+### Predictable IV/Nonce
+
+```python
+# VULNERABLE: Reused or predictable nonce
+nonce = b'\x00' * 12  # Static nonce
+
+# VULNERABLE: Counter-based without persistence
+nonce = counter.to_bytes(12, 'big')
+
+# SAFE: Random nonce
+nonce = secrets.token_bytes(12)
+```
+
+### ECB Mode Patterns
+
+```python
+# VULNERABLE: ECB reveals patterns
+cipher = AES.new(key, AES.MODE_ECB)
+
+# SAFE: GCM hides patterns
+cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+```
+
+### Missing Authentication
+
+```python
+# VULNERABLE: Encryption without authentication
+cipher = AES.new(key, AES.MODE_CBC, iv=iv)
+ciphertext = cipher.encrypt(pad(plaintext, 16))
+# Vulnerable to bit-flipping, padding oracle
+
+# SAFE: Authenticated encryption
+cipher = AES.new(key, AES.MODE_GCM, nonce=nonce)
+ciphertext, tag = cipher.encrypt_and_digest(plaintext)
+```
+
+---
+
+## Grep Patterns for Detection
+
+```bash
+# Weak algorithms
+grep -rn "MD5\|md5\|SHA1\|sha1\|DES\|des\|RC4\|rc4" --include="*.py" --include="*.js"
+grep -rn "MODE_ECB\|ecb" --include="*.py" --include="*.js"
+
+# Insecure random
+grep -rn "Math\.random\|random\.random\|random\.randint" --include="*.py" --include="*.js"
+grep -rn "mt_rand\|rand()" --include="*.php"
+
+# Hardcoded keys
+grep -rn "key\s*=\s*['\"]" --include="*.py" --include="*.js"
+grep -rn "secret\s*=\s*['\"]" --include="*.py" --include="*.js"
+grep -rn "AES\.new.*b'" --include="*.py"
+
+# Static IVs/nonces
+grep -rn "iv\s*=\s*b'\|nonce\s*=\s*b'" --include="*.py"
+grep -rn "\\x00.*\\x00.*\\x00" --include="*.py"
+
+# CBC without HMAC
+grep -rn "MODE_CBC" --include="*.py" | grep -v "hmac\|mac\|tag"
+```
+
+---
+
+## Testing Checklist
+
+- [ ] No hardcoded keys/secrets in source code
+- [ ] Keys not committed to version control
+- [ ] Using modern algorithms (AES-GCM, RSA-2048+, SHA-256+)
+- [ ] CSPRNG used for all security-sensitive randomness
+- [ ] Keys stored securely (HSM, KMS, secrets manager)
+- [ ] Key rotation mechanism exists
+- [ ] No ECB mode usage
+- [ ] Authenticated encryption used (GCM, or encrypt-then-MAC)
+- [ ] Adequate key lengths (256-bit symmetric, 2048+ RSA)
+- [ ] IVs/nonces are random and never reused with same key
+
+---
+
+## References
+
+- [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)
+- [OWASP Key Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html)
+- [CWE-327: Use of Broken Crypto Algorithm](https://cwe.mitre.org/data/definitions/327.html)
+- [CWE-330: Insufficient Randomness](https://cwe.mitre.org/data/definitions/330.html)
+- [CWE-321: Hard-coded Cryptographic Key](https://cwe.mitre.org/data/definitions/321.html)

package/src/.agents/skills/security-review/references/csrf.md

@@ -0,0 +1,398 @@
+# 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
+
+```html
+<!-- 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.
+
+```python
+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.
+
+```python
+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
+
+```python
+# 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.
+
+```javascript
+// Client
+fetch('/api/transfer', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': getCSRFToken()  // Or any custom header
+    },
+    body: JSON.stringify(data)
+});
+```
+
+```python
+# 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
+
+```python
+# 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
+
+```python
+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
+
+```javascript
+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:
+
+```python
+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:
+
+```python
+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:
+
+```javascript
+// 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
+
+```python
+# 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
+
+```python
+# 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
+
+```html
+<!-- 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
+
+```bash
+# 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
+
+---
+
+## References
+
+- [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
+- [CWE-352: Cross-Site Request Forgery](https://cwe.mitre.org/data/definitions/352.html)
+- [Fetch Metadata Headers](https://web.dev/fetch-metadata/)
+- [SameSite Cookies Explained](https://web.dev/samesite-cookies-explained/)