@devo-bmad-custom/agent-orchestration 1.0.0

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

@@ -0,0 +1,353 @@
+# Authentication Security Reference
+
+## Password Requirements
+
+### Strength Requirements
+
+| Context | Minimum Length | Maximum Length |
+|---------|---------------|----------------|
+| With MFA | 8 characters | At least 64 characters |
+| Without MFA | 15 characters | At least 64 characters |
+
+**Composition Rules:**
+- Allow all printable characters including spaces and Unicode
+- No mandatory complexity rules (uppercase, numbers, symbols)
+- No periodic forced password changes
+- Check against breached password databases (e.g., Have I Been Pwned)
+- Implement password strength meters (e.g., zxcvbn)
+
+### Password Storage
+
+**Recommended Algorithms (in order of preference):**
+
+1. **Argon2id** (preferred)
+   ```
+   Memory: minimum 19 MiB (19456 KB)
+   Iterations: minimum 2
+   Parallelism: 1
+   ```
+
+2. **scrypt**
+   ```
+   CPU/memory cost (N): 2^17
+   Block size (r): 8
+   Parallelization (p): 1
+   ```
+
+3. **bcrypt** (legacy systems)
+   ```
+   Work factor: minimum 10 (ideally 12+)
+   Maximum password length: 72 bytes
+   ```
+
+4. **PBKDF2** (FIPS-required environments)
+   ```
+   Iterations: minimum 600,000 with HMAC-SHA-256
+   ```
+
+**Never Use:**
+- MD5, SHA1, SHA256 without key stretching
+- Plain hashing without salt
+- Reversible encryption for passwords
+
+### Vulnerable Patterns
+
+```python
+# VULNERABLE: MD5 hash
+import hashlib
+password_hash = hashlib.md5(password.encode()).hexdigest()
+
+# VULNERABLE: SHA256 without salt/iterations
+password_hash = hashlib.sha256(password.encode()).hexdigest()
+
+# SAFE: bcrypt
+import bcrypt
+password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12))
+
+# SAFE: Argon2
+from argon2 import PasswordHasher
+ph = PasswordHasher()
+password_hash = ph.hash(password)
+```
+
+---
+
+## Error Messages
+
+### Generic Response Principle
+
+Return identical error messages regardless of the specific failure reason.
+
+**Login Responses:**
+```
+# WRONG: Reveals valid usernames
+"User not found"
+"Invalid password"
+"Account locked"
+
+# CORRECT: Generic message
+"Login failed; Invalid user ID or password."
+```
+
+**Password Recovery:**
+```
+# WRONG: Reveals valid emails
+"Email not found"
+"Password reset email sent"
+
+# CORRECT: Generic message
+"If that email address is in our database, we will send you an email to reset your password."
+```
+
+**Account Creation:**
+```
+# WRONG: Reveals existing accounts
+"Email already registered"
+
+# CORRECT: Generic message
+"A link to activate your account has been emailed to the address provided."
+```
+
+---
+
+## Brute Force Protection
+
+### Account Lockout
+
+```python
+# Configuration
+LOCKOUT_THRESHOLD = 5  # Failed attempts before lockout
+OBSERVATION_WINDOW = 15 * 60  # 15 minutes
+LOCKOUT_DURATION = 30 * 60  # 30 minutes
+
+# Implementation
+class LoginAttemptTracker:
+    def record_failed_attempt(self, account_id):
+        # Track by account, NOT by IP
+        # IP-based tracking allows bypassing via distributed attacks
+        pass
+
+    def is_locked(self, account_id):
+        # Check if account is locked
+        pass
+
+    def allow_password_reset_when_locked(self):
+        # Prevent lockout from becoming DoS
+        return True
+```
+
+### Exponential Backoff
+
+```python
+def get_lockout_duration(failed_attempts):
+    # Double duration with each lockout
+    base_duration = 60  # 1 minute
+    return base_duration * (2 ** (failed_attempts // LOCKOUT_THRESHOLD - 1))
+```
+
+### Rate Limiting
+
+```python
+# Per-IP rate limiting (defense in depth)
+RATE_LIMIT = "10/minute"
+
+# Per-account rate limiting
+ACCOUNT_RATE_LIMIT = "5/minute"
+```
+
+---
+
+## Multi-Factor Authentication
+
+### MFA Effectiveness
+
+Microsoft research indicates MFA blocks 99.9% of account compromises.
+
+### MFA Implementation Checklist
+
+- [ ] Require MFA for all users (not just optional)
+- [ ] Support multiple MFA methods (TOTP, WebAuthn, SMS as fallback)
+- [ ] Implement MFA bypass codes for recovery (store securely)
+- [ ] Require re-authentication before disabling MFA
+- [ ] Log all MFA events
+
+### WebAuthn/FIDO2 (Preferred)
+
+```javascript
+// Registration
+const publicKeyCredential = await navigator.credentials.create({
+    publicKey: {
+        challenge: serverChallenge,
+        rp: { name: "Example Corp", id: "example.com" },
+        user: { id: userId, name: username, displayName: displayName },
+        pubKeyCredParams: [{ type: "public-key", alg: -7 }],  // ES256
+        authenticatorSelection: { userVerification: "preferred" }
+    }
+});
+```
+
+**Benefits:**
+- Phishing-resistant (bound to origin)
+- No shared secrets to steal
+- Hardware-backed security
+
+---
+
+## Session Security
+
+### Session ID Requirements
+
+- **Entropy**: Minimum 64 bits of randomness
+- **Length**: At least 16 characters (hex) or 128 bits
+- **Generation**: Cryptographically secure random generator only
+
+```python
+# VULNERABLE: Predictable session ID
+session_id = str(user_id) + str(int(time.time()))
+
+# SAFE: Cryptographically random
+import secrets
+session_id = secrets.token_hex(32)  # 256 bits
+```
+
+### Cookie Security Attributes
+
+```
+Set-Cookie: session_id=abc123;
+    Secure;          # HTTPS only
+    HttpOnly;        # No JavaScript access
+    SameSite=Lax;    # CSRF protection
+    Path=/;          # Scope
+    Max-Age=3600;    # Expiration
+```
+
+### Session Lifecycle
+
+```python
+# VULNERABLE: Not regenerating session on login (Session Fixation)
+def login(username, password):
+    user = authenticate(username, password)
+    session['user_id'] = user.id  # Same session ID - attacker can pre-set it!
+
+# SAFE: Regenerate session ID after authentication
+def login(user, password):
+    if authenticate(user, password):
+        # CRITICAL: Generate new session ID to prevent fixation
+        session.regenerate()
+        session['user_id'] = user.id
+
+# Regenerate after privilege changes
+def elevate_privileges():
+    session.regenerate()
+    session['is_admin'] = True
+
+# Proper logout - invalidate both server and client
+def logout():
+    session.invalidate()  # Server-side invalidation
+    response.delete_cookie('session_id')
+```
+
+### Session Timeouts
+
+| Type | Purpose | Typical Value |
+|------|---------|---------------|
+| **Idle Timeout** | Inactive session | 15-30 minutes |
+| **Absolute Timeout** | Maximum lifetime | 4-8 hours |
+
+### Concurrent Session Control
+
+```python
+# Option 1: Allow only one session per user
+def login(user):
+    invalidate_all_sessions(user.id)
+    return create_session(user)
+
+# Option 2: Limit concurrent sessions
+MAX_SESSIONS = 3
+def login(user):
+    sessions = get_sessions_by_user(user.id)
+    if len(sessions) >= MAX_SESSIONS:
+        oldest = min(sessions, key=lambda s: s['created_at'])
+        invalidate_session(oldest['id'])
+    return create_session(user)
+```
+
+---
+
+## Re-authentication Requirements
+
+Require fresh credentials before:
+- Password changes
+- Email address changes
+- MFA configuration changes
+- Sensitive financial transactions
+- Account deletion
+
+```python
+def requires_recent_auth(max_age=300):  # 5 minutes
+    """Decorator requiring recent authentication."""
+    def decorator(f):
+        def wrapper(*args, **kwargs):
+            last_auth = session.get('last_auth_time')
+            if not last_auth or time.time() - last_auth > max_age:
+                raise ReauthenticationRequired()
+            return f(*args, **kwargs)
+        return wrapper
+    return decorator
+
+@requires_recent_auth(max_age=300)
+def change_password(old_password, new_password):
+    pass
+```
+
+---
+
+## Email Address Changes
+
+### With MFA Enabled
+
+1. Verify current session authentication
+2. Request MFA verification
+3. Send notification to current email address
+4. Send confirmation link to new email address
+5. Require clicking link within time limit (e.g., 8 hours)
+
+### Without MFA
+
+1. Verify current session authentication
+2. Require current password verification
+3. Send notification to current email address
+4. Send confirmation link to both addresses
+5. Require confirmation from both within time limit
+
+---
+
+## Grep Patterns for Detection
+
+```bash
+# Weak hashing
+grep -rn "md5\|sha1\|sha256" --include="*.py" --include="*.js" | grep -i password
+grep -rn "hashlib\\.md5\|hashlib\\.sha" --include="*.py"
+
+# Predictable session IDs
+grep -rn "uuid1\|time\\(\\).*session\|user.*id.*session" --include="*.py"
+
+# Missing cookie security
+grep -rn "Set-Cookie" --include="*.py" --include="*.js" | grep -v -i "secure\|httponly"
+
+# Error message leakage
+grep -rn "not found\|invalid password\|does not exist" --include="*.py" --include="*.js"
+
+# Session handling
+grep -rn "session\\.regenerate\|regenerate_id\|new_session" --include="*.py" --include="*.php"
+```
+
+---
+
+## References
+
+- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+- [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
+- [CWE-287: Improper Authentication](https://cwe.mitre.org/data/definitions/287.html)
+- [CWE-384: Session Fixation](https://cwe.mitre.org/data/definitions/384.html)

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

@@ -0,0 +1,372 @@
+# Authorization Security Reference
+
+## Overview
+
+Authorization verifies that a requested action or service is approved for a specific entity—distinct from authentication, which verifies identity. A user who has been authenticated is often not authorized to access every resource and perform every action.
+
+## Core Principles
+
+### 1. Deny by Default
+
+Every permission must be explicitly granted. The default position is denial.
+
+```python
+# VULNERABLE: Implicit allow
+def get_document(request, doc_id):
+    return Document.objects.get(id=doc_id)
+
+# SAFE: Explicit authorization
+def get_document(request, doc_id):
+    doc = Document.objects.get(id=doc_id)
+    if not request.user.has_permission('read', doc):
+        raise PermissionDenied()
+    return doc
+```
+
+### 2. Enforce Least Privilege
+
+Assign users only the minimum necessary permissions for their role.
+
+```python
+# Define minimal permission sets
+ROLE_PERMISSIONS = {
+    'viewer': ['read'],
+    'editor': ['read', 'write'],
+    'admin': ['read', 'write', 'delete', 'admin']
+}
+```
+
+### 3. Validate Permissions on Every Request
+
+Never rely on UI hiding or client-side checks alone.
+
+```python
+# VULNERABLE: Authorization only on some endpoints
+@app.route('/api/admin/users', methods=['GET'])
+@require_admin  # Good
+def list_users():
+    pass
+
+@app.route('/api/admin/users/<id>', methods=['DELETE'])
+def delete_user(id):  # Missing authorization check!
+    User.delete(id)
+
+# SAFE: Consistent authorization
+@app.route('/api/admin/users/<id>', methods=['DELETE'])
+@require_admin  # Always check
+def delete_user(id):
+    User.delete(id)
+```
+
+---
+
+## Insecure Direct Object References (IDOR)
+
+### The Vulnerability
+
+IDOR occurs when attackers access or modify objects by manipulating identifiers.
+
+```python
+# VULNERABLE: No ownership validation
+@app.route('/api/orders/<order_id>')
+def get_order(order_id):
+    return Order.query.get(order_id).to_dict()
+
+# Attack: User A accesses /api/orders/123 (User B's order)
+```
+
+### Prevention
+
+**1. Validate Object Ownership**
+
+```python
+# SAFE: Scope queries to current user
+@app.route('/api/orders/<order_id>')
+def get_order(order_id):
+    order = Order.query.filter_by(
+        id=order_id,
+        user_id=current_user.id  # Ownership check
+    ).first_or_404()
+    return order.to_dict()
+```
+
+**2. Use Indirect References**
+
+```python
+# Map user-specific indices to actual IDs
+def get_user_order_map(user_id):
+    orders = Order.query.filter_by(user_id=user_id).all()
+    return {i: order.id for i, order in enumerate(orders)}
+
+@app.route('/api/orders/<int:index>')
+def get_order(index):
+    order_map = get_user_order_map(current_user.id)
+    real_id = order_map.get(index)
+    if not real_id:
+        raise NotFound()
+    return Order.query.get(real_id).to_dict()
+```
+
+**3. Perform Object-Level Checks**
+
+```python
+# Check permission on the specific object, not just object type
+def check_permission(user, action, resource):
+    # Bad: Type-level check only
+    # if user.can('read', 'Order'): return True
+
+    # Good: Object-level check
+    if resource.owner_id == user.id:
+        return True
+    if resource.organization_id in user.organization_ids:
+        return user.has_org_permission(action, resource.organization_id)
+    return False
+```
+
+---
+
+## Access Control Models
+
+### Role-Based Access Control (RBAC)
+
+Simple but limited. Good for straightforward permission structures.
+
+```python
+ROLES = {
+    'admin': {'create', 'read', 'update', 'delete'},
+    'editor': {'create', 'read', 'update'},
+    'viewer': {'read'}
+}
+
+def has_permission(user, action):
+    return action in ROLES.get(user.role, set())
+```
+
+### Attribute-Based Access Control (ABAC)
+
+More flexible. Supports complex policies with multiple attributes.
+
+```python
+def evaluate_policy(subject, action, resource, environment):
+    """
+    Subject: user attributes (role, department, clearance)
+    Action: what they're trying to do
+    Resource: object attributes (owner, classification, type)
+    Environment: context (time, location, device)
+    """
+    # Example: Only managers can approve during business hours
+    if action == 'approve':
+        return (
+            subject.role == 'manager' and
+            resource.department == subject.department and
+            environment.is_business_hours
+        )
+    return False
+```
+
+### Relationship-Based Access Control (ReBAC)
+
+Access based on relationships between entities.
+
+```python
+# User can view document if:
+# - They own it
+# - They're in a group that has access
+# - They're in the same organization
+def can_view(user, document):
+    if document.owner_id == user.id:
+        return True
+    if user.groups.intersection(document.shared_with_groups):
+        return True
+    if document.org_id == user.org_id and document.org_visible:
+        return True
+    return False
+```
+
+---
+
+## Common Vulnerabilities
+
+### Horizontal Privilege Escalation
+
+Accessing resources belonging to other users at the same privilege level.
+
+```python
+# VULNERABLE: User A can access User B's profile
+@app.route('/api/profile/<user_id>')
+def get_profile(user_id):
+    return User.query.get(user_id).profile
+
+# SAFE: Only access own profile
+@app.route('/api/profile')
+def get_profile():
+    return current_user.profile
+```
+
+### Vertical Privilege Escalation
+
+Accessing higher-privilege functionality.
+
+```python
+# VULNERABLE: Hidden admin endpoint
+@app.route('/api/admin/delete-all')
+def delete_all():
+    # No authorization check
+    Database.delete_all()
+
+# SAFE: Explicit admin check
+@app.route('/api/admin/delete-all')
+@require_role('super_admin')
+def delete_all():
+    Database.delete_all()
+```
+
+### Path Traversal in Authorization
+
+```python
+# VULNERABLE: Path-based authorization bypass
+@app.route('/files/<path:filepath>')
+def get_file(filepath):
+    # Attacker: /files/../../../etc/passwd
+    return send_file(filepath)
+
+# SAFE: Validate and sanitize path
+@app.route('/files/<path:filepath>')
+def get_file(filepath):
+    base_dir = '/app/user_files'
+    full_path = os.path.realpath(os.path.join(base_dir, filepath))
+    if not full_path.startswith(base_dir):
+        raise PermissionDenied()
+    return send_file(full_path)
+```
+
+### Mass Assignment
+
+```python
+# VULNERABLE: User can set admin flag
+@app.route('/api/users/<id>', methods=['PATCH'])
+def update_user(id):
+    user = User.query.get(id)
+    user.update(**request.json)  # Includes is_admin!
+
+# SAFE: Allowlist fields
+@app.route('/api/users/<id>', methods=['PATCH'])
+def update_user(id):
+    ALLOWED_FIELDS = {'name', 'email', 'bio'}
+    user = User.query.get(id)
+    data = {k: v for k, v in request.json.items() if k in ALLOWED_FIELDS}
+    user.update(**data)
+```
+
+---
+
+## Implementation Patterns
+
+### Middleware/Filter Pattern
+
+```python
+# Apply authorization consistently via middleware
+class AuthorizationMiddleware:
+    def process_request(self, request):
+        if not self.is_authorized(request):
+            raise PermissionDenied()
+
+    def is_authorized(self, request):
+        # Extract resource and action from request
+        resource = self.get_resource(request)
+        action = self.get_action(request)
+        return request.user.has_permission(action, resource)
+```
+
+### Policy Objects
+
+```python
+class DocumentPolicy:
+    def __init__(self, user, document):
+        self.user = user
+        self.document = document
+
+    def can_view(self):
+        return (
+            self.document.is_public or
+            self.document.owner_id == self.user.id or
+            self.user.is_admin
+        )
+
+    def can_edit(self):
+        return self.document.owner_id == self.user.id
+
+    def can_delete(self):
+        return self.document.owner_id == self.user.id or self.user.is_admin
+
+# Usage
+policy = DocumentPolicy(current_user, document)
+if not policy.can_view():
+    raise PermissionDenied()
+```
+
+---
+
+## Grep Patterns for Detection
+
+```bash
+# Missing authorization checks
+grep -rn "def get_\|def post_\|def put_\|def delete_" --include="*.py" | grep -v "@require\|@login\|permission"
+
+# Direct object access without ownership check
+grep -rn "\.get(.*id)\|\.filter(id=" --include="*.py" | grep -v "user_id\|owner"
+
+# Mass assignment
+grep -rn "\*\*request\.\|update(\*\*\|create(\*\*" --include="*.py"
+
+# Path traversal risk
+grep -rn "os\.path\.join.*request\|open(.*request" --include="*.py"
+
+# Admin endpoints
+grep -rn "admin\|superuser" --include="*.py" | grep "route\|endpoint"
+```
+
+---
+
+## Authorization Testing
+
+### Test Cases
+
+1. **Horizontal access**: Can User A access User B's resources?
+2. **Vertical access**: Can regular users access admin endpoints?
+3. **Missing checks**: Are all endpoints protected?
+4. **Parameter tampering**: Can IDs be manipulated?
+5. **Path traversal**: Can file paths escape allowed directories?
+6. **Mass assignment**: Can protected fields be modified?
+
+### Test Automation
+
+```python
+def test_horizontal_access():
+    user_a = create_user()
+    user_b = create_user()
+    resource = create_resource(owner=user_a)
+
+    # User B should not access User A's resource
+    client.login(user_b)
+    response = client.get(f'/api/resources/{resource.id}')
+    assert response.status_code == 403
+
+def test_idor_enumeration():
+    # Try sequential IDs
+    for i in range(1, 100):
+        response = client.get(f'/api/resources/{i}')
+        if response.status_code == 200:
+            # Should be denied or return 404, not 200
+            assert False, f"IDOR vulnerability: /api/resources/{i}"
+```
+
+---
+
+## References
+
+- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)
+- [OWASP IDOR Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html)
+- [OWASP Access Control Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Access_Control_Cheat_Sheet.html)
+- [CWE-639: Authorization Bypass Through User-Controlled Key](https://cwe.mitre.org/data/definitions/639.html)
+- [CWE-862: Missing Authorization](https://cwe.mitre.org/data/definitions/862.html)