Security Policy
Relevant source files
The following files were used as context for generating this wiki page:
The MBBank library implements a multi-layered security approach to interact safely with the "Military Commercial Joint Stock Bank" (MBBank) personal account APIs. This policy covers vulnerability reporting, automated cryptographic protection, and secure development practices required for handling sensitive financial data.
Vulnerability Reporting and Support
The project maintains a strict policy regarding the reporting of security flaws to ensure the safety of user credentials and financial information. Only the latest release of the library is officially supported for security updates.
Reporting Process
Vulnerabilities should be reported using the Security Vulnerability Report template. Reports must include a detailed description, reproduction steps, potential impact, and suggested fixes.
The following types of reports are explicitly excluded:
- AI-generated security reports.
- Vulnerabilities found in third-party dependencies (these must be reported to the respective maintainers).
Sources: SECURITY.md:1-24, CONTRIBUTING.md:73-75
Cryptographic Security and Data Protection
The library manages sensitive interactions through request encryption and session-based authentication.
WebAssembly (WASM) Encryption
The library utilizes a WebAssembly module (main.wasm) fetched directly from MBBank's infrastructure to perform request encryption. This ensures that the encryption logic remains consistent with the bank's official web application.
The wasm_encrypt function in mbbank/wasm_helper/__init__.py initializes a wasmtime engine to execute the binary logic, preventing the need to port complex cryptographic algorithms to Python.
Sources: mbbank/wasm_helper/init.py:290-318, mbbank/sync/mbbank.py:91-100
Sensitive Data Handling
A critical rule for contributors and users is the prohibition of including real banking credentials, account numbers, or session tokens in public issues or Pull Requests.
Sources: CONTRIBUTING.md:69-71
Authentication and Session Management
The library implements an automated authentication flow that handles captchas and session expiration.
Authentication Flow
When a request fails due to an expired session (indicated by error code GW200), the library automatically triggers a re-authentication sequence.
| Component | Responsibility |
|---|---|
_authenticate | Manages retry logic (default 30 times) for captcha processing. |
login | Performs MD5 hashing of passwords and transmits encrypted payloads. |
CapchaProcessing | An abstract interface for solving visual challenges. |
deviceIdCommon | A unique identifier generated per instance to track the session. |
Security-Related Error Handling
Specific exceptions are defined to handle security-sensitive failures during API interaction.
| Exception | Triggering Condition |
|---|---|
CryptoVerifyError | Raised when the API returns a 428 status code, indicating manual crypto verification is required. |
MBBankAPIError | General wrapper for bank-returned error codes (e.g., GW283 for captcha errors). |
CapchaError | Raised when the library exceeds the maximum retry_times for solving a captcha. |
Sources: mbbank/errors.py:28-71, mbbank/sync/mbbank.py:84-86
Development and Code Quality
Security is further reinforced through static analysis and linting tools configured in the project.
Automated Checks
The project uses Ruff with the S (flake8-bandit) plugin enabled to detect common security issues in Python code.
| Tool | Purpose |
|---|---|
ruff | Linting with security rules (Bandit). |
S324 Ignore | Explicitly allows MD5 usage as it is mandated by the MBBank API protocol. |
Sources: ruff.toml:22-35, CONTRIBUTING.md:27-39
Conclusion
The MBBank library prioritizes security by mirroring the official bank client's encryption via WASM and enforcing strict session management. By combining automated cryptographic protections with clear vulnerability reporting guidelines, the project provides a structured framework for interacting with sensitive financial interfaces.
Sources: SECURITY.md:1-11, mbbank/sync/mbbank.py:70-90