> ## 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.

# Core concepts

> The objects Thumper revolves around.

Everything follows a **definition → instance** shape: a *Tripwire* is authored
once, and deploying it mints a separate *Deployment* - with its own bait and its
own secret - for every machine it lands on. Reads become *Alerts*.

## Tripwire

A **tripwire** is a *definition* - a credential recipe. It lives on no machine.
It records what kind of bait to plant and where, not the bait itself:

* **`token_type`** - the honeytoken to generate (AWS access key, GitHub PAT, GCP
  service account, Azure token, SSH private key).
* **`path`** - the recommended location to plant it (e.g. `~/.aws/credentials`).
* **`source`** - how the bait content is produced: `template` (Thumper generates
  a realistic fake - the default), `custom` (you supply the content), or
  `managed` (a monitored real credential, planned).
* **`active`** - whether the tripwire is currently deployable.

From a tripwire, Thumper builds an **install command** you hand to your fleet.
The definition itself plants nothing.

## Endpoint

An **endpoint** is a machine that has **self-enrolled** with the server. When
your MDM/SSH runs a tripwire's install command on a device, the agent calls
`POST /api/enroll` with a shared enroll token and registers itself - recording
its `hostname`, `platform`, and a unique `machine_id`. The server tracks
`last_seen` on each callback, so the dashboard shows which boxes are live.

Your MDM decides *which* machines are in scope; Thumper just records the ones
that enroll.

## Deployment

A **deployment** is one tripwire planted on one endpoint - the *instance* in the
model. Deploying a tripwire to a fleet mints **one deployment per endpoint**,
and each one is unique:

* **`content`** - the bait actually written to disk on that box, rendered for
  that endpoint.
* **`hmac_secret`** - a per-deployment secret, 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.

A deployment also tracks its `path`, its `state` (`pending` until the agent
confirms the bait is planted), and `last_triggered`. Because the bait and secret
are unique per box, a leak on one machine can't forge another's triggers - and a
read is attributable to exactly one endpoint. (A tripwire and an endpoint pair to
at most one deployment.)

## Alert

An **alert** is the record created the moment a deployment's bait is read. The
agent fires an HMAC-signed, enriched callback to `POST /api/trigger`; once the
server verifies it, it writes an alert and fans it out to every configured alert
integration. Each alert captures:

* **What fired** - the `deployment`, `tripwire`, and `endpoint` it belongs to,
  plus denormalized `tripwire_name`, `endpoint_hostname`, and `token_type` so the
  alert reads on its own.
* **The read itself** - `accessed_path`, `process`, `pid`, `os_user`, and
  `event_type`, where the sensor can supply them.
* **When** - a `timestamp` and a compact `triggered_by` summary.

An alert means a process read a credential that exists only to be read. That box
should be treated as compromised.


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