Smart contract threat modeling workbook: goals, assumptions and evidence

Attacker-goal table: measure the claim the attacker can create

A useful smart contract threat modeling workbook connects an attacker objective to a reachable operation, an assumption and a testable security property. Its unit of analysis is the path to an unwanted outcome. A list of vulnerability names is a reference aid; it does not show which paths exist in the proposed system.

Use a deliberately hypothetical lending vault as the running example.

Users deposit an asset and receive shares. A lending component values those shares through an oracle adapter, while an administrator can update selected configuration. The example is a worksheet design, not a deployed protocol or an executed experiment. Replace each role and dependency with the actual release inventory before using it for scope.

Define outcomes before assigning severity.

An attacker might create debt without adequate backing, redeem more than their entitlement, prevent others from exiting or acquire the authority to change the rules. Those goals can share a code path while imposing different acceptance conditions. A denial of service matters differently when it blocks liquidation than when it only delays a display refresh.

For each outcome, write the smallest observable condition that would establish failure.

Avoid a statement such as the oracle is secure. Specify which operation must reject an unavailable or unsuitable valuation and which accounting relation must remain valid after the call. The worksheet should help a reviewer decide what evidence would change the conclusion.

Keep the attacker capability explicit.

A public caller, a compromised operator and an authorized but malicious administrator are different models. Combining them into an attacker with every permission can obscure a useful control; excluding every privileged compromise can make the model irrelevant to the authority that actually exists.

The model should also state what it is trying to preserve for legitimate users.

A control that prevents every withdrawal technically blocks theft through withdrawal, but it fails the intended service. Pair value-preservation properties with availability requirements so the audit does not optimize one objective by silently abandoning another.

Trust-assumption table: separate observation from belief

An assumption is a condition the security argument relies on without proving it inside the current scope. Give it an owner and evidence status. This prevents an architecture diagram from turning an external dependency into an unexplained promise.

Distinguish an observed configuration from a durable assumption.

Reading an oracle address at a particular block establishes a dated configuration. It does not establish that the address can never be replaced or that its future values will satisfy the consumer's purpose. The authority to change the dependency belongs next to the dependency itself.

Use explicit statuses such as observed, documented by the provider, unverified or outside scope.

A provider's description can support the documented status without becoming an independent verification. When the team cannot establish a condition, carry that uncertainty into the audit scope or the release decision instead of filling the cell with a reassuring adjective.

A useful assumption has a falsification condition.

For example, the asset-behavior assumption fails when actual transfers produce a balance change outside the documented model. The next step is then concrete: update the integration, reject the asset or revise the supported behavior and test it. The model should not survive unchanged merely because its original diagram still looks tidy.

The archived discussion of auditing decentralized AI introduces another dependency boundary for teams integrating model-driven services. Include the model and its operating authority in the system inventory when they influence a sensitive decision.

Dependencies can fail together. An oracle adapter, administrator interface and monitoring dashboard may rely on the same infrastructure provider. Treating them as independent protections would overstate the coverage. Record shared dependencies where they can invalidate multiple controls at once.

Scope exclusions need the same discipline. If a review excludes the signing interface, explain that interface compromise remains outside the assurance claim and identify who is responsible for reviewing it. The exclusion may be reasonable for a contract engagement, but it does not remove the risk from the operating system.

OWASP threat modeling process supports the progression from system understanding through threats and mitigations. The evidence statuses here make that progression reviewable for a protocol release.

Privileged-role table: follow the administrative root

A role name describes an intention. Reachability describes authority. Follow each privileged account through the functions it can call and the controllers it can change, including roles that can grant other roles. A diagram that stops at the target's immediate owner can miss the account that replaces that owner.

OpenZeppelin access-control guidance distinguishes ownership from role-based permissions and role administration. Safe module documentation adds an example of alternate execution authority: an enabled module can submit transactions through a path that differs from the ordinary owner-signature mechanism. These are separate semantic nodes in the model, even if a user interface places them on one settings page.

The worksheet should distinguish capability, holder and replacement procedure. An account may currently hold no asset-moving role while retaining the right to grant one. Removing its visible minter permission would not establish revocation of that administrative root. The review needs the transitive path to the sensitive operation.

Do not equate several keys with independent approval. The model can record a required independence condition, but contract source does not prove device custody or organizational separation. Mark that evidence as operational and assign an owner to establish it.

Consider both malicious use and loss of access. A timelock administrator can be a theft risk if compromised and an availability risk if inaccessible. The response plan should specify which operations remain possible under either condition. A threat model that includes only an attacker gaining a role misses the failures caused by a legitimate operator losing it.

Use this table to decide which specialist work is needed. Contract review can examine role enforcement. A separate operational assessment may need to examine credential handling and recovery. The final assurance statement should identify which evidence came from which review so a reader does not infer that one report covered both.

The admin authority inventory supplies the operational handoff. Keep its account and controller identifiers consistent with the source revision in the threat model.

Our report check: five signals did not mean five DeFi threat models

The fixed sample produced 5 reports with threat-model or trust-assumption wording. Reading each match changed the interpretation: 3 were severity-method boilerplate, 1 was a mobile-security checklist entry marked not applicable and 1 was an actual threat-model report for a non-DeFi system.

Method

Retrieved

September 5, 2026

Member frame

23 firms in the fixed research roster, including historical names.

Report frame

155 previously sampled archive entries.

Selection

The first 3 entries per firm from the earlier deterministic archive sample, fetched again for this study. No content-based selection.

Readable denominator

50 selected reports.

Archive coverage

17 sampled archives.

Cap exclusions

105 report entries excluded before reading.

Missing archive coverage

6 firms have no report in this frame.

Signal

Case-insensitive term matching in converted report text. Exact expressions and surrounding text are retained in the output.

Results

Within this selection, the non-DeFi report is Trail of Bits Mosquitto threat model. It is useful evidence of document structure, not proof of a DeFi engagement. The classifications are retained in seo/research/security-scope-disclosures-classification-2026-09-05.json. No conclusion is drawn about unpublished work or firms without matching wording.

Limits

• The frame includes multiple languages, non-contract assessments and older reports. It is a disclosure sample, not a random sample of deployed protocols.
• A matching term may be a checklist item, a library identifier or a project finding. Only separately reviewed examples support finding-level conclusions.
• Archive ownership does not establish report authorship. Some archives contain outside assessments of the archive owner's software.
• No live exploit was executed. An absent match can reflect terminology or text extraction and cannot establish that a firm lacks the capability.

Reproduction uses seo/research/security-scope-disclosures-survey.py; its dated output is seo/research/security-scope-disclosures-survey-2026-09-05.json. These files remain in the repository and are not published as downloads. The output preserves source responses, retrieval outcomes and the selection rules for later verification.

STRIDE mapped to the DeFi example

STRIDE is a set of threat categories used to organize questions. It covers spoofing, tampering, repudiation, information disclosure, denial of service and elevation of privilege. Microsoft's description supplies the category meanings; the mappings below are editorial applications to the hypothetical lending vault.

Apply the categories at a boundary. A public transaction, an oracle observation and an operator's signing session have different trust relationships. Asking each category against the whole protocol at once tends to produce broad statements with no target or test.

The categorization is not a completeness proof. Economic manipulation can cross several categories or fit awkwardly into one. Preserve the attacker-goal row even when the team cannot agree on its label. The goal and violated property determine useful audit work; the label should help organize that work rather than decide whether it exists.

Repudiation requires care in a public-chain system. A transaction records an address and payload, but that record does not establish which human reviewed a signing interface or whether the interface displayed the same action. The on-chain evidence and the operational approval record answer different questions.

Information disclosure also extends beyond contract storage. A public contract does not make its operator's credentials public by design. Conversely, a declaration that a state variable is private is not a confidentiality guarantee for blockchain data. Identify the actual secret and the environment where it is supposed to remain secret.

For denial of service, measure the consequence in the user journey. An unavailable reporting endpoint differs from a blocked withdrawal or liquidation. Specify whether the protocol can reject new risk while preserving actions needed to reduce it. That distinction makes prioritization more defensible than assigning the same severity to every revert.

Threat at boundary

State the unwanted outcome.

Security property

Define what must hold.

Audit evidence

Test or scoped unknown.

Microsoft STRIDE category definitions provides the terminology. This worksheet does not claim that category coverage alone establishes protocol security.

Turning the output into audit scope

Convert the workbook into a set of review obligations. Each important goal should map to a source boundary, an invariant or requirement and the evidence expected from the reviewer. Unresolved assumptions become scope questions, not background notes that disappear when code review begins.

Prioritize by the consequence and the reachable path. A capability that can replace all logic deserves attention even if the function is short. An unsupported token behavior can invalidate accounting across many functions without appearing as a complex algorithm. Explain why each priority matters to the release so the reviewer can challenge the ordering.

Use an acceptance table that separates work performed from conclusions established. A test may run successfully while covering only a mock dependency. A manual review may accept an administrative risk while confirming that the permission check works exactly as designed. Those outcomes should not be summarized as a single undifferentiated pass.

The model needs a revision policy. A new asset, controller, oracle or upgrade mechanism can change the security argument even when the application's headline feature remains the same. Link the model to the release and revisit the affected rows when those dependencies change. Keeping the old model as a dated artifact makes the change review easier.

Do not assign a numerical risk score merely to make the workbook look quantitative. If the team lacks a defensible likelihood estimate, use explicit assumptions and consequence descriptions. A precise-looking score can conceal more uncertainty than a well-supported qualitative decision.

For procurement, request comparable evidence from each candidate reviewer. The audit RFP guide and scope builder help turn these rows into deliverables. The Halborn analysis is one provider reference; ask the selected team to demonstrate the relevant work rather than relying on a general service label.

The completed workbook should allow a second reviewer to identify what remains unknown. That is a practical quality criterion: they should be able to locate the assumption, its owner and the decision it affects without interviewing the original author. Resolve the release-critical unknowns, document accepted limits and preserve the evidence with the final source revision.