Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,6 @@ playwright-report

scripts/harness/deployed.*.json
scripts/harness/runs

# Raw security tool output, kept as the tool wrote it
docs/evidence/scout
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,12 @@ than its pending deposits, and once a wind-down is proposed.
- [Threat model](./docs/THREAT_MODEL.md) — what can go wrong with the oracle,
the roles and the redemption paths, what stops it, what is left, and the
test for each control, with each threat placed under STRIDE.
- [STRIDE threat model](./docs/STRIDE-threat-model.md) — the threat model in
the format of Stellar's STRIDE template: a data flow diagram, numbered flows,
issues for each category and their remediations.
- [Security scan](./docs/SECURITY_SCAN.md) — what the self-service security
tools found in the contracts, how each finding was triaged, and the plan for
what stays open.
- [Monitoring plan](./docs/MONITORING_PLAN.md) — what an operator watches on
chain, where each signal comes from, and what to do when it fires.
- [Grant differences](./docs/GRANT_DIFFERENCES.md) — where the built kit
Expand Down
232 changes: 232 additions & 0 deletions docs/SECURITY_SCAN.md

Large diffs are not rendered by default.

352 changes: 352 additions & 0 deletions docs/STRIDE-threat-model.md

Large diffs are not rendered by default.

62 changes: 57 additions & 5 deletions docs/THREAT_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,28 @@ without checking the feed's state.
`fulfill_is_rejected_while_the_nav_is_paused` in
[`oracle_pricing.rs`](../contracts/async-vault/src/test/oracle_pricing.rs).

### O13. Choosing which report prices an epoch

Once an epoch's notice ends, whoever calls `fulfill_epoch` picks the moment,
and with it which valid report prices the epoch.

- **Control:** Requests are fixed when the epoch is sealed, and only a report
accepted at or after the seal can price it. Between the end of the notice and
the call, the cooldown limits how many reports can land and the caps limit
how far each one moves. Anyone may call `fulfill_epoch` as soon as the notice
ends.
- **Residual:** Whoever fulfils chooses among the reports accepted by then. A
holder who waits for a better report can be beaten by anyone who fulfils
first. A keeper that fulfils as soon as the notice ends removes the choice;
the kit runs none.
- **Tests:** `an_epoch_cannot_be_priced_inside_its_notice` in
[`notice.rs`](../contracts/async-vault/src/test/notice.rs);
`anyone_may_fulfill_a_closed_epoch` in
[`epochs.rs`](../contracts/async-vault/src/test/epochs.rs);
`attest_enforces_cooldown_and_deviation` in
[`nav-oracle/src/test/oracle.rs`](../contracts/nav-oracle/src/test/oracle.rs).
A keeper: none, because the kit runs no keeper.

## Roles

### R1. Governance compromised: the changes that wait
Expand Down Expand Up @@ -1300,6 +1322,31 @@ or queued changes.
release changes a stored type yet. The failures above are read from the
code, and a test belongs with the first release that changes one.

### X14. A call made in a holder's name

Someone requests, cancels or claims for a holder who did not sign, to move the
holder's escrow or take their payout.

- **Control:** Each request, cancellation and claim names its holder and asks
that holder to sign. The vault has no operators or approvals, so no other
account can act for a holder. A claim pays the holder, never the caller. A
wind-down claim for the vault's own address is refused (`NoEntitlement`).
- **Residual:** Whoever holds a holder's keys acts as that holder. A wallet that
signs without showing the call is outside the kit.
- **Tests:** `request_deposit_needs_the_investor_authorisation`,
`one_investor_signature_covers_the_request_and_the_transfer` and
`claiming_needs_the_investor_authorisation` in
[`deposit.rs`](../contracts/async-vault/src/test/deposit.rs);
`request_redeem_needs_the_holder_authorisation` in
[`redeem.rs`](../contracts/async-vault/src/test/redeem.rs);
`cancel_deposit_asks_the_holder_for_one_signature`,
`cancel_redeem_asks_the_holder_for_one_signature`,
`claim_redeem_asks_the_holder_for_one_signature` and
`claim_wind_down_asks_the_holder_for_one_signature` in
[`signatures.rs`](../contracts/async-vault/src/test/signatures.rs);
`the_vault_cannot_claim_against_its_own_escrowed_shares` in
[`wind_down.rs`](../contracts/async-vault/src/test/wind_down.rs).

## STRIDE

STRIDE sorts threats into six kinds: spoofing, tampering, repudiation,
Expand All @@ -1308,6 +1355,8 @@ threats above are grouped by area instead. The table places each one under the
kinds it belongs to. The sections after it say what each kind covers here, and
cover in full the three that the threats above cover least: spoofing,
repudiation and information disclosure.
[`STRIDE-threat-model.md`](./STRIDE-threat-model.md) presents the same threats
in the format of Stellar's STRIDE template, with a data flow diagram.

### Map

Expand All @@ -1328,6 +1377,7 @@ of service. E: elevation of privilege.
| [O10](#o10-the-proof-proves-nothing-on-chain) The proof proves nothing on chain | | x | x | | | |
| [O11](#o11-an-oracle-upgraded-in-place-cannot-read-its-old-report) An oracle upgraded in place cannot read its old report | | | | | x | |
| [O12](#o12-an-integrator-reads-a-price-the-vault-would-refuse) An integrator reads a price the vault would refuse | | x | | | | |
| [O13](#o13-choosing-which-report-prices-an-epoch) Choosing which report prices an epoch | | x | | | | |
| [R1](#r1-governance-compromised-the-changes-that-wait) Governance compromised: the changes that wait | | x | | | | x |
| [R2](#r2-governance-compromised-the-powers-that-act-at-once) Governance compromised: the powers that act at once | | x | | | x | x |
| [R3](#r3-setup-left-open-or-wired-wrong) Setup left open, or wired wrong | | x | | | | x |
Expand Down Expand Up @@ -1355,15 +1405,16 @@ of service. E: elevation of privilege.
| [X11](#x11-storage-that-expires) Storage that expires | | | | | x | |
| [X12](#x12-resource-limits-contention-and-griefing) Resource limits, contention and griefing | | | | | x | |
| [X13](#x13-an-upgrade-cannot-read-what-the-vault-stored) An upgrade cannot read what the vault stored | | | | | x | |
| [X14](#x14-a-call-made-in-a-holders-name) A call made in a holder's name | x | | | | | |

### Spoofing

Acting as another account, contract or person. What proves who is calling:

- **Holders.** Each request, cancellation and claim names a holder, and the
vault asks that holder to sign (`holder.require_auth()`). The vault has no
operators, so no one else can act for a holder. The calls anyone may make
check no role: pricing a sealed epoch, funding the vault, activating a
operators, so no one else can act for a holder (X14). The calls anyone may
make check no role: pricing a sealed epoch, funding the vault, activating a
wind-down that is due, finalizing a round, and sealing an epoch that has run
the minimum epoch duration. They act on ledger time and stored state, and
`fund` asks only the payer to sign.
Expand All @@ -1389,14 +1440,15 @@ Acting as another account, contract or person. What proves who is calling:
copy of the console hosted by someone else can show anything; each operator
hosts its own.

R4 and R12 hold the tests: one signature per account for each privileged call,
and the signing page's refusals.
R4, R12 and X14 hold the tests: one signature per account for each privileged
call, the signing page's refusals, and the holder's signature on each of their
calls.

### Tampering

Changing the price, the books, the code, or a transaction before it is signed:

- the price: O1, O2, O3, O5, O8, O9, O10, O12;
- the price: O1, O2, O3, O5, O8, O9, O10, O12, O13;
- code, roles and wiring: R1, R2, R3, R11;
- what a holder is owed or paid: R10, X3, X8, X9, X10;
- when an epoch is sealed: R8;
Expand Down
117 changes: 117 additions & 0 deletions docs/evidence/scout/command.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
Scout static analysis run
=========================

Date (UTC): 2026-11-12, run started 15:59:36Z, finished 16:10:58Z
Exit code: 0

Tool
----
Image: coinfabrik/scout:0.3.17
Image digest: coinfabrik/scout@sha256:216faf0b3c413cbe69770b0e2f999b9d45fa5bcb481940e8af4be1a48a7a54a5
Image created: 2026-09-25T20:14:45Z, linux/amd64 (run under amd64 emulation on an Apple Silicon host, Docker 29.8.2)
Scout version: cargo-scout-audit 0.3.17
(docker run --rm --platform linux/amd64 --entrypoint cargo coinfabrik/scout:0.3.17 scout-audit --version)
Detector toolchain: nightly-2025-09-18 (bundled in the image)

Code analysed
-------------
Worktree HEAD: 32c6c7bcec2b0fde4e138c8120fb05d6f00d1515
Tag tranche2: db90b9570af12deaace85b237678b69a8a912296 (git log -1 --format=%H db90b95)
Also equal to: 56b22d132350f2e2f26098dea1ca6734c588fd0a
`git diff db90b95 <rev> -- contracts crates Cargo.toml Cargo.lock rust-toolchain.toml`
is empty for both HEAD and 56b22d1.

Scope: one run over the whole Cargo workspace (members = crates/*, contracts/*).
Scout reports all 8 crates as analysed:
contracts: async-vault, share-token, nav-oracle, compliance, identity-verifier
crates: strata-bindings, strata-storage, strata-timelock

Step 1: copy the code to a scratch directory
-------------------------------------------
Scout writes its build output and reports into the project directory, so it ran
on a copy and the worktree was not touched.

rsync -a --exclude target --exclude node_modules --exclude .git \
<worktree>/ <scratch>/scout/src/

The copy was checked against the tagged commit:

git -C <worktree> archive db90b95 contracts crates Cargo.toml Cargo.lock rust-toolchain.toml \
| tar -x -C <scratch>/scout/verify
diff -rq verify/contracts src/contracts && diff -rq verify/crates src/crates \
&& cmp verify/Cargo.lock src/Cargo.lock && cmp verify/Cargo.toml src/Cargo.toml \
&& cmp verify/rust-toolchain.toml src/rust-toolchain.toml
-> no differences

Step 2: git hook for a dylint bug
---------------------------------
Scout builds a dylint driver at run time. dylint_driver 4.1.2 clones
https://github.com/rust-lang/rust-clippy and checks out the branch "master".
Upstream renamed that branch to "main", so without help the driver build fails with:
Error: `revparse_ext` failed for `master` ... revspec 'master' not found
The hook below only creates a local "master" branch in that clone. It does not
change Scout, its detectors or the code under analysis.

<scratch>/scout/git-hooks/post-checkout:
#!/bin/sh
case "$(git remote get-url origin 2>/dev/null)" in
*rust-lang/rust-clippy*)
git rev-parse -q --verify refs/heads/master >/dev/null || git branch master HEAD ;;
esac
exit 0

Step 3: the Scout run
---------------------
This uses the image's own entrypoint, as the scout-audit README shows. The
entrypoint runs, inside /scoutme:
cargo scout-audit --local-detectors /scout-audit/nightly --scout-source /scout-audit $INPUT_SCOUT_ARGS

docker run --rm --name scout-run6 --platform linux/amd64 \
-e SCOUT_OFFLINE=1 \
-e GIT_CONFIG_COUNT=1 -e GIT_CONFIG_KEY_0=core.hooksPath -e GIT_CONFIG_VALUE_0=/scout-fix/hooks \
-v "<scratch>/scout/git-hooks:/scout-fix/hooks:ro" \
-e INPUT_TARGET=/scoutme \
-e INPUT_SCOUT_ARGS="--output-format json,md" \
-v "<scratch>/scout/src:/scoutme" \
coinfabrik/scout:0.3.17

Notes:
- SCOUT_OFFLINE=1 turns off only Scout's telemetry and its own update check. It
does not affect detectors. The soroban-version detector still queried crates.io
and reported: latest Soroban version "29.0.1", project version "26.1.1".
- rust-toolchain.toml pins 1.97.0, so rustup installed that toolchain in the
container for the cargo command. The analysis itself compiles with Scout's
nightly-2025-09-18 toolchain.

Output files
------------
scout-report.json Scout's JSON report (written as report.json, renamed)
scout-report.md Scout's markdown report (written as report.md, renamed)
scout-console.log Console output of the run, ANSI colour codes removed

Results: 28 findings.
By severity: Critical 9, Medium 5, Minor 1, Enhancement 13
integer_overflow_or_underflow 9 Critical
dos_unexpected_revert_with_storage 5 Medium
unused_return_enum 1 Minor
soroban_version 8 Enhancement
storage_change_events 4 Enhancement
assert_violation 1 Enhancement
The markdown report's "Issues found" list counts per category but names each
category after its first detector: "Assert Violation (2 results)" is the Error
Handling category (assert_violation 1 + unused_return_enum 1), and
"Soroban Version (12 results)" is Best Practices (soroban_version 8 +
storage_change_events 4). The per-detector sections and the JSON give the exact counts.

Attempts that did not produce a report
--------------------------------------
1. Worktree mounted read-only, CARGO_TARGET_DIR=/target set for the whole
container: hung. A nested `cargo install dylint-link` waited forever on the
lock of the shared target directory.
2. Worktree read-only, target dir passed only to cargo check: failed, because
Scout builds detectors in the project's default target dir (read-only).
3. Target dir set in a scratch .cargo/config.toml: failed on the rust-clippy
"master" checkout described in step 2.
4. Same, with the git hook: failed with "--target-dir cannot be used multiple
times" (an extra `-- --target-dir /target` clashed with the one Scout passes).
5. Stopped by hand in favour of the copy-based run above.
Loading
Loading