智能合约与以太坊 / 系统课时
排查角色提权与授权链
排查角色提权与授权链
智能合约即使为敏感函数添加了角色检查,也可能因为角色管理关系配置错误,让普通用户间接获得管理员权限。本课使用 OpenZeppelin AccessControl 复现一次角色提权,沿授权链定位漏洞,并给出可验证的修复方法。
学习目标
- 理解
DEFAULT_ADMIN_ROLE、角色管理员与业务角色之间的授权关系。 - 复现未经授权的角色授予,并追踪权限扩大的过程。
- 使用最小权限原则修复漏洞,检查角色管理链和管理员转移风险。
角色权限与授权权限不是一回事
OpenZeppelin Contracts 5.x 的 AccessControl 将权限拆成两个维度:角色成员能执行什么操作,以及谁有权授予或撤销这个角色。
例如,持有 MINTER_ROLE 的账户可以调用受 onlyRole(MINTER_ROLE) 保护的铸币函数,但不代表它能把 MINTER_ROLE 授予其他账户。执行 grantRole 和 revokeRole 时,合约检查的是目标角色对应的管理员角色。
默认配置下,所有角色都由 DEFAULT_ADMIN_ROLE 管理,而 DEFAULT_ADMIN_ROLE 又是自己的管理员。因此,获得该角色的账户可以继续授予新的默认管理员,形成权限扩散。
| 角色 | 默认管理员 | 直接获得的能力 |
|---|---|---|
| DEFAULT_ADMIN_ROLE | DEFAULT_ADMIN_ROLE | 管理默认由其负责的角色,包括自身 |
| MINTER_ROLE | DEFAULT_ADMIN_ROLE | 调用受 MINTER_ROLE 保护的函数 |
| PAUSER_ROLE | DEFAULT_ADMIN_ROLE | 调用受 PAUSER_ROLE 保护的函数 |
上述业务能力只有在合约确实使用对应的 onlyRole 检查时才成立。角色名称本身不会自动赋予铸币、暂停等能力。

审计时首先调用 getRoleAdmin(role) 确定角色的实际管理员,再检查管理员角色由谁持有。不能仅根据 MINTER_ROLE、OPERATOR_ROLE 等名称判断权限大小。
复现错误授权导致的权限扩大
下面使用 Solidity 0.8.20 和 OpenZeppelin Contracts 5.x 演示一个典型漏洞:开发者为后台管理功能封装了 adminGrant,却忘记添加管理员检查。
完整漏洞合约如下,可放入 Remix 新建的 RoleEscalationDemo.sol,并确保导入的是 OpenZeppelin Contracts 5.x。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {AccessControl} from "@openzeppelin/contracts@5.0.2/access/AccessControl.sol";
contract RoleEscalationDemo is AccessControl {
bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
uint256 public minted;
constructor() {
// 初始管理员是部署者
_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
}
function adminGrant(bytes32 role, address account) external {
// 漏洞:内部授权函数没有自动检查调用者权限
_grantRole(role, account);
}
function mint(uint256 amount) external onlyRole(MINTER_ROLE) {
minted += amount;
}
}漏洞发生在 _grantRole 与 grantRole 的混淆上。grantRole 是带角色管理员检查的公开接口;_grantRole 是供合约内部实现授权逻辑使用的内部函数,不负责检查业务调用者是否拥有管理员角色。
因此,将 _grantRole 包装成没有访问控制的外部函数,相当于暴露了一个任意角色授予入口。
在 Remix 的 Deploy & Run Transactions 中,使用 JavaScript VM 环境(较新版本可能显示 Remix VM),按下面步骤复现:
- 使用账户 A 部署合约,A 自动获得
DEFAULT_ADMIN_ROLE。 - 切换到账户 B。部署时未给 B 授予任何角色。
- 调用
mint(100),交易应回滚,因为 B 不具备MINTER_ROLE。 - 读取
MINTER_ROLE()返回的bytes32角色标识,调用adminGrant(MINTER_ROLE, B地址)。 - 再次调用
mint(100),这次成功;读取minted()返回 100。 - 使用 B 调用
adminGrant(DEFAULT_ADMIN_ROLE, B地址),再检查hasRole(DEFAULT_ADMIN_ROLE, B地址),结果为true。
预期结果是账户 B 不需要原管理员 A 授权,就能先取得业务角色,再取得默认管理员角色。虽然示例使用了 minted 计数器而非真实 ERC-20 铸币,但权限绕过的调用方式相同。
沿授权链定位根因
实际审计时,不应只查找缺少 onlyRole 的函数。还需要追踪能够修改角色成员、角色管理关系和业务权限的全部入口。
建议按照以下顺序检查:
- 枚举所有
onlyRole、hasRole和其他敏感函数访问控制条件,列出它们实际要求的角色。 - 调用
getRoleAdmin,记录每个业务角色对应的管理角色。 - 搜索
_grantRole、_revokeRole、_setRoleAdmin及其外部包装函数,检查是否存在缺少授权判断的调用路径。 - 检查角色初始化、代理升级初始化与管理权转移,确认没有意外授予高权限角色。
- 追踪管理员角色自身的授予能力,识别自管理角色及可能产生循环授权的关系。
以业务角色 MINTER_ROLE 为例,可直接调用以下两个只读接口:
getRoleAdmin(MINTER_ROLE)
hasRole(DEFAULT_ADMIN_ROLE, account)上面是 Remix 合约交互面板中的接口调用表达式,并非需要加入合约的源码。第一项在默认配置下返回 0x0000000000000000000000000000000000000000000000000000000000000000,即 DEFAULT_ADMIN_ROLE 的标识;第二项根据实际传入的账户地址返回布尔值。
此外,RoleGranted 与 RoleRevoked 事件有助于重建历史授权过程,但只能反映相应角色变动,不能替代权限检查。应将事件中的 sender、目标账户、角色标识与实际交易调用路径关联起来分析。
修复外部授权入口
对示例漏洞,最直接的修复是限制 adminGrant 的调用者必须持有 DEFAULT_ADMIN_ROLE。只需将原来的函数替换为以下实现。
// 片段示例:替换 RoleEscalationDemo 中的同名函数
function adminGrant(bytes32 role, address account)
external
onlyRole(DEFAULT_ADMIN_ROLE)
{
_grantRole(role, account);
}该片段依赖前面的 RoleEscalationDemo 合约、AccessControl 继承关系及已有的管理员初始化。
修复后重新部署,并按原步骤验证:
- 账户 B 调用
adminGrant时交易回滚,不会取得MINTER_ROLE。 - 账户 B 调用
mint(100)仍然回滚,minted()保持为 0。 - 账户 A 可以授予
MINTER_ROLE给 B,此后 B 能正常执行mint(100)。 - B 即使已经持有
MINTER_ROLE,仍不能授予自身DEFAULT_ADMIN_ROLE。
如果不存在必须保留自定义授权入口的业务需求,应直接删除 adminGrant,使用 AccessControl 已经提供管理员校验的 grantRole,减少重复实现导致的错误。
限制默认管理员的扩散风险
即使所有外部函数都正确检查权限,DEFAULT_ADMIN_ROLE 仍具有较大的权限范围。使用标准 AccessControl 时,它既是多数角色的默认管理员,也是自己的管理员,任何一个持有者被攻破都可能导致进一步授权。
OpenZeppelin Contracts 5.x 提供 AccessControlDefaultAdminRules,可限制默认管理员数量,并为管理员转移加入延迟和两阶段确认。
以下给出一份独立的更安全配置示例:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {AccessControlDefaultAdminRules} from "@openzeppelin/contracts@5.0.2/access/extensions/AccessControlDefaultAdminRules.sol";
contract SecureRoles is AccessControlDefaultAdminRules {
bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
// 指定初始管理员,并设置 2 天的转移延迟
constructor(address initialAdmin)
AccessControlDefaultAdminRules(2 days, initialAdmin)
{}
function mintAllowed() external view returns (bool) {
return hasRole(MINTER_ROLE, msg.sender);
}
}部署时为 initialAdmin 传入受控的管理员地址。预期结果是该地址成为唯一默认管理员,并可通过 grantRole 管理 MINTER_ROLE。默认管理员转移需要由当前管理员调用 beginDefaultAdminTransfer(newAdmin),在等待期结束后由新管理员调用 acceptDefaultAdminTransfer() 完成。
在 Remix 中可以检查 defaultAdmin()、defaultAdminDelay() 与 pendingDefaultAdmin()。初始状态下延迟应为 172800 秒,并且没有待接受的新管理员。默认管理员不能通过普通 grantRole 直接转移,这也是该扩展与基础 AccessControl 的重要区别。
对需要进一步分权的项目,可以通过内部 _setRoleAdmin 为业务角色指定单独的管理角色,但必须审核新管理角色的持有人和授权链,避免将自授予能力交给普通业务账户。
上线前至少应通过三个反向测试:普通用户无法获得管理员角色;业务角色成员无法擅自授予其他账户权限;管理员转移无法绕过预设等待期。只有同时检查角色的使用权限和授予权限,才能真正识别完整的提权路径。