Open Source Prep

Open Source Prep

把私有项目整理成可安全开源的仓库。分 5 个阶段串行执行，密钥扫描必须最先通过才能进入后续步骤。

使用场景

用户说：

• "帮我把这个项目开源"
• "准备开源前要做什么"
• "选一个开源协议"
• "上传 GitHub 前检查一下有没有泄漏"

重要原则

1. 密钥扫描是 gating step — 发现真实密钥时必须停下来让用户先清理，不能直接继续 2. 生成的文档用英文 — 面向国际贡献者；和用户对话用中文 3. LICENSE 文件必须命名为 `LICENSE`（大写无后缀），GitHub 才识别 4. 所有真实 token 示例必须用 `...REDACTED...` 占位符 — 即使是用户主动粘贴进来的 5. 不要直接 push 或切 public — 先让用户检查 diff，手动 commit+push+切可见性

工作流

Phase 1: 密钥 & 敏感文件扫描（BLOCKING）

必须先做，发现问题要停下。扫描三个地方：

1. 当前工作区文件（包括未追踪的） 2. 已 staged / 已 committed 的内容 3. git 全部历史（git log --all -p）

扫描模式见 references/secrets-patterns.md。关键模式包括：

敏感文件名（staged 时警报）：

• .env, .env.local, .env.production
• credentials.json, secrets.json
• *.pem, *.key, *.p12, *.pfx
• id_rsa, id_ed25519

执行命令（按项目大小自适应）：

# 工作区扫描（含未追踪）
git ls-files --others --exclude-standard -z | xargs -0 grep -lE "<pattern>" 2>/dev/null

# 已追踪文件
git grep -nE "<pattern>" 2>/dev/null

# Git 历史
git log --all -p 2>/dev/null | grep -cE "<pattern>"

# 敏感文件名
git ls-files | grep -E "(^|/)(\.env|credentials\.json|.*\.(pem|key|p12|pfx))$"

区分真密钥 vs 占位符：

• ✅ 占位符：包含 ... / REDACTED / example / test / xxx / dummy
• ❌ 真密钥：没有明显占位符标记，且符合真实格式（如 JWT 是三段点分 base64url、AWS 是 20 字符全大写 + 数字等）

发现真密钥时： 1. 列出文件 + 行号 + 截断显示（eyJhbGc...[12 chars]...abcd 前后各 4 位，中间省略） 2. 提供处理建议：

• 如果在工作区 → 移到 .env 并加入 .gitignore
• 如果已 commit 未 push → git filter-repo 或 git reset --soft HEAD~1
• 如果已 push → 必须立即撤销这个 token（本工具无法从 GitHub 删除已泄漏的 commit），然后 git filter-repo --invert-paths + force push

3. 停止后续步骤，让用户处理后再重跑

Phase 2: 协议选择（交互式）

根据决策树推荐，不要一上来就问所有问题：

第一问：项目性质？

• 个人工具 / 小库 / 应用 → 继续问第二
• 商业产品对外开源 / 希望企业安心使用 → Apache 2.0
• 想让所有衍生作品也开源 → 继续问第三

第二问（针对个人项目）：涉及可申请专利的新颖技术？

• 否 → MIT ⭐
• 是 → Apache 2.0

第三问（针对 copyleft 偏好）：SaaS 形态（用户通过网络用不下载）？

• 是 → AGPL v3
• 否 → GPL v3

默认推荐 MIT — 95% 个人项目合适。生成的 LICENSE 使用 templates/LICENSE-MIT.txt 模板，版权人从 git config user.name 读取，年份是当前年份。

协议对比速查：

Phase 3: 必备文档生成

生成以下文件（如已存在则显示 diff，用户确认后再改）：

1. `LICENSE` — 协议文本，填入版权人 + 年份 2. `CONTRIBUTING.md` — 开发环境、PR 流程、测试命令（用 templates/CONTRIBUTING.md） 3. `SECURITY.md` — 漏洞上报流程（用 templates/SECURITY.md） 4. `README.md` 补充（用 Edit tool 插入）：

• 顶部：第三方免责声明（如果项目涉及第三方服务）
• Privacy & Security 章节（如果处理敏感数据）
• License 章节指向 LICENSE 文件

Phase 4: 配置审计

检查并提示修改：

1. `.gitignore` — 确保包含：

   src-tauri/target/   # Tauri
   target/             # Rust 通用
   node_modules/       # Node
   dist/ build/ out/   # 构建产物
   .env*               # 环境变量
   .DS_Store Thumbs.db # OS
   coverage/ *.lcov    # 覆盖率报告

2. Bundle identifier / package name 检查：

• src-tauri/tauri.conf.json 的 identifier 字段
• package.json 的 name 字段
• Cargo.toml 的 [package] name
• 如果包含第三方公司名（如 com.google.*、com.factory.*）→ 警告商标风险
• 建议改为 com.<github-username>.<project-name>

3. 第三方服务引用：

• grep 项目名里有没有商标（"Google X", "Apple X" 等）
• README 是否说明这是 unofficial third-party tool

Phase 5: 可选增强

询问用户是否要做：

• [ ] CHANGELOG.md（从 git log 生成初始版本）
• [ ] GitHub Actions release workflow（.github/workflows/release.yml）
• [ ] Issue/PR 模板（.github/ISSUE_TEMPLATE/）
• [ ] 仓库可见性切换（gh repo edit --visibility public）

注意：切换为 public 是不可逆的信息公开，必须用户明确确认后才执行，且要再跑一次 Phase 1 密钥扫描。

输出格式

每个阶段结束后向用户报告：

## Phase N: xxx

✅ 通过：[...]
⚠️ 警告：[...]
❌ 需处理：[...]

下一步：[...]

最后给一个完整 checklist。

工具文件

• templates/LICENSE-MIT.txt — MIT 协议模板（用 {{YEAR}} {{AUTHOR}} 占位）
• templates/LICENSE-Apache-2.0.txt — Apache 2.0 模板
• templates/LICENSE-GPL-3.0.txt — GPL v3 模板（较长，可用 gh api 拉官方文本）
• templates/LICENSE-AGPL-3.0.txt — AGPL v3 模板
• templates/CONTRIBUTING.md — 贡献指南模板
• templates/SECURITY.md — 安全策略模板
• references/secrets-patterns.md — 完整的密钥正则表达式清单
• references/disclaimer-templates.md — 不同场景的免责声明范文

README Disclaimer Templates

不同场景下在 README 顶部应加的免责声明。

场景 1: 第三方服务的非官方工具

适用：封装 / 集成 / 管理某个商业服务（Factory.ai、Notion、Slack 等）的账号/数据。

> **Disclaimer**
> This is an **unofficial, third-party tool**. It is **not affiliated with, endorsed by, or sponsored by {{SERVICE_NAME}}**. The project name and any {{SERVICE_NAME}}-related references are used only to describe interoperability with {{SERVICE_NAME}}'s products. Use at your own risk and ensure compliance with [{{SERVICE_NAME}}'s Terms of Service]({{SERVICE_URL}}).

场景 2: 处理用户敏感凭据

适用：管理 auth token、API key、密码、私钥等的工具。

## Privacy & Security

- **Local-first**: All credentials and sensitive data are stored **only on your device**. Nothing is uploaded to any third-party server.
- **File permissions**: Auth files use restrictive Unix permissions (`0o600`).
- **No telemetry**: The app makes **no analytics, crash-reporting, or usage-tracking** requests.
- **Never paste real tokens in public places**: If you open an issue or PR, redact any `access_token` / `refresh_token` values.

场景 3: 逆向工程 / 爬虫类工具

适用：通过模拟浏览器、抓包分析 API 等方式实现的工具。

> **Disclaimer**
> This project is provided for **educational and personal use only**. It interacts with {{SERVICE_NAME}}'s unofficial APIs. Usage may violate {{SERVICE_NAME}}'s Terms of Service — **use at your own risk**. The authors accept no responsibility for account suspension, data loss, or legal consequences. For commercial use, consult {{SERVICE_NAME}}'s official APIs.

场景 4: AI/ML 模型相关

适用：使用外部 AI API 或发布模型权重。

> **Disclaimer**
> This project uses third-party AI services ({{AI_SERVICES}}). Output quality, accuracy, and safety depend on those underlying services. Do not rely on AI-generated output for critical decisions without verification. You are responsible for API costs incurred through your usage.

场景 5: 金融 / 交易工具

适用：量化交易、加密货币、投资组合管理。

> **Risk Disclaimer**
> This project is provided for **educational purposes only**. It is **not financial advice**. Trading involves risk of loss — including loss of principal. Past performance does not guarantee future results. The authors are not liable for any financial losses arising from use of this software. **Never share your API keys, private keys, or seed phrases.**

场景 6: 医疗 / 健康数据

> **Medical Disclaimer**
> This project is **not intended for medical diagnosis, treatment, or advice**. It is for informational and research purposes only. Consult a qualified healthcare professional for medical decisions. Not HIPAA-compliant unless explicitly configured.

通用附加条款

如果项目收集/存储任何用户数据（即使本地），建议加：

## Data Handling

{{PROJECT_NAME}} processes the following data:
- {{DATA_TYPE_1}}: stored locally at `{{PATH}}`, never transmitted
- {{DATA_TYPE_2}}: only used in-memory during execution

No data is sent to third-party servers except for {{LEGITIMATE_USE}} (e.g., API calls to the service you're interacting with).

Secret Detection Patterns

完整的密钥正则表达式清单，供 Phase 1 扫描使用。

优先级 1: 高确定性密钥（几乎肯定是真的）

这些模式有强特征，误报率低。发现即警报。

GitHub Personal Access Tokens

• ghp_[A-Za-z0-9]{36} — Classic PAT
• gho_[A-Za-z0-9]{36} — OAuth token
• ghu_[A-Za-z0-9]{36} — User-to-server token
• ghs_[A-Za-z0-9]{36} — Server-to-server token
• ghr_[A-Za-z0-9]{36} — Refresh token
• github_pat_[A-Za-z0-9_]{80,} — Fine-grained PAT

AWS

• AKIA[0-9A-Z]{16} — Access Key ID
• ASIA[0-9A-Z]{16} — Temporary Access Key
• aws_secret_access_key\s*=\s*['"]?[A-Za-z0-9/+=]{40} — Secret Access Key

Google Cloud

• AIza[0-9A-Za-z_-]{35} — API Key
• ya29\.[0-9A-Za-z_-]+ — OAuth token

OpenAI / Anthropic

• sk-[a-zA-Z0-9]{48,} — OpenAI API key（含 sk-proj-）
• sk-ant-[a-zA-Z0-9_-]{90,} — Anthropic API key

Slack

• xox[baprs]-[0-9a-zA-Z-]{10,} — Bot/User/App tokens
• https://hooks\.slack\.com/services/T[A-Z0-9]+/B[A-Z0-9]+/[a-zA-Z0-9]{24} — Webhook URL

Stripe

• sk_live_[0-9a-zA-Z]{24,} — Live secret key
• sk_test_[0-9a-zA-Z]{24,} — Test secret key（一般也不应该在仓库里）
• rk_live_[0-9a-zA-Z]{24,} — Restricted key

Discord / Telegram

• [MN][A-Za-z\d]{23}\.[\w-]{6}\.[\w-]{27} — Discord bot token
• \d{9,10}:[a-zA-Z0-9_-]{35} — Telegram bot token

私钥文件内容

• -----BEGIN (RSA |EC |DSA |OPENSSH |PGP |)PRIVATE KEY-----
• -----BEGIN ENCRYPTED PRIVATE KEY-----

数据库连接串

• (mongodb|postgres|postgresql|mysql|redis)://[^:]+:[^@]+@ — 含密码的 URL

优先级 2: 中等确定性（需要上下文判断）

JWT

• eyJhbGc[0-9A-Za-z_-]{20,}\.eyJ[0-9A-Za-z_-]{20,}\.[0-9A-Za-z_-]{20,} — 三段式

重要：JWT 本身不一定是机密（它在客户端本来就可见），但如果包含 access_token / refresh_token 字面值就是泄漏。

环境变量赋值

• (API_KEY|API_SECRET|SECRET_KEY|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|PRIVATE_KEY)\s*[:=]\s*["']?[A-Za-z0-9+/=_-]{12,}

通用密钥字段（JSON/YAML）

• "(access_token|refresh_token|api_key|secret)"\s*:\s*"[A-Za-z0-9._-]{16,}"

优先级 3: 文件名黑名单

以下文件如果被 git added 或 git ls-files 返回，立即警报：

占位符识别（避免误报）

含下列标记的基本可判定为占位符，不报警：

• REDACTED / redacted
• PLACEHOLDER / placeholder
• YOUR_* / your_*（如 YOUR_API_KEY）
• EXAMPLE / example（如 sk-example123）
• XXXXXX / xxxxx
• **** / ...
• 包含 test / dummy / fake / mock 关键词
• 在 README / docs / test fixture 上下文中且附近有"例如"/"示例"等中文或 e.g. / for example 英文

检测命令

快速扫描（Bash）

# 当前工作区
rg -nP "(?:ghp_|gho_|ghu_|ghs_)[A-Za-z0-9]{36}|AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48,}|-----BEGIN [A-Z ]*PRIVATE KEY-----" --glob '!node_modules/**' --glob '!target/**'

# Git 历史
git log --all -p 2>/dev/null | rg -c "(?:ghp_|AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)"

# 敏感文件名
git ls-files | rg -E "(^|/)(\.env(\..*)?|credentials\.json|secrets\.json|.*\.(pem|key|p12|pfx)|id_rsa|id_ed25519)$"

Python 批量扫描（更精确，支持占位符识别）

见 ../scripts/scan-secrets.py（可选扩展）。

处理流程

发现泄漏后的建议：

情况 A：仅在工作区（未 add）

# 移到 .env
echo 'MY_SECRET=...' >> .env
echo '.env' >> .gitignore
# 从源码中替换为 process.env.MY_SECRET 或类似

情况 B：已 staged 但未 commit

git reset HEAD <file>
# 然后按情况 A 处理

情况 C：已 commit 但未 push

# 如果是最近一个 commit
git reset --soft HEAD~1
# 编辑后重新 commit

# 如果涉及历史中间 commit，用 git filter-repo
pip install git-filter-repo
git filter-repo --invert-paths --path <leaked-file>

情况 D：已 push 到远程（最严重）

1. 立即撤销/轮换泄漏的密钥 — 本工具无法修复已经被别人看到的内容 2. 重写历史：git filter-repo --invert-paths --path <leaked-file> 3. Force push：git push --force-with-lease origin main 4. 通知所有协作者重新克隆 5. 如果是 public 仓库，考虑到已被爬虫/search engine 抓取，换密钥是唯一真正的修复

Contributing to {{PROJECT_NAME}}

Thanks for your interest in contributing! This document describes how to set up your development environment and the conventions used in this project.

Development setup

Prerequisites

<!-- TODO: fill in project-specific tools and versions -->

Clone and run

git clone https://github.com/{{OWNER}}/{{REPO}}.git
cd {{REPO}}
# TODO: add install / dev commands

Before you submit a PR

Please make sure all of the following pass locally:

# TODO: adjust to the project's test/lint/typecheck commands
# e.g. pnpm test / cargo test / pytest

Reporting issues

When filing a bug report, include:

• Your OS and version
• Project version
• Steps to reproduce
• Expected vs actual behavior
• Any relevant log output

Do not paste real credentials (API keys, access tokens, passwords) into issues or PRs. Redact sensitive values before posting.

For security vulnerabilities, follow the process in SECURITY.md — do not file a public issue.

Code style

• Follow each language's standard formatter defaults
• Prefer small, focused functions with unit tests
• English is preferred for code comments to maximize accessibility
• Descriptive commit messages are appreciated (e.g. feat:, fix:, docs:)

Scope of contributions

Before investing time in a large change, please open an issue to discuss whether it fits the project's direction. Features that add significant complexity or dependencies may not be accepted.

License

By contributing, you agree that your contributions will be licensed under the project's LICENSE.

Security Policy

Reporting a vulnerability

Please do not file public GitHub issues for security vulnerabilities.

If you discover a vulnerability, report it privately via one of:

• GitHub Security Advisories: open a private advisory on this repository
• Email: {{CONTACT_EMAIL_OR_GITHUB_PROFILE}}

Please include:

• A description of the vulnerability
• Steps to reproduce
• Potential impact
• Any suggested mitigation

You can expect an initial response within 7 days. We aim to issue a patched release within 30 days of confirming a vulnerability.

Do not paste real credentials in public

When filing regular (non-security) issues or PRs, always redact real credential values:

• API keys, access tokens, refresh tokens, passwords
• JWT payloads containing personally identifying information
• Contents of credential/config files

Use placeholders like <REDACTED> or eyJhbGc...REDACTED... in any shared snippets.

Supported versions

Security patches are released for the latest minor version only. Please keep your installation up to date.

<!-- TODO (if the project handles sensitive data): Add a section describing how the project handles sensitive data:

• Where data is stored (local only? cloud?)
• File permissions / encryption
• Whether telemetry is sent
• Any known-risk surfaces

-->