From a448637477d3f8056d5aab3cead4ff11d7cb75ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=83=A1=E7=BB=8D=E5=BA=B7?= <3052147989@qq.com> Date: Wed, 25 Feb 2026 17:10:54 +0800 Subject: [PATCH] chore: add GitHub templates and community files - Add Issue templates (bug report, feature request) with bilingual support - Add PR template with bilingual support - Add Dependabot configuration for Python, Docker, and GitHub Actions - Add labels configuration with 30+ standardized labels - Add code quality workflow (Black, isort, Flake8, Bandit) - Add LICENSE (Apache 2.0) - Add CONTRIBUTING.md with development guidelines - Add SECURITY.md with vulnerability reporting process Co-Authored-By: Claude Opus 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 37 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 32 ++++ .github/PULL_REQUEST_TEMPLATE.md | 33 ++++ .github/dependabot.yml | 40 +++++ .github/labels.yml | 84 ++++++++++ .github/workflows/code-quality.yml | 75 +++++++++ CONTRIBUTING.md | 149 +++++++++++++++++ LICENSE | 190 ++++++++++++++++++++++ SECURITY.md | 136 ++++++++++++++++ 9 files changed, 776 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/dependabot.yml create mode 100644 .github/labels.yml create mode 100644 .github/workflows/code-quality.yml create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..088c5dc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,37 @@ +--- +name: Bug Report / Bug 报告 +about: Create a report to help us improve / 创建报告帮助我们改进 +title: "bug: " +labels: "bug" +assignees: "" +--- + +# Bug Report / Bug 报告 + +**Version / 版本:** + + + +**Current behavior / 当前行为:** + + + +**Expected behavior / 期望行为:** + + + +**Steps to reproduce / 复现步骤:** + + + +**Related code / 相关代码:** + + + +``` +insert short code snippets here / 在此插入简短代码片段 +``` + +**Other information / 其他信息:** + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..95cd90a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,32 @@ +--- +name: Feature Request / 功能请求 +about: Suggest an idea for this project / 为此项目提出想法 +title: "feat: " +labels: "enhancement" +assignees: "" +--- + +# Feature Request / 功能请求 + +**Describe the Feature Request / 描述功能请求** + + + +**Describe Preferred Solution / 描述首选解决方案** + + + +**Describe Alternatives / 描述替代方案** + + + +**Related Code / 相关代码** + + + +**Additional Context / 附加上下文** + + + +**If the feature request is approved, would you be willing to submit a PR? / 如果功能请求被批准，你愿意提交 PR 吗？** +Yes / No _(Help can be provided if you need assistance submitting a PR / 如果需要帮助提交 PR，我们可以提供协助)_ diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..6059d4f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,33 @@ + + +## Pull request type / PR 类型 + + + +Please check the type of change your PR introduces / 请勾选 PR 引入的更改类型: + +- [ ] Bugfix / Bug 修复 +- [ ] Feature / 新功能 +- [ ] Code style update (formatting, renaming) / 代码风格更新（格式化、重命名） +- [ ] Refactoring (no functional changes, no api changes) / 重构（无功能更改、无 API 更改） +- [ ] Build related changes / 构建相关更改 +- [ ] Documentation content changes / 文档内容更改 +- [ ] Other (please describe) / 其他（请描述）: + +## What is the current behavior? / 当前行为是什么？ + + + +Issue Number / Issue 编号: N/A + +## What is the new behavior? / 新行为是什么？ + + + +- +- +- + +## Other information / 其他信息 + + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..2108459 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,40 @@ +version: 2 +updates: + # Python dependencies + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 10 + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore" + include: "scope" + + # Docker dependencies + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "docker" + commit-message: + prefix: "chore" + include: "scope" + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "ci" + commit-message: + prefix: "chore" + include: "scope" diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..b67eaa8 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,84 @@ +--- +- name: "breaking-change" + color: ee0701 + description: "A breaking change for existing users." +- name: "bug" + color: ee0701 + description: "Inconsistencies or issues which will cause a problem for users or implementors." +- name: "documentation" + color: 0052cc + description: "Solely about the documentation of the project." +- name: "enhancement" + color: 1d76db + description: "Enhancement of the code, not introducing new features." +- name: "refactor" + color: 1d76db + description: "Improvement of existing code, not introducing new features." +- name: "performance" + color: 1d76db + description: "Improving performance, not introducing new features." +- name: "new-feature" + color: 0e8a16 + description: "New features or options." +- name: "maintenance" + color: 2af79e + description: "Generic maintenance tasks." +- name: "ci" + color: 1d76db + description: "Work that improves the continue integration." +- name: "dependencies" + color: 1d76db + description: "Upgrade or downgrade of project dependencies." +- name: "python" + color: 3572A5 + description: "Related to Python code or dependencies." +- name: "docker" + color: 2496ED + description: "Related to Docker configuration or images." + +- name: "in-progress" + color: fbca04 + description: "Issue is currently being resolved by a developer." +- name: "stale" + color: fef2c0 + description: "There has not been activity on this issue or PR for quite some time." +- name: "no-stale" + color: fef2c0 + description: "This issue or PR is exempted from the stable bot." + +- name: "security" + color: ee0701 + description: "Marks a security issue that needs to be resolved ASAP." +- name: "incomplete" + color: fef2c0 + description: "Marks a PR or issue that is missing information." +- name: "invalid" + color: fef2c0 + description: "Marks a PR or issue that is missing information." + +- name: "beginner-friendly" + color: 0e8a16 + description: "Good first issue for people wanting to contribute to the project." +- name: "help-wanted" + color: 0e8a16 + description: "We need some extra helping hands or expertise in order to resolve this." + +- name: "priority-critical" + color: ee0701 + description: "This should be dealt with ASAP. Not fixing this issue would be a serious error." +- name: "priority-high" + color: b60205 + description: "After critical issues are fixed, these should be dealt with before any further issues." +- name: "priority-medium" + color: 0e8a16 + description: "This issue may be useful, and needs some attention." +- name: "priority-low" + color: e4ea8a + description: "Nice addition, maybe... someday..." + +- name: "major" + color: b60205 + description: "This PR causes a major version bump in the version number." +- name: "minor" + color: 0e8a16 + description: "This PR causes a minor version bump in the version number." diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml new file mode 100644 index 0000000..ffb402c --- /dev/null +++ b/.github/workflows/code-quality.yml @@ -0,0 +1,75 @@ +name: Code Quality + +on: + push: + branches: [ "main", "master" ] + paths: + - "**.py" + - "requirements.txt" + - ".github/workflows/code-quality.yml" + pull_request: + paths: + - "**.py" + - "requirements.txt" + - ".github/workflows/code-quality.yml" + workflow_dispatch: + +jobs: + linting: + name: Code Linting + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install flake8 black isort mypy + + - name: Run Black (Code Formatter Check) + run: black --check --diff . + + - name: Run isort (Import Sorting Check) + run: isort --check-only --diff . + + - name: Run Flake8 (Linting) + run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + + - name: Run Flake8 (Complexity Check) + run: flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + + security: + name: Security Scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + actions: read + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install bandit[toml] + + - name: Run Bandit Security Scan + run: bandit -r . -f json -o bandit-report.json || true + + - name: Display Bandit Results + run: | + if [ -f bandit-report.json ]; then + cat bandit-report.json + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d45f992 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,149 @@ +# Contributing to Outlook Email Management Tool / 为 Outlook 邮件管理工具做贡献 + +First off, thank you for considering contributing to this project! / 首先，感谢你考虑为此项目做贡献！ + +The following is a set of guidelines for contributing. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. / 以下是贡献指南。这些主要是指导方针，而非规则。请运用你的最佳判断，并随时在 PR 中提出对本文档的修改建议。 + +## Table of Contents / 目录 + +- [Code of Conduct](#code-of-conduct--行为准则) +- [How Can I Contribute?](#how-can-i-contribute--我如何做贡献) +- [Development Setup](#development-setup--开发环境设置) +- [Pull Request Process](#pull-request-process--pr-流程) +- [Style Guidelines](#style-guidelines--风格指南) + +## Code of Conduct / 行为准则 + +This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. / 此项目及其所有参与者均受我们的行为准则约束。参与即表示你同意遵守此准则。 + +## How Can I Contribute? / 我如何做贡献？ + +### Reporting Bugs / 报告 Bug + +Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible: / 在创建 bug 报告之前，请检查现有 issue，你可能会发现无需创建新的。创建 bug 报告时，请尽可能包含详细信息： + +- Use a clear and descriptive title / 使用清晰描述性的标题 +- Describe the exact steps to reproduce the problem / 描述重现问题的确切步骤 +- Provide specific examples / 提供具体示例 +- Describe the behavior you observed and what you expected / 描述你观察到的行为以及你的期望 +- Include screenshots if possible / 如可能，包含截图 +- Include your environment details (OS, Python version, etc.) / 包含你的环境详情（操作系统、Python 版本等） + +### Suggesting Enhancements / 建议增强功能 + +Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include: / 增强建议通过 GitHub issue 跟踪。创建增强建议时，请包含： + +- Use a clear and descriptive title / 使用清晰描述性的标题 +- Provide a detailed description of the suggested enhancement / 提供建议增强功能的详细描述 +- Explain why this enhancement would be useful / 解释为什么此增强功能有用 +- List some examples of how it would be used / 列出一些使用示例 + +### Your First Code Contribution / 你的第一次代码贡献 + +Unsure where to begin? You can start by looking through `beginner-friendly` and `help-wanted` issues: / 不确定从哪里开始？你可以从 `beginner-friendly` 和 `help-wanted` issue 开始： + +- Beginner-friendly issues - issues which should only require a few lines of code / 初学者友好的 issue - 只需几行代码即可解决 +- Help wanted issues - issues which may be more involved / 需要帮助的 issue - 可能涉及更多内容 + +## Development Setup / 开发环境设置 + +1. Fork the repository / Fork 仓库 +2. Clone your fork / 克隆你的 fork + ```bash + git clone https://github.com/YOUR_USERNAME/outlookEmail.git + cd outlookEmail + ``` + +3. Create a virtual environment / 创建虚拟环境 + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +4. Install dependencies / 安装依赖 + ```bash + pip install -r requirements.txt + ``` + +5. Create a branch for your changes / 为你的更改创建分支 + ```bash + git checkout -b feature/your-feature-name + ``` + +6. Make your changes and test them / 进行更改并测试 + ```bash + python -m unittest discover -s tests -v + ``` + +## Pull Request Process / PR 流程 + +1. Ensure your code follows the project's coding standards / 确保你的代码遵循项目的编码标准 +2. Update the documentation if needed / 如需要，更新文档 +3. Add tests for new features / 为新功能添加测试 +4. Ensure all tests pass / 确保所有测试通过 +5. Update the README.md with details of changes if applicable / 如适用，更新 README.md 中的更改详情 +6. Create a Pull Request with a clear title and description / 创建带有清晰标题和描述的 PR +7. Link any related issues in the PR description / 在 PR 描述中链接相关 issue + +### PR Title Format / PR 标题格式 + +Use conventional commit format: / 使用约定式提交格式： + +- `feat: Add new feature` / `feat: 添加新功能` +- `fix: Fix bug in email fetching` / `fix: 修复邮件获取中的 bug` +- `docs: Update README` / `docs: 更新 README` +- `style: Format code` / `style: 格式化代码` +- `refactor: Refactor authentication` / `refactor: 重构认证` +- `test: Add tests for email service` / `test: 为邮件服务添加测试` +- `chore: Update dependencies` / `chore: 更新依赖` + +## Style Guidelines / 风格指南 + +### Python Code Style / Python 代码风格 + +- Follow PEP 8 style guide / 遵循 PEP 8 风格指南 +- Use meaningful variable and function names / 使用有意义的变量和函数名 +- Add docstrings to functions and classes / 为函数和类添加文档字符串 +- Keep functions small and focused / 保持函数小而专注 +- Use type hints where appropriate / 在适当的地方使用类型提示 + +### Git Commit Messages / Git 提交消息 + +- Use the present tense ("Add feature" not "Added feature") / 使用现在时（"Add feature" 而非 "Added feature"） +- Use the imperative mood ("Move cursor to..." not "Moves cursor to...") / 使用祈使语气（"Move cursor to..." 而非 "Moves cursor to..."） +- Limit the first line to 72 characters or less / 第一行限制在 72 个字符以内 +- Reference issues and pull requests after the first line / 在第一行之后引用 issue 和 PR + +### Testing / 测试 + +- Write unit tests for new features / 为新功能编写单元测试 +- Ensure all tests pass before submitting PR / 提交 PR 前确保所有测试通过 +- Aim for high test coverage / 追求高测试覆盖率 +- Test edge cases and error conditions / 测试边界情况和错误条件 + +## Project Structure / 项目结构 + +``` +outlook_web/ +├── app.py # Application factory +├── routes/ # Blueprint routes +├── controllers/ # Request handlers +├── services/ # Business logic +├── repositories/ # Data access +├── middleware/ # Middleware +└── security/ # Security modules +``` + +For detailed architecture information, see `docs/DEV/00002-前后端拆分-开发者指南.md` / 详细架构信息请参见 `docs/DEV/00002-前后端拆分-开发者指南.md` + +## Questions? / 有问题？ + +Feel free to open an issue with your question or reach out to the maintainers. / 随时开启 issue 提问或联系维护者。 + +## License / 许可证 + +By contributing, you agree that your contributions will be licensed under the Apache License 2.0. / 通过贡献，你同意你的贡献将在 Apache License 2.0 下授权。 + +--- + +Thank you for contributing! / 感谢你的贡献！ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2f2b188 --- /dev/null +++ b/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2026 guanshangshui + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..ab90a23 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,136 @@ +# Security Policy / 安全策略 + +## Supported Versions / 支持的版本 + +We release patches for security vulnerabilities for the following versions: / 我们为以下版本发布安全漏洞补丁： + +| Version / 版本 | Supported / 支持 | +| -------------- | ------------------------- | +| latest (main) | :white_check_mark: | +| < latest | :x: | + +## Reporting a Vulnerability / 报告漏洞 + +**Please do not report security vulnerabilities through public GitHub issues.** / **请勿通过公开的 GitHub issue 报告安全漏洞。** + +If you discover a security vulnerability, please send an email to: / 如果你发现安全漏洞，请发送邮件至： + +**Email / 邮箱:** 3052147989@qq.com + +Please include the following information in your report: / 请在报告中包含以下信息： + +- Type of vulnerability / 漏洞类型 +- Full paths of source file(s) related to the vulnerability / 与漏洞相关的源文件完整路径 +- Location of the affected source code (tag/branch/commit or direct URL) / 受影响源代码的位置（tag/分支/commit 或直接 URL） +- Step-by-step instructions to reproduce the issue / 重现问题的分步说明 +- Proof-of-concept or exploit code (if possible) / 概念验证或漏洞利用代码（如可能） +- Impact of the vulnerability / 漏洞的影响 + +## Response Timeline / 响应时间表 + +- **Initial Response / 初始响应:** We will acknowledge receipt of your vulnerability report within 48 hours. / 我们将在 48 小时内确认收到你的漏洞报告。 +- **Status Update / 状态更新:** We will provide a more detailed response within 7 days, indicating the next steps in handling your report. / 我们将在 7 天内提供更详细的响应，说明处理报告的后续步骤。 +- **Fix Timeline / 修复时间表:** We will work to fix confirmed vulnerabilities as quickly as possible, typically within 30 days. / 我们将尽快修复已确认的漏洞，通常在 30 天内。 + +## Disclosure Policy / 披露政策 + +- Please give us reasonable time to fix the vulnerability before public disclosure. / 请在公开披露前给我们合理的时间修复漏洞。 +- We will credit you in the security advisory unless you prefer to remain anonymous. / 我们将在安全公告中致谢你，除非你希望保持匿名。 +- We will coordinate with you on the disclosure timeline. / 我们将与你协调披露时间表。 + +## Security Best Practices / 安全最佳实践 + +When using this application, please follow these security best practices: / 使用此应用时，请遵循以下安全最佳实践： + +### For Users / 用户 + +1. **Strong Passwords / 强密码** + - Use a strong, unique password for the web interface / 为 Web 界面使用强且唯一的密码 + - Change the default password immediately / 立即更改默认密码 + - Use at least 12 characters with mixed case, numbers, and symbols / 使用至少 12 个字符，包含大小写、数字和符号 + +2. **SECRET_KEY Management / SECRET_KEY 管理** + - Always set a strong SECRET_KEY environment variable / 始终设置强 SECRET_KEY 环境变量 + - Never commit SECRET_KEY to version control / 切勿将 SECRET_KEY 提交到版本控制 + - Use a cryptographically secure random string / 使用加密安全的随机字符串 + - Generate with: `python -c 'import secrets; print(secrets.token_hex(32))'` + +3. **HTTPS / HTTPS** + - Always use HTTPS in production / 生产环境始终使用 HTTPS + - Use a reverse proxy (Nginx/Caddy) with SSL/TLS / 使用带 SSL/TLS 的反向代理（Nginx/Caddy） + - Enable HSTS (HTTP Strict Transport Security) / 启用 HSTS（HTTP 严格传输安全） + +4. **Access Control / 访问控制** + - Limit access to trusted networks / 限制对受信任网络的访问 + - Use firewall rules to restrict access / 使用防火墙规则限制访问 + - Consider using VPN for remote access / 考虑使用 VPN 进行远程访问 + +5. **Regular Updates / 定期更新** + - Keep the application updated to the latest version / 保持应用更新到最新版本 + - Monitor security advisories / 监控安全公告 + - Update dependencies regularly / 定期更新依赖 + +6. **Data Backup / 数据备份** + - Regularly backup the database file / 定期备份数据库文件 + - Store backups securely / 安全存储备份 + - Test backup restoration / 测试备份恢复 + +### For Developers / 开发者 + +1. **Input Validation / 输入验证** + - Always validate and sanitize user input / 始终验证和净化用户输入 + - Use parameterized queries to prevent SQL injection / 使用参数化查询防止 SQL 注入 + - Implement proper error handling / 实现适当的错误处理 + +2. **Authentication & Authorization / 认证与授权** + - Use bcrypt for password hashing / 使用 bcrypt 进行密码哈希 + - Implement rate limiting for login attempts / 为登录尝试实施速率限制 + - Use secure session management / 使用安全的会话管理 + +3. **Data Protection / 数据保护** + - Encrypt sensitive data at rest / 加密静态敏感数据 + - Use HTTPS for data in transit / 使用 HTTPS 传输数据 + - Implement proper access controls / 实施适当的访问控制 + +4. **Dependencies / 依赖** + - Keep dependencies up to date / 保持依赖最新 + - Use Dependabot for automated updates / 使用 Dependabot 自动更新 + - Review security advisories / 审查安全公告 + +5. **Code Review / 代码审查** + - Review all code changes for security issues / 审查所有代码更改的安全问题 + - Use static analysis tools / 使用静态分析工具 + - Follow secure coding practices / 遵循安全编码实践 + +## Known Security Features / 已知安全特性 + +This application includes the following security features: / 此应用包含以下安全特性： + +- **XSS Protection / XSS 防护:** DOMPurify sanitization and iframe sandboxing / DOMPurify 净化和 iframe 沙箱隔离 +- **CSRF Protection / CSRF 防护:** Flask-WTF token validation / Flask-WTF token 验证 +- **Data Encryption / 数据加密:** Fernet symmetric encryption for sensitive data / Fernet 对称加密敏感数据 +- **Rate Limiting / 速率限制:** Login attempt throttling / 登录尝试限流 +- **Audit Logging / 审计日志:** Sensitive operation tracking / 敏感操作跟踪 +- **Password Hashing / 密码哈希:** bcrypt with salt / bcrypt 加盐 + +For more details, see the security section in README.md / 更多详情请参见 README.md 中的安全部分 + +## Security Updates / 安全更新 + +Security updates will be released as soon as possible after a vulnerability is confirmed. We will: / 安全更新将在漏洞确认后尽快发布。我们将： + +- Release a patch version / 发布补丁版本 +- Publish a security advisory / 发布安全公告 +- Update the CHANGELOG / 更新 CHANGELOG +- Notify users through GitHub releases / 通过 GitHub releases 通知用户 + +## Contact / 联系方式 + +For security-related questions or concerns, please contact: / 有关安全相关的问题或疑虑，请联系： + +- **Email / 邮箱:** 3052147989@qq.com +- **GitHub Issues:** For non-security bugs only / 仅用于非安全 bug + +--- + +Thank you for helping keep this project secure! / 感谢你帮助保持此项目的安全！