智能合约与以太坊 / 系统课时
检查 UUPS 升级授权入口
检查 UUPS 升级授权入口
UUPS 代理的升级入口位于逻辑合约中。如果 _authorizeUpgrade 没有限制调用者,攻击者就可能替换整个业务逻辑。本篇使用 OpenZeppelin Contracts 5.x 和 Foundry,构造授权测试、非法实现测试与正常升级测试,确保未经授权的升级无法生效。
学习目标
- 理解 UUPS 升级调用链与
_authorizeUpgrade的安全边界。 - 使用
onlyOwner限制升级权限,识别目标实现校验的局限。 - 编写 Foundry 测试,验证未授权调用失败、非法实现被拒绝及合法升级成功。
找到真正的升级授权入口
UUPS 使用 ERC1967Proxy 保存实现合约地址,并通过 delegatecall 执行业务逻辑。升级函数由逻辑合约提供,调用代理地址上的 upgradeToAndCall 时,实际执行的是当前实现中的升级逻辑。
OpenZeppelin Contracts 5.x 的关键调用顺序如下:
- 用户调用代理地址的
upgradeToAndCall(newImplementation, data)。 onlyProxy确认调用发生在有效代理上下文中。_authorizeUpgrade检查调用者是否有升级权限。- UUPS 内部调用新实现的
proxiableUUID(),检查其返回的 ERC-1967 实现槽位。 - 检查通过后更新实现地址,并在需要时执行初始化调用数据。

最危险的写法是覆盖 _authorizeUpgrade 后不做任何检查。这样虽然保留了 UUPS 的目标兼容性校验,却可能允许任何账户将代理升级到恶意且兼容 UUPS 的实现。
还要区分两个边界:onlyProxy 防止直接在实现合约上调用升级入口,但不检查业务身份;proxiableUUID 验证槽位兼容性,却无法证明新代码值得信任。
实现受控升级合约
下面使用 OpenZeppelin Contracts Upgradeable 5.x,要求 Solidity 编译器满足示例依赖的版本约束。示例采用 OwnableUpgradeable,由代理初始化时指定管理员。生产环境可将 owner 设为多签或带时间锁的治理合约。
在已有 Foundry 项目中安装依赖:
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:
// 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 实现槽位,避免仅通过函数返回值推断升级是否成功。
// 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), "");
}
}执行测试:
forge test --match-contract UUPSAuthorizationTest -vv预期输出(省略耗时与 Gas 等环境相关数值):
[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 的项目,可以使用:
npx @openzeppelin/upgrades-core validate out/build-info预期结果:工具检查构建信息中的可升级合约,发现违反规则的实现时报告错误并返回非零退出码。实际输出取决于编译产物与合约内容;首次使用前需确保已生成 build info,且可升级合约能够被工具识别。该命令不能代替运行时授权测试。
上线前至少确认以下条件:
- 代理创建时已通过初始化数据设置正确 owner,而不是先部署空代理再等待管理员初始化。
- 非授权账户无法执行升级,且失败后 ERC-1967 实现槽位保持不变。
- 新实现能通过 UUPS 兼容性检查,并通过存储布局和升级安全校验。
- 管理权限由多签或治理合约掌握,私钥轮换与紧急处置流程已经演练。
- 升级交易中的
data已审查,避免通过delegatecall执行未经批准的初始化或迁移操作。
还应特别检查继承关系是否发生变化:如果未来版本覆盖或替换 upgradeToAndCall,绕过原有授权逻辑或删除 UUPS 的兼容性保护,即使当前版本安全,也可能引入新的升级漏洞。
最终验收不能停留在“管理员能升级”。必须同时证明攻击者不能升级、非法目标无法生效、合法升级后的状态保持正确,并对候选实现完成独立的代码与存储布局审计。