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

检查 UUPS 升级授权入口

检查 UUPS 升级授权入口

UUPS 代理的升级入口位于逻辑合约中。如果 _authorizeUpgrade 没有限制调用者,攻击者就可能替换整个业务逻辑。本篇使用 OpenZeppelin Contracts 5.x 和 Foundry,构造授权测试、非法实现测试与正常升级测试,确保未经授权的升级无法生效。

学习目标

  • 理解 UUPS 升级调用链与 _authorizeUpgrade 的安全边界。
  • 使用 onlyOwner 限制升级权限,识别目标实现校验的局限。
  • 编写 Foundry 测试,验证未授权调用失败、非法实现被拒绝及合法升级成功。

找到真正的升级授权入口

UUPS 使用 ERC1967Proxy 保存实现合约地址,并通过 delegatecall 执行业务逻辑。升级函数由逻辑合约提供,调用代理地址上的 upgradeToAndCall 时,实际执行的是当前实现中的升级逻辑。

OpenZeppelin Contracts 5.x 的关键调用顺序如下:

  1. 用户调用代理地址的 upgradeToAndCall(newImplementation, data)。
  2. onlyProxy 确认调用发生在有效代理上下文中。
  3. _authorizeUpgrade 检查调用者是否有升级权限。
  4. UUPS 内部调用新实现的 proxiableUUID(),检查其返回的 ERC-1967 实现槽位。
  5. 检查通过后更新实现地址,并在需要时执行初始化调用数据。

UUPS 代理升级的授权与实现校验流程

最危险的写法是覆盖 _authorizeUpgrade 后不做任何检查。这样虽然保留了 UUPS 的目标兼容性校验,却可能允许任何账户将代理升级到恶意且兼容 UUPS 的实现。

还要区分两个边界:onlyProxy 防止直接在实现合约上调用升级入口,但不检查业务身份;proxiableUUID 验证槽位兼容性,却无法证明新代码值得信任。

实现受控升级合约

下面使用 OpenZeppelin Contracts Upgradeable 5.x,要求 Solidity 编译器满足示例依赖的版本约束。示例采用 OwnableUpgradeable,由代理初始化时指定管理员。生产环境可将 owner 设为多签或带时间锁的治理合约。

在已有 Foundry 项目中安装依赖:

bash
forge install OpenZeppelin/openzeppelin-contracts-upgradeable@v5.4.0 --no-commit
forge install OpenZeppelin/openzeppelin-contracts@v5.4.0 --no-commit

预期结果:两个依赖被安装至 lib 目录。不同 Foundry 版本可能需要移除 --no-commit 参数;如果已安装相应依赖,无须重复执行。项目还需配置 forge-std 作为测试依赖,Solidity 编译器可使用 0.8.24。

将以下内容保存到 src/SecureVault.sol:

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Initializable} from
    "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import {OwnableUpgradeable} from
    "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import {UUPSUpgradeable} from
    "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract SecureVault is Initializable, OwnableUpgradeable, UUPSUpgradeable {
    constructor() {
        // 禁止实现合约本身被初始化,避免产生独立的管理状态。
        _disableInitializers();
    }

    function initialize(address admin) public initializer {
        __Ownable_init(admin);
        __UUPSUpgradeable_init();
    }

    function version() public pure virtual returns (uint256) {
        return 1;
    }

    // 唯一的升级授权入口:非 owner 调用时直接回滚。
    function _authorizeUpgrade(address) internal override onlyOwner {}
}

contract SecureVaultV2 is SecureVault {
    function version() public pure override returns (uint256) {
        return 2;
    }
}

contract InvalidImplementation {
    // 故意不实现 ERC-1822 接口,用于验证目标合约检查。
    function version() external pure returns (uint256) {
        return 99;
    }
}

该实现使用三个独立保护措施:

  • _disableInitializers() 锁定实现合约自身的初始化入口,不影响通过代理初始化。
  • onlyOwner 基于代理存储中的 owner 判断授权,未授权时回滚。
  • 继承的 UUPSUpgradeable 检查目标实现的 ERC-1822 槽位兼容性。

预期结果:forge build 编译通过。SecureVault 与 SecureVaultV2 的升级入口相同,后者仅改变 version() 的返回值,不增加状态变量。

用攻击场景验证授权边界

安全审计不能只阅读 onlyOwner 修饰符,还要真实调用代理地址,确认未经授权的账户无法改变实现地址。

创建 test/UUPSAuthorization.t.sol,使用 Foundry 的 vm.prank 模拟不同调用者。测试会读取 ERC-1967 实现槽位,避免仅通过函数返回值推断升级是否成功。

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Test} from "forge-std/Test.sol";
import {ERC1967Proxy} from
    "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import {SecureVault, SecureVaultV2, InvalidImplementation} from
    "../src/SecureVault.sol";

contract UUPSAuthorizationTest is Test {
    bytes32 constant IMPLEMENTATION_SLOT =
        bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1);

    SecureVault internal vault;
    address internal attacker = makeAddr("attacker");
    address internal implementation;

    function setUp() public {
        implementation = address(new SecureVault());
        bytes memory data = abi.encodeCall(
            SecureVault.initialize, (address(this))
        );
        ERC1967Proxy proxy = new ERC1967Proxy(implementation, data);
        vault = SecureVault(address(proxy));
    }

    function implementationOfProxy() internal view returns (address) {
        return address(uint160(uint256(
            vm.load(address(vault), IMPLEMENTATION_SLOT)
        )));
    }

    function testUnauthorizedUpgradeReverts() public {
        SecureVaultV2 next = new SecureVaultV2();
        vm.prank(attacker);
        vm.expectRevert();
        vault.upgradeToAndCall(address(next), "");
        assertEq(implementationOfProxy(), implementation);
    }

    function testInvalidImplementationReverts() public {
        InvalidImplementation invalid = new InvalidImplementation();
        vm.expectRevert();
        vault.upgradeToAndCall(address(invalid), "");
        assertEq(implementationOfProxy(), implementation);
    }

    function testAuthorizedUpgradeSucceeds() public {
        SecureVaultV2 next = new SecureVaultV2();
        vault.upgradeToAndCall(address(next), "");
        assertEq(implementationOfProxy(), address(next));
        assertEq(vault.version(), 2);
        assertEq(vault.owner(), address(this));
    }

    function testDirectImplementationUpgradeReverts() public {
        SecureVaultV2 next = new SecureVaultV2();
        vm.expectRevert();
        SecureVault(implementation).upgradeToAndCall(address(next), "");
    }
}

执行测试:

bash
forge test --match-contract UUPSAuthorizationTest -vv

预期输出(省略耗时与 Gas 等环境相关数值):

text
[PASS] testUnauthorizedUpgradeReverts()
[PASS] testInvalidImplementationReverts()
[PASS] testAuthorizedUpgradeSucceeds()
[PASS] testDirectImplementationUpgradeReverts()
Suite result: ok. 4 passed; 0 failed; 0 skipped

四个断言分别覆盖不同的安全边界。第一项证明普通账户无法升级;第二项证明具有权限的账户也不能升级到缺少 UUPS 兼容接口的目标;第三项证明正常升级后逻辑版本改变且 owner 未丢失;第四项确认实现地址不能直接执行升级操作。

这里的 vm.expectRevert() 只验证发生回滚。进一步审计时,可以精确匹配 OwnableUnauthorizedAccount(address) 等自定义错误,防止错误原因发生变化却仍然通过测试。

区分目标兼容性与目标可信性

OpenZeppelin 的 UUPS 兼容性检查会调用候选实现的 proxiableUUID(),要求返回 ERC-1967 规定的实现槽位。但一个恶意实现同样可以返回正确槽位,因此兼容性检查不等于代码安全审计。

检查项 能阻止什么 不能保证什么
onlyOwner 非 owner 发起升级 owner 私钥未泄露
onlyProxy 在实现地址直接执行升级入口 代理调用者具有权限
proxiableUUID 不兼容目标实现 新实现的业务逻辑安全
存储布局校验 常见的状态变量布局冲突 升级逻辑没有业务漏洞

对高价值合约,可以增加多签审批、Timelock 延迟执行以及链下审计结果校验。若业务要求严格限制目标实现,还可在 _authorizeUpgrade(address newImplementation) 中增加由治理流程维护的候选地址白名单,但必须确保白名单本身不能被普通账户任意修改。

升级前的审计验收

在本地测试通过之后,还需要对实际准备部署的实现执行升级兼容性检查。若使用 OpenZeppelin Upgrades 工具,可结合原有实现的构建信息检查新版本的存储布局及升级安全规则。

对于生成了标准 Foundry build info 的项目,可以使用:

bash
npx @openzeppelin/upgrades-core validate out/build-info

预期结果:工具检查构建信息中的可升级合约,发现违反规则的实现时报告错误并返回非零退出码。实际输出取决于编译产物与合约内容;首次使用前需确保已生成 build info,且可升级合约能够被工具识别。该命令不能代替运行时授权测试。

上线前至少确认以下条件:

  1. 代理创建时已通过初始化数据设置正确 owner,而不是先部署空代理再等待管理员初始化。
  2. 非授权账户无法执行升级,且失败后 ERC-1967 实现槽位保持不变。
  3. 新实现能通过 UUPS 兼容性检查,并通过存储布局和升级安全校验。
  4. 管理权限由多签或治理合约掌握,私钥轮换与紧急处置流程已经演练。
  5. 升级交易中的 data 已审查,避免通过 delegatecall 执行未经批准的初始化或迁移操作。

还应特别检查继承关系是否发生变化:如果未来版本覆盖或替换 upgradeToAndCall,绕过原有授权逻辑或删除 UUPS 的兼容性保护,即使当前版本安全,也可能引入新的升级漏洞。

最终验收不能停留在“管理员能升级”。必须同时证明攻击者不能升级、非法目标无法生效、合法升级后的状态保持正确,并对候选实现完成独立的代码与存储布局审计。

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

目录与阅读设置

阅读设置

17

记录一个想法

检查 UUPS 升级授权入口

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

登录哪都通