From zero to a live detection in five steps.

This walkthrough takes you from an empty workspace to events flowing through behavioral models in about five minutes. We'll use the AWS CloudTrail connector — substitute any of the other 80+ sources without changing the rest.

Prerequisites

• A threatDefendr workspace — start a free trial if you don't have one.
• macOS, Linux, or WSL2. Windows native is supported through the CLI but examples assume a Unix shell.
• Permission to deploy a connector in the source account (CloudTrail, in our case).

1. Install the CLI

The td CLI is the fastest path in. Install it with Homebrew, the install script, or download a static binary.

SHELLbrew
$ brew install threatdefendr/tap/td
✓ td 2026.06.20 installed

$ td --version
td 2026.06.20 (build a4f1c2e)

Or, on any system with curl:

SHELLinstall.sh
$ curl -fsSL https://td.sh/install | sh

2. Authenticate

Run td auth login. The CLI opens your browser, completes SSO against your IdP, and writes a token to ~/.config/td/credentials.

SHELLlogin
$ td auth login
Opening browser…
✓ Logged in as alex@acme.io
✓ Active workspace: acme-prod (us-east-1)

3. Deploy a connector

Connectors are the bridge between your data sources and the threatDefendr fabric. They auto-provision IAM, subscribe to events, and start streaming. List what's available:

SHELLlist connectors
$ td connector available --surface=cloud
NAME                  STATUS     EVENTS/S    AVG INGEST
aws-cloudtrail        stable     ~120k       210ms
aws-guardduty         stable     ~4k         180ms
azure-activity        stable     ~85k        240ms
gcp-audit-log         stable     ~60k        220ms
m365-unified-audit    stable     ~95k        260ms
okta-system-log       stable     ~12k        140ms
... 74 more

Deploy the CloudTrail connector against the management account of your AWS Organization. The CLI will print the IAM trust policy it needs, wait for you to apply it (or use --auto-iam if running with admin credentials), then provision the subscription.

SHELLdeploy
$ td connector deploy aws-cloudtrail \
    --region=us-east-1 \
    --org-trail=acme-organization-trail \
    --auto-iam

→ Provisioning IAM role td-cloudtrail-reader… ok
→ Subscribing to CloudTrail Lake…           ok
→ First event received from acme-prod…       ok
✓ Connector cn_3kPqR9 deployed in 12s
  workspace: acme-prod
  events seen: 84 (since deploy)
  health:     ● HEALTHY

4. Tail events

Now confirm data is flowing. td events tail opens a live stream with severity coloring, filterable by source, severity, or attribute.

SHELLtail
$ td events tail --severity=high --limit=5
2026-06-20T14:21:08Z HIGH  ev_8X… IRONVEIL signed-driver load (host=db-prod-02)
2026-06-20T14:21:09Z HIGH  ev_8Y… lateral WinRM (src=10.4.0.18, dst=db-prod-02)
2026-06-20T14:21:11Z MED   ev_8Z… anomalous OAuth grant (user=svc-deploy)
2026-06-20T14:21:14Z HIGH  ev_90… kerberoasting attempt (account=svc-svc-jenkins)
2026-06-20T14:21:18Z MED   ev_91… large s3 cross-acct copy (bucket=acme-research)

5. Ship a detection

Behavioral models are running by default. To add an organization-specific detection, define one in YAML and commit it. The CLI validates, dry-runs against the last 24 hours of events, then deploys.

YAMLdetections/svc-account-from-corp-ip.yml
version: 1
id: svc-account-from-corp-ip
title: Service account authenticated from corporate IP
severity: HIGH
tactic: [TA0006] # Credential Access

when:
  stream: identity.signin
  match:
    actor.type: service_account
    net.src_geo.cidr_label: corp-egress
  window: 5m

then:
  create_case: true
  contain:
    action: disable-actor
    requires_approval: true

SHELLdeploy detection
$ td detect deploy ./detections/svc-account-from-corp-ip.yml
→ Validating schema…                       ok
→ Dry-run against last 24h…                 ok (3 historical matches)
→ Compiling to streaming plan…              ok
→ Deploying to acme-prod…                 ok
✓ Detection det_2vK4nT is now LIVE
  evaluation lag: p50 218ms · p99 612ms

Where to go next

Now that you've shipped one detection, the natural next stops:

• API reference — query events, list detections, drive cases from your own apps.
• SDKs — native Python / TypeScript / Go libraries.
• Architecture — understand the fabric you're now sitting on top of.
• Detection-as-code guide — the deep version of step 5.