agentleFS
iktok90-designiktok90-design/ai-smart-contract-auditor/skills/initialization/SKILL.md

initialization

Skill36 starsChanged 5 months agoMITView on GitHub

Detect initialization bugs in upgradeable contracts — missing `_disableInitializers()`, re-init attacks, parent-init not chained, constructor-vs-initializer confusion, public `initialize`. Activate on OZ Upgradeable, UUPS, Transparent proxy, Initializable, or any contract with `initialize` / `__init`.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add onlyOwner or onlyProxyAdmin.

    line 43
  2. Very specific:

    Verify every parent's __X_init() is chained.

    line 51
  3. Very specific:

    Test: from a fresh deploy, attempt initialize() twice and from a non-admin EOA — both should revert.

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Initialization detection

When this applies

  • OZ Initializable / *Upgradeable contracts
  • Custom upgradeable contracts with initialize() functions
  • Beacon proxies, UUPS, Transparent — all flavors
  • Factory-deployed clones (EIP-1167 minimal proxies)
  • Any deploy script that uses delegatecall for setup

Detection patterns

Implementation contract not init-locked (CRITICAL)

contract Vault is Initializable, OwnableUpgradeable {
    function initialize() external initializer {
        __Ownable_init(msg.sender);
    }
    // ← no constructor disabling initializers
}

Anyone can call initialize on the implementation address directly. Fix:

/// @custom:oz-upgrades-unsafe-allow constructor
constructor() { _disableInitializers(); }

Public initializer on deployed proxy (CRITICAL)

Proxy deployment script forgets to call initialize atomically → attacker calls it first → owns the contract. Fix: deploy + initialize in same tx via factory or initializer-on-deploy proxy.

Re-init via reinitializer(N) accessible to anyone (HIGH)

function reinitialize() external reinitializer(2) {   // ← no auth
    __Pausable_init();
}

Add onlyOwner or onlyProxyAdmin.

Parent init not called (HIGH)

function initialize() external initializer {
    // __Pausable_init() missing — pausable state defaults to wrong values
}

Verify every parent's __X_init() is chained.

Logic in constructor instead of initializer (HIGH for upgradeable)

constructor() OwnableUpgradeable() { owner = msg.sender; }   // ← runs on impl, not proxy

Upgradeable contracts must do setup in initialize, not constructor.

Constructor runs on proxy (incorrect mental model) (MEDIUM)

Devs sometimes write constructor logic expecting it to run on the proxy. It doesn't — constructor runs at deployment of the implementation, and the proxy never re-runs it.

Clones (minimal proxies) without per-clone init guard (HIGH)

EIP-1167 clones share implementation; each clone's _initialized slot starts at 0. If initialize has no auth, anyone can initialize a fresh clone before the deployer.

Re-init via storage-slot manipulation (HIGH)

OZ v4: _initialized is uint8; v5: _initialized is uint64. Custom upgradeable contracts that don't use OZ may have bypassable guards.

Severity rubric

PatternSeverity
Implementation init not disabled (anyone owns impl)Critical
Deployed proxy with public init un-calledCritical
Re-initializer with no authHigh
Clones with no atomic initHigh
Parent __init missing → broken inheritanceHigh
Constructor used instead of initializer (upgradeable)High
Initializer parameter validation missing (e.g. zero-address admin)Medium
Initial state value seems wrong (defaults to 0)Medium

Remediation patterns

  • Implementation constructor: _disableInitializers().
  • Deploy proxy + call initializer atomically (single factory tx).
  • Mark initialize as initializer, reinitialize as reinitializer(N) with auth.
  • Chain every parent's __X_init() in order matching inheritance.
  • For clones: use a factory that deploys-and-initializes in one call.
  • Test: from a fresh deploy, attempt initialize() twice and from a non-admin EOA — both should revert.

False-positive notes

  • Non-upgradeable contracts that just happen to use initialize as a name — not the same pattern.
  • Initializable used purely as a one-shot setup guard with no proxy involved — lower severity.

Related

  • [[storage-layout]]
  • [[access-control]]
  • [[delegatecall-risks]]

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.