Operations

Honeypot currently supports the following operations:

Operation	Description	Common Use Case
count	Counts the number of events matching the criteria within the time window.	Rate limiting, activity monitoring
unique	Tracks unique values for specified fields within the time window.	Multi-account detection, unique visitors
distance	Calculates geographic distance between consecutive events.	Impossible travel detection
proximity	Tracks proximity to a "normal" location using weighted or session-based updates.	Location-based fraud detection
ratio	Calculates ratios between two event types.	Credential stuffing
sequence	Detects ordered sequences of events with completion tracking.	Funnel analysis, user journeys
time_between	Measures time intervals between consecutive events.	Session analysis, timing patterns

Each operation is described in detail below, including configuration examples and response formats.

Count Operation

Counts the number of events matching the criteria within the time window.

Config Example: Count login attempts per device in 10 minutes

{
  "name": "login_attempts_10m",
  "operation": "count",
  "group_by": "device_id",
  "window_duration_seconds": 600,
  "filters": { "field": "event_name", "operator": "equals", "value": "login" }
}

Returns: { count: number }

Return Example:

{
    "behaviors": {
        "login_attempts_10m": {
            "count": 3,
            "timestamp": "2025-06-12T16:52:04.940Z",
            "remaining_window_seconds": 586
        }
    }
}

Unique Operation

Tracks unique values for specified fields within the time window.

Config Example: Unique emails per handprint

{
    "name": "unique_emails_by_handprint_30d",
    "operation": "unique",
    "group_by": "handprint_id",
    "fields": [
        "event_properties.email"
    ],
    "window_duration_seconds": 2592000,
    "filters": []
}

Returns: { values: string[], unique: number }

Return Example:

{
    "behaviors": {
        "unique_emails_by_handprint_30d": {
            "values": [
                "a@example.com",
                "b@example.com",
                "c@example.com",
                "d@example.com"
            ],
            "unique": 4,
            "timestamp": "2025-06-02:45:49.407Z",
            "remaining_window_seconds": 2591981
        }
    }
}

Distance Operation

Calculates geographic distance between consecutive events.

Config Example: Distance between login locations

{
    "name": "distance_between_phone_login_10m",
    "operation": "distance",
    "group_by": "event_properties.phone",
    "window_duration_seconds": 600,
    "filters": { "field": "event_name", "operator": "equals", "value": "Login" }
}

Returns: { distance: number, latitude: number, longitude: number }

Example Event Sequence

// user logs in from (34.0522, -118.2437)
honeypot.track('Login', {"phone": "123-456-7890"})

// sometime later...

// user logs in from (40.7128, -74.006)
honeypot.track('Login', {"phone": "123-456-7890"})

Example Response

{
    "behaviors": {
        "distance_between_login_10m": {
            "distance": 0,
            "latitude": 34.0515,
            "longitude": -84.0713,
            "timestamp": "2025-06-12T20:55:57.783Z",
            "remaining_window_seconds": 600
        }
    }
}

Note: If fields are not specified, uses latitude and longitude from event data.

Proximity Operation

Tracks proximity to a "normal" location using weighted or session-based updates.

Config Example: User's proximity to normal location

{
    "name": "proximity_to_normal_location_30d",
    "operation": "proximity",
    "group_by": "device_id",
    "window_duration_seconds": 2592000
}

Returns:

{
  "normal_location": { "latitude": number, "longitude": number },
  "distance_to_normal": number,
  "average_distance": number,
  "visit_count": number,
  "distance_sum": number,
  "current_location": { "latitude": number, "longitude": number }
}

Example Response

{
    "behaviors": {
        "proximity_to_normal_location_30d": {
            "normal_location": {
                "latitude": 34.0515,
                "longitude": -84.0713
            },
            "distance_to_normal": 0,
            "average_distance": 0,
            "visit_count": 2,
            "distance_sum": 0,
            "current_location": {
                "latitude": 34.0515,
                "longitude": -84.0713
            },
            "timestamp": "2025-06-12T21:13:49.219Z",
            "remaining_window_seconds": 2591988
        }
    }
}

Configuration Options:

• weighted: Use weighted updates for normal location (default: false)
• weight: Weight for updates when weighted is true (default: 0.2)
• session_threshold_miles: Distance threshold for session-based updates (default: 50)

Ratio Operation

Calculates ratios between two event types (e.g., failed vs total logins).

Config Example: Failed login ratio

{
    "name": "ratio_of_failed_logins_1hr",
    "group_by": "session_id",
    "operation": "ratio",
    "fields": ["Failed Login", "Login"],
    "window_duration_seconds": 3600,
    "operation_config": {
        "allow_intermediate_events": false
    }
}

Returns: { n: number, d: number, ratio: number }

Example Response: Failed login ratio Let's say a fails to login 4 times before a successful login. The data would look like this:

{
    "behaviors": {
        "ratio_of_failed_logins_1hr": {
            "n": 4,
            "d": 1,
            "ratio": 0.8,
            "timestamp": "2025-06-12T21:25:52.972Z",
            "remaining_window_seconds": 3543
        }
    }
}

Note:

• First field in fields is numerator, second is denominator
• Ratio = numerator / (numerator + denominator)
• Use pipe-separated values for multiple event types: "failed_login|login_error"

Sequence Operation

Detects ordered sequences of events with completion tracking.

Configuration Example: Content Sharing Sequence

{
    "name": "sequence_content_sharing_1hr",
    "group_by": "handprint_id",
    "operation": "sequence",
    "fields": ["Sign Up", "Generate Content", "Share Content"],
    "window_duration_seconds": 3600,
    "operation_config": {
        "allow_intermediate_events": true
    }
}

Returns:

{
  "index": number,
  "completed": number,
  "start_time": number,
  "percent_complete": number,
  "completion_times": number[],
  "completion_time_stats": {
    "avg": number,
    "max": number,
    "min": number,
    "sum": number,
    "last": number
  },
  "intermediary_events": number,
  "unique_intermediate_events": string[],
  "event_ids": string[]
}

Configuration Options:

• allow_intermediate_events: Allow other events between sequence steps (default: false)
• allow_duplicates: Allow duplicate events in sequence (default: true)

Example Response:

{
    "behaviors": {
        "sequence_content_sharing_1hr": {
            "index": 2,
            "completed": 1,
            "start_time": 1749764339011,
            "percent_complete": 100,
            "completion_times": [
                59.386
            ],
            "completion_time_stats": {
                "avg": 59.386,
                "max": 59.386,
                "min": 59.386,
                "sum": 59.386,
                "last": 59.386
            },
            "intermediary_events": 1,
            "unique_intermediate_events": [
                "Page View"
            ],
            "event_ids": [
                "e94ae251-232f-41a8-94f0-fc8eb4510f1c",
                "08d7e2f0-4beb-4506-a3f9-4a05ba3abacf",
                "63fe84d4-8638-4449-9a37-a6e3b9e5243a"
            ],
            "timestamp": "2025-06-12T21:38:35.091Z",
            "remaining_window_seconds": 3516
        }
    }
}

Time Between Operation

Measures time intervals between consecutive events.

Configuration Example: Time between login events

{
    "name": "time_between_logins_15m",
    "group_by": "event_properties.email",
    "operation": "time_between",
    "window_duration_seconds": 900,
    "filters": { "field": "event_name", "operator": "equals", "value": "Login" }
}

Returns:

{
  "count": number,
  "time_between_seconds": number,
  "last_timestamp": string
}

Example: Time between login attempts

{
    "behaviors": {
        "time_between_logins_15m": {
            "count": 3,
            "time_between_seconds": 2,
            "last_timestamp": "2025-06-12T21:49:01.872Z",
            "timestamp": "2025-06-12T21:48:56.473Z",
            "remaining_window_seconds": 894
        }
    }
}