Skip to main content

Honeytokens — Decoy Credential Detection

Honeytokens are decoy credentials that BleedWatch generates and you deploy into your environment. When an attacker discovers and attempts to use one, BleedWatch immediately detects the intrusion and alerts your team — turning leaked credentials from a risk into a tripwire.

How Honeytokens Work​

The concept is straightforward:

  1. Create — BleedWatch generates a realistic-looking fake credential
  2. Deploy — You place it somewhere an attacker would find it (a .env file, a config repo, a staging server)
  3. Wait — The credential sits dormant until someone tries to use it
  4. Detect — When triggered, BleedWatch records the source IP, timestamp, and access details
  5. Alert — Your team is notified immediately via your configured alert rules

Because the credential is fake, any usage is by definition unauthorized — producing zero false positives.

Why Use Honeytokens?

Traditional detection focuses on what's leaving your network. Honeytokens detect when an attacker is inside your environment, probing for credentials. They complement your existing monitoring by catching lateral movement and credential harvesting.

Token Types​

BleedWatch generates tokens that mimic real credential formats:

TypeFormatBest Placement
AWS Access KeyAKIA... access key + secret.env files, CI/CD configs, S3 buckets
Stripe Secret Keysk_live_...Payment service configs, environment variables
GitHub Tokenghp_....git-credentials, config files, internal wikis
Generic Secret64-character hex stringDatabase connection strings, API configs

Each generated token follows the exact format of its real counterpart, making it indistinguishable to an attacker scanning for credentials.

Creating a Honeytoken​

Step 1: Choose a Type​

Navigate to Honeytokens in the dashboard sidebar and click Create Honeytoken. Select the token type that matches where you plan to deploy it.

Step 2: Configure Placement​

Optionally add:

  • Placement Hint — A note for your team describing where the token is deployed (e.g., "staging repo .env file" or "S3 bucket config backup"). This is for internal tracking only and is not exposed in alerts.
  • Monitor Endpoint — An optional endpoint for additional monitoring (e.g., a CloudTrail ARN for AWS keys or a webhook URL for external integrations).

Step 3: Deploy​

After creation, BleedWatch displays the generated credential. Copy it and place it in your chosen location. Common deployment strategies:

  • Repository .env files — Place an AWS key in a .env.example or .env.staging that an attacker browsing your repos would find
  • CI/CD variables — Add a Stripe key as an unused environment variable in your build pipeline
  • Internal documentation — Embed a GitHub token in a "legacy credentials" page on your internal wiki
  • Cloud storage — Drop a config file containing the token in an S3 bucket or GCS bucket
Deployment Best Practice

Place honeytokens where a real credential would exist but where legitimate systems won't use them. Avoid placing them in paths that automated tools or legitimate services access, which could trigger false alerts.

Monitoring Honeytokens​

The Honeytokens dashboard shows:

MetricDescription
Total DeployedAll honeytokens ever created
ActiveCurrently deployed and monitoring
TriggeredTokens that have detected unauthorized access

Token Statuses​

StatusMeaning
ActiveDeployed and monitoring — no unauthorized access detected
TriggeredAn attacker attempted to use this credential
DisabledRetired from monitoring (soft-deleted)

When a Honeytoken Triggers​

When an attacker uses a honeytoken, BleedWatch captures:

  • Source IP address — Where the request originated
  • Timestamp — Exact time of the access attempt
  • Trigger details — Additional context about the access (request headers, authentication attempt details)

The token status changes from Active to Triggered, and your configured alert rules fire immediately.

  1. Investigate the source IP — Determine if it's an internal or external address
  2. Check the placement location — Verify whether the credential file or system was accessed
  3. Assess lateral movement — The attacker likely has access to wherever the honeytoken was stored
  4. Rotate real credentials — If the honeytoken was co-located with real secrets, rotate them immediately
  5. Preserve evidence — The trigger details in BleedWatch serve as forensic evidence

Best Practices​

  • Deploy multiple token types across different environments for broader coverage
  • Document placements using the placement hint field so your team knows where each token lives
  • Review triggered tokens regularly — even if alerts fire, periodic review ensures nothing is missed
  • Rotate placements periodically — move honeytokens to new locations to maintain coverage as your infrastructure evolves
  • Combine with alerts — Configure alert rules for honeytoken triggers to ensure immediate notification via Slack, email, or webhook

Troubleshooting​

Honeytoken Not Triggering​

If you believe an attacker accessed your honeytoken but no trigger was recorded:

  1. Verify the token is still in Active status
  2. Confirm the attacker used the credential (merely viewing it does not trigger detection — the credential must be used in an authentication attempt)
  3. Check your placement — ensure the deployed value matches exactly what BleedWatch generated

Too Many Triggers​

If a honeytoken triggers repeatedly from the same source, it may be placed in a location accessed by automated tools. Consider moving it to a less-trafficked location or disabling the token and creating a new one elsewhere.