lawushanshan/installermarker

# InstallerMarker 中文文档请见 [README.zh-CN.md](README.zh-CN.md)。 InstallerMarker 是一款安全的初步分析工具，用于将开源 GitHub 仓库转化为跨平台安装程序计划。它并不保证每个仓库都能自动成为 Windows、macOS 和 Linux 应用程序。相反，它使打包决策变得明确、可重复且可审查。 ## 版本 0.2 的功能 - 接受公开的 GitHub 仓库 URL。 - 读取仓库元数据、发布资产以及一小部分标准清单文件白名单。 - 仅解析一次默认分支，并将分析和配方固定到其不可变的 commit SHA 上。 - 检测常见的项目系列：Electron、Tauri、Go、Rust、Python、Java、Node.js 和 container 服务。 - 将 Windows x64、macOS 和 Linux x64 独立评估为 `available`、`likely` 或 `needs_review`。 - 生成可编辑的安装程序配方草稿，供后续隔离构建使用。 - 将现有的 GitHub Release 安装程序提取到经过验证的 artifact 目录中，而无需执行它们。 它绝不会克隆、从中安装依赖项或执行被检查的仓库。这是有意为之的：提交给安装程序工厂的 URL 必须被视为不受信任的输入。 ## 快速开始 需要 Node.js 20 或更高版本。 安装当前的 GitHub Release 包： ``` npm install --global https://github.com/lawushanshan/installermarker/releases/download/v0.2.2/installermarker-0.2.2.tgz ``` 使用 `installermarker --version` 检查已安装的 CLI 版本。一旦启用了 npm 发布，相同的命令也可以使用 `npx installermarker` 运行。 ``` installermarker https://github.com/owner/repository installermarker https://github.com/owner/repository --recipe --format yaml installermarker https://github.com/owner/repository --recipe --format json --output installermarker.json installermarker validate installermarker.json installermarker materialize installermarker.json --dry-run installermarker materialize installermarker.json --output-dir artifacts/v1 installermarker materialize installermarker.json --target linux-x64 --output-dir artifacts/linux installermarker verify artifacts/v1 ``` 对于私有仓库或更高的 GitHub API 限制，请设置具有只读仓库访问权限的 token： ``` GITHUB_TOKEN=github_pat_xxx installermarker https://github.com/owner/repository --recipe ``` 该 token 仅在该次调用期间的 GitHub API 请求中使用，绝不会写入磁盘。 ## 解释说明 `available` 表示最新的 GitHub release 包含特定于目标平台的交付 artifact。生成的配方会区分可重用的安装程序（`.msi`、`.dmg`、`.pkg`、`.AppImage`、`.deb` 或 `.rpm`）与仍需安装程序封装的归档文件。`likely` 表示检测到了著名的原生跨平台项目系列，但仍需进行隔离构建和冒烟测试。`needs_review` 表示源证据不充分；这不是失败，应通过明确的人工决策来处理。 生成的配方有意包含了用于可执行入口点和构建命令的 `TODO` 值。在启用任何构建 worker 之前，请先确认它们。 配方文件可以是 JSON 或 YAML。请使用对应的 `.json`、`.yaml` 或 `.yml` 文件扩展名，以便 CLI 能够确定性地解析该格式。 配方输出会记录源 commit 和 release 资产的来源。创建输出文件时不会覆盖现有文件；仅在确实需要替换时才传递 `--force`。JSON 契约记录在 [`schema/installermarker.schema.json`](schema/installermarker.schema.json) 中。 该配方还会记录 GitHub 的 SPDX 许可证据。`NOASSERTION` 是审查警告，而非重新分发的许可：在发布重新打包的应用程序之前，请先解决许可问题。 在执行提取之前使用 `validate`。它会单独报告 schema 错误和未解决的审查警告。`validate --strict` 在遇到错误或警告时都会返回非零状态，专为 CI 门禁设计。 `materialize` 目前仅接受 URL 属于源仓库 GitHub Releases 且其 SHA-256 摘要存在于配方中的公开安装程序。它将每个选定的 asset 流式传输到暂存目录，验证其声明的大小和摘要，然后连同 `artifacts.json` 来源清单一起发布这些文件。使用 `--target` 选择单个平台，或省略它以收集配方中的每个可重用安装程序。它既不打开也不安装这些 artifact。绝不会覆盖现有的输出文件。 使用 `verify ` 离线重新检查现有的 `artifacts.json` 或 `build-artifacts.json` 目录。它会验证清单契约、文件名、字节大小和 SHA-256 值，而无需执行任何 artifact。 对于没有现成安装程序的 Electron 和 Tauri 项目，请审查生成的源构建配方，设置其经过审查的 `build.command`，并针对每个目标运行一次原生构建。Go 和 Rust 项目会收到一个 `build-native` 目标：在执行之前，请先选择并审查原生打包命令和输出目录。Worker 接受 Windows 的 `.msi`/`.exe`、macOS 的 `.dmg`/`.pkg` 以及 Linux 的 `.AppImage`/`.deb`/`.rpm` 包。请参阅[源构建](docs/source-build.md)。 ## 项目生命周期 Pull request 会在 Node.js 20 和 22 上运行语法检查、单元测试和包内容检查。推送诸如 `v0.2.0` 的标签会创建一个 npm tarball 并将其附加到 GitHub Release 上。npm 发布是可选的，需要配置 `NPM_TOKEN` 仓库 secret。 在首次发布之前，请创建一个 GitHub 仓库，将其添加为 `origin` remote，并推送 `main`： ``` git remote add origin https://github.com//installermarker.git git push -u origin main ``` 已发布的包元数据会指向此 GitHub 仓库，用于源码、issue 跟踪和主页链接。如果仓库发生转移，请保持这些字段同步。 为 `main` 启用分支保护：要求运行 CI 工作流，要求 pull request 审查，并禁止强制推送。配置 GitHub Actions 时使用最小权限，并为发布凭据使用受保护的环境。 ## 范围和路线图 版本 0.2 包括静态分析、固定的配方生成、对现有安装程序的验证性提取，以及经过审查的 Electron/Tauri、Go 和 Rust 源构建路径。下一阶段将是为 Go/Rust 提供固执己见的打包适配器、支持 Python 和其他项目系列、SBOM 生成、恶意软件/依赖项扫描、安装/卸载冒烟测试，以及与不受信任构建隔离的签名。Windows Authenticode 和 macOS Developer ID/notarization 凭据绝不能暴露给仓库构建脚本。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md)、[docs/architecture.md](docs/architecture.md)、[docs/materialize.md](docs/materialize.md)、[docs/verify.md](docs/verify.md) 和 [docs/releasing.md](docs/releasing.md)。 发布历史记录在 [CHANGELOG.md](CHANGELOG.md) 中维护。 有关由仓库管理的无 secret 提取运行，请参阅 [GitHub Actions worker 指南](docs/github-actions.md)。 有关在受保护环境中进行的原生 Windows、macOS 和 Linux 源构建，请参阅[源构建指南](docs/source-build.md)。

标签：GNU通用公共许可证, MITM代理, Node.js, 云安全监控, 安全沙箱, 文档结构分析, 暗色界面, 自动化打包, 自定义脚本, 静态分析