@devo-bmad-custom/agent-orchestration 1.0.1 → 1.0.3

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

@@ -1,372 +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)
+# 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)