人工智能AI AgentAI 应用交互助手桌面应用多智能体Agent 记忆工具调用【免费下载链接】OpenHanako可作为日常办公助手无需复杂配置即可让 AI 记住信息、操作电脑、搜索浏览、执行代码等。具备记忆系统、人格塑造、多 Agent 协作、安全沙盒等核心功能支持多平台接入和插件扩展。项目地址https://gitcode.com/liliMozi/OpenHanako点击查看免费下载本文以 SECURITY.md 为骨架结合 OpenHanako 仓库中的安全模块实现系统讲解该项目的漏洞报告流程、安全关注范围、本地凭证存储的权限契约owner-only 读写、每次启动都会执行的文件权限自愈机制以及迁移备份的 90 天保留策略。读完你不仅能理解这份安全文档的全部承诺还能掌握这些承诺在代码中是如何落地与验证的例如凭证文件写入、权限修复、跨平台差异等具体实现细节。1. 项目背景与安全文档定位OpenHanako 是一款可作为日常办公助手的 AI 桌面应用具备记忆系统、人格塑造、多 Agent 协作、安全沙盒等核心能力支持多平台接入和插件扩展。项目已更名为HanaAgent但出于过渡期兼容考虑仓库路径与安全报告 URL 仍保留在旧版openhanako名称上——这一点在安全文档开篇即有说明。该项目的安全文档承担了三类职责外部沟通明确漏洞发现者如何报告问题、响应时限边界声明界定哪些安全问题是项目关注范围Scope存储契约详细说明本地凭证Provider 密钥、OAuth Token、设备记录在数据目录中的存放方式、权限保证与已知边界。2. 漏洞报告流程Reporting a Vulnerability2.1 报告渠道安全文档给出的报告方式分为两个优先级首选在仓库 Security 标签页打开 Private vulnerability report私有漏洞报告路径为https://github.com/liliMozi/openhanako/security备选若私有报告不可用则在https://github.com/liliMozi/openhanako/issues提交 Issue。2.2 报告需要包含的信息为了让维护者能快速复现与评估报告应包含漏洞的描述Description of the vulnerability复现步骤Steps to reproduce潜在影响Potential impact。2.3 响应承诺维护者承诺在72 小时内响应并先与报告者协作修复再对外公开披露coordinated disclosure。这是一个典型的负责任的漏洞披露流程意味着漏洞细节在修复完成前不会被公开展示。3. 安全关注范围ScopeSECURITY.md 明确了四个重点关注的安全风险类型这些也是仓库中安全代码模块实际防范的对象风险类型英文原文仓库中的相关机制沙盒逃逸Sandbox escapePathGuard / Seatbelt bypasslib/sandbox/下的沙盒策略模块凭证泄露Credential leakagecore/credential-file-healer.ts、shared/secret-fs.ts等凭证保管模块远程代码执行Remote code execution执行边界与策略模块如 core/execution-boundary.ts、core/execution-router.tsElectron 渲染进程 XSSCross-site scripting in the Electron renderer桌面端 CSP 配置vite.csp-profiles.ts及配套的 csp-sync.test.ts从源码结构看这份 Scope 列表与仓库安全基础设施的划分一一对应属于“有实际防御实现支撑的边界声明”而非空泛的承诺。4. 本地凭证存储契约Local credential storage4.1 数据目录与存放位置Provider 密钥、OAuth Token 和设备记录均存放在数据目录中该目录由环境变量HANA_HOME指定默认值为~/.hanako即用户主目录下的.hanako隐藏目录。4.2 项目承诺的三项保证安全文档明确承诺以下三点每一项都有对应的源码实现保证一凭证文件仅所有者可读写数据目录仅所有者可访问。代码层面的落地位于 shared/secret-fs.ts其中定义了两个核心常量SECRET_FILE_MODE 0o600凭证文件所有者可读可写其他任何账户无任何权限SECRET_DIR_MODE 0o700凭证目录仅所有者可进入和列出。该模块特意将权限固化在函数内部而非作为参数传入原因在模块注释中说明得很清楚一个把 mode 作为可选参数的通用原子写函数每一个新调用点都可能是忘记传权限参数从而写出全机器可读凭证的隐患。这里权限不是参数调用方根本不可能写错静态扫描也能仅凭函数名区分凭证写入与普通写入。凭证写入统一走writeSecretFileSync(filePath, content)先清除可能残留的临时文件.tmp再以0o600创建临时文件并写入内容随后做一次 best-effort 的权限收紧tightenBestEffort最后原子rename到目标位置。之所以要先清残留临时文件是因为以 mode 创建文件对已存在的文件不生效——若一次崩溃留下了旧临时文件它会把旧权限带给下一个写入。从调用面来看writeSecretFileSync被 core/migrations.ts、core/provider-catalog.ts、core/device-registry.ts、core/local-user-account.ts、core/web-session-store.ts、core/plugin-config.ts、core/first-run.ts 等大量模块共用构成了整个数据目录的凭证写入统一入口。保证二每次启动都验证权限发生漂移时自动修复并记录日志。新写入文件带正确权限只能覆盖升级后写入的文件磁盘上已有的文件会保留其创建时的权限且永远不会被重写的文件会一直带着旧权限。因此每次启动都执行自愈而非只做一次性迁移——因为权限会在之后再次漂移恢复备份、跨机器拷贝数据目录、外部同步都会重新引入原始权限。实现位于 core/credential-file-healer.ts 的healCredentialFileModes({ hanakoHome, log })其工作范围包括数据目录本身收紧为0o700顶层凭证文件清单TOP_LEVEL_SECRET_FILES共 10 个provider-catalog.json、models.json、added-models.yaml、auth.json、device-credentials.json、devices.json、pairing-sessions.json、local-user-auth.json、users.json、web-sessions.json每个 Agent 目录下的config.yaml可能含 Provider 密钥以及迁移过程中产生的config.yaml.pre-scope-migration备份、config.yaml.tmp崩溃残留三个整树凭证目录SECRET_TREESmigration-backups迁移备份、本地 Provider 插件目录其定义文件携带 Provider 密钥、security目录签名密钥与授权记录插件数据目录中每个插件的config.yaml可能持有连接器与服务凭证但只修配置文件本身不动插件数据目录里属于其他 store 的下载文件、任务状态与产物会话清单迁移检查点checkpoints/session-manifest/内完整拷贝的 agents 目录。每次修复都会记录日志如[credential-custody] tightened 相对路径修复失败的文件会被归入failed列表并上报错误总线errorBus以credential-custody:路径去重但不会中断应用启动——因为部分文件系统可移动介质、网络挂载会直接拒绝 chmod若因此打断用户反而小题大做。保证三迁移产生的备份同样持有凭证副本超过 90 天即被清理且仅在存活目录可读且非空时清理。实现位于 core/credential-backup-retention.ts 的pruneStaleCredentialBackups({ hanakoHome, now, maxAgeMs, log })保留窗口常量CREDENTIAL_BACKUP_MAX_AGE_MS 90 * DAY_MS即 90 天删除不可逆必须同时满足两个条件备份超过保留窗口且当前provider-catalog.json可读、可解析、含非空 providers若存活目录缺失、无法解析或为空无论备份多旧都全部保留——这正是回滚存在的目的每个决定删除或保留都记录日志保证策略可审计而非静默执行健康检查刻意直接读取并解析目录文件而不是走 catalog store 的加载器——因为 store 的加载器在目录缺失时会回退触发旧文件迁移让一次提问产生改写状态的副作用对应测试 credential-backup-retention.test.ts 专门验证了缺失的目录必须保持缺失。4.3 自愈与保留在启动序列中的位置这两个启动步骤在 core/engine.ts 中以runBestEffortStartupMigrationStep形式顺序执行见 core/engine.ts先pruneStaleCredentialBackups步骤credential-backup-retention清理过期迁移备份再healCredentialFileModes步骤credential-custody收紧凭证权限。代码注释解释了放置顺序的用意放在所有数据迁移之后让本轮迁移刚写出的文件也被覆盖到。两个步骤互相独立任何一步出意外都不会连累另一步——清理和矫正解耦。另外值得注意的工程细节目录名全部从所属模块导入常量而非各处重复拼写。例如 core/security-dir.ts 是唯一命名security目录的地方core/migration-backups.ts 是唯一命名migration-backups的地方。模块注释记录了一次真实事故某列表手写了providers而 store 实际写的是provider-plugins导致自愈 pass 走过一条不存在的路径、静默地什么都没修。这个教训直接促成了目录名单一来源的约定。5. 保护的边界什么不是承诺SECURITY.md 诚实且具体地划出了权限保护的三个边界5.1 同用户程序不可防权限位决定的是哪些账户可以打开文件它无法限制以同一用户身份运行的程序——这类程序可以读取该用户能读取的一切。要收窄这一点需要由操作系统凭证存储如 macOS Keychain、Windows Credential Locker键控的加密而本项目目前没有做this project does not do today。5.2 Windows 平台不执行任何权限操作NTFS 不实现 POSIX 权限位平台文件 API 也无法表达它们因此应用在 Windows 上完全不执行权限工作secret-fs.ts中SUPPORTS_POSIX_MODE process.platform ! win32Windows 分支直接跳过 chmod。在 Windows 上真正保护数据的是数据目录从父目录继承的 ACL默认位置用户配置文件内已排除其他标准账户但通过HANA_HOME把数据目录放到别处时它继承的权限取决于目标位置的授权应用既不调整也不报告。因此文档给出的 Windows 建议是尽量让数据目录留在默认位置。5.3 凭证以明文存储凭证文件是明文存放的权限保护只是谁可以打开不提供内容加密。安全文档据此给出操作纪律不要把数据目录放进版本控制、共享盘或转发的压缩包里。6. 测试覆盖契约如何被验证这份安全契约不仅有文档与实现还有成体系的测试印证tests/credential-file-healer.test.tsPOSIX 平台运行验证了数据目录本身被收紧为0o70010 个顶层凭证文件全部收紧为0o600并进入healed列表每个 Agent 的config.yaml、scope 迁移备份config.yaml.pre-scope-migration、崩溃残留config.yaml.tmp含检查点内副本都被修复migration-backups目录树、本地 Provider 插件目录树、security目录树签名密钥resource-ticket-key、授权记录grants.json整体收紧插件数据目录只修配置文件、不动邻居文件负向断言同样构成契约已合规时保持静默healed为空、无日志缺失数据目录时抛错而非假装干净通过某个文件 chmod 失败时记入failed其余文件照常处理。tests/credential-backup-retention.test.ts 验证了超过 90 天且存活目录健康时删除备份窗口内如 89 天保留理由为within-retention-window存活目录缺失/无法解析/无 providers 时无条件保留所有备份live-catalog-unusable健康检查不会触发目录重建保留窗口常量恰好等于 90 天。这些测试直接对应 SECURITY.md 中每次启动验证并在漂移时恢复、每次修正都记录日志、备份 90 天后清理且仅当回滚目标健康时清理的每一句承诺属于可执行的契约定义。7. 实操要点速查将本文内容沉淀为可直接照做的检查清单数据目录位置确认HANA_HOME指向可信的本地路径默认~/.hanako即可不要为了省事把它放到共享盘或网盘同步目录。Windows 用户保持数据目录在默认位置不要通过HANA_HOME挪到权限不受控的目录不要期待应用会帮你收紧权限。权限巡检在 Linux/macOS 下可以自行抽查——ls -l ~/.hanako应为drwx------0o700其中的auth.json、provider-catalog.json等应为-rw-------0o600。若发现漂移重启应用即可触发自愈并产生[credential-custody] tightened ...日志。备份纪律迁移备份最多保留 90 天且存活目录健康时才会清理涉及回滚时不要手动删除migration-backups。明文凭证意识任何情况下都不要把数据目录纳入版本控制、打包或传输同用户下的其他程序仍可读取这些明文文件。漏洞报告遵循私有报告优先的流程报告需包含描述、复现步骤与潜在影响响应承诺为 72 小时内。8. 总结SECURITY.md 是一份承诺 边界双轨并行的安全文档它既给出了外部可依赖的漏洞报告流程与响应时限又用精确的语言划定了本地凭证保护的保证范围与三个明确边界同用户程序、Windows ACL 继承、明文存储。而仓库源码把每一句承诺都落成了可执行、可测试的模块——统一入口的 owner-only 写入secret-fs.ts、每次启动幂等的权限自愈credential-file-healer.ts、90 天可审计的备份保留credential-backup-retention.ts并由 credential-file-healer.test.ts 与 credential-backup-retention.test.ts 固化为契约。理解这份文档等于同时理解了该应用在本地凭证安全上做了什么、不做什么、以及为什么。赞分享人工智能AI AgentAI 应用交互助手桌面应用多智能体Agent 记忆工具调用【免费下载链接】OpenHanako可作为日常办公助手无需复杂配置即可让 AI 记住信息、操作电脑、搜索浏览、执行代码等。具备记忆系统、人格塑造、多 Agent 协作、安全沙盒等核心功能支持多平台接入和插件扩展。项目地址https://gitcode.com/liliMozi/OpenHanako点击查看免费下载相关推荐Craft Agents 安全机制解析从漏洞报告策略到凭证加密存储与传输鉴权的源码级实现Craft Agents 安全机制解析从漏洞报告策略到凭证加密存储与传输鉴权的源码级实现 本文基于 Craft Agentscraft agents oss人工智能大模型AI AgentMCP Clients工具调用交互助手Open WebUI 安全策略深度解读漏洞报告规则、CVE 协调机制与默认安全权限设计Open WebUI 安全策略深度解读漏洞报告规则、CVE 协调机制与默认安全权限设计 Open WebUI 的安全策略 docs/SECURITY.md人工智能大模型AI 应用RAGAI Agent本地部署交互助手后端前端Taro 安全策略全解读受支持版本、漏洞报告渠道与响应机制Taro 安全策略全解读受支持版本、漏洞报告渠道与响应机制 本篇指南基于 Taro 开源仓库根目录下的 SECURITY.md https://link.gi前端小程序跨平台移动开发上一篇5分钟把魔兽世界宏命令工具跑起来wow_api的API查询与智能宏生成全攻略下一篇魔兽世界插件开发快速上手指南wow_api 工具集全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考