智能合约与以太坊 / 系统课时

排查角色提权与授权链

排查角色提权与授权链

智能合约即使为敏感函数添加了角色检查,也可能因为角色管理关系配置错误,让普通用户间接获得管理员权限。本课使用 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。

solidity
// 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),按下面步骤复现:

  1. 使用账户 A 部署合约,A 自动获得 DEFAULT_ADMIN_ROLE。
  2. 切换到账户 B。部署时未给 B 授予任何角色。
  3. 调用 mint(100),交易应回滚,因为 B 不具备 MINTER_ROLE。
  4. 读取 MINTER_ROLE() 返回的 bytes32 角色标识,调用 adminGrant(MINTER_ROLE, B地址)。
  5. 再次调用 mint(100),这次成功;读取 minted() 返回 100。
  6. 使用 B 调用 adminGrant(DEFAULT_ADMIN_ROLE, B地址),再检查 hasRole(DEFAULT_ADMIN_ROLE, B地址),结果为 true。

预期结果是账户 B 不需要原管理员 A 授权,就能先取得业务角色,再取得默认管理员角色。虽然示例使用了 minted 计数器而非真实 ERC-20 铸币,但权限绕过的调用方式相同。

沿授权链定位根因

实际审计时,不应只查找缺少 onlyRole 的函数。还需要追踪能够修改角色成员、角色管理关系和业务权限的全部入口。

建议按照以下顺序检查:

  1. 枚举所有 onlyRole、hasRole 和其他敏感函数访问控制条件,列出它们实际要求的角色。
  2. 调用 getRoleAdmin,记录每个业务角色对应的管理角色。
  3. 搜索 _grantRole、_revokeRole、_setRoleAdmin 及其外部包装函数,检查是否存在缺少授权判断的调用路径。
  4. 检查角色初始化、代理升级初始化与管理权转移,确认没有意外授予高权限角色。
  5. 追踪管理员角色自身的授予能力,识别自管理角色及可能产生循环授权的关系。

以业务角色 MINTER_ROLE 为例,可直接调用以下两个只读接口:

solidity
getRoleAdmin(MINTER_ROLE)
hasRole(DEFAULT_ADMIN_ROLE, account)

上面是 Remix 合约交互面板中的接口调用表达式,并非需要加入合约的源码。第一项在默认配置下返回 0x0000000000000000000000000000000000000000000000000000000000000000,即 DEFAULT_ADMIN_ROLE 的标识;第二项根据实际传入的账户地址返回布尔值。

此外,RoleGranted 与 RoleRevoked 事件有助于重建历史授权过程,但只能反映相应角色变动,不能替代权限检查。应将事件中的 sender、目标账户、角色标识与实际交易调用路径关联起来分析。

修复外部授权入口

对示例漏洞,最直接的修复是限制 adminGrant 的调用者必须持有 DEFAULT_ADMIN_ROLE。只需将原来的函数替换为以下实现。

solidity
// 片段示例:替换 RoleEscalationDemo 中的同名函数
function adminGrant(bytes32 role, address account)
    external
    onlyRole(DEFAULT_ADMIN_ROLE)
{
    _grantRole(role, account);
}

该片段依赖前面的 RoleEscalationDemo 合约、AccessControl 继承关系及已有的管理员初始化。

修复后重新部署,并按原步骤验证:

  1. 账户 B 调用 adminGrant 时交易回滚,不会取得 MINTER_ROLE。
  2. 账户 B 调用 mint(100) 仍然回滚,minted() 保持为 0。
  3. 账户 A 可以授予 MINTER_ROLE 给 B,此后 B 能正常执行 mint(100)。
  4. B 即使已经持有 MINTER_ROLE,仍不能授予自身 DEFAULT_ADMIN_ROLE。

如果不存在必须保留自定义授权入口的业务需求,应直接删除 adminGrant,使用 AccessControl 已经提供管理员校验的 grantRole,减少重复实现导致的错误。

限制默认管理员的扩散风险

即使所有外部函数都正确检查权限,DEFAULT_ADMIN_ROLE 仍具有较大的权限范围。使用标准 AccessControl 时,它既是多数角色的默认管理员,也是自己的管理员,任何一个持有者被攻破都可能导致进一步授权。

OpenZeppelin Contracts 5.x 提供 AccessControlDefaultAdminRules,可限制默认管理员数量,并为管理员转移加入延迟和两阶段确认。

以下给出一份独立的更安全配置示例:

solidity
// 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 为业务角色指定单独的管理角色,但必须审核新管理角色的持有人和授权链,避免将自授予能力交给普通业务账户。

上线前至少应通过三个反向测试:普通用户无法获得管理员角色;业务角色成员无法擅自授予其他账户权限;管理员转移无法绕过预设等待期。只有同时检查角色的使用权限和授予权限,才能真正识别完整的提权路径。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查角色提权与授权链

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通