Exfiltration guard and canaries

canary stops a stolen secret or a bulk copy of personal data leaving your app, and plants records and keys that raise an alarm when an intruder touches them.

The guard is off until main.yaml has an exfiltration or canaries section. Once on, it adds one in-memory scan to outbound calls and responses.

exfiltration:
  mode: enforce
  outbound:
    secrets: block
    receivers: { api.partner-crm.com: [personal] }
  responses:
    pan: block
    bulk: { personal: 500 }
    actor-window: { window: 1h, personal: 5000 }
canaries:
  records: { users: 2 }
  keys: true
  on-touch: alert

import { canary } from "mainsdk/canary";

// plant two canary users in each region's canary tenant, once; counts only, never ids
await canary.plant("users", { count: 2 });
const { records } = await canary.status();   // { users: 4 }

canary:
  driver: builtin

Quick start

exfiltration:
  mode: enforce
  outbound:
    secrets: block
    receivers: { api.partner-crm.com: [personal] }
  responses:
    pan: block
    bulk: { personal: 500 }
    actor-window: { window: 1h, personal: 5000 }
canaries:
  records: { users: 2 }
  keys: true
  on-touch: alert

import { canary } from "mainsdk/canary";

// plant two canary users in each region's canary tenant, once; counts only, never ids
await canary.plant("users", { count: 2 });
const { records } = await canary.status();   // { users: 4 }

Configuration

The Quick start block above shows every section. Unknown keys and invalid values fail mainsdk check with MAIN-EXFIL-0006.

What you get

What it always does

• A resolved secret leaves only for its own provider, in any common encoding, and the value is never logged
• A response carrying a secret or a card number becomes a 500 with no value in it
• A canary touch raises one critical security event and the reader is not told
• Never in the request path beyond one in-memory scan; fail static

What the guard checks

mode is observe (log a would-block), warn (log and write a security event) or enforce (block). A push of main.exfiltration.mode can only move toward enforce; anything looser is refused with MAIN-CONFIG-0021.

Canaries

Canary records belong to a canary owner in each region (canary-us, canary-eu, canary-in), so an owner-scoped query never returns one and raises nothing. A cross-owner read, an unscoped support query or a dump that returns one raises a single critical canary.touched event with MAIN-CANARY-0001; the response is unchanged unless on-touch: block. The registry of ids is kept as HMAC-SHA256 values under MAINSDK_CANARY_KEY from secrets, so a reader of the database cannot tell which rows are canaries. canary.status and the CLI show counts only.

With keys: true, plant also stores a decoy API key as MAINSDK_CANARY_TOKEN, referenced by no code. Presenting it to apikeys.verify is refused like an unknown key (MAIN-APIKEY-0002) and raises canary.key_used with MAIN-CANARY-0002; so does sending it out or returning it.

mainsdk canary plant --env staging
mainsdk canary status --env staging --json

mainsdk check reports MAIN-EXFIL-0006 for an invalid exfiltration value and MAIN-CANARY-0003 for a model that does not exist or a canary set with nothing planted in the env.

Errors and checks

mainsdk check raises MAIN-EXFIL-0006 and MAIN-CANARY-0003; the rest are logged or returned at run time.

• MAIN-CANARY-0001
• MAIN-CANARY-0002
• MAIN-CANARY-0003
• MAIN-EXFIL-0001
• MAIN-EXFIL-0002
• MAIN-EXFIL-0003
• MAIN-EXFIL-0004
• MAIN-EXFIL-0005
• MAIN-EXFIL-0006

Each code's cause and fix is in check codes.

Swapping drivers

There is one driver, so there is nothing to swap today. The calls and main.yaml sections do not depend on it.

Testing

@mainsdk/testing turns the guard on with an empty canaries section, and its attack simulator can drive a canary touch, all offline with the built-in matcher. See Test your app.

Next

• Network permissions
• Secrets
• API keys