See the attack. Act on it.

The mental model

Three moving parts, in order:

1. Signals come in — security events reported by the SDKs, each with a type, a severity, and a confidence score. Some carry a cross-customer threat-intel match.
2. Rules watch those signals. A rule’s trigger is a set of security types plus thresholds; when they’re met, the rule takes exactly one action.
3. Incidents are the human side. Actions that raise an incident create a triage record — status, severity, assignee, and an append-only timeline — that your team works to resolution.

That flow is the reactive layer: it responds to signals after they’re reported. TillShield also has an inline layer — a request-time WAF that enforces a separate kind of rule (matched on the request itself, not on telemetry) at your own edge or origin. The two are distinct: reactive rules watch security events and take an account-level action; inline rules allow, block, challenge, or log a request as it arrives. See Inline enforcement.

How detection works

TillShield doesn’t collect anything itself. It consumes the security events your TillPulse SDKs emit and normalizes them into a small set of security types:

Severity and confidence

Every signal lands with two numbers you write rules against. Severity is how serious the detection is (low → critical). Confidence is how sure the SDK is that the detection is real, from 0 to 1. Keeping the two separate is deliberate: a low-confidence critical and a high-confidence low are very different situations, and you get to decide how each is handled.

Writing reactive rules

A reactive rule is a trigger and an action. The trigger selects which signals count and how many, over what window, before the rule fires. (For request-time rules matched at the edge, see Inline enforcement — a different rule shape.)

{
  name: "integrity-lockdown",
  when: {
    types: ["device_compromised", "cert_pinning_failure"],
    minSeverity: "high",       // low | medium | high | critical
    minConfidence: 0.8,        // 0..1
    threshold: { count: 3, within: "10m" },
  },
  then: { action: "revoke_sessions" },
  testMode: false,             // dry-run: log, don't act
  cooldown: "30m",
}

The trigger

• types — one or more security types the rule watches.
• minSeverity — ignore anything below this severity.
• minConfidence — ignore anything the SDK isn’t sure enough about.
• threshold — a count of matching signals within a time window. One-offs don’t have to fire the rule; a burst does.

The action

A rule takes exactly one of four actions when it fires:

• raise_incident — open a triage record with the triggering events attached.
• quarantine_session — cut off the offending session, leaving the rest of the account intact.
• revoke_auth_sessions — end every auth session for the user; TillShield asks TillAuth to do it. Gated by default — see the note below.
• alert — notify the channel you already route TillPulse alerts to.

Test-mode and cooldowns

Turn on testMode to run a rule as a dry-run: it evaluates the trigger and logs what it would have done, without doing it. Use it to tune thresholds against real traffic before a rule can revoke anyone’s session. A per-rule cooldown then caps how often the action can repeat, so a single persistent attacker can’t make the rule fire a hundred times a minute.

Inline enforcement (the WAF)

Reactive rules act after a signal is reported. The inline layer acts during the request: a WAF that runs at your own edge or origin and turns a detection into a decision before the response is served. It ships as two server-side SDKs and a drop-in Worker; you manage the rules and the threat-intel feed from the dashboard.

How it works on the hot path:

• Local evaluation. Your compiled ruleset — plus a sha256 threat-intel deny list — is fetched from TillDev and cached. Every request is then decided locally, in-process: no round-trip to TillDev on the hot path.
• Async reporting. Decisions are batched and reported back to TillDev out of band (never blocking the response), so they show up in your dashboard and feed the shared deny list.
• Fail-open by default. If the config can’t be reached before the first fetch, or an internal error occurs, the request is allowed through. Set the fail mode to closed if you’d rather reject on uncertainty.
• Optional incident roll-up. A per-rule flag rolls repeated blocks up into a TillShield incident, so the same triage workflow covers inline activity.

Edge keys

The inline SDKs authenticate with a per-project, server-side edge key — a secret prefixed tse_, minted in the dashboard under Shield → Inline WAF. It is distinct from your public ingest DSN: the DSN is a publishable client credential, the edge key is a server secret that must never ship to a browser or app bundle. Provide it as an environment variable and the SDK sends it as a bearer token when it fetches config.

The inline SDKs

The inline layer ships as two server-side SDKs and a zero-code Worker. Pick the one that matches where your traffic terminates — each fetches your ruleset, caches it, and enforces decisions in-process.

@tillstack/shield-node

For Node origins. One package, three adapters — Express / Connect middleware, a Fastify onRequest hook, and a raw http handler:

import { createShield } from '@tillstack/shield-node'

const shield = createShield({ edgeKey: process.env.SHIELD_EDGE_KEY })

app.use(shield.express())            // Express / Connect
// Fastify: fastify.addHook('onRequest', shield.fastifyHook)

Blocked and challenged requests are answered by the SDK (with an x-tillshield header); everything else falls through to your app untouched.

@tillstack/shield-cloudflare

For Cloudflare Workers. It decides at the edge using Cloudflare’s own request signals (CF-Connecting-IP, request.cf.country). Wrap your fetch handler; pass a KV namespace for a rate limiter shared across isolates:

import { createShield, type ShieldCloudflare } from '@tillstack/shield-cloudflare'

let shield: ShieldCloudflare | null = null   // env only exists per-request

export default {
  fetch(req: Request, env: Env, ctx: ExecutionContext) {
    shield ??= createShield({ edgeKey: env.SHIELD_EDGE_KEY, kv: env.SHIELD_KV })
    return shield.wrap(() => new Response('ok'))(req, env, ctx)
  },
}

Full wiring — per-isolate caching, fail modes, KV rate limits, TillGate interstitials, key hygiene — in the Workers guide.

Drop-in edge worker (tillshield-edge)

Zero application code. tillshield-edge is a ready-made reverse-proxy Worker: set SHIELD_EDGE_KEY (as a secret) and SHIELD_ORIGIN (where clean traffic should go), deploy it, and route your hostname at it. Requests are screened at the edge and forwarded to your origin — nothing in your app changes.

wrangler secret put SHIELD_EDGE_KEY     # tse_…
wrangler deploy --var SHIELD_ORIGIN:https://origin.example.com
# then point your hostname's route at the deployed worker

Conditions, modes, and rate limits

An inline rule has a priority (lower runs first; the first rule that matches decides the request), a set of AND-combined match conditions, a mode, and an optional rate limit. Values in an array are OR-combined; an empty match matches every request (pair it with a rate limit for a blanket limiter).

A rate_limit adds a token-bucket cap: requests per window_seconds, keyed by by: "ip" or by: "ip_path". When the bucket is exhausted the rule’s mode applies and a Retry-After is set.

{
  name: "deny-known-hostile",
  priority: 10,               // lower runs first; first match wins
  mode: "block",              // block | challenge | log
  match: {
    threat_intel: true,       // sha256(client IP) in the shared deny list
    paths: ["/api/*", "/login"],
    methods: ["POST"],
  },
  rate_limit: { requests: 20, window_seconds: 60, by: "ip" },
  response_status: 403,
}

Rules and the threat-intel deny list are managed from the TillShield section of your workspace; the SDKs only fetch and enforce them. Changes propagate on the next config refresh — no redeploy.

Incident triage

A raise_incident action creates a record your team works — not another alert to acknowledge and forget. Every incident has a status, a severity, an assignee, and a timeline.

Status

Incidents move through four states, in order:

open → investigating → contained → resolved

• open — freshly raised, unowned.
• investigating — someone is on it.
• contained — the threat is stopped; cleanup remains.
• resolved — closed out, with the record intact.

The timeline

The timeline is append-only. Notes your team adds, every status change, and every action a rule took automatically are one ordered history — nothing is edited away after the fact. Assign an incident to a teammate and it shows up on their plate; the severity and the triggering events stay attached from open to resolved. Every one of these changes is also written to the shared TillDev audit log.

Threat intelligence & the privacy model

When a malicious package, certificate, or binary is seen attacking one TillDev customer, its indicator is shared across every org — so a threat that has hit someone else can surface for you before it reaches your users. The value is obvious; the trick is doing it without leaking anyone’s data.

The model is deliberately narrow:

• sha256 indicators only. What’s shared is a one-way hash of the offending artifact — a package name, certificate, binary, or hashed client IP — never the value itself. There is no reversible payload and no raw identifier in the feed.
• Hashes, never plaintext. We store only sha256 hashes, never plaintext, so no raw identifier lands in the shared table. The indicator’s job is simply to carry the type label (“this package is hostile”) — it flags a known-bad artifact across orgs; it is not a store of confidential data.
• Anonymous. No org identity travels with an indicator. You learn that a fingerprint is hostile; you never learn who it attacked first.
• Opt-out is real, and per-workspace. Contribution to the shared feed is on by default and can be turned off in Shield → Settings. Turning it off stops your indicators from being written to the global feed — and you still consume the shared feed either way.
• An implemented signal, not a footnote. When an incoming event’s hashed indicator is already known-hostile in the shared feed, TillShield emits a threat_intel_match security event with its own severity and confidence — so the same reactive rules and actions apply. You can revoke sessions on a known-bad binary the same way you would on repeated device_compromised reports.

Enabling SDK security capture

TillShield only sees what your SDK sends. Device-integrity, pinning, and overlay checks live in the TillPulse mobile SDKs and are enabled in your SDK configuration — turn on the checks you want and the events flow into TillShield automatically. Conceptually:

import { init } from '@tillstack/react-native'

init({
  dsn: process.env.TILLPULSE_DSN,
  // Security capture feeds TillShield. Enable the checks you need.
  security: {
    deviceIntegrity: true,   // root / jailbreak
    tlsPinning: true,        // pinning-failure reporting
    overlayDetection: true,  // Android overlay abuse
  },
})

The exact option names and platform coverage live in the SDK reference — React Native and Flutter. Once security events are arriving, you write rules against them from the TillShield section of your workspace; no rule fires until you create one.