📖 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:

Component / Data Flow / Interaction	Spoofing	Tampering	Repudiation	Information Disclosure	DoS	Elevation of Privilege
OAuth2 Login (App ↔ OAuth Provider)	Fake OAuth page via phishing/intent hijack	Intercept/alter redirect URI	User denies consent later	Tokens/PII leaked in logs/URLs	Provider rate limits	App requests excessive scopes
Password Auth (App ↔ Mail/SMTP)	MITM captures creds / server spoof	Modify TLS session	Deny failed logins	Credentials in memory/backups	Brute-force lockouts	App uses elevated IMAP/SMTP roles
IMAP/SMTP TLS	Spoof certs without pinning	Downgrade protocol/cipher	—	Metadata leaks in traffic	Connection exhaustion	Protocol quirks abused
Local Storage	Malicious app pretends to be Thunderbird	DB/file tampering on rooted device	User denies local action	Leaks via backups/cache	Storage exhaustion	Sandbox escape
Keystore / Keychain	Fake app tries to use alias	Key misuse	—	Extraction on rooted/jailbroken devices	Keystore unavailable	Hardware bypass
OpenPGP / S-MIME	Key ownership spoofing	Keyring/signature tampering	Dispute sent signatures	Decrypted data in RAM/tmp	Expensive crypto stalls UI	Access other apps’ keys
Attachments & Sharing	Malicious target app intercepts	Temp file tampering	—	World-readable URIs	Huge file upload stalls	Excess file access
Notifications	Fake notification spoof	Alter PendingIntents	—	Sensitive lockscreen previews	Spam storms	Privileged actions triggered
Background Sync	Fake wakeups/intents	Job params altered	—	Logs leak PII	Endless sync drains battery	Privileged execution
Autodiscovery	Malicious config host	Alter SRV/HTTP response	—	Domain/email leaked to third parties	Slow setup blocks	Elevated server access
Inter-app Intents	Other app claims TB filters	Extras modified	—	Data leaked to unintended receivers	Intent floods	Bypass auth gates
Logging / Telemetry	—	Log modification	User denies actions	PII in logs	Disk filled	Logs help attacker
iOS Keychain & APIs	Phishing ASWebAuthSession	Keychain tamper	—	Keys/files leak to iCloud	Background fetch abused	App Group misuse

6. Add Mitigations

What to do:

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

Example:

Threat Identified	Proposed Mitigation
OAuth redirect interception / fake OAuth page	Use system browser (Custom Tabs / ASWebAuthSession); claimed HTTPS redirect URIs; verify state/nonce; PKCE; minimize scopes; store tokens in Keystore/Secure Enclave; rotate refresh tokens
Redirect URI tampering	Enforce exact redirect match; strict validation
Excessive OAuth scopes	Scope minimization; review/limit permissions
MITM during password authentication	TLS 1.2+ (prefer 1.3); strict hostname verification; consider pinning for known providers; prefer implicit TLS over STARTTLS
Credential leakage (memory, logs, backups)	Encrypt at rest with Keystore-derived keys; zeroize memory; redact logs; protect screenshots; mark sensitive dirs as no-backup
IMAP/SMTP STARTTLS downgrade	Prefer implicit TLS; reject weak suites; enforce hostname checks
Local DB tampering	Encrypt per-account DB keys (wrapped by Keystore); integrity checks
Local DB leakage via backups/cache	Internal app storage only; opt-out sensitive paths from auto backup; FileProvider URIs with time-limited grants
Spoofed notifications	Only accept OS push channels (FCM/APNs); verify app identity
Sensitive lock-screen previews	Redact by default; user toggle for previews; use immutable PendingIntents and explicit components
PendingIntent tampering	Use `FLAG_IMMUTABLE`; explicit component declarations
Attachment exfiltration via world-readable files	SAF/DocumentFile APIs; FileProvider URIs; no world-readable files; enforce MIME checks and size limits
Sync loops draining battery/data	Backoff with jitter; network/battery constraints; circuit breakers; validate job inputs
Malicious autodiscovery configs	Prefer HTTPS; validate domains; ship trusted provider directory; warn on insecure configs
OpenPGP/S-MIME plaintext residue	Isolate decrypted buffers; wipe temp files; constant-time crypto; disable remote content by default; clear trust UX
Token theft from logs	Structured logging with allowlist fields; redact headers/URLs
Intent spoofing / inter-app abuse	Minimize exported components; explicit intents; verify caller UID; require permissions
Logging/Telemetry leaks	Opt-in; redact PII; bounded retention; local-first storage
iOS Keychain/data leakage	Use `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`; careful App Groups; minimize iCloud backup; strong ATS/TLS

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

Component / Flow	Spoofing	Tampering	Repudiation	Information Disclosure	DoS	Elevation of Privilege
Example Flow A
Example Flow B
Example Flow C

6. Mitigations

Threat Identified	Proposed Mitigation
Threat 1	Mitigation 1
Threat 2	Mitigation 2
Threat 3	Mitigation 3

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

Component / Flow	Spoofing	Tampering	Repudiation	Information Disclosure	DoS	Elevation of Privilege
OAuth2 Login	Fake OAuth page via phishing	Redirect URI manipulation	User denies consent	Tokens leaked in logs/URLs	Provider rate limits	Excessive scopes
Password Auth	MITM server spoof	Modify TLS session	User denies failed login	Credentials in memory/backups	Brute-force lockouts	Use of admin roles
IMAP/SMTP TLS	Spoofed certificates	Downgrade attack	—	Metadata leakage	Connection exhaustion	Protocol quirks abused
Local Storage	Malicious app pretends to be Thunderbird	DB/file tampering	User denies local action	Backups/cache leaks	Storage exhaustion	Sandbox escape
Keystore	Fake app tries to access alias	Misuse of key	—	Key extraction on rooted devices	Keystore unavailable	Hardware bypass

6. Mitigations

Threat Identified	Proposed Mitigation
Fake OAuth login	System browser (Custom Tabs/ASWebAuthSession); claimed HTTPS redirect URIs; PKCE; validate state/nonce
Redirect tampering	Strict URI validation; reject mismatches
Excessive scopes	Scope minimization; permission reviews
MITM on password login	TLS 1.2+ (prefer 1.3); strict hostname verification; pin known providers
Credential leakage	Keystore/Keychain storage; redact logs; disable backups; zeroize memory; protect screenshots
TLS downgrade	Prefer implicit TLS; reject weak suites; enforce hostname checks
DB tampering	Encrypt per-account DB; integrity seals
Backup/cache leaks	Internal storage only; opt-out backups; FileProvider URIs
Keystore misuse	Use StrongBox/TEE; require user auth for sensitive ops; handle key invalidation

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

Component / Flow	Spoofing	Tampering	Repudiation	Information Disclosure	DoS	Elevation of Privilege
Push Channel (FCM/APNs)	Fake/local notification	Payload altered	User disputes receipt	Payload leaks sender/subject	Notification flood	Malicious PendingIntent abuse
Post-Push Fetch	MITM fetch request	Inject mailbox updates	—	Token leakage in logs	Retry storms	Fetcher over-privileged
Notification UI	—	Modify notification action	—	Lockscreen preview leaks	Notification spam wakes device	Privileged screen opened

6. Mitigations

Threat Identified	Proposed Mitigation
Fake/local notification	Only accept OS push channels; verify channel IDs
Payload tampering	Opaque IDs in payloads; fetch details securely
Metadata leakage	Redact payloads; fetch details after wake; redact lock-screen previews by default
Notification spam	Rate limits; quotas; quiet hours; batching
PendingIntent abuse	Use `FLAG_IMMUTABLE`; explicit component targets
MITM fetch	TLS 1.3; strict cert validation; pinning
Token leakage in logs	Redact tokens/headers; structured logging
Notification action abuse	Require unlock/biometric for sensitive actions

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.

Navigation Menu

Uh oh!

Uh oh!

📖 Threat Modeling Guide

STRIDE Quick Reference

How to use this guide

Threat Modeling Workflow

1. Project Overview

2. Define Scope

3. Draw a System Diagram

4. Identify Assets

5. Identify Threats (Using STRIDE)

6. Add Mitigations

7. Risk Ranking (Optional, but recommended)

📖 Threat Modeling Template

Title

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking

🛡️ Example 1: Account Authentication

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking

🔔 Example 2: Push Notifications

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking

Uh oh!

Uh oh!

FilesExpand file tree

threat-modeling-guide.md

Latest commit

History

threat-modeling-guide.md

File metadata and controls

📖 Threat Modeling Guide

STRIDE Quick Reference

How to use this guide

Threat Modeling Workflow

1. Project Overview

2. Define Scope

3. Draw a System Diagram

4. Identify Assets

5. Identify Threats (Using STRIDE)

6. Add Mitigations

7. Risk Ranking (Optional, but recommended)

📖 Threat Modeling Template

Title

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking

🛡️ Example 1: Account Authentication

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking

🔔 Example 2: Push Notifications

1. Project Overview

2. Scope

3. System Diagram

4. Assets

5. Threats

6. Mitigations

7. Risk Ranking