> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jesta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> From a tripwire definition to a fired alert.

A tripwire starts as a definition on the server and ends as a verified alert in
the configured SIEM. In between, fleet tooling plants a unique honeytoken on each
machine and the on-box agent watches it.

## The flow

<Steps>
  <Step title="Define" icon="pen-to-square" iconType="solid">
    <Icon icon="pen-to-square" color="#3b82f6" size={20} /> You create a
    **tripwire** in the UI - a token type, a source, and a path. The server stores
    the definition and builds an install command for it.
  </Step>

  <Step title="Distribute" icon="share-nodes" iconType="solid">
    <Icon icon="share-nodes" color="#8b5cf6" size={20} /> Your MDM/SSH runs that
    install command on the machines you choose. *Your* tooling is the control
    plane for which machines are in scope - Thumper doesn't manage device groups.
  </Step>

  <Step title="Enroll & plant" icon="seedling" iconType="solid">
    <Icon icon="seedling" color="#10b981" size={20} /> On each machine the Bash
    agent calls `POST /api/enroll` with the shared enroll token, then
    `GET /api/agent/deployments` to pull its **own** instances. It writes the bait
    to disk and starts watching.
  </Step>

  <Step title="Watch" icon="eye" iconType="solid">
    <Icon icon="eye" color="#06b6d4" size={20} /> The agent monitors the bait
    paths for a read (via `fs_usage` on macOS; see
    [Read detection](/thumper/read-detection)).
  </Step>

  <Step title="Trigger" icon="bell" iconType="solid">
    <Icon icon="bell" color="#ef4444" size={20} /> On a read, the agent POSTs an
    HMAC-signed, enriched callback to `POST /api/trigger`. The server verifies the
    signature, records an **alert**, and fans it out to every configured alert
    integration.
  </Step>
</Steps>

## Why per-endpoint uniqueness matters

Deploying a tripwire mints a separate **deployment** for every endpoint, and each
one carries its **own** bait content and its **own** HMAC secret. The secret is
minted server-side and handed only to that endpoint's agent - it is never
returned by the UI API and never written into the planted file.

That isolation buys two things:

* **No cross-box forgery.** A secret leaked from one machine can't be used to
  forge a trigger for another. Each deployment can only sign for itself.
* **Attributable reads.** Because the bait and secret are unique per box, a fired
  alert points to exactly one endpoint - there's no ambiguity about which machine
  was touched.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.