survey_custom_certificate_template/docs/SECURITY_QUICK_REFERENCE.md

# Security Quick Reference Guide

## Access Control

### User Roles and Permissions

| Role | Model | Read | Write | Create | Delete |
|------|-------|------|-------|--------|--------|
| Survey Manager | Wizard | ✓ | ✓ | ✓ | ✓ |
| Survey Manager | Placeholder | ✓ | ✓ | ✓ | ✓ |
| Survey Manager | Survey (custom fields) | ✓ | ✓ | ✓ | ✓ |
| Survey User | Wizard | ✓ (own) | ✗ | ✗ | ✗ |
| Survey User | Placeholder | ✓ (own) | ✗ | ✗ | ✗ |
| Survey User | Survey (has_custom_certificate) | ✓ | ✗ | ✗ | ✗ |

### Field-Level Security

| Field | Visible To | Editable By |
|-------|-----------|-------------|
| custom_cert_template | Survey Manager | Survey Manager |
| custom_cert_template_filename | Survey Manager | Survey Manager |
| custom_cert_mappings | Survey Manager | Survey Manager |
| has_custom_certificate | Survey User+ | Survey Manager |

## Input Validation Rules

### Placeholder Keys

**Format**: `{key.field_name}`

**Rules**:
- Must start with `{key.`
- Must end with `}`
- Field name can only contain: letters, numbers, underscores
- Maximum length: 200 characters

**Valid Examples**:
- `{key.name}`
- `{key.course_name}`
- `{key.field_123}`

**Invalid Examples**:
- `key.name` (missing braces)
- `{key.field-name}` (hyphen not allowed)
- `{key.field name}` (space not allowed)

### Value Fields

**Rules**:
- Can only contain: letters, numbers, underscores, dots
- Maximum length: 200 characters
- No special characters or spaces

**Valid Examples**:
- `survey_title`
- `partner_id.name`
- `partner_id.email`

**Invalid Examples**:
- `field-name` (hyphen not allowed)
- `field name` (space not allowed)
- `field'; DROP TABLE--` (SQL injection attempt)

### Custom Text

**Rules**:
- Maximum length: 1000 characters
- HTML tags are escaped/removed
- Control characters are removed
- Special characters are sanitized

**Sanitization Applied**:
- HTML escaping (< becomes &lt;, etc.)
- Control character removal
- HTML tag stripping
- Length truncation if needed

## JSON Mappings Structure

### Required Structure

```json
{
  "placeholders": [
    {
      "key": "{key.field_name}",
      "value_type": "survey_field|user_field|custom_text",
      "value_field": "field_name",
      "custom_text": "text"
    }
  ]
}
```

### Validation Rules

1. Must be valid JSON syntax
2. Root must be a dictionary/object
3. Must contain "placeholders" key
4. "placeholders" must be a list/array
5. Each placeholder must be a dictionary
6. Each placeholder must have "key" and "value_type"
7. "key" must match placeholder key format
8. "value_type" must be one of: survey_field, user_field, custom_text
9. "value_field" maximum 200 characters
10. "custom_text" maximum 1000 characters

## Security Features

### Protection Against Attacks

| Attack Type | Protection Method |
|-------------|-------------------|
| XSS (Cross-Site Scripting) | HTML escaping, tag stripping |
| SQL Injection | Field name validation, character whitelisting |
| Command Injection | Input sanitization, pattern validation |
| Path Traversal | Field name validation, no path separators |
| DoS (Denial of Service) | File size limits, text length limits |
| Data Corruption | JSON validation, database constraints |

### Sanitization Methods

#### `_sanitize_placeholder_value(value)`

**Purpose**: Sanitize user input for safe use in documents

**Actions**:
1. HTML escape all characters
2. Remove control characters (except \n and \t)
3. Strip HTML tags
4. Truncate to 10,000 characters

**Usage**:
```python
safe_value = wizard._sanitize_placeholder_value(user_input)
```

#### `_sanitize_certificate_value(value)`

**Purpose**: Sanitize data before certificate generation

**Actions**: Same as `_sanitize_placeholder_value`

**Usage**:
```python
safe_value = survey._sanitize_certificate_value(data_value)
```

### Validation Methods

#### `_validate_placeholder_key(key)`

**Purpose**: Validate placeholder key format

**Returns**: Boolean (True if valid)

**Usage**:
```python
if wizard._validate_placeholder_key(key):
    # Key is valid
```

#### `_validate_json_structure(json_string)`

**Purpose**: Validate JSON mappings structure

**Returns**: Tuple (is_valid, error_message)

**Usage**:
```python
is_valid, error = wizard._validate_json_structure(json_str)
if not is_valid:
    raise ValidationError(error)
```

#### `_validate_and_sanitize_placeholders()`

**Purpose**: Validate all placeholders before saving

**Raises**: ValidationError if validation fails

**Usage**:
```python
wizard._validate_and_sanitize_placeholders()
```

## Database Constraints

### Placeholder Model Constraints

1. **source_key**: Format and length validation
2. **value_field**: Character whitelist and length validation
3. **custom_text**: Length validation

### Survey Model Constraints

1. **custom_cert_mappings**: JSON structure validation

## Security Best Practices

### For Developers

1. **Always sanitize user input** before using in documents
2. **Validate at multiple layers**: UI, application, database
3. **Use whitelisting** instead of blacklisting for validation
4. **Log security events** for audit trails
5. **Fail securely** with clear error messages

### For Administrators

1. **Restrict access** to survey managers only
2. **Monitor logs** for suspicious activity
3. **Keep Odoo updated** for security patches
4. **Review templates** before deployment
5. **Test with malicious inputs** before production

### For Users

1. **Use strong passwords** for survey manager accounts
2. **Don't share credentials** with unauthorized users
3. **Report suspicious activity** to administrators
4. **Review generated certificates** for unexpected content
5. **Keep templates simple** to reduce attack surface

## Common Security Errors

### Error: "Invalid placeholder key format"

**Cause**: Placeholder key doesn't match required pattern

**Solution**: Use format `{key.field_name}` with only letters, numbers, underscores

### Error: "Invalid characters in field name"

**Cause**: value_field contains special characters

**Solution**: Use only letters, numbers, underscores, and dots

### Error: "Custom text too long"

**Cause**: Custom text exceeds 1000 characters

**Solution**: Reduce text length or split into multiple placeholders

### Error: "Invalid JSON in certificate mappings"

**Cause**: Malformed JSON structure

**Solution**: Check JSON syntax and required structure

## Testing Security

### Manual Security Tests

1. **Test with XSS payloads**:
   - `<script>alert('XSS')</script>`
   - `<img src=x onerror=alert('XSS')>`

2. **Test with SQL injection**:
   - `field'; DROP TABLE users--`
   - `1' OR '1'='1`

3. **Test with path traversal**:
   - `../../etc/passwd`
   - `..\..\..\windows\system32`

4. **Test with long inputs**:
   - 1001+ character custom text
   - 201+ character field names

5. **Test with malformed JSON**:
   - Missing braces
   - Invalid structure
   - Wrong data types

### Automated Security Tests

Run the security test suite:

```bash
odoo-bin -c odoo.conf -d database_name -i survey_custom_certificate_template --test-enable --stop-after-init
```

Or run specific test:

```bash
odoo-bin -c odoo.conf -d database_name --test-tags survey_custom_certificate_template.test_security_validation
```

## Security Checklist

Before deploying to production:

- [ ] All users have appropriate access levels
- [ ] Field-level security is configured
- [ ] Input validation is working
- [ ] Sanitization is applied to all user inputs
- [ ] JSON validation is enforced
- [ ] Database constraints are active
- [ ] Security tests pass
- [ ] Logs are monitored
- [ ] File size limits are enforced
- [ ] Error messages don't leak sensitive information

## Support

For security issues or questions:

1. Check this guide first
2. Review the implementation documentation
3. Run security tests
4. Contact system administrator
5. Report security vulnerabilities privately

## Version

Document Version: 1.0
Last Updated: 2024
Module Version: 19.0.1.0.0