prodrom3/nostos

# nostos [](https://github.com/prodrom3/nostos/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](./LICENSE) [](./VERSION) [](https://pypi.org/project/nostos/) [](#compatibility) ``` __ ____ ____ _____/ /_____ _____ / __ \/ __ \/ ___/ __/ __ \/ ___/ / / / / /_/ (__ ) /_/ /_/ (__ ) /_/ /_/\____/____/\__/\____/____/ the homecoming - a fleet of git repositories ``` ## 概述 nostos 是三个工具合而为一： 1. 一个 **批量拉取引擎**，遍历目录树（或/和精选索引），发现所有可达的 Git 仓库，并发更新它们。脏树、分离 HEAD 和缺少上游的情况会被报告并跳过，绝不覆盖。 2. 一个 **元数据索引**（SQLite），记录每个仓库的身份、来源、标签、备注和分级状态。 3. 一个 **上游探测层**，查询 GitHub、GitLab 和 Gitea（托管或自建）的健康信号（已归档、星标、最后推送、最新发布、许可证），采用严格的安全失败策略。 使用场景： - 平台 / DevEx 团队保持共享工具仓库在开发者工作站上的新鲜度。 - 构建机或镜像主机维护上游项目的只读克隆。 - 入职自动化工具，初始化并刷新一套精选的团队仓库。 - 发布工程师在协调变更前协调多个长期检出的仓库。 ## 快速开始 ``` pipx install nostos # or: pip install nostos nostos completion install # enable shell tab-completion nostos --dry-run # preview updates under cwd nostos ~/projects --workers 16 # pull in parallel nostos add https://github.com/org/tool.git --tag recon nostos list --tag recon --untouched-over 90 nostos triage # classify new intake ``` 除了 `argcomplete`（用于 Tab 补全，安装时自带）外，无需任何第三方运行时依赖。 ## 安装 ### 要求 | 组件 | 最低要求 | 推荐 | | --- | --- | --- | | Python | 3.10 | 3.12+ | | Git | 2.25 | **2.45.1+**（nostos 在启动时会对存在 CVE-2024-32002 / 32004 / 32465 的版本发出警告） | | OS | Linux / macOS / Windows | - | ### 安装 ``` # 隔离（推荐） pipx install nostos # 系统级 pip install nostos # 从源头 git clone https://github.com/prodrom3/nostos.git cd nostos && pip install . ``` 通过 `nostos --version` 和 `nostos --help` 验证安装。 ### Shell Tab 补全 ``` nostos completion install # auto-detects your shell exec $SHELL # reload nostos # lists all verbs ``` `install` 是幂等的，会在 `~/.bashrc`、`~/.zshrc` 或 `~/.config/fish/conf.d/nostos.fish` 中写入托管配置块。可通过 `nostos completion uninstall` 移除。上游 argcomplete 不支持原生 Windows Shell（PowerShell / cmd）；请使用 Git Bash 或 WSL。 ## 用法 nostos 是动词优先：`nostos <动词> [参数]`。若不指定动词，则隐式执行 `pull`，因此旧脚本和定时任务仍可继续工作。 | 动词 | 用途 | | --- | --- | | `pull`（默认） | 批量更新发现的仓库。 | | `add` | 将本地路径或远程 URL 摄入元数据索引。 | | `list` | 过滤并打印仓库舰队。 | | `show` | 打印单个仓库的完整元数据。 | | `tag` | 在仓库上添加或移除标签。 | | `note` | 添加带时间戳的备注。 | | `triage` | 交互式遍历新添加的仓库并分类。 | | `refresh` | 获取上游元数据。由 [docs/upstream-probes.md](docs/upstream-probes.md) 管控安全策略。 | | `digest` | 周更变更集报告（零网络）。 | | `dashboard` | 渲染静态 HTML 舰队健康报告。 | | `vault` | Obsidian 笔记本桥接（`export` / `sync`）。详见 [docs/vault.md](docs/vault.md)。 | | `export` / `import` | 用于跨机器迁移或备份的可移植 JSON 包。详见 [docs/bundle-schema.md](docs/bundle-schema.md)。 | | `update` | 自更新。自动检测源码 / pipx / pip 安装。 | | `doctor` | 索引完整性检查；`--fix` 自动修复安全问题。 | | `attack` | MITRE ATT&CK 技术查找 + 标签辅助。 | | `completion` | Shell Tab 补全配置。 | | `rm` | 从索引中移除仓库（可选 `--purge` 删除克隆）。 | 每个动词均有 `--help`。所有列出或返回结果的动词均支持 `--json`。 ### 关键标志 - `nostos pull` | 标志 | 默认值 | 描述 | | --- | --- | --- | | `path` | cwd | 要扫描的根目录。 | | `--from-index` | 关闭 | 拉取元数据索引中注册的所有仓库。 | | `--dry-run` | 关闭 | 列出发现的仓库但不拉取。 | | `--fetch-only` | 关闭 | 仅从远程获取；不合并或变基。 | | `--tags` | 关闭 | 同时获取所有 Git 标签。 | | `--rebase` | 关闭 | 使用 `git pull --rebase`。 | | `--depth N` | 5 | 目录扫描深度限制。 | | `--workers N` | 8 | 并发工作线程数。 | | `--timeout N` | 120 | Git 操作超时秒数。 | | `--exclude PATTERN...` | - | 排除匹配目录名的 Glob 模式。 | | `--json` | 关闭 | 机器可读输出。 | | `-q`, `--quiet` | 关闭 | 仅打印摘要，抑制进度。 | 每个被拉取的仓库都会自动在元数据索引中注册并更新 `last_touched_at`。 ### 示例 ``` # 每日批量拉取 nostos ~/projects # CI友好：静默、JSON、仅获取 nostos --fetch-only --quiet --json | jq '.counts' # 摄入 + 分类 nostos add https://github.com/org/tool.git --tag recon --source "blog:orange.tw" nostos triage # 查找90天未使用的C2工具 nostos list --tag c2 --untouched-over 90 # 便携备份 nostos export --out fleet.json nostos import fleet.json --clone-dir ~/repos # on another machine ``` ## 配置 可选的 INI 配置文件位于 `~/.nostosrc`。CLI 标志始终覆盖文件中的值。 ``` [defaults] depth = 5 workers = 8 timeout = 120 max_log_files = 20 rebase = false clone_dir = /home/user/repos [exclude] patterns = archived-*, .backup-*, vendor-* ``` ### 环境变量 | 变量 | 作用 | | --- | --- | | `NO_COLOR` | 设置为非空值时禁用 ANSI 颜色。 | | `NOSTOS_SHELL` | 覆盖 `$SHELL` 以检测 `nostos completion` 的目标 Shell（接受 `bash` / `zsh` / `fish`）。 | | `GITHUB_TOKEN` 等 | 在 `~/.config/nostos/auth.toml` 中通过 `token_env = "..."` 引用，用于上游探测。 | 优先级从高到低：**CLI 标志** -> **`~/.nostosrc`** -> **内置默认值**。 ## 核心概念 ### 元数据索引 SQLite 位于 `$XDG_DATA_HOME/nostos/index.db`（默认 `~/.local/share/nostos/index.db`，权限 `0600`，WAL 模式，`secure_delete=ON`）。每行对应一个仓库，以及标签、定时备注、来源和分级状态。每个动词都读写该文件；批量 `pull` 会自动注册其触及的每个仓库。 | 列 | 描述 | | --- | --- | | `path` | 绝对路径（经 `realpath` 规范化）。唯一。 | | `remote_url` | `origin` 远程（HTTPS 凭证已剥离）。 | | `source` | 自由文本来源（`"blog:..."`、`"auto-discovered"`、`"legacy-watchlist"`）。 | | `status` | `new`、`reviewed`、`in-use`、`dropped`、`flagged`。 | | `quiet` | 安全标志：永不探测该仓库的上游。 | | `added_at` / `last_touched_at` | ISO-8601 UTC 时间戳。 | | tags / notes | 多对多标签；附加型带时间戳的备注。 | 出于静态保密，建议将 `$XDG_DATA_HOME/nostos/` 放置在磁盘加密卷（LUKS / FileVault / BitLocker）上。nostos 默认不内置数据库加密。 ### 上游探测 `nostos refresh` 会为每个仓库缓存上游健康信息（已归档、星标、最后推送、发布、许可证），由 `~/.config/nostos/auth.toml` 管控。未配置的宿主不会被联系。安全失败不变量详见 [docs/upstream-probes.md](docs/upstream-probes.md)。 ### 可移植包 `nostos export` / `nostos import` 将元数据索引序列化为带模式版本的 JSON 包。导入时会针对本地文件系统解析每个条目（精确匹配、`$HOME` 相对匹配、`--remap`），并克隆尚不存在于本地的远程仓库。完整模式与算法见 [docs/bundle-schema.md](docs/bundle-schema.md)。 ### Obsidian 笔记本 `nostos vault export` 将索引转换为每个仓库一个 Markdown 文件（带 YAML 前置事项）。`nostos vault sync` 将操作者对 `status` / `tags` 的编辑同步回数据库。详细信息和 Dataview 查询见 [docs/vault.md](docs/vault.md)。 ## 输出 ### 人类可读 ``` [1/9] updated: /home/user/projects/repo-a [2/9] up-to-date: /home/user/projects/repo-d [3/9] skipped: /home/user/projects/repo-e --- Summary --- Updated (3): ... Skipped (1): /home/user/projects/repo-e - dirty working tree Total: 9 | Updated: 3 | Up-to-date: 5 | Skipped: 1 | Failed: 0 ``` ### JSON ``` nostos --json | jq '.counts' ``` 进度行输出到 `stderr`；`--json` 输出到 `stdout` 以保持管道清洁。 ## CI / 自动化 | 退出码 | 含义 | | --- | --- | | `0` | 所有发现的仓库已更新或已是最新。 | | `1` | 至少一个仓库更新失败。 | 跳过的仓库（脏、分离、无上游）**不会**导致运行失败；它们会在摘要中显示供审查。 ``` # GitHub Actions - name: Refresh vendored clones run: | nostos ./vendor --quiet --json > /tmp/nostos.json jq '.counts' /tmp/nostos.json ``` ``` # crontab */30 * * * * /usr/local/bin/nostos ~/projects --quiet --fetch-only ``` ## 日志 每次运行会在 `./logs/`（相对于安装根目录）写入带时间戳的日志文件，例如 `2026-04-17_14-30-00.log`。最多保留最近的 20 个（可通过 `max_log_files` 配置）。文件权限为 `0600`。形如 `https://user:token@host/` 的 HTTPS 凭证在写入前会被脱敏为 `https://***@host/`。 ## 安全 nostos 将对不受信工作目录上的 Git 操作视为攻击面，并将元数据索引视为情报资产。纵深防御应用于这两层。 | 控制项 | 描述 | | --- | --- | | Git 版本检查 | 启动时对 Git < 2.45.1（CVE-2024-32002 / 32004 / 32465）发出警告。 | | 安全远程克隆 | `add ` 使用 `--no-checkout` 克隆并禁用钩子（通过 `GIT_CONFIG_*`）。 | | 凭证脱敏 | HTTPS 凭证从所有日志和索引的 `remote_url` 字段中剥离。 | | 文件权限 | 日志与索引数据库权限为 `0600`；配置与数据目录权限为 `0700`（Unix）。 | | 所有权检查 | `~/.nostosrc`、`auth.toml` 和旧版观察列表若非当前用户拥有或全局可写将被拒绝。 | | 仓库所有权 | Unix 上跳过非当前用户拥有的仓库。 | | 符号链接保护 | 若 `logs/` 是符号链接则拒绝。 | | 无 Shell 注入 | 所有子进程调用均使用列表参数；从不使用 `shell=True`。 | | 索引加固 | SQLite `journal_mode=WAL`、`secure_delete=ON`、`foreign_keys=ON`；删除行在磁盘上覆写。 | | 探测安全关闭 | 上游探测仅联系 `auth.toml` 中列出的主机；`--offline` 强制禁用网络层。 | | 每仓库静默标志 | `add --quiet-upstream` 使仓库无法被上游探测；探测层永不查询或记录此类仓库。 | | 令牌卫生 | 令牌默认从环境变量读取，以 `Authorization: Bearer` 发送，并在所有日志与错误路径中脱敏。 | 通过 [GitHub security advisory](https://github.com/prodrom3/nostos/security/advisories/new) 私下报告安全问题。完整披露流程见 [SECURITY.md](SECURITY.md)。 ## 兼容性 | OS | Python 3.10 | 3.11 | 3.12 | 3.13 | | --- | :---: | :---: | :---: | :---: | | Ubuntu（最新） | ✓ | ✓ | ✓ | ✓ | | macOS（最新） | ✓ | ✓ | ✓ | ✓ | | Windows（最新） | ✓ | ✓ | ✓ | ✓ | CI 在每次推送和拉取请求中都会遍历该矩阵的每个单元格。 ## 架构 详见 [docs/architecture.md](docs/architecture.md) 了解模块布局、依赖关系图以及运行 / 摄入 / 导入流程（`pull`、`add` -> `triage`、`import`）。 ## 版本与支持 nostos 遵循 [语义化版本](https://semver.org/) 2.0。重大变更仅出现在新主版本中，并在 [CHANGELOG.md](CHANGELOG.md) 和对应的 GitHub 发布说明中说明。 - **稳定**：CLI 标志、退出码、JSON 输出模式、可移植包模式（读取器接受 `READABLE_SCHEMAS` 中的所有版本）。 - **内部**：`core/` Python API 不是公开的稳定 API；导入请自担风险。 当前版本：请查看 [`VERSION`](./VERSION) 和 `nostos --version`。 响应预期（尽力而为、非商业用途）：请参考 [MAINTAINERS.md](MAINTAINERS.md)。 ## 项目文档 | 文件 | 用途 | | --- | --- | | [CHANGELOG.md](CHANGELOG.md) | 每个版本的变更日志（镜像 GitHub 发布）。 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发设置、测试 / 校验 / mypy 工作流、PR 风格。 | | [MAINTAINERS.md](MAINTAINERS.md) | 主要维护者、升级路径、发布权限。 | | [SECURITY.md](SECURITY.md) | 私下披露流程。 | | [LICENSE](LICENSE) | MIT 许可证。 | 深度文档位于 [`docs/`](docs/)： | 文件 | 主题 | | --- | --- | | [docs/architecture.md](docs/architecture.md) | 模块布局、依赖关系图、运行 / 摄入 / 导入流程。 | | [docs/upstream-probes.md](docs/upstream-probes.md) | 上游探测认证、命令、安全不变性。 | | [docs/bundle-schema.md](docs/bundle-schema.md) | 可移植包格式 v2 与导入解析算法。 | | [docs/vault.md](docs/vault.md) | Obsidian 笔记本桥接及双向同步细节。 | ## 许可证 根据 [MIT 许可证](./LICENSE) 发布。作者为 [prodrom3](https://github.com/prodrom3)，维护者为 **radamic** 组织。

标签：Gitea, GitLab, Git仓库管理, Obsidian, Python, SOC Prime, SQLite, 上游探测, 二进制发布, 仓库同步, 健康检查, 元数据索引, 周报, 失败关闭, 定时任务, 平台兼容, 并发更新, 开发工具, 开源工具, 批量操作, 无后门, 版本管理, 状态追踪, 网络安全研究, 网络调试, 自动化, 软件分发, 逆向工具, 零依赖