Introduction to WebDecoy

What is WebDecoy?

WebDecoy is a deception-based threat detection platform that helps you identify and respond to malicious actors targeting your web applications. Unlike traditional security tools that try to block known threats, WebDecoy uses honeypots and decoy resources to detect attackers through their behavior.

The Deception Approach

When attackers probe your systems, they don’t know which resources are real and which are traps. WebDecoy creates convincing decoy links, fake API endpoints, and hidden honeypot elements that legitimate users never interact with. When someone does interact with these decoys, you know immediately that they’re either:

• Automated bots scanning your site
• Malicious actors looking for vulnerabilities
• Scrapers stealing your content
• Reconnaissance tools mapping your infrastructure

Key Capabilities

Feature	Description
Decoy Links	Hidden honeypot links that detect scanners and crawlers
API Honeypots	Fake API endpoints that catch attackers probing for vulnerabilities
Bot Scanners	JavaScript-based detection of automated browsers and bots
Threat Intelligence	IP reputation, geolocation, and abuse history for every detection
MITRE ATT&CK Mapping	Industry-standard threat classification for detected behaviors
Automated Response	Integration with Cloudflare, AWS WAF, and other services for automatic blocking

---

How WebDecoy Protects Your Applications

WebDecoy provides multiple layers of detection that work together to identify threats:

Detection Layers

┌─────────────────────────────────────────────────────────────┐
│                    Your Web Application                      │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Decoy Links                                        │
│  Hidden links that only automated tools discover             │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: API Honeypots                                      │
│  Fake endpoints that catch vulnerability scanners            │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Bot Scanner (JavaScript)                           │
│  Client-side detection of headless browsers and automation   │
├─────────────────────────────────────────────────────────────┤
│  Layer 4: Form Honeypots                                     │
│  Invisible form fields that catch spam bots                  │
└─────────────────────────────────────────────────────────────┘

Detection Flow

1. Visitor arrives at your website or application
2. Bot Scanner (if enabled) analyzes the browser for automation signatures
3. Decoy interactions are monitored for any access to honeypot resources
4. Detection is created when suspicious activity is detected
5. Threat scoring calculates a unified risk score (0-100)
6. MITRE mapping classifies the behavior using industry standards
7. Response actions can automatically block the attacker via integrations

What Gets Detected

WebDecoy catches a wide range of malicious activities:

• Web Scrapers - Tools that steal your content
• Vulnerability Scanners - Tools probing for security weaknesses
• Credential Stuffers - Automated login attempts with stolen passwords
• API Abusers - Bots exploiting your API endpoints
• Reconnaissance - Attackers mapping your infrastructure
• AI Crawlers - Unauthorized AI training data collection

---

Key Terminology

Understanding these terms will help you use WebDecoy effectively:

Core Concepts

Term	Definition
Organization	Your account container. All resources (domains, decoys, detections) belong to an organization. Organizations are also the billing unit.
Property	A logical grouping within your organization. Use properties to separate different websites, applications, or environments (e.g., “Production Website”, “Staging API”).
Decoy	A honeypot resource that legitimate users never access. Can be a link, API endpoint, or form field.
Detection	A recorded event when someone interacts with a decoy or triggers bot detection. Contains full details about the request and threat assessment.

Detection Terms

Term	Definition
Threat Score	A unified risk score from 0-100 that combines multiple signals into a single assessment. Higher scores indicate greater risk.
Bot Score	A 0-100 score specifically measuring the likelihood that a visitor is automated (bot) vs. human.
MITRE ATT&CK Tactic	A standardized classification of attacker behavior from the MITRE ATT&CK framework (e.g., “Reconnaissance”, “Initial Access”).
Confidence Level	How certain WebDecoy is about a detection (High, Medium, Low).

Resource Types

Term	Definition
Decoy Link	A hidden honeypot URL on your website that legitimate users cannot see or access.
Endpoint Decoy	A fake API endpoint (supports POST, PUT, DELETE) that captures attack attempts.
Bot Scanner	A JavaScript snippet that runs in visitors’ browsers to detect automation.
Custom Domain	Your own domain configured to serve decoy content via WebDecoy.

Threat Categories

Term	Definition
Bot	Automated software visiting your site (may be good or bad).
Attacker	Someone actively attempting to exploit vulnerabilities.
Scanner	Automated tools probing for security weaknesses.
Crawler	Bots indexing content (search engines are good crawlers).
Scraper	Tools copying your content without permission.

---

Platform Architecture Overview

WebDecoy consists of three main components that work together:

System Components

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│                  │     │                  │     │                  │
│    Dashboard     │────▶│    Backend API   │────▶│  Ingest Service  │
│    (Frontend)    │     │                  │     │                  │
│                  │     │                  │     │                  │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                         │                        │
        │                         │                        │
        ▼                         ▼                        ▼
   You manage:              Stores:                  Handles:
   - Decoys                 - Organizations          - Decoy requests
   - Domains                - Properties             - Bot detections
   - Integrations           - Detections             - SSL certificates
   - Settings               - Subscriptions          - Custom domains

Dashboard (Frontend)

The web-based interface where you:

• View and analyze detections
• Create and manage decoys
• Configure bot scanners
• Set up integrations
• Manage billing and settings

Backend API

The central service that:

• Stores all your data securely
• Manages authentication via Auth0
• Processes subscription billing via Stripe
• Coordinates integrations with third-party services

Ingest Service

The detection engine that:

• Receives decoy interactions in real-time
• Enriches detections with threat intelligence
• Calculates threat and bot scores
• Triggers automated response actions
• Manages SSL certificates for custom domains

Data Flow Example

Here’s what happens when an attacker triggers a decoy:

1. Attacker visits your decoy URL (e.g., https://yourdomain.com/admin-backup.zip)
2. Ingest service receives the request on your custom domain
3. Threat enrichment adds IP reputation, geolocation, and fingerprinting
4. Scoring engine calculates unified threat score
5. MITRE mapping classifies the behavior (e.g., “Reconnaissance”)
6. Detection created and stored in the database
7. Integrations triggered (e.g., Cloudflare blocks the IP)
8. Dashboard updated with the new detection for your review

---

Next Steps

Now that you understand what WebDecoy does, let’s get you set up:

• Account Setup and Login - Create your account and log in
• Setting Up Your Organization - Configure your first organization