Skip to content

Commit 45770fa

Browse files
ElliotFriendElliotFriend
authored
Security monitoring templates (#2570)
* add the monitoring template for builders * add position monitoring template for users * add sidebar position frontmatter to new pages * apply suggestions from copilot review * update routes.txt file * add some forgotten italics in an example table * make table rows more obviously marked as examples * add descriptions to page(s) frontmatter(s) * move templates into their own category * generate new routes file * improvements from other reviewers * clarify audience in page descriptions
1 parent 8d14d05 commit 45770fa

4 files changed

Lines changed: 188 additions & 0 deletions

File tree

‎docs/build/security-docs/monitoring/README.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Onchain Monitoring Templates
3+
sidebar_label: Onchain Monitoring
4+
sidebar_position: 20
5+
---
6+
7+
import DocCardList from "@theme/DocCardList";
8+
9+
Learn how to monitor your important positions and protocols on Stellar.
10+
11+
<DocCardList />

‎docs/build/security-docs/monitoring/monitoring-template-builders.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: On-Chain Monitoring Plan Template (Builders)
3+
description: For Builders - turn your threat model into a monitoring plan
4+
sidebar_position: 10
5+
---
6+
7+
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.
8+
9+
**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.
10+
11+
**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.
12+
13+
## What are we monitoring?
14+
15+
**Directions**: Describe the system in scope, then inventory the components and on-chain addresses this plan covers.
16+
17+
_Input text: high-level description of the protocol, the value it holds, and the parts of it this plan covers._
18+
19+
| Component | On-chain address (`C...` contract / `G...` account) | Notes |
20+
| --- | --- | --- |
21+
| _e.g. Lending pool core_ | _C..._ | _Holds pooled collateral and debt_ |
22+
| | | |
23+
24+
:::note
25+
26+
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.
27+
28+
:::
29+
30+
## What could go wrong?
31+
32+
**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.
33+
34+
### Severity reminders
35+
36+
| Severity | Meaning |
37+
| --- | --- |
38+
| **Critical** | Direct, large-scale loss of funds or control; requires immediate response. |
39+
| **High** | Serious impact to funds, users, or availability; requires prompt response. |
40+
| **Medium** | Limited or containable impact; response can be scheduled. |
41+
| **Low** | Minor or informational; monitored for awareness. |
42+
43+
### Threat register
44+
45+
| Threat ID | Threat (from threat model) | Affected component | Severity |
46+
| --- | --- | --- | --- |
47+
| _e.g. Elevation.1_ | _Unauthorized change of contract admin/owner_ | _Lending pool core, access control_ | _Critical_ |
48+
| | | | |
49+
50+
## What does exploitation look like on-chain?
51+
52+
**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.
53+
54+
| Threat ID | Exploitation scenario | Observable on-chain effect(s) |
55+
| --- | --- | --- |
56+
| _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_ |
57+
| | | |
58+
59+
:::note
60+
61+
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.
62+
63+
:::
64+
65+
## What will we monitor for?
66+
67+
**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 `<ThreatID>.M.<n>` so it traces back to its threat, the same way remediations in the threat model are identified as `<ThreatID>.R.<n>`.
68+
69+
| Monitor ID | Observable on-chain effect | Trigger condition & baseline | Monitoring rule (plain-language intent) |
70+
| --- | --- | --- | --- |
71+
| _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._ |
72+
| _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._ |
73+
| | | | |
74+
75+
Each monitor can be stated in a single line:
76+
77+
- We address **[Threat ID]** in **[affected component]** by monitoring for **[on-chain effect]** on **[address]**.
78+
- _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...**._
79+
80+
## What happens when an alert fires?
81+
82+
**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.
83+
84+
| Monitor ID | Severity | Response / action (who, channel, automated action) | Owner | Status | Last reviewed |
85+
| --- | --- | --- | --- | --- | --- |
86+
| _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_ |
87+
| | | | | | |
88+
89+
**Status values**: _Active_ (live and alerting), _Tuning_ (live but thresholds being refined), _Planned_ (agreed but not yet implemented).
90+
91+
## Did we do a good job?
92+
93+
- Does every threat in the threat model have at least one monitor, or a documented reason it can't be monitored on-chain?
94+
- Is every trigger threshold grounded in an actual baseline rather than a guess?
95+
- Does every monitor have a defined response, an owner, and a status?
96+
- Have any monitors fired? Were they true positives? Did the response work as written?
97+
- Are all on-chain addresses still current after the latest deploy or upgrade?
98+
- Were any threats found that only surface off-chain, needing a different kind of monitoring?
99+
100+
Treat this plan as a living document: revisit it whenever the contracts, addresses, or threat model change.

‎docs/build/security-docs/monitoring/monitoring-template-users.mdx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Position Monitoring Plan Template (Users)
3+
description: For Users - Monitor your important positions on Stellar
4+
sidebar_position: 20
5+
---
6+
7+
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.
8+
9+
**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.
10+
11+
## What am I protecting?
12+
13+
**Directions**: List the positions and wallets you hold and care about.
14+
15+
_Input text: a short description of each position and where it lives._
16+
17+
| Position | Wallet / position address (`G...` account / `C...` contract) | Value at risk (optional) |
18+
| --- | --- | --- |
19+
| _e.g. XLM collateral in a lending position_ | _G..._ | _Dollar amount or percentage_ |
20+
| | | |
21+
22+
## What would going wrong look like?
23+
24+
**Directions**: In plain language, note what "something going wrong" would look like for each position, and the level of concern using the reminders below.
25+
26+
### How concerned am I?
27+
28+
| Level | Meaning |
29+
| ------------------- | ------------------------------------------- |
30+
| **Drop everything** | I need to act right now to avoid loss. |
31+
| **Important** | I want to know quickly and will act soon. |
32+
| **Keep an eye** | Useful to know; I'll check when convenient. |
33+
| **Low** | Informational only. |
34+
35+
| Position | What "going wrong" looks like | How concerned am I |
36+
| --- | --- | --- |
37+
| _e.g. XLM collateral..._ | _My position drifts toward liquidation; the protocol's admin changes unexpectedly; the pool drains suddenly._ | _Important_ |
38+
| | | |
39+
40+
## What will alert me?
41+
42+
**Directions**: Turn each concern into a specific condition you can be alerted on, and choose how you want to be notified.
43+
44+
| Position | Alert me when... | Notify me by |
45+
| --- | --- | --- |
46+
| _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_ |
47+
| | | |
48+
49+
:::note
50+
51+
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.
52+
53+
:::
54+
55+
## What will I do?
56+
57+
**Directions**: Decide your action before an alert fires — it's much harder to think clearly once one does.
58+
59+
| Position | If it fires, I will... | Status |
60+
| --- | --- | --- |
61+
| _e.g. XLM collateral..._ | _Add collateral or withdraw before liquidation._ | _Watching_ |
62+
| | | |
63+
64+
**Status values**: _Watching_ (alerts active) or _Paused_ (temporarily off).
65+
66+
## Did I set this up well?
67+
68+
- Does every position I care about have at least one alert?
69+
- Are my "alert me when" conditions specific enough that I could act on them?
70+
- Do I know what I'll do before an alert fires?
71+
- Is my list of addresses still current?
72+
- Am I relying on a protocol to watch something that only I can see for my own position?
73+
74+
Revisit this whenever you open, close, or change a position.

‎routes.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,9 @@
149149
/docs/build/guides/transactions/submit-transaction-wait-js
150150
/docs/build/guides/transactions/upload-wasm-bytecode
151151
/docs/build/security-docs
152+
/docs/build/security-docs/monitoring
153+
/docs/build/security-docs/monitoring/monitoring-template-builders
154+
/docs/build/security-docs/monitoring/monitoring-template-users
152155
/docs/build/security-docs/securing-web-based-projects
153156
/docs/build/security-docs/threat-modeling
154157
/docs/build/security-docs/threat-modeling/STRIDE-template

0 commit comments

Comments
 (0)