icp-deploy-check
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseICP deploy check
ICP 部署检查
Run this static, read-only gate over a Rust canister repo before a mainnet
deploy. It reads source and reports; it never deploys, never calls mainnet, never
needs a key. The fix patterns behind each check live in the
skill — this skill is the checklist, that one is the reference.
canister-securityScope: every update entrypoint and the // hooks
in the Rust canister(s), plus any frontend or agent code in the same repo
(check #2 only). Produce one row per check: / / /
with evidence.
initpre_upgradepost_upgradeic-cdkPASSFAILREVIEWN/Afile:line在 Rust canister 仓库上运行此静态、只读门禁,部署至 mainnet 之前执行。它只读取源代码并生成报告;绝不执行部署,绝不调用 mainnet,也绝不需要密钥。各项检查背后的修复模式位于 skill 中——这个 skill 是检查清单,那个是参考资料。
canister-security范围:Rust canister 中的每个 update 入口点及 // hook,以及同一仓库中的任何 frontend 或 agent 代码(仅适用检查 #2)。每项检查输出一行: / / / ,并附带 证据。
ic-cdkinitpre_upgradepost_upgradePASSFAILREVIEWN/Afile:lineEnumerating update entrypoints
枚举 update 入口点
Checks #1 and #3 both start from the full list of update methods. Match the
attribute with or without arguments — ,
and are all
entrypoints:
#[update(guard = "...")]#[update(name = "...")]#[ic_cdk::update(manual_reply = true)]bash
rg -n -A4 '#\[(ic_cdk::)?update\b'\bupdate]update('update\]'guard = "..."Callers are read with (ic-cdk >= 0.18). Older code
uses / — treat them as equivalent when
tracing.
ic_cdk::api::msg_caller()ic_cdk::caller()ic_cdk::api::caller()检查 #1 和 #3 都从完整的 update 方法列表开始。匹配 attribute 时要涵盖带参数和不带参数两种形式——、 和 均为入口点:
#[update(guard = "...")]#[update(name = "...")]#[ic_cdk::update(manual_reply = true)]bash
rg -n -A4 '#\[(ic_cdk::)?update\b'\bupdate]update('update\]'guard = "..."调用方通过 读取(ic-cdk >= 0.18)。旧代码使用 / ——追踪时将它们视为等价。
ic_cdk::api::msg_caller()ic_cdk::caller()ic_cdk::api::caller()The five checks
五项检查
1. Anonymous principal reaches a state change — FAIL if reachable
1. Anonymous principal 可到达状态变更——可达则 FAIL
Every state-changing update must reject before its
first mutation.
Principal::anonymous()- Trace, don't pattern-match. For each update that mutates state (writes a
/stable structure, credits/debits a balance, mints, sets config, makes a state-changing inter-canister call), confirm that on every path to the mutation the call is rejected (
thread_local!,trapreturn, or guardErr) when the caller is anonymous. Accept any of:Err- an explicit comparison against (
Principal::anonymous()with trap/return, or==gating the mutation), on!=or a variable bound to it;msg_caller() - a attribute — open
guard = "fn_name"and confirm its body returnsfn_namefor the anonymous principal;Err - a controller/owner/allowlist check that rejects the caller (anonymous can never
be a controller). An owner-equality check counts only if the owner can never
be anonymous — as the default owner with no
RefCell::new(Principal::anonymous())first means anonymous is the owner untilrequire_authenticatedruns.init
- an explicit comparison against
- Not authentication — FAIL if these are the only "guard":
- / per-caller locks /
CallerGuardsets: these are reentrancy locks, they accept the anonymous principal like any other;PENDING - a guard identified only by its name (,
require_caller, ...) without reading its body;check_access - or a comparison whose result is computed but never acted on, or that runs after the mutation.
is_controller(...)
- An update that is deliberately open to anonymous callers (e.g. a public
counter, an open sign-up whose cost is bounded) is , not
REVIEW— state why it is intended. Query methods cannot persist state and are out of scope.FAIL
每个会改变状态的 update 都必须在首次 mutation 之前拒绝 。
Principal::anonymous()- 追踪,不要只做模式匹配。 对于每个会改变状态的 update(写入 /stable structure、贷记/借记余额、mint、设置 config、执行会改变状态的 inter-canister call),确认通往该 mutation 的每条路径都会在调用方为 anonymous 时拒绝调用(
thread_local!、trap返回或 guard 返回Err)。接受以下任一方式:Err- 显式比较 (使用
Principal::anonymous()并 trap/返回,或使用==控制 mutation),比较对象为!=或绑定到它的变量;msg_caller() - attribute——打开
guard = "fn_name",确认其函数体会对 anonymous principal 返回fn_name;Err - controller/owner/allowlist 检查会拒绝调用方(anonymous 永远不能成为 controller)。只有当 owner 永远不可能是 anonymous 时,owner 相等性检查才算有效——如果以 作为默认 owner,且此前没有执行
RefCell::new(Principal::anonymous()),那么在require_authenticated运行前,anonymous 就是 owner。init
- 显式比较
- 这不算身份认证——如果以下内容是唯一的“guard”,则判定为 FAIL:
- / per-caller lock /
CallerGuardset:这些是 reentrancy lock,与其他 principal 一样,它们会接受 anonymous principal;PENDING - 仅凭名称识别的 guard(、
require_caller等),却没有读取其函数体;check_access - 或某种比较,其结果虽然被计算,却从未用于采取行动,或者检查发生在 mutation 之后。
is_controller(...)
- 如果某个 update 有意对 anonymous 调用方开放(例如公开 counter,或成本受限的开放注册),则判定为 ,而非
REVIEW——需说明其设计意图。Query method 无法持久化状态,不在检查范围内。FAIL
2. fetch_root_key
in shipped code — FAIL if present
fetch_root_key2. 发布代码中存在 fetch_root_key
——存在则 FAIL
fetch_root_keyfetch_root_key()ic-agentfetchRootKey()bash
rg -n 'fetch_root_key|fetchRootKey|shouldFetchRootKey'- FAIL on any occurrence in a shipped frontend or client path — even behind
an environment check (,
if network === "local",process.env.DFX_NETWORK): environment branching is how the call leaks into production builds. The fix is to stop fetching it: pass the root key from the#[cfg(feature = "local")]cookie (ic_env, viaIC_ROOT_KEY) assafeGetCanisterEnv()torootKey. SeeHttpAgent.create()for the full pattern.canister-security - Not a finding: test-only code (,
#[cfg(test)], PocketIC harnesses, scripts that only ever target a local replica) — marktests/with a note.PASS
fetch_root_key()ic-agentfetchRootKey()bash
rg -n 'fetch_root_key|fetchRootKey|shouldFetchRootKey'- 只要在已发布的 frontend 或 client 路径中出现任何匹配项,就判定为 FAIL——即使它位于环境检查之后(、
if network === "local"、process.env.DFX_NETWORK):环境分支正是调用泄漏到 production build 的途径。修复方式是停止获取该 key:将#[cfg(feature = "local")]cookie 中的 root key(ic_env,通过IC_ROOT_KEY获取)作为safeGetCanisterEnv()传给rootKey。完整模式请参阅HttpAgent.create()。canister-security - 不构成问题: 仅用于测试的代码(、
#[cfg(test)]、PocketIC harness,以及仅指向 local replica 的脚本)——标记为tests/并附注说明。PASS
3. Unguarded admin / privileged method — FAIL if not privileged-guarded
3. 无防护的 admin / privileged method——未受 privileged guard 保护则 FAIL
Mint / burn / migrate / upgrade / config / / withdraw updates must be
restricted to a controller, owner or admin — not merely to authenticated users.
set_*- Candidates: from the enumerated update list (not a separate grep), take every
method whose name contains — anywhere, not only as a prefix —
. Name matching only finds candidates: an update whose visible body changes fees, ownership, other users' balances, or canister-wide settings is privileged regardless of its name. A user-facing method acting on the caller's own account (
(?i)(mint|burn|admin|migrate|upgrade|config|set_|withdraw|transfer_from|owner|controller|pause|allowlist|whitelist),deposit,transfer) is not privileged — it belongs to check #1. Do not speculate about helpers whose bodies you cannot see (claim): judge the code shown and note what is out of view.credit(...) - PASS only if the method (or the body of its function) rejects the call unless the caller is a controller (
guard = "..."acted on), the owner, or a member of an admin set.is_controller(&caller) - FAIL if the only protection is anonymous rejection. , or a body that only checks
guard = "require_authenticated", still lets any signed-in principal call!= Principal::anonymous(). Aset_configattribute is evidence of nothing until you have read the guard function.guard =
Mint / burn / migrate / upgrade / config / / withdraw update 必须限制给 controller、owner 或 admin,而不能仅仅限制给 authenticated user。
set_*- 候选项: 从已枚举的 update 列表中获取每个名称任意位置包含以下内容的 method——不要求仅作为前缀——。仅按名称匹配只能找到候选项:如果 update 的可见函数体会修改 fees、ownership、其他用户的余额或 canister 全局设置,则无论其名称如何,都属于 privileged。对调用方自有账户进行操作的面向用户 method(
(?i)(mint|burn|admin|migrate|upgrade|config|set_|withdraw|transfer_from|owner|controller|pause|allowlist|whitelist)、deposit、transfer)不属于 privileged——它们归入检查 #1。不要臆测函数体不可见的 helper(例如claim):依据所示代码进行判断,并注明哪些部分不可见。credit(...) - 仅当该 method(或其 function 的函数体)会拒绝调用方,除非调用方是 controller(且
guard = "..."的结果确实被用于采取行动)、owner 或 admin set 的成员时,才能判定为is_controller(&caller)。PASS - 如果唯一的保护仅是拒绝 anonymous,则判定为 。
FAIL或仅检查guard = "require_authenticated"的函数体,仍允许任意已登录 principal 调用!= Principal::anonymous()。在读取 guard function 之前,set_configattribute 本身不能证明任何事情。guard =
4. pre_upgrade
trap risk — REVIEW
pre_upgrade4. pre_upgrade
trap 风险——REVIEW
pre_upgradeA that serializes a large or unbounded heap can exceed the
instruction limit and trap, making the canister permanently un-upgradeable.
pre_upgrade- Detect: .
rg -n '#\[(ic_cdk::)?pre_upgrade\b' -A10anyREVIEWthat serializes (pre_upgrade,stable_save,candid::encode_*) a collection (serde/Vec/HashMap/BTreeMap) whose size users can grow.String/PASSwhen state lives inN/Aand there is no manual copy.ic-stable-structures - Recommend bounding the data or moving it into .
ic-stable-structures
对大型或无界 heap 进行序列化的 可能超过 instruction limit 并 trap,使 canister 永久无法再升级。
pre_upgrade- 检测: 。如果
rg -n '#\[(ic_cdk::)?pre_upgrade\b' -A10会序列化用户可增长的数据集合(pre_upgrade/Vec/HashMap/BTreeMap),并使用String、stable_save或candid::encode_*,则标记为serde。当状态存放在REVIEW中且没有手动复制时,标记为ic-stable-structures/PASS。N/A - 建议限制数据规模,或将其移入 。
ic-stable-structures
5. Single controller / no backup — REVIEW (operator, deploy-time)
5. 单一 controller / 无备份——REVIEW(运维、部署时)
A canister controlled by one principal — especially a plaintext dev identity — is
one lost or compromised key from being unrecoverable or silently re-coded.
- Detect: this is not visible in source. Ask for, or have the operator run,
(legacy:
icp canister status <name> -e ic) and read the controller list. Require a threshold/multisig controller (e.g. an orbit station or SNS) or a documented backup controller principal held offline. A single controller isdfx canister info <id> --network ic, not an automaticREVIEW.FAIL
仅由一个 principal 控制的 canister——尤其是使用 plaintext dev identity 的 canister——只需丢失或失陷一个密钥,就可能变得不可恢复,或其控制权被悄然改写。
- 检测: 这一点无法从源代码中看出。请索取相关信息,或让运维人员运行 (旧版:
icp canister status <name> -e ic),然后读取 controller list。要求使用 threshold/multisig controller(例如 orbit station 或 SNS),或者持有离线保管且有文档记录的 backup controller principal。单一 controller 应判定为dfx canister info <id> --network ic,而不是自动判定为REVIEW。FAIL
Report format
报告格式
Target: <crate> (Rust ic-cdk canister) — N update methods
[FAIL ] #1 src/lib.rs:42 claim_bonus — credits balance, no anonymous rejection
[FAIL ] #3 src/lib.rs:57 set_config — guard require_authenticated rejects only anonymous; needs controller/owner check
[PASS ] #2 no fetch_root_key / fetchRootKey in shipped code
[N/A ] #4 no pre_upgrade; state in ic-stable-structures
[REVIEW] #5 controller set — operator to confirm a backup/multisig controller
Verdict: NOT ready to deploy (2 FAIL)A grep hit is a candidate: open the , trace the guard, and only
then mark . A must also be traced — a guard attribute or a guard-like
name proves nothing on its own. When no source is available, say so and list what
you would check rather than inventing evidence.
file:lineFAILPASSfile:lineTarget: <crate> (Rust ic-cdk canister) — N update methods
[FAIL ] #1 src/lib.rs:42 claim_bonus — credits balance, no anonymous rejection
[FAIL ] #3 src/lib.rs:57 set_config — guard require_authenticated rejects only anonymous; needs controller/owner check
[PASS ] #2 no fetch_root_key / fetchRootKey in shipped code
[N/A ] #4 no pre_upgrade; state in ic-stable-structures
[REVIEW] #5 controller set — operator to confirm a backup/multisig controller
Verdict: NOT ready to deploy (2 FAIL)grep 命中仅代表候选项:打开 ,追踪 guard,然后才能标记 。 同样必须经过追踪——guard attribute 或类似 guard 的名称本身不能证明任何事情。如果没有可用源代码,应明确说明,并列出将会检查的内容,而不是编造 证据。
file:lineFAILPASSfile:lineBoundaries
边界
This is a fast pre-deploy gate, not a full audit. It does not cover TOCTOU across
, callback-trap ordering, cycle-drain economics, or unbounded storage
growth — see the skill for those. It performs no network
or mainnet action.
awaitcanister-security这是快速的部署前门禁,而不是完整审计。它不涵盖跨 的 TOCTOU、callback-trap 排序、cycle-drain 经济性或无界 storage 增长——这些内容请参阅 skill。它不执行任何 network 或 mainnet 操作。
awaitcanister-security