From fe4ba366665171b471bb5282c7af382f3d7a6b71 Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 09:56:38 -0500 Subject: [PATCH 01/12] add the monitoring template for builders --- .../monitoring-template-builders.mdx | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/build/security-docs/monitoring-template-builders.mdx diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx new file mode 100644 index 0000000000..015fe42ab9 --- /dev/null +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -0,0 +1,94 @@ +--- +title: On-Chain Monitoring Plan Template (Builders) +--- + +This template turns a completed [threat model](./threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks what could go wrong and how will we design against it, this plan asks how will we watch for it in production. Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. + +**Directions**: fill out each section below to the best of your ability. Carry your threat identifiers over from your STRIDE threat model so the two documents stay linked. Work through the sections in order; every threat should leave the exercise with at least one monitor and a defined response. + +**Keep completed plans internal.** A filled-in monitoring plan is a map of what you do — and don't — watch for. Publish the blank template; treat a populated version as sensitive. + +## What are we monitoring? + +**Directions**: describe the system in scope, then inventory the components and on-chain addresses this plan covers. + +_Input text: high-level description of the protocol, the value it holds, and the parts of it this plan covers._ + +| Component | On-chain address (`C...` contract / `G...` account) | Notes | +| --- | --- | --- | +| _e.g. Lending pool core_ | _C..._ | _Holds pooled collateral and debt_ | +| | | | + +**Note**: keep this inventory current. Addresses can change with new versions, and an out-of-date address list is the most common reason a monitor silently stops working. If it's discovered later that scope has changed, update this section with the latest information. + +## What could go wrong? + +**Directions**: list the threats this plan monitors, carried over from your threat model. Reuse the identifiers from your STRIDE model (for example, `Elevation.1`) so each monitor traces back to a known threat. Assign each threat a severity using the reminders below. + +### Severity reminders + +| Severity | Meaning | +| --- | --- | +| **Critical** | Direct, large-scale loss of funds or control; requires immediate response. | +| **High** | Serious impact to funds, users, or availability; requires prompt response. | +| **Medium** | Limited or containable impact; response can be scheduled. | +| **Low** | Minor or informational; monitored for awareness. | + +### Threat register + +| Threat ID | Threat (from threat model) | Affected component | Severity | +| --- | --- | --- | --- | +| _Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core — access control_ | _Critical_ | +| | | | | + +## What does exploitation look like on-chain? + +**Directions**: for each threat, describe how exploitation might unfold and the observable on-chain effect(s) it would leave behind. There can be several scenarios, and several effects, per threat. + +| Threat ID | Exploitation scenario | Observable on-chain effect(s) | +| --- | --- | --- | +| _Elevation.1_ | _A leaked admin key reassigns ownership, then raises borrow caps and drains reserves._ | _`set_admin` / ownership-transfer event; privileged parameter change from a non-allowlisted caller_ | +| | | | + +:::note + +If a threat has no observable on-chain effect (for example, a compromised frontend or an oracle's upstream data source), record it here and plan to monitor it off-chain — don't drop it just because it isn't visible on-chain. + +::: + +## What will we monitor for? + +**Directions**: map each observable effect to a monitoring rule, stating the trigger condition and the baseline that makes it meaningful. Uniquely identify each monitor as `.M.` so it traces back to its threat — the same way remediations in your threat model are identified as `.R.`. + +| Monitor ID | Observable on-chain effect | Trigger condition & baseline | Monitoring rule (plain-language intent) | +| --- | --- | --- | --- | +| _Elevation.1.M.1_ | _Owner/admin address changes_ | _Any set_admin event. Baseline: zero — never expected in normal operation._ | _Alert immediately on any admin change on the core contract._ | +| _Elevation.1.M.2_ | _Privileged call from an unexpected address_ | _Caller not in the known-admin allowlist. Baseline: only the multisig calls these._ | _Alert on privileged calls from non-allowlisted addresses._ | +| | | | | + +Each monitor can be stated in a single line: + +- We address **[Threat ID]** in **[affected component]** by monitoring for **[on-chain effect]** on **[address]**. +- _For example: **Elevation.1.M.1** - We address **Elevation.1** in **the lending pool factory** by monitoring for **deploy invocations from users not on an approved list** at address **CABC123...**._ + +## What happens when an alert fires? + +**Directions**: for each monitor, define what happens when it triggers — who is notified, through which channel, any automated action, and who owns the rule. This is where your monitoring vendor's automated-response capability (for example, pausing a contract) is recorded. + +| Monitor ID | Severity | Response / action (who, channel, automated action) | Owner | Status | Last reviewed | +| --- | --- | --- | --- | --- | --- | +| _Elevation.1.M.1_ | Critical | Page on-call security (PagerDuty + Slack); trigger guardian pause; open incident bridge. | Protocol Security | Active | YYYY-MM-DD | +| | | | | | | + +**Status values**: _Active_ (live and alerting), _Tuning_ (live but thresholds being refined), _Planned_ (agreed but not yet implemented). + +## Did we do a good job? + +- Does every threat in your threat model have at least one monitor, or a documented reason it can't be monitored on-chain? +- Is every trigger threshold grounded in an actual baseline rather than a guess? +- Does every monitor have a defined response, an owner, and a status? +- Have any monitors fired? Were they true positives, and did the response work as written? +- Are all on-chain addresses still current after the latest deploy or upgrade? +- Were any threats found that only surface off-chain, needing a different kind of monitoring? + +Treat this plan as a living document: revisit it whenever your contracts, addresses, or threat model change. From ab91215bf23e3f085bee3d4ef5d6d53ce8420bf0 Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 10:07:42 -0500 Subject: [PATCH 02/12] add position monitoring template for users --- .../monitoring-template-users.mdx | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/build/security-docs/monitoring-template-users.mdx diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring-template-users.mdx new file mode 100644 index 0000000000..929c98f4c9 --- /dev/null +++ b/docs/build/security-docs/monitoring-template-users.mdx @@ -0,0 +1,72 @@ +--- +title: Position Monitoring Plan Template (Users) +--- + +This template helps you — as someone holding positions on Stellar — set up monitoring for what you own, without needing a formal threat model. Fill in one row per position or wallet you care about: what could go wrong, when you want to be alerted, and what you'll do about it. + +**Directions**: fill out each section below to the best of your ability. Keep the same position in the same row across every table so the plan reads straight across. + +## What am I protecting? + +**Directions**: list the positions and wallets you hold and care about. + +_Input text: a short description of each position and where it lives._ + +| Position | Wallet / position address (`G...` account / `C...` contract) | Value at risk (optional) | +| --- | --- | --- | +| _e.g. XLM collateral in a lending position_ | _G..._ | _Dollar amount or percentage_ | +| | | | + +## What would going wrong look like? + +**Directions**: in plain language, note what "something going wrong" would look like for each position, and how much you'd care using the reminders below. + +### How worried am I? + +| Level | Meaning | +| ------------------- | ------------------------------------------- | +| **Drop everything** | I need to act right now to avoid loss. | +| **Important** | I want to know quickly and will act soon. | +| **Keep an eye** | Useful to know; I'll check when convenient. | +| **Low** | Informational only. | + +| Position | What "going wrong" looks like | How worried am I | +| --- | --- | --- | +| _XLM collateral..._ | _My position drifts toward liquidation; the protocol's admin changes unexpectedly; the pool drains suddenly._ | _Important_ | +| | | | + +## What will alert me? + +**Directions**: turn each worry into a specific condition you can be alerted on, and choose how you want to be notified. + +| Position | Alert me when... | Notify me by | +| --- | --- | --- | +| _XLM collateral..._ | _Health factor drops below 1.5; any admin change on the market; pool liquidity falls more than 30% in an hour._ | _Push + Telegram_ | +| | | | + +:::note + +Don't assume the protocol is watching your specific position. Its monitoring is tuned to the health of the whole system; yours should be tuned to your seat. + +::: + +## What will I do? + +**Directions**: decide your action before an alert fires — it's much harder to think clearly once one does. + +| Position | If it fires, I will… | Status | +| --- | --- | --- | +| _XLM collateral..._ | _Add collateral or withdraw before liquidation._ | _Watching_ | +| | | | + +**Status values**: _Watching_ (alerts active) or _Paused_ (temporarily off). + +## Did I set this up well? + +- Does every position I care about have at least one alert? +- Are my "alert me when" conditions specific enough that I could act on them? +- Do I know what I'll do before an alert fires? +- Is my list of addresses still current? +- Am I relying on a protocol to watch something that only I can see for my own position? + +Revisit this whenever you open, close, or change a position. From 70f1bd1845fb4b3dd3681e2a0597b81522474b98 Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 10:19:17 -0500 Subject: [PATCH 03/12] add sidebar position frontmatter to new pages --- docs/build/security-docs/monitoring-template-builders.mdx | 1 + docs/build/security-docs/monitoring-template-users.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx index 015fe42ab9..f25eb8f755 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -1,5 +1,6 @@ --- title: On-Chain Monitoring Plan Template (Builders) +sidebar_position: 20 --- This template turns a completed [threat model](./threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks what could go wrong and how will we design against it, this plan asks how will we watch for it in production. Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring-template-users.mdx index 929c98f4c9..f63efa81bb 100644 --- a/docs/build/security-docs/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring-template-users.mdx @@ -1,5 +1,6 @@ --- title: Position Monitoring Plan Template (Users) +sidebar_position: 25 --- This template helps you — as someone holding positions on Stellar — set up monitoring for what you own, without needing a formal threat model. Fill in one row per position or wallet you care about: what could go wrong, when you want to be alerted, and what you'll do about it. From 4cb979c306d3bcdabea58c3cdb574c2c861c8377 Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 10:23:16 -0500 Subject: [PATCH 04/12] apply suggestions from copilot review --- docs/build/security-docs/monitoring-template-builders.mdx | 2 +- docs/build/security-docs/monitoring-template-users.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx index f25eb8f755..c21d8d5297 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -3,7 +3,7 @@ title: On-Chain Monitoring Plan Template (Builders) sidebar_position: 20 --- -This template turns a completed [threat model](./threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks what could go wrong and how will we design against it, this plan asks how will we watch for it in production. Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. +This template turns a completed [threat model](./threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks: "What could go wrong and how will we design against it?", this plan asks "How will we watch for it in production?" Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. **Directions**: fill out each section below to the best of your ability. Carry your threat identifiers over from your STRIDE threat model so the two documents stay linked. Work through the sections in order; every threat should leave the exercise with at least one monitor and a defined response. diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring-template-users.mdx index f63efa81bb..60861193f6 100644 --- a/docs/build/security-docs/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring-template-users.mdx @@ -47,7 +47,7 @@ _Input text: a short description of each position and where it lives._ :::note -Don't assume the protocol is watching your specific position. Its monitoring is tuned to the health of the whole system; yours should be tuned to your seat. +Don't assume the protocol is watching your specific position. Its monitoring is tuned to the health of the whole system; yours should be tuned to your own position/exposure. ::: From 0930bae9026b63f31955b42f4b58ff4d3c6e6d2b Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 10:24:43 -0500 Subject: [PATCH 05/12] update routes.txt file --- routes.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/routes.txt b/routes.txt index cb608fc94b..ec944587b5 100644 --- a/routes.txt +++ b/routes.txt @@ -149,6 +149,8 @@ /docs/build/guides/transactions/submit-transaction-wait-js /docs/build/guides/transactions/upload-wasm-bytecode /docs/build/security-docs +/docs/build/security-docs/monitoring-template-builders +/docs/build/security-docs/monitoring-template-users /docs/build/security-docs/securing-web-based-projects /docs/build/security-docs/threat-modeling /docs/build/security-docs/threat-modeling/STRIDE-template From 17058c3de48524e13c3ba6e21030e9468515d8be Mon Sep 17 00:00:00 2001 From: Elliot Date: Wed, 8 Jul 2026 10:44:09 -0500 Subject: [PATCH 06/12] add some forgotten italics in an example table --- docs/build/security-docs/monitoring-template-builders.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx index c21d8d5297..1e675b6eb1 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -78,7 +78,7 @@ Each monitor can be stated in a single line: | Monitor ID | Severity | Response / action (who, channel, automated action) | Owner | Status | Last reviewed | | --- | --- | --- | --- | --- | --- | -| _Elevation.1.M.1_ | Critical | Page on-call security (PagerDuty + Slack); trigger guardian pause; open incident bridge. | Protocol Security | Active | YYYY-MM-DD | +| _Elevation.1.M.1_ | _Critical_ | _Page on-call security (PagerDuty + Slack); trigger guardian pause; open incident bridge._ | _Protocol Security_ | _Active_ | _YYYY-MM-DD_ | | | | | | | | **Status values**: _Active_ (live and alerting), _Tuning_ (live but thresholds being refined), _Planned_ (agreed but not yet implemented). From 1cb0cf7f9767cbf900f213027f7587fb9d0e2a0b Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 08:43:14 -0500 Subject: [PATCH 07/12] make table rows more obviously marked as examples --- .../security-docs/monitoring-template-builders.mdx | 10 +++++----- docs/build/security-docs/monitoring-template-users.mdx | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx index 1e675b6eb1..d35f622ee2 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -39,7 +39,7 @@ _Input text: high-level description of the protocol, the value it holds, and the | Threat ID | Threat (from threat model) | Affected component | Severity | | --- | --- | --- | --- | -| _Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core — access control_ | _Critical_ | +| _e.g. Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core — access control_ | _Critical_ | | | | | | ## What does exploitation look like on-chain? @@ -48,7 +48,7 @@ _Input text: high-level description of the protocol, the value it holds, and the | Threat ID | Exploitation scenario | Observable on-chain effect(s) | | --- | --- | --- | -| _Elevation.1_ | _A leaked admin key reassigns ownership, then raises borrow caps and drains reserves._ | _`set_admin` / ownership-transfer event; privileged parameter change from a non-allowlisted caller_ | +| _e.g. Elevation.1_ | _A leaked admin key reassigns ownership, then raises borrow caps and drains reserves._ | _`set_admin` / ownership-transfer event; privileged parameter change from a non-allowlisted caller_ | | | | | :::note @@ -63,8 +63,8 @@ If a threat has no observable on-chain effect (for example, a compromised fronte | Monitor ID | Observable on-chain effect | Trigger condition & baseline | Monitoring rule (plain-language intent) | | --- | --- | --- | --- | -| _Elevation.1.M.1_ | _Owner/admin address changes_ | _Any set_admin event. Baseline: zero — never expected in normal operation._ | _Alert immediately on any admin change on the core contract._ | -| _Elevation.1.M.2_ | _Privileged call from an unexpected address_ | _Caller not in the known-admin allowlist. Baseline: only the multisig calls these._ | _Alert on privileged calls from non-allowlisted addresses._ | +| _e.g. Elevation.1.M.1_ | _Owner/admin address changes_ | _Any set_admin event. Baseline: zero — never expected in normal operation._ | _Alert immediately on any admin change on the core contract._ | +| _e.g. Elevation.1.M.2_ | _Privileged call from an unexpected address_ | _Caller not in the known-admin allowlist. Baseline: only the multisig calls these._ | _Alert on privileged calls from non-allowlisted addresses._ | | | | | | Each monitor can be stated in a single line: @@ -78,7 +78,7 @@ Each monitor can be stated in a single line: | Monitor ID | Severity | Response / action (who, channel, automated action) | Owner | Status | Last reviewed | | --- | --- | --- | --- | --- | --- | -| _Elevation.1.M.1_ | _Critical_ | _Page on-call security (PagerDuty + Slack); trigger guardian pause; open incident bridge._ | _Protocol Security_ | _Active_ | _YYYY-MM-DD_ | +| _e.g. Elevation.1.M.1_ | _Critical_ | _Page on-call security (PagerDuty + Slack); trigger guardian pause; open incident bridge._ | _Protocol Security_ | _Active_ | _YYYY-MM-DD_ | | | | | | | | **Status values**: _Active_ (live and alerting), _Tuning_ (live but thresholds being refined), _Planned_ (agreed but not yet implemented). diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring-template-users.mdx index 60861193f6..3742f0ae60 100644 --- a/docs/build/security-docs/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring-template-users.mdx @@ -33,7 +33,7 @@ _Input text: a short description of each position and where it lives._ | Position | What "going wrong" looks like | How worried am I | | --- | --- | --- | -| _XLM collateral..._ | _My position drifts toward liquidation; the protocol's admin changes unexpectedly; the pool drains suddenly._ | _Important_ | +| _e.g. XLM collateral..._ | _My position drifts toward liquidation; the protocol's admin changes unexpectedly; the pool drains suddenly._ | _Important_ | | | | | ## What will alert me? @@ -42,7 +42,7 @@ _Input text: a short description of each position and where it lives._ | Position | Alert me when... | Notify me by | | --- | --- | --- | -| _XLM collateral..._ | _Health factor drops below 1.5; any admin change on the market; pool liquidity falls more than 30% in an hour._ | _Push + Telegram_ | +| _e.g. XLM collateral..._ | _Health factor drops below 1.5; any admin change on the market; pool liquidity falls more than 30% in an hour._ | _Push + Telegram_ | | | | | :::note @@ -57,7 +57,7 @@ Don't assume the protocol is watching your specific position. Its monitoring is | Position | If it fires, I will… | Status | | --- | --- | --- | -| _XLM collateral..._ | _Add collateral or withdraw before liquidation._ | _Watching_ | +| _e.g. XLM collateral..._ | _Add collateral or withdraw before liquidation._ | _Watching_ | | | | | **Status values**: _Watching_ (alerts active) or _Paused_ (temporarily off). From 0e0d0458fb5f6dac43da5a72a989f2929d784383 Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 09:23:00 -0500 Subject: [PATCH 08/12] add descriptions to page(s) frontmatter(s) --- docs/build/security-docs/monitoring-template-builders.mdx | 1 + docs/build/security-docs/monitoring-template-users.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring-template-builders.mdx index d35f622ee2..419b24f90e 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring-template-builders.mdx @@ -1,5 +1,6 @@ --- title: On-Chain Monitoring Plan Template (Builders) +description: Turn your threat model into a monitoring plan. sidebar_position: 20 --- diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring-template-users.mdx index 3742f0ae60..63e4ccb81e 100644 --- a/docs/build/security-docs/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring-template-users.mdx @@ -1,5 +1,6 @@ --- title: Position Monitoring Plan Template (Users) +description: Monitor your important positions on Stellar sidebar_position: 25 --- From d0fffb72035c0469e0ccf9ff2de2ff40eb9dc37f Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 09:30:43 -0500 Subject: [PATCH 09/12] move templates into their own category --- docs/build/security-docs/monitoring/README.mdx | 11 +++++++++++ .../{ => monitoring}/monitoring-template-builders.mdx | 4 ++-- .../{ => monitoring}/monitoring-template-users.mdx | 2 +- 3 files changed, 14 insertions(+), 3 deletions(-) create mode 100644 docs/build/security-docs/monitoring/README.mdx rename docs/build/security-docs/{ => monitoring}/monitoring-template-builders.mdx (92%) rename docs/build/security-docs/{ => monitoring}/monitoring-template-users.mdx (99%) diff --git a/docs/build/security-docs/monitoring/README.mdx b/docs/build/security-docs/monitoring/README.mdx new file mode 100644 index 0000000000..a70214c69a --- /dev/null +++ b/docs/build/security-docs/monitoring/README.mdx @@ -0,0 +1,11 @@ +--- +title: Onchain Monitoring Templates +sidebar_label: Onchain Monitoring +sidebar_position: 20 +--- + +import DocCardList from "@theme/DocCardList"; + +Learn how to monitor your important positions and protocols on Stellar. + + diff --git a/docs/build/security-docs/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx similarity index 92% rename from docs/build/security-docs/monitoring-template-builders.mdx rename to docs/build/security-docs/monitoring/monitoring-template-builders.mdx index 419b24f90e..e918853a79 100644 --- a/docs/build/security-docs/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx @@ -1,10 +1,10 @@ --- title: On-Chain Monitoring Plan Template (Builders) description: Turn your threat model into a monitoring plan. -sidebar_position: 20 +sidebar_position: 10 --- -This template turns a completed [threat model](./threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks: "What could go wrong and how will we design against it?", this plan asks "How will we watch for it in production?" Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. +This template turns a completed [threat model](../threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks: "What could go wrong and how will we design against it?", this plan asks "How will we watch for it in production?" Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. **Directions**: fill out each section below to the best of your ability. Carry your threat identifiers over from your STRIDE threat model so the two documents stay linked. Work through the sections in order; every threat should leave the exercise with at least one monitor and a defined response. diff --git a/docs/build/security-docs/monitoring-template-users.mdx b/docs/build/security-docs/monitoring/monitoring-template-users.mdx similarity index 99% rename from docs/build/security-docs/monitoring-template-users.mdx rename to docs/build/security-docs/monitoring/monitoring-template-users.mdx index 63e4ccb81e..fd641acdef 100644 --- a/docs/build/security-docs/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-users.mdx @@ -1,7 +1,7 @@ --- title: Position Monitoring Plan Template (Users) description: Monitor your important positions on Stellar -sidebar_position: 25 +sidebar_position: 20 --- This template helps you — as someone holding positions on Stellar — set up monitoring for what you own, without needing a formal threat model. Fill in one row per position or wallet you care about: what could go wrong, when you want to be alerted, and what you'll do about it. From 3e194558f5ce1fbb0cd7870de3d5766d46670694 Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 09:37:37 -0500 Subject: [PATCH 10/12] generate new routes file --- routes.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/routes.txt b/routes.txt index 49fcf623b6..aa56d4367e 100644 --- a/routes.txt +++ b/routes.txt @@ -149,8 +149,9 @@ /docs/build/guides/transactions/submit-transaction-wait-js /docs/build/guides/transactions/upload-wasm-bytecode /docs/build/security-docs -/docs/build/security-docs/monitoring-template-builders -/docs/build/security-docs/monitoring-template-users +/docs/build/security-docs/monitoring +/docs/build/security-docs/monitoring/monitoring-template-builders +/docs/build/security-docs/monitoring/monitoring-template-users /docs/build/security-docs/securing-web-based-projects /docs/build/security-docs/threat-modeling /docs/build/security-docs/threat-modeling/STRIDE-template From 0a76891d45f3b06d5ec7b58414415b59cbb146c6 Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 15:17:35 -0500 Subject: [PATCH 11/12] improvements from other reviewers --- .../monitoring-template-builders.mdx | 34 +++++++++++-------- .../monitoring/monitoring-template-users.mdx | 20 +++++------ 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/build/security-docs/monitoring/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx index e918853a79..5e18a4d856 100644 --- a/docs/build/security-docs/monitoring/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx @@ -4,15 +4,15 @@ description: Turn your threat model into a monitoring plan. sidebar_position: 10 --- -This template turns a completed [threat model](../threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks: "What could go wrong and how will we design against it?", this plan asks "How will we watch for it in production?" Each threat you identified becomes one or more observable on-chain effects, and each effect becomes a rule your monitoring solution watches while your contracts are live. +This template turns a completed [threat model](../threat-modeling/README.mdx) into an operational monitoring plan for a protocol or set of smart contracts on Stellar. Where the threat model asks _what could go wrong and how will we design against it_, this plan asks _how will we watch for it in production_. Each threat identified in the threat model becomes one or more observable on-chain effects, and each effect becomes a rule that the monitoring solution watches while the contracts are live. -**Directions**: fill out each section below to the best of your ability. Carry your threat identifiers over from your STRIDE threat model so the two documents stay linked. Work through the sections in order; every threat should leave the exercise with at least one monitor and a defined response. +**Directions**: Fill out each section below to the best of your ability. Carry the threat identifiers over from the STRIDE threat model so the two documents stay linked. Work through the sections in order; every threat should leave the exercise with at least one monitor and a defined response. -**Keep completed plans internal.** A filled-in monitoring plan is a map of what you do — and don't — watch for. Publish the blank template; treat a populated version as sensitive. +**Keep completed plans internal.** A filled-in monitoring plan is a map of what is (and isn’t) monitored. Treat a populated version as sensitive. ## What are we monitoring? -**Directions**: describe the system in scope, then inventory the components and on-chain addresses this plan covers. +**Directions**: Describe the system in scope, then inventory the components and on-chain addresses this plan covers. _Input text: high-level description of the protocol, the value it holds, and the parts of it this plan covers._ @@ -21,11 +21,15 @@ _Input text: high-level description of the protocol, the value it holds, and the | _e.g. Lending pool core_ | _C..._ | _Holds pooled collateral and debt_ | | | | | -**Note**: keep this inventory current. Addresses can change with new versions, and an out-of-date address list is the most common reason a monitor silently stops working. If it's discovered later that scope has changed, update this section with the latest information. +:::note + +Keep this inventory current. Addresses can change with new versions, and an out-of-date address list is the most common reason a monitor silently stops working. If it's discovered later that scope has changed, update this section with the latest information. + +::: ## What could go wrong? -**Directions**: list the threats this plan monitors, carried over from your threat model. Reuse the identifiers from your STRIDE model (for example, `Elevation.1`) so each monitor traces back to a known threat. Assign each threat a severity using the reminders below. +**Directions**: List the threats this plan monitors, carried over from the threat model. Reuse the identifiers from the STRIDE model (for example, `Elevation.1`) so each monitor traces back to a known threat. Assign each threat a severity using the reminders below. ### Severity reminders @@ -40,12 +44,12 @@ _Input text: high-level description of the protocol, the value it holds, and the | Threat ID | Threat (from threat model) | Affected component | Severity | | --- | --- | --- | --- | -| _e.g. Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core — access control_ | _Critical_ | +| _e.g. Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core, access control_ | _Critical_ | | | | | | ## What does exploitation look like on-chain? -**Directions**: for each threat, describe how exploitation might unfold and the observable on-chain effect(s) it would leave behind. There can be several scenarios, and several effects, per threat. +**Directions**: For each threat, describe how exploitation might unfold and the observable on-chain effect(s) it would leave behind. There can be several scenarios, and several effects, per threat. | Threat ID | Exploitation scenario | Observable on-chain effect(s) | | --- | --- | --- | @@ -54,17 +58,17 @@ _Input text: high-level description of the protocol, the value it holds, and the :::note -If a threat has no observable on-chain effect (for example, a compromised frontend or an oracle's upstream data source), record it here and plan to monitor it off-chain — don't drop it just because it isn't visible on-chain. +If a threat has no observable on-chain effect (for example, a compromised frontend or an oracle's upstream data source), record it here and plan to monitor it off-chain. Don't drop it just because it isn't visible on-chain. ::: ## What will we monitor for? -**Directions**: map each observable effect to a monitoring rule, stating the trigger condition and the baseline that makes it meaningful. Uniquely identify each monitor as `.M.` so it traces back to its threat — the same way remediations in your threat model are identified as `.R.`. +**Directions**: Map each observable effect to a monitoring rule, stating the trigger condition and the baseline that makes it meaningful. Uniquely identify each monitor as `.M.` so it traces back to its threat, the same way remediations in the threat model are identified as `.R.`. | Monitor ID | Observable on-chain effect | Trigger condition & baseline | Monitoring rule (plain-language intent) | | --- | --- | --- | --- | -| _e.g. Elevation.1.M.1_ | _Owner/admin address changes_ | _Any set_admin event. Baseline: zero — never expected in normal operation._ | _Alert immediately on any admin change on the core contract._ | +| _e.g. Elevation.1.M.1_ | _Owner/admin address changes_ | _Any `set_admin` event. Baseline: zero; never expected in normal operation._ | _Alert immediately on any admin change on the core contract._ | | _e.g. Elevation.1.M.2_ | _Privileged call from an unexpected address_ | _Caller not in the known-admin allowlist. Baseline: only the multisig calls these._ | _Alert on privileged calls from non-allowlisted addresses._ | | | | | | @@ -75,7 +79,7 @@ Each monitor can be stated in a single line: ## What happens when an alert fires? -**Directions**: for each monitor, define what happens when it triggers — who is notified, through which channel, any automated action, and who owns the rule. This is where your monitoring vendor's automated-response capability (for example, pausing a contract) is recorded. +**Directions**: For each monitor, define what happens when it triggers: who is notified, through which channel, any automated action, and who owns the rule. This is where the monitoring vendor's automated-response capability (for example, pausing a contract) is recorded. | Monitor ID | Severity | Response / action (who, channel, automated action) | Owner | Status | Last reviewed | | --- | --- | --- | --- | --- | --- | @@ -86,11 +90,11 @@ Each monitor can be stated in a single line: ## Did we do a good job? -- Does every threat in your threat model have at least one monitor, or a documented reason it can't be monitored on-chain? +- Does every threat in the threat model have at least one monitor, or a documented reason it can't be monitored on-chain? - Is every trigger threshold grounded in an actual baseline rather than a guess? - Does every monitor have a defined response, an owner, and a status? -- Have any monitors fired? Were they true positives, and did the response work as written? +- Have any monitors fired? Were they true positives? Did the response work as written? - Are all on-chain addresses still current after the latest deploy or upgrade? - Were any threats found that only surface off-chain, needing a different kind of monitoring? -Treat this plan as a living document: revisit it whenever your contracts, addresses, or threat model change. +Treat this plan as a living document: revisit it whenever the contracts, addresses, or threat model change. diff --git a/docs/build/security-docs/monitoring/monitoring-template-users.mdx b/docs/build/security-docs/monitoring/monitoring-template-users.mdx index fd641acdef..fce5ec5d8d 100644 --- a/docs/build/security-docs/monitoring/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-users.mdx @@ -4,13 +4,13 @@ description: Monitor your important positions on Stellar sidebar_position: 20 --- -This template helps you — as someone holding positions on Stellar — set up monitoring for what you own, without needing a formal threat model. Fill in one row per position or wallet you care about: what could go wrong, when you want to be alerted, and what you'll do about it. +This template helps you, as someone holding positions on Stellar, set up monitoring for what you own, without needing a formal threat model. Fill in one row per position or wallet you care about: what could go wrong, when you want to be alerted, and what you'll do about it. -**Directions**: fill out each section below to the best of your ability. Keep the same position in the same row across every table so the plan reads straight across. +**Directions**: Fill out each section below to the best of your ability. Keep the same position in the same row across every table so the plan reads straight across. ## What am I protecting? -**Directions**: list the positions and wallets you hold and care about. +**Directions**: List the positions and wallets you hold and care about. _Input text: a short description of each position and where it lives._ @@ -21,9 +21,9 @@ _Input text: a short description of each position and where it lives._ ## What would going wrong look like? -**Directions**: in plain language, note what "something going wrong" would look like for each position, and how much you'd care using the reminders below. +**Directions**: In plain language, note what "something going wrong" would look like for each position, and the level of concern using the reminders below. -### How worried am I? +### How concerned am I? | Level | Meaning | | ------------------- | ------------------------------------------- | @@ -32,14 +32,14 @@ _Input text: a short description of each position and where it lives._ | **Keep an eye** | Useful to know; I'll check when convenient. | | **Low** | Informational only. | -| Position | What "going wrong" looks like | How worried am I | +| Position | What "going wrong" looks like | How concerned am I | | --- | --- | --- | | _e.g. XLM collateral..._ | _My position drifts toward liquidation; the protocol's admin changes unexpectedly; the pool drains suddenly._ | _Important_ | | | | | ## What will alert me? -**Directions**: turn each worry into a specific condition you can be alerted on, and choose how you want to be notified. +**Directions**: Turn each concern into a specific condition you can be alerted on, and choose how you want to be notified. | Position | Alert me when... | Notify me by | | --- | --- | --- | @@ -48,15 +48,15 @@ _Input text: a short description of each position and where it lives._ :::note -Don't assume the protocol is watching your specific position. Its monitoring is tuned to the health of the whole system; yours should be tuned to your own position/exposure. +Don't assume the protocol is watching your specific position. Its monitoring is tuned to the health of the whole system; yours should be tuned to your concerns. ::: ## What will I do? -**Directions**: decide your action before an alert fires — it's much harder to think clearly once one does. +**Directions**: Decide your action before an alert fires — it's much harder to think clearly once one does. -| Position | If it fires, I will… | Status | +| Position | If it fires, I will... | Status | | --- | --- | --- | | _e.g. XLM collateral..._ | _Add collateral or withdraw before liquidation._ | _Watching_ | | | | | From 4c0813866d39c6d712ba02427bb97fa3a6c05ad4 Mon Sep 17 00:00:00 2001 From: Elliot Date: Fri, 10 Jul 2026 15:45:54 -0500 Subject: [PATCH 12/12] clarify audience in page descriptions --- .../security-docs/monitoring/monitoring-template-builders.mdx | 2 +- .../security-docs/monitoring/monitoring-template-users.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/security-docs/monitoring/monitoring-template-builders.mdx b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx index 5e18a4d856..f60c3771a8 100644 --- a/docs/build/security-docs/monitoring/monitoring-template-builders.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-builders.mdx @@ -1,6 +1,6 @@ --- title: On-Chain Monitoring Plan Template (Builders) -description: Turn your threat model into a monitoring plan. +description: For Builders - turn your threat model into a monitoring plan sidebar_position: 10 --- diff --git a/docs/build/security-docs/monitoring/monitoring-template-users.mdx b/docs/build/security-docs/monitoring/monitoring-template-users.mdx index fce5ec5d8d..5a3d09c10c 100644 --- a/docs/build/security-docs/monitoring/monitoring-template-users.mdx +++ b/docs/build/security-docs/monitoring/monitoring-template-users.mdx @@ -1,6 +1,6 @@ --- title: Position Monitoring Plan Template (Users) -description: Monitor your important positions on Stellar +description: For Users - Monitor your important positions on Stellar sidebar_position: 20 ---