Expand monitoring section (#421)

JosepBove · mattaereal · web-flow · commit 051babbd6666 · 2026-03-23T17:41:59.000-03:00
* feat(monitoring): redesign monitoring section with tools catalog and first principles

* Merge branch 'develop' into feat/monitoring-improvements

* chore(contributors): add JosepBove as Monitoring framework steward

* chore: remove docs/pages/config/index.mdx

* docs(monitoring): add alert on alert tampering recommendation

* docs(monitoring): sort tools alphabetically and rename open-source section

* Refine monitoring overview and response mechanisms

Clarified monitoring failures and emphasized the importance of documented responses for alerts. Expanded on the role of automated systems in response mechanisms.

* Remove Forta Firewall details from tools.md

Removed Forta Firewall section from monitoring tools documentation. I don't want us to suggest something that has been deprecated for the past three years, and not a single update. If we want to add it, let's just add a more straightforward suggestion

* Revise email usage guidelines for critical alerts

Clarified the recommendation against using email for critical alerts.

---------

Co-authored-by: Matías Aereal Aeón &lt;388605+mattaereal@users.noreply.github.com&gt;
diff --git a/docs/pages/config/contributors.json b/docs/pages/config/contributors.json
@@ -1,4 +1,20 @@
 {
+  "JosepBove": {
+    "slug": "JosepBove",
+    "name": "Josep Bove",
+    "avatar": "https://avatars.githubusercontent.com/JosepBove",
+    "github": "https://github.com/JosepBove",
+    "twitter": "https://twitter.com/JosepBove",
+    "website": null,
+    "company": "OP Labs",
+    "role": "steward",
+    "job_title": null,
+    "description": "Steward of Monitoring framework",
+    "badges": [
+      { "name": "Framework-Steward", "assigned": "2026-03-17", "framework": "Monitoring" },
+      { "name": "First-Contribution", "assigned": "2026-03-16" }
+    ]
+  },
   "mattaereal": {
     "slug": "mattaereal",
     "name": "matta",
diff --git a/docs/pages/monitoring/guidelines.mdx b/docs/pages/monitoring/guidelines.mdx
@@ -4,6 +4,13 @@ description: "On-chain monitoring: track large fund transfers, token minting, an
 tags:
   - Engineer/Developer
   - Security Specialist
+contributors:
+  - role: wrote
+    users: [JosepBove]
+  - role: reviewed
+    users: []
+  - role: fact-checked
+    users: []
 ---
 
 import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -19,33 +26,88 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
 Effective on-chain monitoring is complex and involves setting up systems and processes to continuously observe
 blockchain activities and detect any anomalies.
 
+## Key Principles
+
+- **Transparency:** Prefer open-source or auditable tools so your monitoring infrastructure can itself be reviewed.
+- **Real-time detection:** Minimize the time between an on-chain event and the alert reaching a responder.
+- **Automation:** Automate repetitive detection tasks to reduce human error and ensure consistent coverage.
+- **Scalability:** Design your monitoring setup to scale as protocol activity and the number of monitored contracts grows.
+
 ## Best Practices
 
 ### Define Monitoring Objectives
 
-1. Determine the critical metrics to monitor, such as large fund transfers, token minting events, and changes in
-contract ownership.
+1. Determine the critical metrics to monitor. Common categories include:
+   - Large fund transfers from protocol or treasury wallets
+   - Token minting and burning events
+   - Changes in contract ownership or admin roles
+   - Contract upgrades and proxy implementation changes
+   - Access control modifications (role grants, revocations)
+   - Unusual gas usage patterns that may indicate griefing or exploitation attempts
 
 ### Implement Monitoring Tools
 
 1. Use automated monitoring tools that can continuously track blockchain activities and generate alerts for anomalies.
+   See the [Tools](/monitoring/tools) page for a catalog of available options.
 2. Supplement automated tools with periodic manual reviews.
 
 ### Establish Alerting Mechanisms
 
 1. Set up real-time alerts to notify relevant project members of any suspicious activities or threshold breaches.
-2. Use multiple channels for alerts, such as email, SMS, and messaging apps where available, to ensure timely response.
+2. Use multiple channels for alerts (Discord webhooks, Telegram bots, PagerDuty, Slack) to ensure timely delivery.
+3. Every alert must have a designated owner and a documented response. An alert with no one responsible is
+   indistinguishable from no alert at all.
+
+### Monitoring Strategies
+
+Structure monitoring coverage across these tracks:
+
+#### Transaction monitoring
+
+- Large fund transfers above defined thresholds
+- Unusual transaction frequency from key addresses
+- Flash loan interactions with protocol contracts
+
+#### Contract event monitoring
+
+- Token minting and burning
+- Approval and transfer events outside normal patterns
+- Contract upgrades and ownership transfers
+- Admin role grants and revocations
+
+#### Bridge monitoring
+
+- Unusual inflow or outflow volumes through bridge contracts
+- Bridge contract state changes or ownership modifications
+
+#### Oracle and governance monitoring
+
+- Price feed deviations beyond expected bounds
+- Unexpected governance proposals or accelerated vote execution
+
+#### Node and network monitoring
+
+- Block propagation times and node health
+- Network latency affecting transaction confirmation
+- RPC endpoint availability
 
 ### Regular Reviews and Updates
 
 1. Conduct regular reviews of your monitoring systems to ensure they are functioning correctly and covering all
-necessary metrics.
+   necessary metrics.
 2. Regularly update thresholds and alert configurations to reflect your current needs.
+3. **Test your alerts periodically**: verify that alert delivery actually works end-to-end, not just that the
+   detection rule is configured. A misconfigured webhook or expired token can silently break your alerting.
+4. **Alert on alert tampering**: configure alerts for the disabling or modification of existing alerts. This
+   protects against both accidental misconfiguration and adversarial tampering that could silently disable your
+   detection coverage.
 
 ### Incident Response
 
 1. Develop and maintain an [incident response plan](/incident-management/overview) to handle alerts and anomalies as
-soon as possible.
+   soon as possible.
+2. Document who gets paged for each alert category and what the first response steps are. This should be decided
+   before an incident, not during one.
 
 ---
 
diff --git a/docs/pages/monitoring/index.mdx b/docs/pages/monitoring/index.mdx
@@ -13,4 +13,5 @@ title: "Monitoring"
 
 - [Monitoring](/monitoring/overview)
 - [On-Chain Monitoring Guidelines](/monitoring/guidelines)
+- [On-Chain Monitoring Tools](/monitoring/tools)
 - [Monitoring Alert Thresholds](/monitoring/thresholds)
diff --git a/docs/pages/monitoring/overview.mdx b/docs/pages/monitoring/overview.mdx
@@ -1,9 +1,16 @@
 ---
 title: "Monitoring | Security Alliance"
-description: "Monitoring Framework: Maintain blockchain security with on-chain monitoring. Detect anomalies and potential breaches in real-time with guidelines for alerts, thresholds, and tools."
+description: "Blockchain security monitoring framework: detect anomalies and breaches in real-time with guidelines for alerts, thresholds, and monitoring tools."
 tags:
   - Engineer/Developer
   - Security Specialist
+contributors:
+  - role: wrote
+    users: [JosepBove]
+  - role: reviewed
+    users: []
+  - role: fact-checked
+    users: []
 ---
 
 import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -21,6 +28,29 @@ allows you to detect anomalies and potential security breaches in real-time, ena
 This section focuses on monitoring the on-chain security of a project, including guidelines for setting up monitoring
 systems, defining thresholds for alerts, and utilizing existing on-chain monitoring tools.
 
+## First Principles
+
+Before deploying any monitoring tool, establish the fundamentals that make monitoring effective.
+
+### Know what you're monitoring and why
+
+Define which on-chain events are meaningful to your project and what response each alert should trigger. A monitoring
+setup without defined responses is noise: it consumes attention without producing safety. For every alert you
+configure, answer: *who receives this, and what do they do when it fires?*
+
+### Act on your alerts
+
+Organizations fail to monitor in two ways: not logging at all or logging without acting. Both leave you blind.
+
+Every alert must map to a concrete, documented response. For smart contract protocols, this typically means having a pause mechanism or circuit breaker and, in higher-maturity setups, possibly a carefully designed automated system that can trigger when a critical alert fires, but only where the trigger conditions and failure modes have been explicitly reviewed. Without this, monitoring only tells you what happened, not what you could have prevented.
+
+### Monitor with redundancy *(higher maturity)*
+
+No monitoring provider has perfect uptime or perfect detection. For critical systems, run two independent providers
+monitoring the same invariants in parallel (one self-hosted, one managed). If one has downtime or misses an event,
+the other still provides coverage. See the [Tools](/monitoring/tools) page for guidance on combining self-hosted and
+managed options.
+
 ---
 
 </TagProvider>
diff --git a/docs/pages/monitoring/thresholds.mdx b/docs/pages/monitoring/thresholds.mdx
@@ -1,9 +1,16 @@
 ---
 title: "Monitoring Alert Thresholds | Security Alliance"
-description: "Define on-chain monitoring thresholds without excessive false positives. Establish baseline metrics, set multi-layered alert thresholds, and implement anomaly detection for unusual token activity."
+description: "On-chain threshold configuration: set baseline metrics, multi-layered alerts, and anomaly detection rules to catch unusual blockchain activity."
 tags:
   - Engineer/Developer
   - Security Specialist
+contributors:
+  - role: wrote
+    users: [JosepBove]
+  - role: reviewed
+    users: []
+  - role: fact-checked
+    users: []
 ---
 
 import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -18,7 +25,8 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
 
 Setting appropriate thresholds for on-chain monitoring is hard when taking into account you want to detect unusual
 activities, without generating excessive false positives. Here are some guidelines for defining and configuring
-thresholds.
+thresholds. For guidance on what to monitor and how to set up alerting, see the
+[Guidelines](/monitoring/guidelines) page.
 
 ## Generic Guidelines
 
@@ -53,6 +61,9 @@ compare it to its previous behavior. If for example it is common that 4% of toke
 day with 20% of tokens changing owner in the past 10 minutes, then that could be detected as an anomaly and a cause
 for investigation.
 
+Several of the tools in the [Tools](/monitoring/tools) catalog offer built-in anomaly detection. Hypernative uses
+ML-based behavioral modeling, and Tenderly supports custom alert rules that can approximate anomaly thresholds.
+
 ---
 
 </TagProvider>
diff --git a/docs/pages/monitoring/tools.mdx b/docs/pages/monitoring/tools.mdx
@@ -0,0 +1,148 @@
+---
+title: "On-Chain Monitoring Tools | Security Alliance"
+description: "On-chain monitoring tools catalog: open-source and commercial options for transaction monitoring, anomaly detection, alerting, and reliability assessment."
+tags:
+  - Engineer/Developer
+  - Security Specialist
+contributors:
+  - role: wrote
+    users: [JosepBove]
+  - role: reviewed
+    users: []
+  - role: fact-checked
+    users: []
+---
+
+import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
+
+<TagProvider>
+<TagFilter />
+
+# On-Chain Monitoring Tools
+
+<TagList tags={frontmatter.tags} />
+<AttributionList contributors={frontmatter.contributors} />
+
+> The tools below are primarily focused on EVM-compatible chains. For non-EVM chains (Solana, Cosmos, etc.), verify
+> chain support before selecting a tool. For critical systems, consider running monitors from two independent providers
+> simultaneously. See the [Reliability Considerations](#reliability-considerations) section below.
+
+## Open Source / Self-Hosted
+
+### BlockScout
+
+Open-source blockchain explorer with monitoring capabilities. Track transactions, contract events, and token transfers
+with custom alerts for your contracts and addresses. Can be self-hosted for free (MIT license) or deployed via
+BlockScout's managed options: Autoscout (self-service managed hosting, $250-950/month depending on transaction volume)
+or Explorer as a Service (EaaS, enterprise pricing). A PRO API is also available with a free tier (100K credits/day,
+5 req/s) and paid plans from $49/month.
+
+- **Chains:** Multiple EVM networks
+- **GitHub:** [blockscout/blockscout](https://github.com/blockscout/blockscout)
+- **Website:** [blockscout.com](https://www.blockscout.com)
+
+### Prometheus + Grafana
+
+Infrastructure-level metrics collection (Prometheus) and visualization/alerting (Grafana). Useful for monitoring
+blockchain node health, block propagation times, RPC endpoint availability, and custom on-chain metrics exported
+via a scraper.
+
+- **Chains:** Chain-agnostic (infrastructure layer)
+- **GitHub:** [prometheus/prometheus](https://github.com/prometheus/prometheus) | [grafana/grafana](https://github.com/grafana/grafana)
+
+## Commercial / Hosted
+
+### Etherscan
+
+Address monitoring via Watch List, free for registered users. Monitor up to 50 Ethereum addresses and receive
+email notifications on inbound and outbound transactions. Configurable per address via the account dashboard.
+The API supports polling-based monitoring (3 req/s, 100K calls/day on the free tier) but has no push or streaming
+endpoints; custom polling layers are required for automated alerting.
+
+- **Free plan:** Watch List available with a free account; API free tier for personal use
+- **Chains:** Ethereum (and Etherscan-family explorers for other EVM chains)
+- **Website:** [etherscan.io](https://etherscan.io)
+- **Documentation:** [docs.etherscan.io](https://docs.etherscan.io)
+
+### Guardrail
+
+Real-time DeFi security monitoring and automated threat response. Deploys customizable Guards (rule sets that
+inspect every on-chain transaction per block, per function, or per event) and can trigger automated protective
+responses such as contract pauses, wallet flagging, and on-call escalation. Covers DeFi protocols, DApps, oracle
+networks, DAO governance, and multisig operations.
+
+- **Chains:** 30+ (Ethereum, Arbitrum, Optimism, Base, Polygon, zkSync, Scroll, and others)
+- **Website:** [guardrail.ai](https://www.guardrail.ai)
+
+### Hexagate
+
+Chainalysis's real-time on-chain threat detection and automated prevention platform. Uses ML-driven anomaly
+detection and GateSigner (pre-signing transaction simulation) to catch exploits before they land on-chain.
+Supports custom detection rules via Gatelang. Free access available for protocols building on partner chains
+(Base, Avalanche, Polygon, Cronos, Immutable, and others) through chain-specific application programs.
+
+- **Free plan:** Available for protocols on partner chains; check with your chain's foundation
+- **Chains:** 75+ blockchains
+- **Website:** [chainalysis.com/product/hexagate](https://www.chainalysis.com/product/hexagate/)
+
+### Hypernative
+
+Machine learning-based anomaly detection and pre-crime threat detection for DeFi protocols. Detects novel attack
+patterns by modeling protocol behavior rather than relying solely on known signatures.
+
+- **Chains:** 70+ blockchains
+- **Website:** [hypernative.io](https://hypernative.io)
+
+### Tenderly
+
+Real-time smart contract monitoring platform with a free tier. Supports 12 alert trigger types (function calls,
+event emissions, balance changes, state variable changes, and transaction value thresholds) with delivery to
+8 destinations: Slack, Discord, Telegram, email, webhooks, PagerDuty, Sentry, and Web3 Actions (TypeScript
+serverless functions that run on Tenderly's infrastructure). The CLI and SDKs are open-source (GPL-3.0).
+
+- **Free plan:** Available; exact monitoring quotas visible on the pricing page
+- **Chains:** 100+ networks
+- **Website:** [tenderly.co](https://tenderly.co)
+- **GitHub:** [Tenderly](https://github.com/Tenderly) (CLI, SDKs, framework plugins)
+
+## Reliability Considerations
+
+Your monitoring system is only effective if it is itself reliable. Before committing to a tooling setup, evaluate
+these factors:
+
+### Self-hosted vs. managed
+
+| | Self-Hosted | Managed Platform |
+| --- | --- | --- |
+| **Control** | Full control over configuration and data | Vendor controls infrastructure |
+| **Operational burden** | You own uptime, upgrades, and maintenance | Vendor handles ops |
+| **Vendor risk** | None | Platform downtime or shutdown affects you |
+| **Cost** | Infrastructure cost + engineering time | Subscription fee |
+
+### Key reliability metrics to evaluate
+
+- **Uptime SLA:** What guaranteed availability does the provider offer? Is there a status page?
+- **Time-to-alert:** How quickly after an on-chain event does a notification reach you? Minutes matter during an exploit.
+- **Alert delivery guarantees:** Does the platform guarantee at-least-once delivery, or is it best-effort?
+
+### Redundancy recommendation
+
+For any protocol holding significant value, do not rely on a single monitoring provider. Run at least two independent
+monitoring setups (ideally one self-hosted and one managed) covering the same critical invariants. If the managed
+platform has downtime or misses an anomaly, the self-hosted layer still provides coverage, and vice versa.
+
+### Alert channel reliability
+
+Your monitoring is only as good as the delivery mechanism for its alerts.
+
+- **Prefer:** PagerDuty or OpsGenie (escalation policies, on-call rotations, delivery receipts)
+- **Use with care:** Slack, Discord, Telegram (useful for visibility, but easy to miss; no delivery guarantees)
+- **Don’t rely on email as the sole channel for critical alerts**: Email may be appropriate as a secondary or audit channel, not primary paging (high latency, often filtered to spam)
+
+For high-severity alerts, use a dedicated paging tool with escalation so that if the primary on-call misses the
+alert, it automatically escalates to a secondary.
+
+---
+
+</TagProvider>
+<ContributeFooter />
diff --git a/utils/fetched-tags.json b/utils/fetched-tags.json
@@ -654,6 +654,10 @@
       "Engineer/Developer",
       "Security Specialist"
     ],
+    "/monitoring/tools": [
+      "Engineer/Developer",
+      "Security Specialist"
+    ],
     "/multisig-for-protocols/backup-signing-and-infrastructure": [
       "Engineer/Developer",
       "Security Specialist",
diff --git a/vocs.config.tsx b/vocs.config.tsx
@@ -236,6 +236,7 @@ const config = {
           items: [
             { text: 'Overview', link: '/monitoring/overview', dev: true },
             { text: 'Guidelines', link: '/monitoring/guidelines', dev: true },
+            { text: 'Tools', link: '/monitoring/tools', dev: true },
             { text: 'Thresholds', link: '/monitoring/thresholds', dev: true },
           ]
         },
diff --git a/wordlist.txt b/wordlist.txt
@@ -307,6 +307,7 @@ reauthentication
 CAIP
 unbonding
 unbond
+Cronos
 Zenity
 Cowork
 nsjail

Original file line number	Diff line number	Diff line change
`@@ -236,6 +236,7 @@ const config = {`
`236`	`236`	`items: [`
`237`	`237`	`{ text: 'Overview', link: '/monitoring/overview', dev: true },`
`238`	`238`	`{ text: 'Guidelines', link: '/monitoring/guidelines', dev: true },`
	`239`	`+ { text: 'Tools', link: '/monitoring/tools', dev: true },`
`239`	`240`	`{ text: 'Thresholds', link: '/monitoring/thresholds', dev: true },`
`240`	`241`	`]`
`241`	`242`	`},`
-Original file line number
+Diff line change
 CAIP
 unbonding
 unbond
 +Cronos
 Zenity
 Cowork
 nsjail