icp-deploy-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ICP 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
canister-security
skill — this skill is the checklist, that one is the reference.
Scope: every update entrypoint and the
init
/
pre_upgrade
/
post_upgrade
hooks in the Rust
ic-cdk
canister(s), plus any frontend or agent code in the same repo (check #2 only). Produce one row per check:
PASS
/
FAIL
/
REVIEW
/
N/A
with
file:line
evidence.
在 Rust canister 仓库上运行此静态、只读门禁,部署至 mainnet 之前执行。它只读取源代码并生成报告;绝不执行部署,绝不调用 mainnet,也绝不需要密钥。各项检查背后的修复模式位于
canister-security
skill 中——这个 skill 是检查清单,那个是参考资料。
范围:Rust
ic-cdk
canister 中的每个 update 入口点及
init
/
pre_upgrade
/
post_upgrade
hook,以及同一仓库中的任何 frontend 或 agent 代码(仅适用检查 #2)。每项检查输出一行:
PASS
/
FAIL
/
REVIEW
/
N/A
,并附带
file:line
证据。

Enumerating update entrypoints

枚举 update 入口点

Checks #1 and #3 both start from the full list of update methods. Match the attribute with or without arguments —
#[update(guard = "...")]
,
#[update(name = "...")]
and
#[ic_cdk::update(manual_reply = true)]
are all entrypoints:
bash
rg -n -A4 '#\[(ic_cdk::)?update\b'
\b
matches both
update]
and
update(
; a bare
'update\]'
pattern silently skips every parameterized entrypoint. Record each method's name, its attribute arguments (especially
guard = "..."
), and its body.
Callers are read with
ic_cdk::api::msg_caller()
(ic-cdk >= 0.18). Older code uses
ic_cdk::caller()
/
ic_cdk::api::caller()
— treat them as equivalent when tracing.
检查 #1 和 #3 都从完整的 update 方法列表开始。匹配 attribute 时要涵盖带参数和不带参数两种形式——
#[update(guard = "...")]
、
#[update(name = "...")]
和
#[ic_cdk::update(manual_reply = true)]
均为入口点:
bash
rg -n -A4 '#\[(ic_cdk::)?update\b'
\b
可同时匹配
update]
和
update(
;只使用裸模式
'update\]'
会悄悄漏掉所有带参数的入口点。记录每个方法的名称、attribute 参数(尤其是
guard = "..."
)及其函数体。
调用方通过
ic_cdk::api::msg_caller()
读取(ic-cdk >= 0.18)。旧代码使用
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
Principal::anonymous()
before its first mutation.
  • Trace, don't pattern-match. For each update that mutates state (writes a
    thread_local!
    /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 (
    trap
    ,
    Err
    return, or guard
    Err
    ) when the caller is anonymous. Accept any of:
    • an explicit comparison against
      Principal::anonymous()
      (
      ==
      with trap/return, or
      !=
      gating the mutation), on
      msg_caller()
      or a variable bound to it;
    • a
      guard = "fn_name"
      attribute — open
      fn_name
      and confirm its body returns
      Err
      for the anonymous principal;
    • 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 —
      RefCell::new(Principal::anonymous())
      as the default owner with no
      require_authenticated
      first means anonymous is the owner until
      init
      runs.
  • Not authentication — FAIL if these are the only "guard":
    • CallerGuard
      / per-caller locks /
      PENDING
      sets: these are reentrancy locks, they accept the anonymous principal like any other;
    • a guard identified only by its name (
      require_caller
      ,
      check_access
      , ...) without reading its body;
    • is_controller(...)
      or a comparison whose result is computed but never acted on, or that runs after the mutation.
  • An update that is deliberately open to anonymous callers (e.g. a public counter, an open sign-up whose cost is bounded) is
    REVIEW
    , not
    FAIL
    — state why it is intended. Query methods cannot persist state and are out of scope.
每个会改变状态的 update 都必须在首次 mutation 之前拒绝
Principal::anonymous()
。
  • 追踪,不要只做模式匹配。 对于每个会改变状态的 update(写入
    thread_local!
    /stable structure、贷记/借记余额、mint、设置 config、执行会改变状态的 inter-canister call),确认通往该 mutation 的每条路径都会在调用方为 anonymous 时拒绝调用(
    trap
    、
    Err
    返回或 guard 返回
    Err
    )。接受以下任一方式:
    • 显式比较
      Principal::anonymous()
      (使用
      ==
      并 trap/返回,或使用
      !=
      控制 mutation),比较对象为
      msg_caller()
      或绑定到它的变量;
    • guard = "fn_name"
      attribute——打开
      fn_name
      ,确认其函数体会对 anonymous principal 返回
      Err
      ;
    • controller/owner/allowlist 检查会拒绝调用方(anonymous 永远不能成为 controller)。只有当 owner 永远不可能是 anonymous 时,owner 相等性检查才算有效——如果以
      RefCell::new(Principal::anonymous())
      作为默认 owner,且此前没有执行
      require_authenticated
      ,那么在
      init
      运行前,anonymous 就是 owner。
  • 这不算身份认证——如果以下内容是唯一的“guard”,则判定为 FAIL:
    • CallerGuard
      / per-caller lock /
      PENDING
      set:这些是 reentrancy lock,与其他 principal 一样,它们会接受 anonymous principal;
    • 仅凭名称识别的 guard(
      require_caller
      、
      check_access
      等),却没有读取其函数体;
    • is_controller(...)
      或某种比较,其结果虽然被计算,却从未用于采取行动,或者检查发生在 mutation 之后。
  • 如果某个 update 有意对 anonymous 调用方开放(例如公开 counter,或成本受限的开放注册),则判定为
    REVIEW
    ,而非
    FAIL
    ——需说明其设计意图。Query method 无法持久化状态,不在检查范围内。

2.
fetch_root_key
in shipped code — FAIL if present

2. 发布代码中存在
fetch_root_key
——存在则 FAIL

fetch_root_key()
(Rust
ic-agent
) /
fetchRootKey()
(JS agent) fetches the root public key from the replica it is talking to and trusts it. If that code runs against mainnet, a man-in-the-middle can substitute its own key and forge every certified response. This lives in frontend or agent/client code, not in the canister, so scan the whole repo:
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
    ,
    #[cfg(feature = "local")]
    ): environment branching is how the call leaks into production builds. The fix is to stop fetching it: pass the root key from the
    ic_env
    cookie (
    IC_ROOT_KEY
    , via
    safeGetCanisterEnv()
    ) as
    rootKey
    to
    HttpAgent.create()
    . See
    canister-security
    for the full pattern.
  • Not a finding: test-only code (
    #[cfg(test)]
    ,
    tests/
    , PocketIC harnesses, scripts that only ever target a local replica) — mark
    PASS
    with a note.
fetch_root_key()
(Rust
ic-agent
)/
fetchRootKey()
(JS agent)会从其正在通信的 replica 获取 root public key 并信任该 key。如果该代码针对 mainnet 运行,中间人攻击者可以替换成自己的 key,并伪造每一个已认证响应。该代码位于 frontend 或 agent/client 代码中,而非 canister 中,因此需要扫描整个仓库:
bash
rg -n 'fetch_root_key|fetchRootKey|shouldFetchRootKey'
  • 只要在已发布的 frontend 或 client 路径中出现任何匹配项,就判定为 FAIL——即使它位于环境检查之后(
    if network === "local"
    、
    process.env.DFX_NETWORK
    、
    #[cfg(feature = "local")]
    ):环境分支正是调用泄漏到 production build 的途径。修复方式是停止获取该 key:将
    ic_env
    cookie 中的 root key(
    IC_ROOT_KEY
    ,通过
    safeGetCanisterEnv()
    获取)作为
    rootKey
    传给
    HttpAgent.create()
    。完整模式请参阅
    canister-security
    。
  • 不构成问题: 仅用于测试的代码(
    #[cfg(test)]
    、
    tests/
    、PocketIC harness,以及仅指向 local replica 的脚本)——标记为
    PASS
    并附注说明。

3. Unguarded admin / privileged method — FAIL if not privileged-guarded

3. 无防护的 admin / privileged method——未受 privileged guard 保护则 FAIL

Mint / burn / migrate / upgrade / config /
set_*
/ withdraw updates must be restricted to a controller, owner or admin — not merely to authenticated users.
  • Candidates: from the enumerated update list (not a separate grep), take every method whose name contains — anywhere, not only as a prefix —
    (?i)(mint|burn|admin|migrate|upgrade|config|set_|withdraw|transfer_from|owner|controller|pause|allowlist|whitelist)
    . 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 (
    deposit
    ,
    transfer
    ,
    claim
    ) is not privileged — it belongs to check #1. Do not speculate about helpers whose bodies you cannot see (
    credit(...)
    ): judge the code shown and note what is out of view.
  • PASS only if the method (or the body of its
    guard = "..."
    function) rejects the call unless the caller is a controller (
    is_controller(&caller)
    acted on), the owner, or a member of an admin set.
  • FAIL if the only protection is anonymous rejection.
    guard = "require_authenticated"
    , or a body that only checks
    != Principal::anonymous()
    , still lets any signed-in principal call
    set_config
    . A
    guard =
    attribute is evidence of nothing until you have read the guard function.
Mint / burn / migrate / upgrade / config /
set_*
/ withdraw update 必须限制给 controller、owner 或 admin,而不能仅仅限制给 authenticated user。
  • 候选项: 从已枚举的 update 列表中获取每个名称任意位置包含以下内容的 method——不要求仅作为前缀——
    (?i)(mint|burn|admin|migrate|upgrade|config|set_|withdraw|transfer_from|owner|controller|pause|allowlist|whitelist)
    。仅按名称匹配只能找到候选项:如果 update 的可见函数体会修改 fees、ownership、其他用户的余额或 canister 全局设置,则无论其名称如何,都属于 privileged。对调用方自有账户进行操作的面向用户 method(
    deposit
    、
    transfer
    、
    claim
    )不属于 privileged——它们归入检查 #1。不要臆测函数体不可见的 helper(例如
    credit(...)
    ):依据所示代码进行判断,并注明哪些部分不可见。
  • 仅当该 method(或其
    guard = "..."
    function 的函数体)会拒绝调用方,除非调用方是 controller(且
    is_controller(&caller)
    的结果确实被用于采取行动)、owner 或 admin set 的成员时,才能判定为
    PASS
    。
  • 如果唯一的保护仅是拒绝 anonymous,则判定为
    FAIL
    。
    guard = "require_authenticated"
    或仅检查
    != Principal::anonymous()
    的函数体,仍允许任意已登录 principal 调用
    set_config
    。在读取 guard function 之前,
    guard =
    attribute 本身不能证明任何事情。

4.
pre_upgrade
trap risk — REVIEW

4.
pre_upgrade
trap 风险——REVIEW

A
pre_upgrade
that serializes a large or unbounded heap can exceed the instruction limit and trap, making the canister permanently un-upgradeable.
  • Detect:
    rg -n '#\[(ic_cdk::)?pre_upgrade\b' -A10
    .
    REVIEW
    any
    pre_upgrade
    that serializes (
    stable_save
    ,
    candid::encode_*
    ,
    serde
    ) a collection (
    Vec
    /
    HashMap
    /
    BTreeMap
    /
    String
    ) whose size users can grow.
    PASS
    /
    N/A
    when state lives in
    ic-stable-structures
    and there is no manual copy.
  • Recommend bounding the data or moving it into
    ic-stable-structures
    .
对大型或无界 heap 进行序列化的
pre_upgrade
可能超过 instruction limit 并 trap,使 canister 永久无法再升级。
  • 检测:
    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,
    icp canister status <name> -e ic
    (legacy:
    dfx canister info <id> --network 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 is
    REVIEW
    , not an automatic
    FAIL
    .
仅由一个 principal 控制的 canister——尤其是使用 plaintext dev identity 的 canister——只需丢失或失陷一个密钥,就可能变得不可恢复,或其控制权被悄然改写。
  • 检测: 这一点无法从源代码中看出。请索取相关信息,或让运维人员运行
    icp canister status <name> -e ic
    (旧版:
    dfx canister info <id> --network ic
    ),然后读取 controller list。要求使用 threshold/multisig controller(例如 orbit station 或 SNS),或者持有离线保管且有文档记录的 backup controller principal。单一 controller 应判定为
    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
file:line
, trace the guard, and only then mark
FAIL
. A
PASS
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
file:line
evidence.
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)
grep 命中仅代表候选项:打开
file:line
,追踪 guard,然后才能标记
FAIL
。
PASS
同样必须经过追踪——guard attribute 或类似 guard 的名称本身不能证明任何事情。如果没有可用源代码,应明确说明,并列出将会检查的内容,而不是编造
file:line
证据。

Boundaries

边界

This is a fast pre-deploy gate, not a full audit. It does not cover TOCTOU across
await
, callback-trap ordering, cycle-drain economics, or unbounded storage growth — see the
canister-security
skill for those. It performs no network or mainnet action.
这是快速的部署前门禁,而不是完整审计。它不涵盖跨
await
的 TOCTOU、callback-trap 排序、cycle-drain 经济性或无界 storage 增长——这些内容请参阅
canister-security
skill。它不执行任何 network 或 mainnet 操作。