JSONbored/nightward

# Nightward [](https://github.com/JSONbored/nightward/actions/workflows/ci.yml) [](https://github.com/JSONbored/nightward/actions/workflows/nightward-policy.yml) [](https://github.com/JSONbored/nightward/actions/workflows/scorecard.yml) [](https://www.bestpractices.dev/projects/12713) [](LICENSE) Nightward 能在你同步之前发现 AI 工具的风险：MCP 风险、仅限本地的状态、密钥泄露以及可审查的修复计划，所有操作均在本地完成。 它会扫描常见的 Codex、Claude、Cursor、Windsurf、VS Code、Raycast、JetBrains、Zed、Continue、Cline/Roo、Aider、OpenCode、Goose、LM Studio、Ollama/Open WebUI、Neovim、MCP 配置位置，以及仓库/工作区 AI 配置；将内容分为可迁移、仅限本地或密钥类别；高亮 MCP 安全发现；并生成脱敏的分析信号、修复计划、SARIF 策略输出、快照计划和 dry-run 备份计划。 公开文档和固定数据的 TUI 演示位于 。 Nightward 默认为只读模式，但它可以运行明确的、需确认的本地操作，例如 provider 安装、provider 启用/禁用、计划扫描的安装/移除、可迁移配置快照、策略忽略以及 Nightward 拥有的报告/缓存清理。 ## TUI 预览 [](site/guide/tui.md) README 使用了 GIF，以便在 GitHub 上直接渲染预览。文档主页使用了更轻量的 [WebM 循环](site/public/demo/tui/nightward-opentui.webm)，而 [TUI 指南](site/guide/tui.md)保留了完整的七屏图库。 ## 概览 | 界面 | 功能 | 默认写入行为 | | --- | --- | --- | | TUI | 仪表板、清单、发现、分析、修复计划、备份预览、操作队列 | 在确认的操作执行前保持只读 | | CLI | 可脚本化的扫描、检查、策略、SARIF、快照、计划、备份和操作命令 | 除非请求了明确的输出/导出路径或 `--confirm` 操作，否则保持只读 | | MCP server | 用于 AI 客户端的 Stdio 工具/资源/提示 | 只读；可以列出/预览操作，但写入操作必须在 CLI/TUI/Raycast 中执行 | | Raycast | macOS 配套命令以及已确认的 Nightward Actions | 剪贴板/报告文件夹操作以及需确认的写入操作 | | GitHub Action | 工作区策略和 SARIF 检查 | 仅写入请求的 CI 输出 | | Trunk plugin | 本地工作区策略/分析 linter | 向标准输出 SARIF | ## 示例输出 以下示例是根据提交的固定主目录 [testdata/homes/policy](testdata/homes/policy) 生成的。主机名、HOME 目录、本地路径、时间戳和看似密钥的固定数据在 JSON、报告或截图提交前均已进行脱敏处理。  - [脱敏样本扫描 JSON](site/public/demo/nightward-sample-scan.json) - [静态 HTML 报告](site/public/demo/nightward-sample-report.html) - [OpenTUI 画廊](site/guide/tui.md)、[演示 GIF](site/public/demo/nightward-opentui.gif) 和 [主页 WebM 循环](site/public/demo/tui/nightward-opentui.webm) - 使用 Chrome、Chromium、Brave 或设置 `NIGHTWARD_CHROME=/path/to/browser`，通过 `make demo-assets` 重新生成 JSON、HTML 报告和报告截图。使用 `make tui-media` 重新生成仅包含固定数据的 TUI 媒体，并在提交前审查每一帧画面。 ``` flowchart LR configs["AI agent/devtool config"] --> scan["nw scan"] scan --> classify["classify paths"] scan --> mcp["review MCP trust boundaries"] classify --> tui["TUI"] classify --> json["redacted JSON"] mcp --> findings["findings + analysis signals"] findings --> fix["fix exports + action queue"] findings --> sarif["policy SARIF"] classify --> backup["backup plan + confirmed snapshot"] ``` ## 为什么需要 AI 编码工具将有用的状态分散在配置文件、MCP server 定义、技能、规则、命令、扩展设置、凭据、缓存和应用专属数据库中。盲目地同步所有这些内容既脆弱又不安全。 Nightward 首先回答了以下实际问题： - 这台机器上存在什么？ - 哪些内容足以放入私有的 dotfiles 仓库进行迁移？ - 哪些是机器本地的、应用专属的、运行时缓存或凭据材料？ - 哪些 MCP 配置需要进行安全审查？ - 在同步之前，我应该考虑哪些具体的修复计划？ - 备份计划在写入任何内容之前会包含、审查或排除哪些内容？ ## 亮点 - 由 OpenTUI 驱动的交互式应用，包含仪表板、发现、分析、修复计划、清单、备份预览、操作队列和帮助部分。 - `nightward` 规范命令以及 `nw` 短别名。 - 用于自动化和 CI 的脱敏 JSON。 - 针对本地机器的 HOME 扫描，以及针对 CI、Trunk 和 dotfiles 仓库的 `--workspace` 扫描。 - MCP 发现，包括未固定包的执行、包名冒充风险、远程包来源、shell 包装器、Docker/socket 暴露、敏感环境变量密钥、敏感请求头、本地/私有端点、广泛的文件系统访问权限、token 路径、过时配置、应用专属状态、解析失败以及未知的服务器形态。 - 针对供应链、密钥泄露、文件系统范围、网络暴露、执行风险、机器本地和应用专属状态审查的离线分析信号。 - 可选的 provider 框架，支持 Gitleaks、TruffleHog、Semgrep、Trivy、OSV-Scanner、Grype、Syft、OpenSSF Scorecard 和 Socket；provider 的安装和支持联网的执行仍需经过确认/选择加入把关。 - 扫描摘要将清单桶与发现桶分开：项的分类/风险/工具计数与发现的严重程度/规则/工具计数是区分开的。 - 修复元数据：修复类型、置信度、风险、审查要求、影响、步骤以及有边界的操作规范（Nightward 可以在这些规范中安全地预览写入）。 - 用于 GitHub 代码扫描的 SARIF 输出。 - 可从固定的发布标签导入的 Trunk 插件定义，用于 `nightward-policy` 和 `nightward-analyze`。 - 带有需填写原因的忽略功能的可选 `.nightward.yml` 策略配置。 - 针对可解析的 MCP 配置发现的、仅限计划的脱敏修复导出。 - 只读快照计划以及已确认的可迁移配置快照创建。 - 用于扫描、策略和 SARIF 模式的可复用 GitHub Action。 - 用于仪表板、发现、分析、Provider 检查、Nightward Actions、解释发现/信号、修复计划/分析导出和报告文件夹访问的 Raycast 扩展。 - 用于需要本地扫描、分析、发现、规则、provider、策略、报告、提示、修复计划和有边界操作上下文的 AI 客户端的 Stdio MCP server。 - 针对 macOS launchd 和 Linux systemd 用户定时器的用户级每日夜间扫描计划。 - 无遥测，无云仪表板，Nightward runtime 默认无网络调用。 - 面向 OpenSSF 的项目规范：DCO、治理文档、威胁模型、覆盖率门槛、固定的 CI actions、发布快照检查、已签名的发布配置和安全报告策略。 ## 安装 请尝试带有发布版本控制的 npm 启动器： ``` npx @jsonbored/nightward scan npm install -g @jsonbored/nightward nw ``` 这会安装一个 Nightward CLI 发行版，包含两个命令名： - `nightward`：规范的项目命令 - `nw`：适用于频繁终端/TUI 使用的短别名 若要从此检出版本进行本地开发： ``` make install-local ``` npm 包专门设计为 GitHub Release 二进制文件的轻量级启动器。它不会运行 `postinstall` 脚本；在首次执行时，它会下载匹配的发布归档文件，从 `checksums.txt` 验证归档的 SHA-256，在解压前拒绝不安全的归档条目，在本地缓存二进制文件，然后运行 `nightward` 或 `nw`。严格的环境可以设置 `NIGHTWARD_NPM_REQUIRE_SIGSTORE=1`，以要求在信任校验和文件之前对 `checksums.txt.sigstore.json` 进行 Cosign 验证。 ## 快速开始 打开 TUI： ``` nw ``` 在同一个 TUI 中查看已保存的扫描： ``` nw tui --input scan.json ``` 扫描本地 HOME 状态并输出脱敏 JSON： ``` nw scan --json ``` 改为扫描仓库/工作区而不是 HOME： ``` nw scan --workspace . --json ``` 检查本地预设： ``` nw doctor --json ``` 在接受具有写入能力的操作之前，接受 Beta 责任披露： ``` nw disclosure accept ``` 列出并解释发现： ``` nw findings list nw findings explain mcp_unpinned_package-abc123 ``` 生成仅限计划的修复报告： ``` nw fix plan --json nw fix plan --rule mcp_secret_env nw fix export --format markdown ``` 运行离线分析和 provider 检查： ``` nw analyze --json nw analyze --workspace . --json nw analyze package npm:@modelcontextprotocol/server-filesystem --json nw analyze finding mcp_unpinned_package-abc123 --json nw providers list --json nw providers doctor --with syft,gitleaks --json nw rules list --json nw rules explain mcp_secret_header --json ``` 支持联网的 provider 在被明确允许之前将保持阻止状态： ``` nw providers doctor --with trivy,grype,scorecard,socket --online --json nw analyze --workspace . --with trivy,osv-scanner,grype,scorecard,socket --online --json ``` 创建或解释策略配置： ``` nw policy init nw policy explain nw policy check --config .nightward.yml --strict --json nw actions apply policy.ignore --finding mcp_server_review-abc123 --reason "reviewed locally" --confirm ``` 生成 dry-run 备份计划： ``` nw plan backup ``` 生成只读快照计划： ``` nw snapshot plan --output ~/nightward-snapshots --json ``` 从脱敏扫描 JSON 渲染本地静态 HTML 报告： ``` nw scan --json --output /tmp/nightward-scan.json nw report html --input /tmp/nightward-scan.json --output /tmp/nightward-report.html nw report diff --from /tmp/previous-scan.json --to /tmp/nightward-scan.json nw report html --from /tmp/previous-scan.json --to /tmp/nightward-scan.json --output /tmp/nightward-report.html nw tui --from /tmp/previous-scan.json --to /tmp/nightward-scan.json nw report html nw report history nw report latest ``` 运行策略检查或生成 SARIF： ``` nw policy check --strict --json nw policy sarif --output nightward.sarif nw policy check --workspace . --include-analysis --strict --json nw policy sarif --workspace . --include-analysis --output - nw policy badge --workspace . --include-analysis --sarif-url https://example.invalid/nightward.sarif --output nightward-badge.json ``` 将 Nightward 暴露给支持 MCP 的 AI 客户端： ``` nw mcp serve ``` 预览计划的夜间扫描： ``` nw schedule plan --preset nightly nw schedule install --preset nightly --dry-run nw schedule remove --dry-run ``` ## 分类模型 Nightward 将发现的状态分类为： - `portable`：审查后通常可以安全同步 - `machine-local`：绑定到本地路径、身份或机器预设 - `secret-auth`：凭据或认证材料；默认排除 - `runtime-cache`：生成的运行时数据；默认排除 - `app-owned`：由其他应用拥有的数据库、扩展二进制文件、加密的应用状态或缓存 - `unknown`：Nightward 无法自信分类的已发现状态 备份计划包含可迁移项，将仅限本地/未知的项标记为待审查，并在默认情况下排除密钥/认证、运行时缓存和应用专属状态。 ``` flowchart TD found["Discovered path"] --> bucket{"Classification"} bucket -->|portable| include["include in private backup plan"] bucket -->|machine-local or unknown| review["review before syncing"] bucket -->|secret-auth| excludeSecret["exclude by default"] bucket -->|runtime-cache| excludeCache["exclude by default"] bucket -->|app-owned| export["prefer app-supported export"] ``` ## 修复计划模型 Nightward 将审查指导与可应用的操作分离开来。修复计划仍然是高风险 MCP 编辑的结构化审查材料，而共享操作层可以在 Nightward 知道确切写入范围时应用有边界的本地操作： - `pin-package`：当包名可解析时，固定 `npx`、`uvx` 或 `pipx` 包执行 - `externalize-secret`：将内联的密钥值移出 agent 配置，只保留环境变量密钥名或设置文档 - `replace-shell-wrapper`：用直接的可执行文件调用替换简单的 shell 传递 - `narrow-filesystem`：在人工审查后用显式路径替换广泛的文件系统访问 - `manual-review`：手动检查不受支持的、模棱两可的或高风险的配置 - `ignore-with-reason`：仅在记录了为何预期出现该情况的原因后，保留建议性的发现 密钥值永远不会在扫描 JSON、发现输出、修复计划 JSON、Markdown 导出、SARIF 或 TUI 详细文本中发出。已确认的操作会在 Nightward 本地状态下写入审计事件。 `scan --json` 仍处于 1.0 版本之前，可能会进行破坏性的结构改进。当前的摘要 schema 使用了显式键，例如 `items_by_classification`、`items_by_risk`、`findings_by_severity` 和 `findings_by_rule`，这样项的风险就不会与发现的严重程度混淆。 ## 分析模型 `nw analyze` 将扫描发现和分类转换为可解释的信号。它并不声称某个包、服务器、二进制文件或 URL 是安全的。它报告的是 Nightward 从本地结构中能够证明的内容、其重要性以及信号的置信度。 默认分析是离线且内置的。可选 provider 由 `providers doctor` 发现；除非用户明确选择 provider 并选择加入支持联网的行为，否则 Nightward 不会调用在线服务。CLI/TUI/Raycast 操作层可以在确认后安装已知的 provider CLI。MCP 可以列出和预览这些操作，但不能应用本地写入。显式的本地 provider 是 `gitleaks`、`trufflehog`、`semgrep` 和 `syft`。支持联网的 provider 是 `trivy`、`osv-scanner`、`grype`、`scorecard` 和 `socket`，它们需要明确的在线 provider 选择加入。Socket 支持根据依赖清单元数据创建远程 Socket 扫描工件；Nightward 在 v1 中不会获取或规范化远程 Socket 报告。 Provider 运行使用显式的跳过/阻止/就绪状态、超时、有边界的输出捕获，并且仅包含脱敏的元数据。过大的 provider 标准输出作为 provider 警告直接失败，而不是被部分解析。Semgrep 执行需要一个 repo 本地配置文件，因此 Nightward 默认不使用自动规则发现。 策略配置可以通过 `include_analysis`、`analysis_threshold`、`analysis_providers` 和 `allow_online_providers` 启用分析和选定的 provider 执行；支持联网的 provider 仍需明确的策略选择加入。 ``` sequenceDiagram participant User participant Nightward participant LocalTool as Optional local provider User->>Nightward: nw analyze Nightward-->>User: offline built-in signals User->>Nightward: nw analyze --workspace . --with gitleaks Nightward->>LocalTool: run only after explicit provider selection LocalTool-->>Nightward: provider signals Nightward-->>User: redacted analysis report ``` ## TUI 默认的 `nightward` / `nw` 命令会打开 TUI： - 仪表板：扫描计数和计划状态 - 清单：按工具、分类和风险划分的已发现路径 - 发现：具有所选发现详情面板的严重程度/工具/规则过滤器 - 分析：离线风险信号和 provider 警告摘要 - 修复计划：安全/审查/阻止的修复组 - 备份计划：私有 dotfiles dry-run 预览 - 操作：需确认的 provider、策略、计划、备份、清理和设置操作 TUI 现在是 Rust CLI 二进制文件的一部分，并直接使用 `opentui_rust` 来实现彩色仪表板、填充面板、严重程度丝带和基于固定数据的截图。发布归档和通过 npm 下载的二进制文件只需要 `nightward` 和 `nw`。 键盘快捷键： - `1`-`8`：切换部分 - 方向键或 `h`/`j`/`k`/`l`：导航 - `enter`：在操作视图中确认所选操作 - `/`：搜索发现 - `s`：切换严重程度 - `x`：清除过滤器 - `q` 或 `esc`：退出 仅限固定数据的 OpenTUI 演示：[TUI 画廊](site/guide/tui.md)、[仪表板 PNG](site/public/demo/tui/overview.png)、[演示 GIF](site/public/demo/nightward-opentui.gif) 和 [主页 WebM 循环](site/public/demo/tui/nightward-opentui.webm)。 ## MCP Server Nightward 可以将本地上下文和有边界的 Nightward 操作工作流暴露给支持 MCP 的 AI 客户端： ``` { "mcpServers": { "nightward": { "command": "nw", "args": ["mcp", "serve"] } } } ``` 该服务器支持扫描、检查、发现、发现/信号解释、分析、修复计划、策略检查、报告历史/差异、操作列表/预览、规则、provider、资源和提示。它只使用 stdio，不打开网络监听器，并且不能重写任意的 MCP 或 agent 配置。MCP 客户端不能应用本地写入，因为工具调用参数不是带外的本地确认通道；请使用 CLI、TUI 或 Raycast 扩展来应用预览的操作。 ## GitHub Action Nightward 可以作为本地 GitHub Action 以扫描、策略或 SARIF 模式运行： ``` - uses: JSONbored/nightward@v0.1.4 with: mode: sarif output: nightward.sarif ``` 有关输入、输出和 SARIF 上传示例，请参见 [docs/action.md](docs/action.md)。 ## 网站 Nightward 的公开文档/营销网站位于 [site](site)，并使用带有本地搜索功能的 VitePress。它被设计为一个仓库专属的静态网站，默认不包含分析功能；部署后的公开网站可以通过构建时的环境变量选择加入自托管的 Umami。 ``` cd site npm ci npm run build ``` 有关页面映射、自定义域说明、分析边界和 Stitch 登录页简介，请参见 [docs/website.md](docs/website.md)。 ## Trunk 插件 Nightward 包含一个用于 Trunk Check 的仓库内 `plugin.yaml`。导入固定的发布标签并启用仓库/工作区策略扫描： ``` trunk plugins add --id nightward https://github.com/JSONbored/nightward v0.1.4 trunk check enable nightward-policy ``` `nightward-policy` 通过 `nw policy sarif --workspace ${workspace} --output -` 输出 SARIF。`nightward-analyze` 通过 `--include-analysis` 添加离线分析信号。 ## Raycast 扩展 只读的 Raycast 扩展位于 [integrations/raycast](integrations/raycast)。 ``` cd integrations/raycast npm ci npm run build npm run dev ``` 命令： - `Nightward Dashboard` - `Nightward Status` - `Nightward Findings` - `Nightward Analysis` - `Nightward Provider Doctor` - `Nightward Actions` - `Explain Nightward Finding` - `Explain Nightward Signal` - `Export Nightward Fix Plan` - `Export Nightward Analysis` - `Open Nightward Reports` 该扩展通过 shell 调用 `nw` 或 `nightward`，渲染脱敏的输出，复制明确请求的导出内容，并打开本地报告文件夹。Provider Doctor 可以为 Raycast Analysis 启用/禁用 provider 选择，并且只能通过共享操作注册表预览/应用已知的 provider 安装。`Nightward Actions` 使用与 CLI/TUI 相同的注册表来执行已确认的 provider、策略、计划、备份、清理和披露操作。 有关首选项、验证和只读边界，请参见 [docs/raycast-extension.md](docs/raycast-extension.md)。 ## 调度 `nightly` 预设运行： ``` nightward scan --json ``` 用户级别的调度目标： - macOS：`launchd` 用户代理 - Linux：systemd 用户定时器 调度操作仅安装用户级别的作业。它们从不安装 root 守护进程、复制密钥、修改 dotfiles、恢复文件或推送到 Git。 ## 开发 ``` make test make test-junit make coverage-check make fuzz-check make trunk-flaky-validate make trunk-check make ci-scripts-test make raycast-verify make npm-package-verify make release-snapshot make verify cargo run --bin nightward -- --help cargo run --bin nw -- scan --json cargo run --bin nw -- scan --workspace . --json cargo run --bin nw -- scan --json | jq '.summary' cargo run --bin nw -- findings list --json cargo run --bin nw -- findings list --json | jq '[.[] | select(.rule=="mcp_server_review")]' cargo run --bin nw -- analyze --all --json cargo run --bin nw -- providers doctor --json cargo run --bin nw -- rules list --json cargo run --bin nw -- fix plan --json cargo run --bin nw -- fix export --format markdown cargo run --bin nw -- policy sarif --output /tmp/nightward.sarif cargo run --bin nw -- policy sarif --workspace . --include-analysis --output - cargo run --bin nw -- schedule plan --json ``` 维护者使用的本地安全检查： ``` trunk check --show-existing --all make gitleaks make cargo-audit make cargo-deny make coverage-check make fuzz-check make release-snapshot ``` ## 项目文档 - [安全策略](SECURITY.md) - [治理](GOVERNANCE.md) - [维护者](MAINTAINERS.md) - [贡献指南](CONTRIBUTING.md) - [贡献测试夹具](docs/contributing-fixtures.md) - [行为准则](CODE_OF_CONDUCT.md) - [支持](SUPPORT.md) - [路线图](ROADMAP.md) - [安装和发布渠道](docs/install.md) - [分发计划](docs/distribution.md) - [网站和文档计划](docs/website.md) - [增长待办事项](docs/growth.md) - [适配器](docs/adapters.md) - [分析](docs/analysis.md) - [修复](docs/remediation.md) - [测试](docs/testing.md) - [依赖维护](docs/dependency-maintenance.md) - [GitHub Action](docs/action.md) - [MCP 服务器](docs/mcp-server.md) - [Raycast 扩展](docs/raycast-extension.md) - [CI/安全说明](docs/ci-security.md) - [发布流程](docs/release.md) - [威胁模型](docs/threat-model.md) - [OpenSSF 证据](docs/openssf-best-practices.md) - [隐私模型](docs/privacy-model.md) - [截图/GIF 捕获计划](docs/screenshots.md) ## 贡献者 [](https://github.com/JSONbored/nightward/graphs/contributors) ## Star 历史 [](https://www.star-history.com/#JSONbored/nightward&Date) ## 许可证 MIT

标签：AI代理审计, AI安全, Chat Copilot, CISA项目, Claude配置, Codex工具, Cursor编辑器, IDE插件, JetBrains安全, LLM工具安全, MCP配置, MITM代理, MIT许可, Neovim安全, Raycast扩展, SARIF, StruQ, TUI, VS Code安全, 代码安全, 修复计划, 只读扫描, 可视化界面, 威胁情报, 安全助手, 安全合规, 安全基线, 安全扫描, 开发者工具, 快照, 教学环境, 数据备份, 时序注入, 暗色界面, 本地优先, 本地状态检测, 漏洞枚举, 点文件管理, 知识库安全, 秘密暴露检测, 红队评估, 终端用户界面, 网络代理, 越权风险, 通知系统