capability_proxy

版本信息

项目	内容
组件版本	1.110.15
首发版本	1.70.7
文档作者	chenyuan66
最后更新	2026-06-01

1. 组件概述

1.1 组件简介

capability_proxy是BMC系统中的特权操作代理组件，以Bus服务形式运行在其他BMC组件与底层特权操作之间。它将各类需要Linux特权能力的操作集中到capability_proxy统一代理，使上游组件无需持有这些高危权限即可完成文件操作等特权。

1.2 解决什么问题

capability_proxy 组件解决了 BMC 系统中文件特权的以下问题：

特权最小化：各BMC组件的高危权限收敛到capability_proxy。减少攻击面
操作标准化：所有特权操作必须通过白名单校验，防止越权访问
调用方管控：基于标识+路径+操作类型三重校验，精准控制每个组件能做什么
集中审计：特权操作同意经由capability_proxy，日志可追溯

1.3 核心功能

核心功能一：文件操作代理
核心功能二：文件所有权管理，支持本地用户和域用户的UID/GID映射
核心功能三：权限检查代理，支持IPMI和RPC两种权限校验模式
核心功能四：文件系统挂载代理
核心功能五：驱动代理
核心功能六：Device Mapper 代理

1.4 关键术语表

术语	解释
capability_proxy	特权操作代理组件，切面组件，负责收敛各组件的特权操作
切面组件	以特权模式拦截横切特权操作的组件设计模式
白名单	经过审批的路径+操作类型+调用方的组件列表
Requestor	调用capabilities_proxy的上游组件标识
CAP_DAC_OVERRIDE	可绕过文件权限检查的Linux能力，正在从各组件剥离
CAP_SYS_RAWIO	裸I/O访问能力，高危权限
Device Mapper	Linux 内核逻辑卷管理框架，mmcblksp用于eMMC分区映射
dmsetup	Device Mapper 用户态管理工具
NFS v4.x	网络文件系统，capability_proxy依次尝试v4.2/4.1/4.0
skynet	actor模型的Lua微服务运行时框架
MDS	Model-Driven Service ,元数据服务

1.5 外部交互边界图

2. API 使用说明与示例

2.1 文件操作

bash

NAME             TYPE      SIGNATURE               RESULT/VALUE  FLAGS
.Access          method    a{ss}sy                     b             -
.IsPermitted     method    a{ss}ss                     b             -
.Mkdir           method    a{ss}suuub                  -             -

功能说明

文件基础操作代理，提供 /mkdir/access/is_permitted 等操作，全部经过白名单三重校验（Requestor 授权 + 路径合法 + 操作类型允许）。

属性	内容
接口名	bmc.kepler.Managers.Security.File
首发版本	1.70.7
废弃状态	正常可用

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
Access	a{ss}sy	b	检查文件/目录是否存在	入参： a{ss}: 额外信息，预留 s: 文件路径 s: 模式字符串（如 "0"） y: 权限模式 0~7 出参： b: true 表示存在，false 表示不存在
IsPermitted	a{ss}ss	b	检查权限	入参： a{ss}: 额外信息，预留 s: 文件路径 s: 权限类型（r/w/rw/c）出参： b: true 表示有权限，false 表示无权限
Mkdir	a{ss}suuub	-	创建目录	入参： a{ss}: 额外信息，预留 s: 目录路径 u: 权限模式 u: UID u: GID b: 是否创建父目录

返回值与异常

返回值类型	含义	触发条件	处理建议
true	操作成功	操作正常执行	无
false	操作失败	路径不在白名单/Requestor未授权/操作类型不允许	检查白名单配置

应用场景

account组件管理用户home目录
bios组件BIOS升级包解压到指定目录
各组件通过IsPermitted检查当前用户对文件的读/写/创建权限

限制条件

所有操作必须通过白名单三重校验
Tar压缩仅限指定路径
IsPermitted支持IPMi和RPC两种模式

调试示例

命令行调试

bash

# 检查文件是否存在
busctl --user call bmc.kepler.capability_proxy \
 /bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File \
 Access a{ss}sy 0 "/tmp/user.txt" 0

响应：b true

# 检查用户对文件的写权限
busctl --user call bmc.kepler.capability_proxy \
 /bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File \
 IsPermitted a{ss}ss 4 "Interface" "CLI" "UserName" "<当前管理员>" "ClientAddr" "127.0.0.1" "Privilege" "16" "/tmp/user.txt" "w"

响应：b true

# 创建目录
busctl --user call bmc.kepler.capability_proxy \
 /bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File \
 Mkdir a{ss}suuub 0 "/data/trust/home/newdir" 755 1000 1000 false

/data/trust/home 目录下面存在newdir目录

2.2 文件系统挂载

支持本地文件系统和远程文件系统的挂载和卸载。

bash

NAME                                      TYPE      SIGNATURE   RESULT/VALUE                             FLAGS
.MountLocal                               method    a{ss}ssb        b                                       -
.GetMountStatus                           method    a{ss}s        (ssss)                                    -
.MountRemote                              method    a{ss}sssuss     b                                       -
.Umount                                   method    a{ss}s          b                                       -

功能说明

属性	内容
接口名	bmc.kepler.Managers.Sercurity.File.Mount
首发版本	1.70.7
废弃状态	正常可用

属性参数说明

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
GetMountStatus	a{ss}s	(ssss)	获取挂载状态	入参： a{ss}: 额外信息，预留 s: 挂载点路径出参： (ssss): (文件系统名, 目录, 类型, 选项)
MountLocal	a{ss}sssb	b	挂载本地文件系统	入参： a{ss}: 额外信息，预留 s: 源路径 s: 目标路径 s: 文件系统类型（VFAT） b: 错误是否继续出参： b: true 表示成功，false 表示失败
MountRemote	a{ss}sssuss	b	挂载远程文件系统	入参： a{ss}: 额外信息，预留 s: 源路径（URI） s: 目标路径 s: 协议（NFS/CIFS） u: 端口 s: 用户名 s: 密码出参： b: true 表示成功，false 表示失败
Umount	a{ss}s	b	卸载文件系统	入参： a{ss}: 额外信息，预留 s: 挂载点路径出参： b: true 表示成功，false 表示失败

返回值与异常

返回值类型	含义	触发条件	处理建议
true	成功	挂载成功	无
false	失败	挂载点不在白名单/网络不通/权限不足	检查网络和挂载参数

应用场景

ums组件挂载SP分区
web_backend 挂载NFS日志共享盘
各组件卸载挂载点释放资源

限制条件

挂载点必须在白名单中
不允许重复挂载

调试示例

命令行调试

bash

# 挂载本地
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File.Mount \
MountLocal "a{ss}sssb" 1 "Requestor" "bmc.kepler.ums" "/dev/mmcblk0p5" "/data/ibma" "vfat" false

响应：b true

# 卸载
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File.Mount \
Umount "a{ss}s" 1 "Requestor" "bmc.kepler.ums" "/data/ibma"

响应：b true

# 查询挂载状态
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File.Mount \
GetMountStatus a{ss}s 0 "/data/ibma"

响应：(ssss) "/dev/mmcblk0p5" "/data/ibma" "vfat" "rw,relatime,gid=xxx,fmask=xxx,dmask=xxx,codepage=xxx,iocharset=xxx,shortname=xxx,errors=xxx"

2.3 Device Mapper

通过dmsetup管理Linux Device Mapper 逻辑卷

bash

NAME                                      TYPE      SIGNATURE   RESULT/VALUE                             FLAGS
.Create                                  method      a{ss}ss         b                                     -
.Remove                                  method      a{ss}s          b                                     -

功能说明

属性	内容
接口名	bmc.kepler.Managers.Security.File.DeviceMapper
首发版本	1.70.7
废弃状态	正常可用

属性参数说明

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
Create	a{ss}ss	b	创建 Device Mapper 卷	入参： a{ss}: 额外信息，预留 s: 卷名称 s: 底层设备出参： b: true 表示成功，false 表示失败
Remove	a{ss}s	b	删除 Device Mapper 卷	入参： a{ss}: 额外信息，预留 s: 卷名称出参： b: true 表示成功，false 表示失败

返回值与异常

返回值类型	含义	触发条件	处理建议
true	成功	dmsetup操作成功	无
false	失败	名单不在白名单/设备不存在	检查设备路径

应用场景

ums 组件创建eMMC分区映射

限制条件

mmcblksp卷

调试示例

命令行调试

bash

# 创建Device Mapper 卷
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File.DeviceMapper \
Create "a{ss}ss" 1 "Requestor" "bmc.kepler.ums" "mmcblksp" "/dev/mmcblk0p1"

响应：b true

# 删除Device Mapper 卷
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/File bmc.kepler.Managers.Security.File.DeviceMapper \
Remove "a{ss}s" 1 "Requestor" "bmc.kepler.ums" "mmcblksp"

响应：b true

2.4 驱动代理

内核模块加载/卸载代理，带白名单校验和命令注入防护

bash

NAME                                      TYPE      SIGNATURE   RESULT/VALUE                             FLAGS
.Insmod                                  method     a{ss}a{ss}        b                                     -
.Rmmod                                   method     a{ss}a{ss}        b                                     -

功能说明

属性	内容
接口名	bmc.kepler.Managers.Security.Proxy.Driver
首发版本	1.70.7
废弃状态	正常可用

属性参数说明

方法配置参数

方法名	入参类型	出参类型	描述	取值范围
Insmod	a{ss}a{ss}	b	加载内核模块	入参： a{ss}: 额外信息，预留 a{ss}: 扩展参数字典（名值对）出参： b: true 表示成功，false 表示失败
Rmmod	a{ss}a{ss}	b	卸载内核模块	入参： a{ss}: 额外信息，预留 a{ss}: 扩展参数字典（名值对）出参： b: true 表示成功，false 表示失败

返回值与异常

返回值类型	含义	触发条件	处理建议
true	成功	insmod/rmmod成功	无
false	失败	模块路径不在白名单/参数不在白名单	检查检查白名单配置

应用场景

bios组件加载SFC网卡驱动
compute组件加载NPU相关驱动

限制条件

模块路径必须在驱动白名单中
每个扩展参数（名和值）均在白名单中
Shell特殊字符校验，防止命令注入

调试示例

命令行调试

bash


# 加载内核模块
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/Proxy bmc.kepler.Managers.Security.Proxy.Driver \
Insmod "a{ss}sa{ss}" 1 "Requestor" "bmc.kepler.remote_console" "/lib/modules/5.10.0/kernel/drivers/uio/uio_pdrv_genirq.ko" 1 "of_id" "2"

响应：b true

# 卸载内核模块
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/Managers/1/Security/Proxy bmc.kepler.Managers.Security.Proxy.Driver \
Rmmod "a{ss}sa{ss}" 1 "Requestor" "bmc.kepler.remote_console" "/lib/modules/5.10.0/kernel/drivers/uio/uio_pdrv_genirq.ko" 0

响应：b true

3. 组件扩展案例

4. 日志说明

4.1 一键日志收集

文件路径	内容说明
/var/log/app.log	capability_proxy组件日志
/var/log/framework.log	capability_proxy 启动日志

4.2 关键日志信息

日志片段	日志级别	含义解读	建议处理动作
2026-06-01 19:20:25.078345 capability_proxy NOTICE: xxxxxx	NOTICE	capability_proxy 组件重要功能执行节点日志	用于判断重要功能执行到的节点状态
2026-06-01 19:27:47.781111 capability_proxy ERROR: xxxxxx	ERROR	capability_proxy 组件错误日志	用于记录功能执行错误的原因
2026-06-26 19:46:00.855091 maca NOTICE:xxxx.lua(xxxx) :component[capability_proxy] exited total 2 times, total 7 times for all modules	FRAMEWORK	启动日志	用于判断组件操作是否成功

5. 问题定界指南

5.1 典型问题定界

现象描述	是否为本组件问题	判断依据	关键证据收集方法
IsPermitted 返回 false	可能是	用户不是文件所有者或没有对应权限	查看日志中的 user %s is not owner 或 user %s has no privilege
Mkdir 返回 false	可能是	目录路径不在白名单或创建失败	查看日志中的 dir %s not support create 或 mkdir dst_path error
Insmod/Rmmod 返回 false	可能是	命令包含特殊字符或执行失败	查看日志中的 invalid command with special character 或 failed to execute command
DeviceMapper Create/Remove 返回 false	可能是	设备名称不在白名单或 dmsetup 执行失败	查看日志中的 device name not in mapper list 或 dmsetup create/remove failed

5.3 调试方法

开启调试日志

bash

# 开启 capability_proxy 详细日志
busctl --user call bmc.kepler.capability_proxy \
/bmc/kepler/capability_proxy/MicroComponent \
bmc.kepler.MicroComponent.Debug SetDlogLevel a{ss}sy 0 debug 1

# 查看实时日志
tail -f /var/log/app.log | grep capability_proxy

复现问题方法

前置条件设置：

确认白名单配置正确
确保 capability_proxyficate 服务正常运行

操作步骤：

调用busctl调用目标接口
观察返回值（true/false）
查看日志中的ERROR信息

预期结果：

日志中会记录操作失败的具体原因（白名单校验失败、路径不存在、权限不足等）

6. 常见问题解答

Q1：文件操作返回 false 如何排查？

问题描述

调用 File 接口（/mkdir/access 等）返回 false

一句话答案

查看 /var/log/app.log 中的 ERROR 日志，根据具体错误信息定位原因

根因说明

可能原因包括：路径不在 FILE_WHITE_LIST、Requestor 未授权、操作类型不允许、源文件不存在、目标路径校验失败等

解决方案

根据日志中的具体错误信息处理：

not in whitelist：检查 FILE_WHITE_LIST 配置
not exists：确认源文件是否存在
no privilege：检查用户权限
check_dst_path_is_valid failed：检查目标路径是否在白名单中

适用版本：
1.70.7以上

Q2：IsPermitted 返回 false？

问题描述

检查用户对文件的权限返回 false

一句话答案

确认用户是文件所有者，并且拥有 r/w/rw/c 中对应的权限

根因说明

IsPermitted 首先检查用户是否是文件所有者（通过 UID 匹配），然后检查用户对文件的权限位（读/写/读写/创建）

解决方案：

查看日志中 invalid permission str
查看日志中 has no privilege，确认权限不足的具体原因
查看日志中 check real path failed ，确认文件路径

适用版本：
1.70.7以上

Q3：NFS 挂载失败？

问题描述

MountRemote 返回 false

一句话答案

检查挂载点是否在 MOUNT_PATH_LIST 中、NFS 服务器是否可达

根因说明

挂载点必须在 MOUNT_PATH_LIST 中

解决方案

查看日志中 xxx path not in mount list 确认挂载点白名单
查看日志中 mount point is already mounted 是否已经挂载
检查 NFS 服务器状态和网络连通性

适用版本：
1.70.7以上

Q4：内核模块加载被拒绝？

问题描述

Insmod 返回 false

一句话答案

确认模块路径和参数在 DRIVER_PROXY_LIST 白名单中，且不包含 shell 特殊字符

根因说明

Insmod 检查模块路径是否在驱动白名单中，每个扩展参数的名和值也需在白名单中，且不能包含 shell 特殊字符

解决方案：

检查 DRIVER_PROXY_LIST 白名单配置

适用版本：
1.70.7以上

capability_proxy ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

1.2 解决什么问题 ​

1.3 核心功能 ​

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 文件操作 ​

功能说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.2 文件系统挂载 ​

功能说明 ​

属性参数说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.3 Device Mapper ​

功能说明 ​

属性参数说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

2.4 驱动代理 ​

功能说明 ​

属性参数说明 ​

方法配置参数 ​

返回值与异常 ​

应用场景 ​

限制条件 ​

调试示例 ​

命令行调试 ​

3. 组件扩展案例 ​

4. 日志说明 ​

4.1 一键日志收集 ​

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.3 调试方法 ​

开启调试日志 ​

复现问题方法 ​

6. 常见问题解答 ​

Q1：文件操作返回 false 如何排查？ ​

Q2：IsPermitted 返回 false？ ​

Q3：NFS 挂载失败？ ​

Q4：内核模块加载被拒绝？ ​

capability_proxy

版本信息

1. 组件概述

1.1 组件简介

1.2 解决什么问题

1.3 核心功能

1.4 关键术语表

1.5 外部交互边界图

2. API 使用说明与示例

2.1 文件操作

功能说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.2 文件系统挂载

功能说明

属性参数说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.3 Device Mapper

功能说明

属性参数说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

2.4 驱动代理

功能说明

属性参数说明

方法配置参数

返回值与异常

应用场景

限制条件

调试示例

命令行调试

3. 组件扩展案例

4. 日志说明

4.1 一键日志收集

4.2 关键日志信息

5. 问题定界指南

5.1 典型问题定界

5.3 调试方法

开启调试日志

复现问题方法

6. 常见问题解答

Q1：文件操作返回 false 如何排查？

Q2：IsPermitted 返回 false？

Q3：NFS 挂载失败？

Q4：内核模块加载被拒绝？