Security monitoring templates

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 `<ThreatID>.M.<n>` so it traces back to its threat — the same way remediations in your threat model are identified as `<ThreatID>.R.<n>`.
+
+| 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.

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.