📖 Threat Modeling Guide

This guide walks you through how to apply the STRIDE methodology for identifying and addressing security risks in Thunderbird’s mobile clients. Each step includes examples specific to Android/iOS email handling. Use it during design, feature work, and release planning. Keep sessions short and focused.

[!NOTE] Start small. Pick a single feature or flow. The goal is to surface and mitigate risks early, not to produce perfect documentation.

STRIDE Quick Reference

We’ll use the STRIDE framework to help identify common types of threats:

• Spoofing: Impersonating someone or something else (e.g., faking identity, app, servers).
• Tampering: Unauthorized modification of data, code or configuration (e.g., altering a file, changing network packets).
• Repudiation: Denying actions that occurred without reliable attribution/logging
• Information Disclosure: Revealing sensitive data to unauthorized individuals (e.g., leaking PII, credentials).
• Denial of Service: Preventing legitimate users from accessing a service or resource (e.g., crashing a server, exhausting resources).
• Elevation of Privilege: Gaining unauthorized access to higher-level permissions (e.g., a regular user becoming an administrator).

How to use this guide

Below is a simple, repeatable workflow. Each section provides prompts and examples. Capture notes in your feature’s issue/PR or a short doc.

Threat Modeling Workflow

1. Project Overview

What to do:

Write down what Thunderbird Mobile is, what it does, and its major features. This frames the context of your threat model.

Example:

• Project Name: Thunderbird for Android
• Description: A mobile email client providing access to IMAP/POP3/SMTP accounts with support for OAuth, local message storage, PGP/SMIME, and notifications.
• Key Features: Account setup, secure login, message sync, local storage, notifications, attachments, encryption support.

2. Define Scope

What to do:

Pick one area to model at a time. Define clear boundaries. Don’t try to cover the entire app in one go.

Examples:

• Account authentication and credential storage
• OAuth2 login for Gmail/Outlook providers
• Message synchronization with mail servers: connection management, IDLE, message fetch
• Local message storage and full‑text index
• Attachment handling: view/save/share flow
• Background services and notifications (Android)
• OpenPGP signing/encryption/decryption (Android)

3. Draw a System Diagram

What to do:

Draw a simple diagram (use Mermaid) of the project within your chosen scope. Identify:

• Key Components: UI, storage, crypto, background jobs, network services
• Data Flows: How information moves between components.
• Trust Boundaries: Where different levels of trust exist (e.g., separating user input from backend processing, public network vs. internal network).
• Actors: User, external systems, third-party services, Attackers
• Data Stores: Local database (messages, headers, metadata), file storage (attachments, cache), Android Keystore (tokens/keys), logs/metrics (if enabled), cryptographic keyrings

Example (Account Authentication):

• Actors: User, Thunderbird app, IMAP/SMTP server, OAuth provider, Attacker, Push providers, OS keychain, other apps via Intents/Shares
• Data Flows:
  • User enters credentials or OAuth flow
  • App exchanges tokens with server
  • Tokens stored locally in Keystore/Secure Enclave
• Trust Boundaries:
  • User input (untrusted) → App UI
  • App → Mail server (TLS required)
  • App → Local storage (protected by OS sandbox & keystore)

Use this Mermaid diagram as a starting point; copy it into your notes and adjust for your scope.

flowchart LR
   subgraph Interaction 
       USER[End User]
       ATTACKER[Attacker: Malicious App, Network, User]
   end 
    
  subgraph "Mobile Client"
     APP[Mobile App]
     CRYPTO[Crypto: OpenPGP/S-MIME]
     STORAGE[Local Storage: SQLite, Files, KeyStore]
     BACKGROUND[Background Services: Sync, Notifications]
     OAUTH[OAuth via Browser/Custom Tabs]
  end

  subgraph "External Services"
     OAUTH_PROVIDER[(OAuth2 Providers: Google/Microsoft/etc)]
     PUSH[(Push: FCM, APNs)]
     MAIL[(IMAP/POP3 Servers)]
     SMTP[(SMTP Servers)]
     AUTO_CONFIG[(Autoconfig/Autodiscover)]
  end

  USER -->|Uses app| APP
  ATTACKER -.->|Phishing, MITM, Malicious app| APP
  APP <--> STORAGE
  APP <--> CRYPTO
  APP <--> BACKGROUND
  APP -->|OAuth browser| OAUTH --> OAUTH_PROVIDER --> APP
  BACKGROUND <--> PUSH
  BACKGROUND <--> MAIL
  BACKGROUND <--> SMTP
  APP <--> AUTO_CONFIG

  classDef external fill:#fff3,stroke:#f66,stroke-width:2px;
  class MAIL,AUTO_CONFIG,OAUTH_PROVIDER,PUSH,SMTP external;

4. Identify Assets

What to do:

List what you want to protect for your scope.

• Data: Credentials, tokens, email content, attachments, keys, contacts
• Functionality: Ability to send/receive email, sync, notifications
• Reputation: User trust, brand image, compliance with store policies
• Availability: Access to email, notifications working, sync reliability

5. Identify Threats (Using STRIDE)

What to do:

For each component, data flow, and interaction identified in your diagram, ask STRIDE questions:

Example:

6. Add Mitigations

What to do:

For each threat, describe what you’ll do about it.

Example:

7. Risk Ranking (Optional, but recommended)

What to do:

Label each threat High/Medium/Low based on likelihood and impact.

• High: likely and/or severe impact → prioritize now
• Medium: plausible and moderate → schedule soon
• Low: unlikely or low impact → backlog/accept with rationale

Example:

• High: Credential theft, insecure storage, MITM, data leakage
• Medium: DoS via login brute force, excessive sync, notification spam
• Low: Repudiation of sent messages, log tampering

Perfect 🚀 — here’s a ready-to-use Markdown template file your team can copy for any new feature or flow in Thunderbird Mobile. It includes placeholders for each section, an empty system diagram stub, and separate Threats and Mitigations tables.

📖 Threat Modeling Template

Use this template when modeling a new feature or flow.

Title

1. Project Overview

• Project Name:
• Description:
• Key Features:

2. Scope

• Scope for this session

3. System Diagram

flowchart LR
  USER[User] --> APP[Thunderbird App]
  ATTACKER[Attacker] -.-> APP

  subgraph Device
    APP --> COMPONENT1[Component 1]
    APP --> COMPONENT2[Component 2]
  end

  subgraph External
    SERVICE1[(External Service 1)]
    SERVICE2[(External Service 2)]
  end

  APP --> SERVICE1
  APP --> SERVICE2

4. Assets

• Data:
• Functionality:
• Reputation:
• Availability:

5. Threats

6. Mitigations

7. Risk Ranking

• High: Likely and/or severe → prioritize now.
• Medium: Plausible and moderate → schedule soon.
• Low: Unlikely or low impact → backlog or accept with rationale.

🛡️ Example 1: Account Authentication

1. Project Overview

• Project Name: Thunderbird for Android/iOS – Account Authentication
• Description: Handling account setup, login, and credential storage for IMAP/SMTP or OAuth2 providers.
• Key Features: Password auth, OAuth2 flows (Google/Microsoft), token storage, secure connections.

2. Scope

• Account authentication and credential storage.

3. System Diagram

flowchart LR
  USER[User] --> APP[Thunderbird App]
  ATTACKER[Attacker] -.-> APP

  subgraph Device
    APP --> STORAGE[Local Storage: DB/Files]
    APP --> KEYSTORE[Keystore/Secure Enclave]
    APP --> OAUTH_FLOW[OAuth Flow via Browser]
  end

  subgraph External
    OAUTH_PROVIDER[(OAuth Provider)]
    MAIL[(IMAP/POP3 Servers)]
    SMTP[(SMTP Servers)]
  end

  OAUTH_FLOW --> OAUTH_PROVIDER --> APP
  APP --> MAIL
  APP --> SMTP

4. Assets

• Data: User credentials, OAuth tokens, session cookies.
• Functionality: Secure login, ability to sync and send mail.
• Reputation: Privacy-first branding.
• Availability: Reliable authentication, minimal lockouts.

5. Threats

6. Mitigations

7. Risk Ranking

• High: Credential theft, token leakage, MITM, TLS downgrade.
• Medium: Brute-force lockouts, storage exhaustion.
• Low: Repudiation of login attempts.

🔔 Example 2: Push Notifications

1. Project Overview

• Project Name: Thunderbird for Android/iOS – Push Notifications
• Description: Handling push notifications via FCM (Android) or APNs (iOS) to wake the app for secure fetch.
• Key Features: Receive push, show notifications, fetch mail securely.

2. Scope

• Push notification handling (end-to-end from server push to user notification).

3. System Diagram

flowchart TB
  USER[User] --> APP[Thunderbird App]
  ATTACKER[Attacker] -.-> APP

  subgraph Device
    APP --> NOTIF_HANDLER[Notification Handler]
    NOTIF_HANDLER --> FETCHER[Secure Fetcher]
    FETCHER --> DB[(Encrypted Local DB)]
  end

  subgraph External
    FCM[(FCM - Android)]
    APNS[(APNs - iOS)]
    MAIL[(Mail Server IMAP/SMTP)]
  end

  FCM --> NOTIF_HANDLER
  APNS --> NOTIF_HANDLER
  NOTIF_HANDLER -->|TLS fetch| MAIL

4. Assets

• Data: Notification payloads, message IDs, device tokens.
• Functionality: Timely, trustworthy notifications.
• Reputation: No privacy leaks in lock-screen banners.
• Availability: Notifications work without spam or battery drain.

5. Threats

6. Mitigations

7. Risk Ranking

• High: Metadata leaks in push payloads, MITM on fetch, PendingIntent abuse.
• Medium: Notification spam floods, retry storms.
• Low: Repudiation of notification receipt.