Skip to content

docs: add the STRIDE template and the security scan - #449

Merged
hpmaxi merged 2 commits into
docs/438-stride-threat-modelfrom
docs/443-audit-bank-evidence
Nov 13, 2026
Merged

hpmaxi merged 2 commits into
docs/438-stride-threat-modelfrom
docs/443-audit-bank-evidence

Conversation

@hpmaxi

@hpmaxi hpmaxi commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #443

The SCF Audit Bank asks for two pieces with the application: a STRIDE threat model, and the results of a self-service security tool with a plan for what stays open. #442 maps the threat model to STRIDE inside docs/THREAT_MODEL.md, but not in the shape of Stellar's template, and nothing records a scan. This adds both as documents a reviewer can read on their own.

Stacked on #442: it builds on that mapping and should merge after it.

Changes

  • A STRIDE document in the template's four sections: a data flow diagram with trust boundaries, 13 numbered flows, 30 issues across the six categories and their remediations, the Soroban checks and eight investigation points.
  • Two new threats in the threat model: a call made in a holder's name (X14) and the choice of which report prices an epoch (O13).
  • A security scan document: every Scout, Almanax, Certora and Security Portal finding with its triage, and a remediation plan.
  • Scout's raw report, command and version, committed as evidence.
  • An issue for the one new bug the sweep found (A zero-asset redemption from a delisted holder stays stuck and keeps its epoch open #445).
  • The README links both documents.

Deviations

  • Scout ran in Docker on a copy of 56b22d1, whose code equals the tranche2 tag, with a git hook for a dependency's branch rename.
  • Raw output is committed for Scout only; the other three tools appear as triaged findings.
  • The plan's dates read "before the audit starts", not a fixed day.
  • Four issues about what the whole ledger records point to the threat model's Repudiation and Information disclosure sections, not an O/R/X id.

Acceptance criteria

A. STRIDE in the template's format

  • docs/STRIDE-threat-model.md has the template's four headings, the STRIDE reminders table as written, and answers the five closing questions
  • At least one Mermaid data flow diagram: actors, contracts, the off-chain parts (console, investor app, attester, keeper) and external contracts; every trust boundary a subgraph; every arrow numbered with its step and the call it carries
  • Numbered happy-path flows for deposit, request, epoch close, attest, fulfil, claim and a timelocked admin change, so a threat can cite a step
  • Each of S, T, R, I, D, E has at least one issue (Spoof.1, Tamper.1, …), each with its attacker, the step it targets and what it breaks
  • Each issue points to the O/R/X threat in docs/THREAT_MODEL.md that already treats it, instead of restating it; an issue with no threat there becomes a new threat or a follow-up issue
  • Each issue has at least one remediation (Spoof.1.R.1, …) marked In place (with the code or test), Recommended or Accepted (with the reason and the risk that remains)
  • The Soroban checks are each answered with a link or become an issue or an investigation point: overflow-checks in the release profile, upgrades through update_current_contract_wasm, __constructor and a second init, TTL and archival, require_auth on the right address
  • What cannot be confirmed from the repo is listed as investigation points (IP.N) in the last section
  • The README links the document

B. Self-service scan and remediation plan

  • The tool is one of those on Stellar's security tools page that reads code (Scout, Almanax or Certora Sunbeam). The choice, the version, the command and the crates scanned are written down
  • It runs on every contract in scope (async-vault, share-token, nav-oracle, compliance, identity-verifier, and the shared crates they use); the raw report is committed
  • docs/SECURITY_SCAN.md lists every finding with its severity, its location and its triage: fixed, false positive (with why) or accepted (with why)
  • The remediation plan covers each critical, high and medium finding that stays open: the fix, who does it, the issue that tracks it and a date before the audit starts
  • Findings already fixed link their PR; open ones have an issue
  • The README links the document

Test plan

Automated tests

None: documentation only. Checks run on the changed files:

  1. Every relative link and anchor in the four changed documents resolves.
  2. Every Rust test the new text cites exists as a function under contracts/ or crates/, and every console test title exists in the app's tests.
  3. Every issue in the STRIDE document has a remediation, and every step it cites exists in the numbered flows.
  4. The Mermaid diagram parses with Mermaid 11 as a flowchart-v2.
  5. Every Scout hit in scout-report.json appears in SECURITY_SCAN.md with its file and line.

Manual verification

  1. Open docs/STRIDE-threat-model.md on the branch: the diagram renders, and each issue links to its threat.
  2. Open docs/SECURITY_SCAN.md: each Scout hit matches a line in docs/evidence/scout/scout-report.md.
  3. To rerun Scout, follow docs/evidence/scout/command.txt. You should get the same 28 hits from 6 detectors.

Breaking changes

None.

Checklist

  • Self-reviewed my own diff
  • Tests added or updated
  • Docs updated (if applicable)
  • No unrelated changes bundled in

Screenshots

None.

Present the threat model in the shape the Audit Bank asks for: a data
flow diagram with its trust boundaries, numbered flows, issues for each
STRIDE category with their remediations, the Soroban checks and the
points the repository cannot confirm. Each issue points to the threat
that holds its control and tests instead of restating it.

Two risks had no threat of their own and get one: a call made in a
holder's name (X14) and the choice of which report prices an epoch
(O13).
@hpmaxi hpmaxi added documentation Improvements or additions to documentation priority: high epic:docs Runbook, README, contributing, release tranche-3 Grant Tranche 3 work labels Nov 12, 2026
@vercel

vercel Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
strata-vault-kit-app Ready Ready Preview Nov 12, 2026 5:56pm UTC

Request Review

Record what the self-service security tools found in the contracts and
how each finding was triaged. Scout is the tool of record: its version,
command and raw report are committed, and its 28 hits match an earlier
run on the tranche2 tag. Almanax, Certora Sunbeam and a check against
the Soroban Security Portal add their findings and proofs.

No critical, high or medium finding from the scanners is a new bug. The
plan covers the three open bugs the sweep found or confirmed.

@luchobonatti luchobonatti left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall. A few suggestions inline.

Comment thread docs/SECURITY_SCAN.md
`main`. [`command.txt`](./evidence/scout/command.txt) has every step.
- **Raw report.** [`scout-report.json`](./evidence/scout/scout-report.json),
[`scout-report.md`](./evidence/scout/scout-report.md) and the console output
[`scout-console.log`](./evidence/scout/scout-console.log). The summary list at

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scout-console.log doesn't seem to be in the PR (also command.txt:90). Maybe commit it or drop both references?

Comment thread docs/SECURITY_SCAN.md
The [Soroban Security Portal](https://sorobansecurity.com) is a public database of
vulnerabilities found in audits of other Stellar projects, not a scanner. Of
its 954 published vulnerabilities, the 340 rated critical, high or medium were
grouped into 16 kinds, and each kind was checked against Strata.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table has 17 rows; P0A (#445) is our own finding rather than a Portal entry. Maybe move it to a separate manual-review line?

Comment thread docs/SECURITY_SCAN.md
| Item | Severity | Fix | Who | Tracked in | By |
| --- | --- | --- | --- | --- | --- |
| A zero-share deposit refund blocked by cash dust | Medium | Release the dust so the refund pays, in the same change as the next row | Strata team (BootNode) | [#434](https://github.com/BootNodeDev/strata-vault-kit/issues/434) | Before the audit starts |
| A zero-asset redemption from a delisted holder stays stuck (P0A) | Low | Let the request settle when the holder cannot receive its shares, for example by burning them as a wind-down claim does, so the epoch reconciles | Strata team (BootNode) | [#445](https://github.com/BootNodeDev/strata-vault-kit/issues/445) | With #434 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#445 is priority: medium on the issue. Maybe align both here and in the Portal table?

Comment thread docs/SECURITY_SCAN.md

| Item | Severity | Fix | Who | Tracked in | By |
| --- | --- | --- | --- | --- | --- |
| A zero-share deposit refund blocked by cash dust | Medium | Release the dust so the refund pays, in the same change as the next row | Strata team (BootNode) | [#434](https://github.com/BootNodeDev/strata-vault-kit/issues/434) | Before the audit starts |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#443 asks for a date in this column. Maybe a target date instead of "Before the audit starts"?

[STRIDE template](https://developers.stellar.org/docs/build/security-docs/threat-modeling/STRIDE-template).
Each issue below points to the threat in [`THREAT_MODEL.md`](./THREAT_MODEL.md)
that holds its full control, residual risk and tests, instead of restating
them. Three issues are about what the whole ledger records or shows rather than

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Four, maybe? Repudiate.3/.4 and Info.1/.4.

control in place with a test. The recommended ones are tracked in issues or
listed as investigation points below. The accepted ones give the reason and
the risk that remains.
- **Have additional issues been found after the threat model?** The security

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add #435 here too?

@hpmaxi
hpmaxi merged commit 0e62656 into docs/438-stride-threat-model Nov 13, 2026
10 checks passed
@hpmaxi
hpmaxi deleted the docs/443-audit-bank-evidence branch November 13, 2026 15:32

This branch was successfully deployed

1 active deployment
Preview — 24eeeeb7 Deployed Nov 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation epic:docs Runbook, README, contributing, release priority: high tranche-3 Grant Tranche 3 work

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants