From ea0b5536c9cfe343c978fd981ef6386f92e4e504 Mon Sep 17 00:00:00 2001
From: Quinn Turner <quinnturnertech@gmail.com>
Date: Mon, 5 Aug 2024 17:16:19 -0300
Subject: [PATCH] docs: Add monitoring guidance

---
 README.md                |   4 ++
 docs/vocab-monitoring.md | 127 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 131 insertions(+)
 create mode 100644 docs/vocab-monitoring.md

diff --git a/README.md b/README.md
index a50b974..13a0846 100644
--- a/README.md
+++ b/README.md
@@ -155,6 +155,10 @@ router.route("/login").post(async (req, res, next) => {
 export default router;
 ```
 
+> [!IMPORTANT]  
+> Logging events is not enough to secure your application. You should also monitor these events and take action when necessary.
+> [We have provided some example implementations using popular logging and alerting tools](./docs/vocab-monitoring.md).
+
 ### DOM Utilities
 
 This package also provides a set of DOM utilities to help increase security.
diff --git a/docs/vocab-monitoring.md b/docs/vocab-monitoring.md
new file mode 100644
index 0000000..d1ab45f
--- /dev/null
+++ b/docs/vocab-monitoring.md
@@ -0,0 +1,127 @@
+# Monitoring logging using OWASP vocabulary
+
+`owasp/vocab` provides a set of standard events to log for monitoring and alerting purposes. The intent is to simplify monitoring and alerting such that, assuming developers trap errors and log them using this vocabulary, monitoring and alerting are improved by keying on these terms.
+
+Here are some example implementations using popular logging and alerting tools:
+
+- [Kibana](https://www.elastic.co/kibana)
+- [SumoLogic](https://www.sumologic.com/)
+- [Splunk](https://www.splunk.com/)
+- [Datadog](https://www.datadoghq.com/)
+- [New Relic](https://newrelic.com/)
+- [Sentry](https://sentry.io/)
+
+## Kibana
+
+1. **Send Logs to Elasticsearch**: Ensure your logs are being sent to Elasticsearch.
+2. **Create a Kibana Dashboard**: Go to the Kibana dashboard and create a new visualization.
+3. **Define the Query**: Use the Kibana query language (KQL) to search for specific event properties.
+
+   **Example Kibana query:**
+
+   ```txt
+   event: "malicious_direct_reference:*"
+   ```
+
+4. **Create an Alert**: Use Kibana's alerting feature to set up alerts based on the query.
+
+**Example Alert Configuration:**
+
+- **Trigger**: When the event count exceeds 0 within a 5-minute window.
+- **Actions**: Send notifications via email, Slack, or other channels.
+
+## SumoLogic
+
+1. **Navigate to the SumoLogic Dashboard**: Go to the SumoLogic dashboard and create a new monitor.
+2. **Define the Query**: Use a query to search for the specific event property.
+
+   **Example SumoLogic query:**
+
+   ```txt
+   _sourceCategory=your/source/category
+   | json field=_raw "event"
+   | where event matches "malicious_direct_reference:*"
+   | count by event
+   ```
+
+3. **Create an Alert Condition:** Define the alert condition based on the query results.
+4. **Set Alert Thresholds:** Specify thresholds to trigger alerts.
+5. **Configure Notifications:** Set up email, Slack, or other notifications.
+
+   **Example Alert Condition:**
+
+   ```txt
+   | where event matches "malicious_direct_reference:*"
+   | count by event
+   | sort by _count desc
+   | if (_count > 0) {
+       alert "Malicious Direct Reference Detected"
+       severity = "critical"
+       description = "A malicious direct reference was detected in the logs."
+   }
+   ```
+
+## Splunk
+
+1. **Send Logs to Splunk**: Ensure your logs are being indexed in Splunk.
+2. **Create a Splunk Search**: Use the Splunk search language to find specific event properties.
+
+   **Example Splunk query:**
+
+   ```txt
+   index=your_index sourcetype=your_sourcetype "event=malicious_direct_reference:*"
+   ```
+
+3. **Create an Alert**: Set up an alert based on the search query.
+
+**Example Alert Configuration:**
+
+- **Trigger Condition**: When the number of matching events is greater than 0 within a 5-minute window.
+- **Actions**: Configure email, Slack, or other notifications.
+
+## Datadog
+
+1. **Send Logs to Datadog**: Ensure your logs are being sent to Datadog.
+1. **Create a Log Search**: Use the Datadog log search to find specific event properties.
+
+   **Example Datadog query:**
+
+   ```txt
+   event:malicious_direct_reference:*
+   ```
+
+1. **Create a Monitor**: Set up a log monitor based on the search query.
+
+**Example Monitor Configuration:**
+
+- **Alert Condition**: When the count of matching logs exceeds 0 in a 5-minute window.
+- **Notifications**: Configure email, Slack, or other alerting channels.
+
+## New Relic
+
+1. **Send Logs to New Relic**: Ensure your logs are being sent to New Relic.
+1. **Create a Log Query**: Use the New Relic query language (NRQL) to search for specific event properties.
+
+**Example NRQL query:**
+
+```sql
+SELECT count(*) FROM Log WHERE event LIKE 'malicious_direct_reference:%'
+```
+
+1. **Create an Alert**: Set up an alert condition based on the query.
+
+**Example Alert Condition:**
+
+- **Trigger**: When the query result is greater than 0 within a 5-minute window.
+- **Actions**: Configure email, Slack, or other notifications.
+
+## Sentry
+
+1. **Send Logs to Sentry**: Ensure your logs are being sent to Sentry.
+2. **Set Up Alerts**: Use Sentry's alerting feature to monitor for specific event properties.
+
+   **Example Sentry Alert Rule:**
+
+   - **Filter**: Events with the tag `event` containing `malicious_direct_reference:*`.
+   - **Trigger Condition**: When the event occurs more than 0 times in a 5-minute window.
+   - **Actions**: Send notifications via email, Slack, or other integrations.