Canary Token Injection#

InfraGuard injects invisible tracking elements into HTML decoy pages. When a blue teamer or scanner interacts with the decoy, the canary phones home to InfraGuard’s API, revealing who is investigating the redirector.

Canary Types#

Type	Element	Detection Mechanism
Tracking Pixel	1x1 transparent `<img>`	Image load triggers a callback with a unique canary ID
Honeypot Link	Hidden `<a>` tag (CSS `display:none`)	Only HTML parsers and crawlers follow invisible links
Honeypot Form	Hidden fake login form	Credential stuffing tools or manual investigators interact with it

All canary callbacks hit InfraGuard’s own API endpoints, so the operator is alerted via the normal plugin pipeline.

Configuration#

Canary tokens are configured per-domain in the drop_action block:

domains:
  cdn.example.com:
    upstream: "https://10.0.0.5:8443"
    drop_action:
      type: "decoy"
      target: "BankingBlog"    # folder name in pages/
      canary:
        enabled: true
        tracking_pixel: true   # inject 1x1 image canary
        honeypot_link: true    # inject hidden link canary
        honeypot_form: false   # inject hidden form canary (off by default)

How It Works#

Tracking Pixel#

A 1x1 transparent image is injected just before </body>:

<img src="/_ig/px?c=a1b2c3d4e5f6"
     width="1" height="1" alt=""
     style="position:absolute;left:-9999px" />

When loaded, InfraGuard receives a GET request to /_ig/px with the unique canary ID. The requesting IP, User-Agent, and timestamp are recorded.

Honeypot Link#

A hidden anchor tag is injected before </body>:

<a href="/_ig/hp?c=f7e8d9c0b1a2"
   style="display:none;visibility:hidden;position:absolute;left:-9999px"
   tabindex="-1" aria-hidden="true"></a>

Real browsers never render or follow this link. Automated HTML parsers, web crawlers, and scanners that parse the DOM will discover and follow it, revealing themselves.

Honeypot Form#

A hidden fake login form is injected:

<form action="/_ig/hf?c=1a2b3c4d5e6f" method="POST"
      style="position:absolute;left:-9999px;opacity:0;height:0;overflow:hidden"
      tabindex="-1" aria-hidden="true">
  <input type="text" name="username" autocomplete="username" />
  <input type="password" name="password" autocomplete="current-password" />
  <button type="submit">Login</button>
</form>

Credential stuffing tools and manual investigators examining the page source may submit to this form, triggering an alert.

Canary Callback Paths#

Path	Type	Method
`/_ig/px`	Tracking pixel	GET
`/_ig/hp`	Honeypot link	GET
`/_ig/hf`	Honeypot form	POST

Each callback includes a c query parameter with a unique 12-character hex canary ID generated per page render.

Security Notes#

Each canary ID is generated with secrets.token_hex(6) (cryptographically random)
Canary IDs are unique per page render, so each visit generates a distinct callback
HTML injection uses html.escape() on all dynamic values to prevent XSS
Canaries are only injected into responses with text/html content type
The honeypot form is disabled by default since it captures POST data