|
| 1 | +# Security Policy |
| 2 | + |
| 3 | +## Supported Versions |
| 4 | + |
| 5 | +| Version | Supported | |
| 6 | +| ------- | ------------------ | |
| 7 | +| 1.0.x | :white_check_mark: | |
| 8 | +| < 1.0 | :x: | |
| 9 | + |
| 10 | +## Reporting a Vulnerability |
| 11 | + |
| 12 | +If you discover a security vulnerability in php-ymap, please report it privately: |
| 13 | + |
| 14 | +**DO NOT open a public GitHub issue for security vulnerabilities.** |
| 15 | + |
| 16 | +### How to Report |
| 17 | + |
| 18 | +1. **Email:** Send details to the maintainers via GitHub (use the "Report a security vulnerability" feature in the Security tab) |
| 19 | +2. **Include:** |
| 20 | + - Description of the vulnerability |
| 21 | + - Steps to reproduce |
| 22 | + - Potential impact |
| 23 | + - Suggested fix (if available) |
| 24 | + |
| 25 | +### What to Expect |
| 26 | + |
| 27 | +- **Acknowledgment:** Within 48 hours |
| 28 | +- **Initial assessment:** Within 1 week |
| 29 | +- **Fix timeline:** Depends on severity and complexity |
| 30 | +- **Credit:** You will be credited in the security advisory (unless you prefer to remain anonymous) |
| 31 | + |
| 32 | +## Security Best Practices for Users |
| 33 | + |
| 34 | +### Credential Management |
| 35 | + |
| 36 | +**DO:** |
| 37 | +- Store IMAP credentials in environment variables |
| 38 | +- Use secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.) |
| 39 | +- Rotate credentials regularly |
| 40 | +- Use application-specific passwords when available |
| 41 | + |
| 42 | +**DON'T:** |
| 43 | +- Hardcode credentials in source code |
| 44 | +- Commit credentials to version control |
| 45 | +- Log credentials in plain text |
| 46 | +- Share credentials across multiple applications |
| 47 | + |
| 48 | +### TLS/SSL Configuration |
| 49 | + |
| 50 | +php-ymap connects to IMAP servers using the native PHP IMAP extension. Ensure secure connections: |
| 51 | + |
| 52 | +```php |
| 53 | +$config = new ConnectionConfig( |
| 54 | + host: 'imap.example.com', |
| 55 | + port: 993, // Use SSL port |
| 56 | + username: getenv('IMAP_USER'), |
| 57 | + password: getenv('IMAP_PASS'), |
| 58 | + flags: '/imap/ssl', // Enable SSL |
| 59 | + mailbox: 'INBOX' |
| 60 | +); |
| 61 | +``` |
| 62 | + |
| 63 | +**Flags for secure connections:** |
| 64 | +- `/imap/ssl` - Use SSL/TLS encryption |
| 65 | +- `/imap/ssl/novalidate-cert` - **Avoid in production** (disables certificate verification) |
| 66 | + |
| 67 | +### Input Validation |
| 68 | + |
| 69 | +When using php-ymap in web applications: |
| 70 | + |
| 71 | +- **Sanitize user inputs** before using in IMAP searches |
| 72 | +- **Validate email addresses** before using in filters |
| 73 | +- **Limit result sets** to prevent resource exhaustion |
| 74 | +- **Implement rate limiting** on IMAP operations |
| 75 | + |
| 76 | +### Attachment Handling |
| 77 | + |
| 78 | +When processing attachments: |
| 79 | + |
| 80 | +```php |
| 81 | +// Sanitize filenames before saving to disk |
| 82 | +$filename = basename($attachment->getFilename()); |
| 83 | +$filename = preg_replace('/[^a-zA-Z0-9._-]/', '_', $filename); |
| 84 | + |
| 85 | +// Validate file types |
| 86 | +$allowedTypes = ['image/jpeg', 'image/png', 'application/pdf']; |
| 87 | +if (!in_array($attachment->getContentType(), $allowedTypes)) { |
| 88 | + // Reject or handle appropriately |
| 89 | +} |
| 90 | + |
| 91 | +// Limit file sizes |
| 92 | +if ($attachment->getSize() > 10 * 1024 * 1024) { // 10MB |
| 93 | + // Reject large attachments |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +### Resource Limits |
| 98 | + |
| 99 | +Prevent memory exhaustion: |
| 100 | + |
| 101 | +```php |
| 102 | +// Limit number of messages fetched |
| 103 | +$messages = $service |
| 104 | + ->inbox() |
| 105 | + ->limit(100) // Don't fetch unbounded result sets |
| 106 | + ->fetch(); |
| 107 | + |
| 108 | +// Use field selection to reduce memory usage |
| 109 | +$messages = $service |
| 110 | + ->inbox() |
| 111 | + ->fields(['uid', 'subject', 'from', 'date']) // Omit large bodies |
| 112 | + ->fetch(); |
| 113 | +``` |
| 114 | + |
| 115 | +## Known Security Considerations |
| 116 | + |
| 117 | +1. **IMAP Extension:** php-ymap depends on PHP's native IMAP extension which uses the c-client library. Keep PHP updated to receive security patches. |
| 118 | + |
| 119 | +2. **Memory Usage:** Large attachments are loaded into memory. For production use with large attachments, consider implementing streaming (see TASK_LIST.md). |
| 120 | + |
| 121 | +3. **Connection Security:** Always use SSL/TLS for IMAP connections when connecting over untrusted networks. |
| 122 | + |
| 123 | +## Disclosure Policy |
| 124 | + |
| 125 | +When a security issue is fixed: |
| 126 | + |
| 127 | +1. A security advisory will be published on GitHub |
| 128 | +2. CHANGELOG.md will be updated with security fix details |
| 129 | +3. A new patch version will be released |
| 130 | +4. Affected versions will be clearly documented |
| 131 | + |
| 132 | +## Security Updates |
| 133 | + |
| 134 | +Subscribe to security advisories: |
| 135 | +- Watch the GitHub repository for security alerts |
| 136 | +- Check CHANGELOG.md for security-related fixes |
0 commit comments