企业官网建设流程全解析

CANN oam-tools 安全指南：最小权限运行、文件权限管控、构建安全与公网依赖披露

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

本篇技术指南以 SECURITY_en.md 安全声明为主体，系统讲解 CANN oam-tools（昇腾故障定位工具集，包含故障信息收集、软硬件信息展示、AI Core error 报错分析等能力）在运行用户选择、文件权限控制、源码构建、异常运行处理四个维度上的安全基线，并完整披露项目代码中引用的公网依赖地址。读完本文，你将掌握：如何在主机与容器中正确设置umask与新文件/目录权限、如何以最小权限账户安装和运行工具、如何理解并落实附录中 14 类场景的推荐权限上限，以及编译期间项目依赖了哪些第三方开源组件及其下载来源。

运行用户建议：遵循权限最小化原则

安全声明的第一条原则是不要使用 root 或其他管理员类型账户执行任何命令。原因在于：故障定位工具在采集数据、生成日志、解析 Core Dump 等过程中会创建大量文件与目录，若以高权限账户运行，一旦出现路径覆盖、权限放大的意外情况，风险面会被显著放大。

该原则在仓库的安装脚本中有直接体现。安装脚本 会根据执行者身份自动区分默认安装路径：

• 以 root 执行时，默认安装路径为/usr/local/Ascend，默认属主为root:root；
• 以普通用户执行时，默认安装路径为${HOME}/Ascend，默认属主为当前用户及其主组。

同时，脚本在安装时会校验用户名与用户组的匹配关系（checkusergrouprelationvalid），并仅在 root 用户下允许指定--install-path之外的属主参数（checkemptyuserandgroup），普通用户只能为自己安装，从机制上落实"最小权限"。

性能分析工具的使用约束也重申了这一原则：性能分析使用前准备 明确要求"出于安全性及权限最小化角度考虑，本工具不应使用 root 等高权限账户，建议使用普通用户权限执行"，并禁止 other 用户可写（如 666、777）的权限配置。

文件权限控制：umask 与新建文件/目录的默认权限

umask 基线：0027 及以上

安全声明建议用户在主机（包括宿主机）及容器中设置运行系统umask值为0027 及以上。umask 表示创建文件/目录时需要"屏蔽"的权限位：

• 0027屏蔽了 group 的写权限（0020）和 other 的全部权限（0007），因此：
  • 新建目录默认最高权限为750（rwxr-x---），即属主可读写执行、属组可读执行、其他用户无任何权限；
  • 新建文件默认最高权限为640（rw-r-----），即属主可读写、属组可读、其他用户不可访问。
• 所谓"及以上"是指 umask 数值只能更大（更严格），不可更小（更宽松）。

这一要求在仓库中不仅写入安全声明，还贯穿到具体工具的运行约束中。例如 msprof 性能分析工具的使用前约束明确指出："使用性能分析工具前请确保执行用户的 umask 值大于等于 0027，否则会导致获取的性能数据所在目录和文件权限过大"。测试基建中也有相关说明（如 conftest.py 对构建输出目录权限来源的注释），侧面印证了权限设置对产物落盘的影响。

敏感内容与安装目录的权限管控

除 umask 外，安全声明还要求对个人隐私数据、商业资产、源文件及 Toolkit 开发过程中保存的各类文件做好权限控制，具体包括本项目安装目录的权限管控和输入公共数据文件的权限管控，设定值建议参考文末附录 A：文件（夹）各场景权限管控推荐最大值。

仓库的打包配置 oam_tools.xml 正是按附录思想落地的实现证据，其install_mod字段与附录推荐值一一对应：

安装脚本同样内建了权限自检逻辑：

• parent_dirs_permission_check（install.sh）在 root 安装时会逐级向上检查安装路径的父目录：目录必须属主为 root，且权限推荐为755——权限过小或过大都会告警，静默模式下权限非法（错误码0x0095）会直接终止安装；
• creat_checkpath（install.sh）创建安装目录时，root 场景使用755、普通用户场景使用750，与安全声明"新建文件夹默认最高权限为 750"保持一致；
• 权限不足时统一报错0x0093 Permission denied，引导用户先修正目录权限再重试。

构建安全声明：源码编译后的中间文件权限控制

从源码编译安装本项目时，需要用户自行完成编译（编译方式与依赖清单可参考 快速安装指南）。编译过程会生成目标文件、库文件、头文件等中间产物，安全声明要求编译完成后对中间文件做好权限控制，防止中间产物被非授权用户读取或篡改。

从构建系统源码可以进一步理解"为什么需要这样要求"：

• dependencies.cmake 为 C++ 组件启用了-Wall、-Wextra、-Wshadow、-Wformat=2、-fno-common、-fPIC等加固编译选项，并通过find_cann_package链接 unified_dlog、securec、runtime、slog 等 CANN 公共组件，这些组件产物同样属于需要管控权限的敏感中间文件；
• 测试相关第三方库通过 CMakeLists.txt 中的add_cann_third_party(mockcpp)、add_cann_third_party(gtest_shared)拉取，UT 场景下会额外引入 mockcpp 2.7 与 gtest（详见 快速安装指南 的依赖版本表）；
• 版本信息与场景信息在打包时被生成为只读文件：oam_tools_version.h、scene.info、version.info在 oam_tools.xml 中的install_mod均为440，属于"只读、仅属主和属组可读"的收紧权限形态。

建议在编译完成后，参照附录 A 对编译产物目录（如build输出目录）执行chmod收紧操作，避免中间文件以过宽权限残留在磁盘上。

运行安全声明：异常退出时的定位路径

Toolkit 在运行异常时会退出进程并打印报错信息，安全声明明确指出这属于正常行为，用户应依据报错提示定位具体错误原因，途径包括：

1. 查看 CANN 日志：项目提供了一整套日志采集能力，如 设备侧日志采集、主机侧日志采集、RC 侧日志采集，可帮助用户在异常后集中获取 CANN 各侧日志用于排查；
2. 解析生成的 Core Dump 文件：项目的故障分析模块支持对 coredump 进行解析，对应实现见 coredump_analyze.py，配套文档包括 coredump 文件解析、stackcore 文件解析、coretrace 文件解析 等，可深入定位异常现场。

此外，安装与卸载脚本在运行结束时也会打印带错误码的状态信息（如0x0001操作失败、0x0081文件写入失败、0x0090文件删除失败、0x0093权限拒绝等，见 install.sh），用户可依据ERR_NO前缀快速缩小问题范围。

公网地址声明：构建依赖的下载来源披露

本项目代码中包含的公网地址全部用于编译期第三方依赖下载，均来自 gitcode.com 的cann-src-third-party组织，具体声明如下（与 SECURITY.md 中文版保持一致）：

上述依赖下载行为在构建源码中可交叉印证：

• download_libs.py 直接硬编码了 abseil-cpp 20230802.1 与 mockcpp 2.7-h2 的下载地址；
• fetch_cann_cmake.cmake 会从 gitcode.com/cann/cmake.git（tagmaster-058）拉取 cann-cmake 构建框架，其中包含add_cann_third_party宏，用于按需获取 protobuf、abseil-cpp 等依赖；
• CMakeLists.txt 中的add_cann_third_party(mockcpp)、add_cann_third_party(gtest_shared)即触发上述下载流程。

需要说明的是：以上地址均为编译期依赖来源，而非运行时数据上传地址；oam-tools 运行期采集的故障与性能数据只在本机落盘。若构建环境无法访问这些地址，可参照 快速安装指南 中离线依赖的准备方式，提前将依赖包放置到本地路径。

漏洞机制

项目遵循社区定义的漏洞管理流程：安全声明中提供了Vulnerability Management章节，将漏洞问题统一导向社区的安全管理文档，用于接收和处置安全漏洞报告。涉及漏洞上报、处置周期或安全公告等问题时，请以社区安全管理渠道的说明为准。

附录 A：文件（夹）各场景权限管控推荐最大值

以下为安全声明附录中的完整权限参考表，适用于安装、运行、开发全过程，是落实"最小权限"原则的直接操作依据：

使用建议：

• 先设 umask 再创建：在主机与容器中执行umask 0027（或更严格值），确保新建目录不超过 750、新建文件不超过 640；
• 按场景收紧：对密钥、证书、密文等最高敏感内容，使用600/700甚至更严格权限；对日志、Debug 文件使用440/640；对程序与脚本使用550；
• 定期复核：安装完成后可对照 oam_tools.xml 中的install_mod与实际落盘权限做一致性检查，发现过宽权限及时修正。

进一步阅读

• 安全声明全文（英文版）：SECURITY_en.md；中文版：SECURITY.md
• 安装包权限实现：scripts/package/oam_tools/oam_tools.xml
• 安装与权限自检逻辑：scripts/package/oam_tools/scripts/install.sh
• 构建依赖与下载：cmake/dependencies.cmake、cmake/fetch_cann_cmake.cmake、cmake/download_libs.py
• 性能分析工具的权限约束：docs/zh/profiling/preparation/before_you_start.md
• 运行异常定位（Core Dump / 日志解析）：src/asys/analyze/coredump_analyze.py 与 docs/zh/asys/coredump_files_parsing.md

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools