Skip to content

SECURITY.md

Latest commit

 

History

History
230 lines (169 loc) · 5.97 KB

SECURITY.md

File metadata and controls

230 lines (169 loc) · 5.97 KB

Security Policy

Overview

This application handles sensitive information including email credentials and OAuth2 access tokens. We take security seriously and have implemented multiple safeguards.

Security Measures Implemented

1. Credential Protection

Environment Variables (.env file)

  • Never committed to version control (.gitignore)
  • Stores email address and Azure Client ID only
  • Client ID is not a secret, but kept in .env for convenience
  • Should have restrictive file permissions (600 recommended)

Token Cache (.token_cache.json)

  • Automatically ignored by .gitignore
  • Contains OAuth2 access tokens
  • Encrypted at rest by MSAL library
  • Automatically refreshed when expired
  • Should have restrictive file permissions (600 recommended)

2. OAuth2 Authentication

Modern Security Standards

  • Uses Microsoft Authentication Library (MSAL)
  • OAuth2 device code flow - no passwords stored locally
  • Tokens are short-lived and automatically refreshed
  • Supports multi-factor authentication (MFA)
  • No plaintext password storage

Scope Minimization

  • Only requests IMAP.AccessAsUser.All permission
  • No broader access than necessary
  • User must explicitly grant consent

3. IMAP Connection Security

Encrypted Communication

  • Always uses IMAP over SSL/TLS (port 993)
  • No plaintext transmission of credentials
  • Certificate validation enabled

Read-Only Preview

  • BODY.PEEK command prevents marking emails as read during preview
  • Non-invasive email scanning

4. Code Security

No Remote Code Execution

  • No eval() or exec() functions
  • No dynamic code loading
  • All dependencies from trusted PyPI sources

Input Validation

  • Email search criteria are parameterized
  • No direct string interpolation in IMAP commands
  • Safe header decoding with error handling

Error Handling

  • Graceful error handling prevents credential leaks
  • No sensitive data in error messages
  • Proper resource cleanup on exit

Best Practices for Users

File Permissions

Set restrictive permissions on sensitive files:

chmod 600 .env
chmod 600 .token_cache.json

Regular Security Maintenance

  1. Rotate Azure App Registration

    • Periodically create a new app registration
    • Update Client ID in .env
    • Delete old token cache

  2. Review App Permissions

  3. Monitor Account Activity

Secure Usage

DO:

  • ✅ Keep your .env file private
  • ✅ Use strong MFA on your Microsoft account
  • ✅ Run the tool on trusted computers only
  • ✅ Review email previews carefully before deletion
  • ✅ Keep dependencies updated

DON'T:

  • ❌ Share your .env file
  • ❌ Commit .token_cache.json to version control
  • ❌ Run on public/shared computers
  • ❌ Share your Azure Client ID publicly (not secret, but unnecessary)
  • ❌ Disable MFA for convenience

Dependency Security

All dependencies are pinned to specific versions in requirements.txt:

  • python-dotenv: Environment variable management
  • rich: Terminal UI (no network access)
  • dateparser: Date parsing (no network access)
  • msal: Official Microsoft Authentication Library

Updating Dependencies

Check for security updates regularly:

pip list --outdated
pip install --upgrade <package-name>

Update requirements.txt after testing:

pip freeze > requirements.txt

Incident Response

If You Suspect Compromise

  1. Immediately Revoke Access

  2. Delete Local Tokens

    rm .token_cache.json

  3. Change Your Password

    • Update your Microsoft account password
    • Check account activity for suspicious access

  4. Delete Azure App Registration

  5. Review Account Activity

    • Check for unauthorized email deletions
    • Review recent sign-ins
    • Enable additional security features

If .env is Exposed

  1. Delete the Azure App

    • The Client ID becomes invalid
    • Create a new app registration

  2. Update .env

    • Generate new Client ID
    • Delete token cache

  3. Check for Unauthorized Access

    • Review account activity

Vulnerability Reporting

If you discover a security vulnerability:

  1. Do NOT open a public GitHub issue
  2. Contact via private channels
  3. Provide detailed information:
    • Description of the vulnerability
    • Steps to reproduce
    • Potential impact
    • Suggested fix (if any)

Security Limitations

This Tool:

  • Cannot recover deleted emails
  • Has full access to your INBOX once authenticated
  • Stores tokens locally on your computer
  • Requires trusting the MSAL library

Microsoft's Security:

  • Token validity periods controlled by Microsoft
  • MFA enforcement depends on account settings
  • Basic authentication may be disabled by Microsoft

Compliance Notes

Data Storage:

  • Credentials stored locally only
  • No cloud storage or telemetry
  • No analytics or tracking

Data Transmission:

  • Only communicates with Microsoft servers
  • No third-party services involved
  • All connections encrypted (HTTPS/IMAPS)

Security Checklist

Before using this tool, ensure:

  • You're using a personal Microsoft account (not work/school)
  • Two-factor authentication is enabled
  • .env file has restrictive permissions (600)
  • .token_cache.json is in .gitignore
  • You understand the tool has full INBOX access
  • You trust the computer you're running it on
  • Dependencies are from official PyPI sources
  • You've reviewed the source code

Updates

This security policy may be updated periodically. Check back regularly for changes.

Last Updated: 2025-12-07 Version: 1.0.0