Anomaly Alerting

Volidator includes a Zero-Knowledge threat alerting engine. It lets you get notified immediately when suspicious events happen (such as brute force login attempts or batch data deletion spikes) without exposing your sensitive logs or action names to the server.

---

The Big Picture (How it works)

Imagine a security guard who is completely blindfolded.

1. You tell the guard: “If you hear the word Click 50 times in 5 minutes, tap my shoulder.”
2. The guard does not know what Click means (it could be a failed login, a file download, or a settings change).
3. Your server sends the word Click (the blind index) every time a failed login occurs.
4. When the guard counts 50 clicks in 5 minutes, they send you an encrypted envelope.
5. You open the envelope with your secret key and read: “Alert: auth.login.failed threshold exceeded!”

Volidator’s alerting works exactly this way:

• Action names are converted to blind hashes locally in your browser.
• The server counts the occurrences in a sliding window using real-time stubs.
• Alerts are dispatched as email links containing the encrypted rule name, which only decrypts when you view it in your dashboard.

---

Step 1: Configure the Alert in the Dashboard

Before your system can detect anomalies, you must define an alert rule:

1. Open the Volidator Dashboard and navigate to the Alert Rules tab.
2. Enter your client-side Project Encryption Key to unlock the creation form.
3. Fill in the alert parameters:
   • Rule Name: A friendly description (e.g., Failed Login Storm). This name is encrypted locally in your browser before saving.
   • Action Name: The exact event string you log in your code (e.g., auth.login.failed). The browser calculates the blind index hash of this action name automatically.
   • Count Threshold: The maximum allowed event count before triggering the alert (e.g., 50).
   • Window: The sliding time window to track events (e.g., 5 minutes).
   • Notification Email: The destination address where the alert link will be sent.
4. Click Save Alert Rule.

---

Step 2: Triggering Alerts in Your Code

To trigger the alert counter, simply write standard logs using the Volidator SDK. The SDK handles the blind indexing automatically.

Here is a real-world Express.js login handler example:

import { volidator } from "./volidator-client";

app.post("/api/login", async (req, res) => {
  const { username, password } = req.body;

  const user = await authenticateUser(username, password);

  if (!user) {
    // 1. Authentication failed! Log the event.
    // Volidator will automatically calculate the blind index hash for "auth.login.failed"
    // and send it to the ingestion queue.
    await volidator.log({
      actor: username,
      action: "auth.login.failed",
      metadata: {
        reason: "invalid_credentials"
      },
      req // Extracts IP and User-Agent context automatically
    });

    return res.status(401).json({ error: "Invalid credentials" });
  }

  // Login succeeded, proceed to issue session token...
});

---

Step 3: Decrypting Alert Notifications

When a threshold is breached (for example, 50 failed logins hit your endpoint in 5 minutes):

1. Volidator sends an automated notification email to your designated address.
2. The email contains a link back to your Volidator dashboard with the encrypted rule name as a URL parameter.
3. Click the link.
4. The dashboard prompts you to enter your Project Encryption Key (if not already saved in your browser session).
5. The browser decrypts the rule name locally in the browser memory and displays a prominent warning banner identifying the exact trigger event.