# Guardian Engine

Guardian Stack's server API transforms raw browser signals into actionable fraud intelligence. When your client calls `guardian.get()`, our processing engine analyzes hundreds of signals to detect bots, VPNs, browser tampering, and sophisticated fraud attempts.

### How Server Processing Works

**The magic happens server-side** where we can safely perform intensive analysis without impacting user experience or exposing detection logic to potential attackers.

<figure><img src="/files/KaaZuMJlNBY26b42YBMq" alt=""><figcaption></figcaption></figure>

***

### Complete Event Response Structure

#### Core Identification

```json
{
  "identification": {
    "id": "1760039992053.8tuafsur",      // Your unique event reference
    "ip": "81.56.52.67",                 // Source IP for threat analysis
    "timestamp": "2025-10-09T19:59:52.364Z", // When the risk was assessed
    "url": "http://localhost:4176/",      // Context of user action
    "location": { /* geolocation data */ },
    "browser": { /* parsed browser info */ }
  }
}
```

**Fraud Detection Usage:**

* **`id`** - Reference this in your fraud logs and dispute resolution
* **`ip`** - Cross-reference with your existing IP reputation lists
* **`location`** - Flag geographic anomalies (user in US, IP in Russia)
* **`browser`** - Detect impossible browser configurations

***

#### Bot Detection Analysis

```json
{
  "botDetection": {
    "detected": false,                    // 🚨 BLOCK if true
    "score": 0,                          // 0-100: Higher = more bot-like
    "automationSignalsPresent": false,   // Selenium/Puppeteer detected
    "indicators": []                     // Why we flagged this as a bot
  }
}
```

**What This Means for Fraud:**

* **`detected: true`** → Almost certainly automated traffic. **Recommended action: BLOCK**
* **`score > 80`** → Very high bot probability. Consider challenging or blocking
* **`score 40-80`** → Suspicious but inconclusive. Add friction or monitor
* **`automationSignalsPresent: true`** → Definitive automation tools detected

**Common Bot Indicators You'll See:**

* `webdriver` → Selenium automation (credential stuffing, account creation bots)
* `headless_chrome` → Headless browser (scraping, automated purchases)
* `puppeteer` → Advanced automation (sophisticated fraud attempts)

***

#### IP Intelligence Deep Dive

```json
{
  "ipInfo": {
    "is_datacenter": false,              // 🚨 High fraud risk if true
    "is_tor": false,                     // 🚨 Anonymous network usage
    "is_proxy": false,                   // 🚨 Traffic routing detected
    "is_vpn": false,                     // ⚠️ Privacy tool or fraud
    "is_abuser": false,                  // 🚨 Known malicious IP
    "company": {
      "type": "isp",                     // vs "hosting" (red flag)
      "abuser_score": "0.0007 (Low)"    // Historical fraud patterns
    }
  }
}
```

**Critical Fraud Signals:**

* **`is_datacenter: true`** → Traffic from hosting providers (bots, farms)
* **`is_tor: true`** → Maximum anonymity seeking (high fraud correlation)
* **`is_abuser: true`** → IP has fraud history across the internet
* **`company.type: "hosting"`** → Not residential internet (suspicious for consumers)

**Risk Assessment Guide:**

```javascript
// High risk combinations
if (ipInfo.is_datacenter && ipInfo.is_proxy) {
  // Hosting provider + proxy = bot farm
}

if (ipInfo.is_tor || ipInfo.is_abuser) {
  // Known bad actor infrastructure
}
```

***

#### VPN Detection Engine

```json
{
  "vpn": {
    "detected": false,                   // Privacy tool or fraud?
    "confidence": "none",                // How certain we are
    "browserTimezone": "Europe/Rome",    // What browser claims
    "ipTimezone": "Europe/Rome",         // What IP location shows
    "timezoneDifference": 0              // Hours apart (key fraud signal)
  }
}
```

**Fraud Detection Intelligence:**

* **`detected: true`** → User hiding real location (why?)
* **`timezoneDifference > 6`** → Major geographic inconsistency
* **`confidence: "high"`** → Very likely VPN usage

**Fraud Context Matters:**

```javascript
// Legitimate privacy vs fraud indicators
if (vpn.detected && user.isNewAccount) {
  // New user + VPN = suspicious
} else if (vpn.detected && user.hasHistory) {
  // Existing user + VPN = privacy conscious
}
```

***

#### Browser Tampering Detection

```json
{
  "tampering": {
    "detected": true,                    // 🚨 Environment manipulation
    "anomalyScore": 0.55,               // 0-1: Abnormality level  
    "antiDetectBrowser": false,         // Specialized fraud tool
    "indicators": [
      {
        "source": "vendor_mismatch",     // Browser lying about identity
        "severity": "medium"
      }
    ]
  }
}
```

**What Tampering Means:**

* **`detected: true`** → Browser has been modified to avoid detection
* **`antiDetectBrowser: true`** → Professional fraud tools detected
* **`anomalyScore > 0.7`** → Major inconsistencies in browser environment

**Tampering = Fraud Intent:**

* Users don't accidentally modify browsers
* Tampering tools are expensive and specialized
* High correlation with fraud attempts

**Key Indicators:**

* `vendor_mismatch` → Browser claims to be Chrome but acts like Firefox
* `canvas_spoofing` → Artificial fingerprint to avoid tracking
* `webgl_anomalies` → Graphics inconsistencies (virtual environments)

***

#### Privacy Settings vs. Fraud

```json
{
  "privacySettings": {
    "detected": false,                   // Privacy tools active
    "score": 0,                         // Intensity of privacy measures
    "indicators": []                    // What privacy tools found
  }
}
```

**The Privacy Dilemma:**

* **Legitimate privacy users** → Ad blockers, privacy browsers, VPNs for safety
* **Fraud actors** → Same tools to avoid detection

**Smart Fraud Detection:**

```javascript
// Don't punish privacy, but be aware
if (privacySettings.detected && !botDetection.detected) {
  // Likely legitimate privacy-conscious user
} else if (privacySettings.detected && tampering.detected) {
  // Privacy tools + tampering = fraud attempt
}
```

***

#### Virtualization Red Flags

```json
{
  "virtualization": {
    "detected": false,                   // 🚨 VM environment detected
    "confidence": "none",                // Detection certainty
    "indicators": []                    // VM signatures found
  }
}
```

**Why VMs Matter for Fraud:**

* **Scalability** → Easy to spin up hundreds of fraud instances
* **Isolation** → No risk to fraudster's real machine
* **Throwaway** → Delete evidence after attack

**VM Detection = High Fraud Risk:**

* Consumer users rarely run VMs for browsing
* Professional fraud operations always use VMs
* Combined with other signals = almost certain fraud

***

#### Incognito Detection Intelligence

```json
{
  "incognito": {
    "detected": false,                   // Private browsing mode
    "score": 0,                         // Detection confidence
    "indicators": []                    // Technical signatures
  }
}
```

**Incognito Fraud Context:**

* **By itself** → Normal privacy behavior
* **With VPN + new account** → Avoiding identification
* **With bot signals** → Automated incognito sessions

***

#### Request IP Velocity Intelligence

```json
{
  "velocity": {
    "5m": 3,
    "1h": 17,
    "24h": 68
  }
}
```

* **What it is**: Number of requests from the same IP (scoped to your `siteKey` when provided) within rolling 5-minute, 1-hour, and 24-hour windows.
* **How it's computed**:
  * Server-side counts within \[now − window, now].
  * Includes the current event (+1), so first-ever event yields at least 1.
  * Uses server time; not affected by client timezones.
* **Why it matters**: Sudden spikes strongly correlate with automation, credential stuffing, scraping, and abuse.

{% hint style="danger" %}
**Default High-Risk Thresholds**

**5m ≥ 25** OR **1h ≥ 150** OR **24h ≥ 1000** → high velocity
{% endhint %}

**Fraud Detection Usage**

* **High burst traffic**: Treat as a strong indicator of automation.
* **Per-site scope**: When `siteKey` is present, velocity is computed per site; otherwise global per IP.
* **Noise considerations**:
  * Popular endpoints can have legitimate spikes; combine with bot, datacenter, or tampering signals for confidence.
  * Logged-in returning users with high velocity may be power users; tune responses accordingly.

**Recommended Actions**

* **Block** when high velocity co-occurs with any of:
  * Datacenter IP, TOR, known abuser IP
  * Bot indicators or browser tampering
* **Challenge** when high velocity is isolated but the user is new/anonymous
* **Allow but monitor** for high velocity from known, low-risk customers

Here are the docs for Visitor Velocity Intelligence that you can copy:

***

### **Visitor Velocity Intelligence**

```json
{
  "visitorVelocity": {
    "5m": 3,
    "1h": 17,
    "24h": 68,
    "7d": 241
  }
}
```

**What it is:** Number of requests from the same `visitorId` (scoped to your siteKey when provided) within rolling 5-minute, 1-hour, 24-hour, and 7-day windows.

**How it's computed:**

* Server-side counts within \[now − window, now].
* Includes the current event (+1), so first-ever event yields at least 1.
* Uses server time; not affected by client timezones.
* Only computed when a `visitorId` is available.

{% hint style="info" %}
**Why it matters:** Tracks request patterns per stable visitor identity, catching automation, credential stuffing, and abuse even when the attacker rotates IPs. Complements IP-based velocity to detect account-level or device-level spikes.
{% endhint %}

**Compared to Request Velocity:**

* `velocity`: Counts by IP address (may aggregate many visitors behind NAT/proxies).
* `visitorVelocity`: Counts by stable `visitorId` (resilient to IP rotation for the same visitor).

{% hint style="danger" %}
**Suggested High-Risk Thresholds**

5m ≥ 10 OR 1h ≥ 60 OR 24h ≥ 500 OR 7d ≥ 2000 → high visitor velocity
{% endhint %}

### Fraud Decision Framework

#### Immediate Block Scenarios

```javascript
// These combinations = definite fraud
const shouldBlock = (
  event.botDetection.detected ||
  event.ipInfo.is_abuser ||
  event.ipInfo.is_tor ||
  (event.tampering.detected && event.tampering.antiDetectBrowser) ||
  (event.ipInfo.is_datacenter && event.botDetection.score > 60)
);
```

#### Challenge/Additional Verification

```javascript
// Suspicious but not definitive
const shouldChallenge = (
  (event.vpn.detected && user.isNewAccount) ||
  (event.tampering.detected && !event.tampering.antiDetectBrowser) ||
  (event.ipInfo.is_datacenter && event.virtualization.detected) ||
  event.botDetection.score > 70
);
```

> #### We also offer our [server-side SDK](https://www.npmjs.com/package/@mugshotlabs/guardianjs-server) which includes many helper functions to save time in destructuring the event data.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guardianstack.ai/documentation/getting-started/guardian-engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.