Security & Vulnerability Reporting
Relevant source files
The following files were used as context for generating this wiki page:
The putio-ios project maintains a strict protocol for handling security and privacy issues to protect user data and maintain the integrity of the application. Security management encompasses private vulnerability reporting, secure credential handling, and user-facing security controls.
The primary objective of the security framework is to ensure that vulnerabilities—ranging from authentication bypasses to sensitive credential exposure—are reported privately and mitigated before public disclosure.
Sources: SECURITY.md:1-5, CLAUDE.md:14-18
Vulnerability Reporting Process
If a security or privacy issue is discovered, it must be reported privately to the development team. Public disclosure is only permitted after a reasonable investigation and fix period has elapsed.
Reporting Channels
The designated contact for all security-related reports is:
- Email:
devs@put.io
Sources: SECURITY.md:7-11
Reporting Guidelines
To ensure reports are actionable and non-destructive, reporters must adhere to the following constraints:
- Scope of Testing: Only test against accounts, environments, and data under the reporter's direct control.
- Impact Mitigation: Testing must remain low-volume and non-destructive.
- Focus: Reports must target technical vulnerabilities specifically within this repository.
Sources: SECURITY.md:20-25
Report Scope
Useful reports typically address technical vulnerabilities in the following categories:
| Category | Description |
|---|---|
| Identity Management | Issues involving authentication, authorization, or session handling. |
| Credential Security | Exposure of tokens, secrets, or other sensitive credentials. |
| Access Control | Privilege escalation or bypass of existing access controls. |
| Data Privacy | Exposure of private user data. |
| Input Validation | Unsafe request handling or injection-based vulnerabilities. |
Sources: SECURITY.md:13-18
Secure Development Workflow
The project implements several architectural safeguards to prevent the accidental introduction or exposure of vulnerabilities during development and CI/CD.
Secret Management
- Git Safety: Private service keys, tokens, and signing keys are kept out of the repository's version control.
- Local Overrides: Developers use
Config/Local.xcconfigfor secrets. This file is gitignored and can be generated from templates or 1Password. - CI/CD Security: Release secrets are managed via a defined contract and loaded through GitHub Actions rather than being stored in code.
Sources: CLAUDE.md:23-26, CONTRIBUTING.md:24-30, CONTRIBUTING.md:105-107
Environment Isolation
The following diagram illustrates how the application isolates sensitive credentials and configuration based on the environment:
The application uses placeholders in Info.plist that are populated by specific configuration files, ensuring that no sensitive tokens are hardcoded in the public source.
Sources: CONTRIBUTING.md:88-92, CLAUDE.md:37-43
Application Security Features
The iOS application includes several user-configurable security features managed through the Settings module and enforced via the AppDelegate.
User Security Controls
Users can manage their account security through the securitySection of the application settings.
| Feature | Logic Location | Description |
|---|---|---|
| Two-Factor Auth | SettingsViewModel | Toggle 2FA and view/regenerate recovery codes. |
| Active Sessions | AuthAppsTableViewController | View and manage locations where the user is currently logged in. |
| Account Destruction | SettingsViewModel | Options to clear local data or permanently destroy the account. |
| Privacy Mode | SettingsViewModel | Toggle to control whether the app continues to populate account history. |
Sources: Putio/Features/Settings/SettingsViewModel+Sections.swift:130-165, Putio/Features/Settings/SettingsViewModel+Sections.swift:180-190
Session and Token Persistence
The app uses a dedicated keychain wrapper to handle the OAuth access token securely.
- Storage: The
PutioKeychainclass manages token persistence using scoped service keys. - Lifecycle: Upon logout, the keychain is cleared, the
apiclient token is reset, and Intercom sessions are terminated. - E2E Security: During E2E testing, a specific
PUTIO_E2E_RESET_STATEenvironment variable can trigger a complete wipe of the keychain,UserDefaults, and localRealmdatabases to ensure no residual data exists between tests.
Sources: Putio/AppDelegate.swift:230-240, Putio/AppDelegate.swift:105-115, PutioTests/PutioKeychainTests.swift:7-16
Authentication Flow Security
The authentication process includes state validation to prevent cross-site request forgery (CSRF) or mismatched callback attacks during the web-based OAuth flow.
The LoginViewController verifies that the state returned in the callback URL matches the currentOAuthState initiated by the app. It also rejects unexpected callback endpoints.
Sources: PutioTests/ErrorPresentationTests.swift:24-60
External Integrations & Diagnostics
Security and stability monitoring are integrated into the application lifecycle, but can be toggled based on build configuration.
- Sentry: Used for crash reporting and error tracking. It is enabled only if the
SENTRY_ENABLEDflag is set. - Intercom: Managed via
INTERCOM_ENABLED. It handles secure user attributes, including the user's ID and a secure hash for identity verification. - Audit Logging: The application uses
SwiftyBeaverfor internal logging. In debug builds, logs are sent to the console to assist in identifying security logic failures (e.g., Realm write errors).
Sources: Putio/AppDelegate.swift:65-80, Putio/AppDelegate.swift:200-210, Putio/Common/Helpers/Realm.swift:30-32
Conclusion
Security in the putio-ios repository is a multi-layered system involving private vulnerability disclosure protocols, secure development practices that isolate secrets from the codebase, and robust application-level controls such as 2FA and secure keychain persistence. These measures collectively ensure that user data remains protected while providing developers with a safe framework for contribution and distribution.