Testing by people, on your terms.

Plan an engagement

Under Shield → Engagements, choose New engagement. Give it a name, a kind (purple, red or pentest) and who tests: your own people, or an outside firm. Then write it down the way a statement of work would:

• What it is for, and the rules of engagement, as plain text.
• The assets in scope and out of scope, each with an optional note, up to 50 of each.
• The networks testing comes from, as addresses or CIDR ranges. They must be public and no wider than a /16 for IPv4 or a /32 for IPv6. An outside tester needs at least one.
• The window it may run in, up to 90 days.
• A stop contact: who testers call to stop, or to report something critical at once.

Each engagement gets a number, E-1, E-2 and so on, per workspace. A workspace can have 20 open at once. Only owners and admins see engagements. From the CLI:

tilldev shield engagements plan --name "Q4 pentest" --kind pentest --tester external --firm "Northwind Security" \
  --in-scope api.acme.com,app.acme.com --out-of-scope billing.acme.com --sources 81.2.69.0/24 \
  --starts 2026-11-02T08:00:00Z --ends 2026-11-13T18:00:00Z --stop-contact "+44 20 7946 0000, Sam on call" \
  --rules-file roe.md
tilldev shield engagements authorise 4 --ref "SOW-2026-118"      # owners only; asks for an approval
tilldev shield engagements testers add 4 "Northwind team"       # prints the private link once
tilldev shield engagements                                      # open engagements
tilldev shield engagements show 4
tilldev shield engagements findings move 4 2 open               # confirm; later: retest, fixed
tilldev shield engagements report 4 > E-4.md

An owner authorises it

Testing can’t start until an owner records that it is authorised, with an optional reference such as the contract or ticket that allows it. Authorising asks for a fresh approval (engagement.authorise), and the owner approves exactly the scope, window and tester networks they were shown: if the plan changed while they were looking, the authorisation is refused.

While the engagement is planned, changing anything the owner approved (kind, tester, firm, scope, tester networks, window) withdraws the authorisation. Once testing starts those are fixed; the window can only end sooner.

States and the window

An authorised engagement starts by itself when its window opens, and testing ends by itself when the window closes, paused or not. A plan whose window passes before it starts is cancelled. The team can start, pause, resume, end, close or cancel by hand at any time the table allows; a pause can carry a reason the testers see, and a cancellation one for the record. Closing needs every new finding triaged.

Runbook: a purple-team exercise

1. Plan a purple engagement with your own people as testers and the networks they will test from.
2. Add the ATT&CK techniques you want to try as plays, by id (T1078.004), up to 200. Start with the gaps on the coverage map.
3. Have an owner authorise it. It starts when the window opens.
4. Run each technique and log when it ran. TillShield then lists the TillTell findings that came from the tester networks for that technique, from 15 minutes before the run to 24 hours after, and suggests Detected when there are some.
5. Judge each play. The outcome is always the team’s call:

A detected play proves its technique on the coverage map for 90 days, like a TillDrill defense drill. A missed one is a rule to write. The engagement shows how many of the plays that ran were detected or blocked.

Runbook: an external pentest

1. Agree the scope and dates with the firm, then plan a pentest engagement with them as the tester.
2. Paste the rules of engagement. A template to start from is below.
3. List the networks the firm tests from, so their traffic is told apart from an attack.
4. Have an owner authorise it, with the statement of work as the reference.
5. Give each tester a private link. Through it they read the rules, report findings, log runs and talk to you.
6. Triage findings as they come in: confirm or reject each one. Confirmed findings go into the inventory with a fix-by date.
7. Fix, then ask for a retest. The tester confirms the fix, or sends it back.
8. Close the engagement and export the report.

Objective
  Find what an outside attacker could reach from the internet in api.acme.com and app.acme.com.

In scope
  api.acme.com and app.acme.com, and the accounts we create for you on them.

Out of scope
  billing.acme.com, our staff, our offices, and any third party, including our payment provider.

Not allowed
  Denial of service or load beyond 10 requests a second.
  Social engineering or phishing.
  Reading, changing or deleting other customers' data. Stop and report if you reach any.
  Keeping access after the window ends.

Testing comes from
  81.2.69.0/24 only. Traffic from anywhere else is not you.

Stopping
  If we ask you to stop, stop at once. To ask us to stop, or to report something critical, call the stop contact.

Data
  Keep what you see to what proves a finding. Delete copies 30 days after the report.

Runbook: a red-team run

A red-team run tests whether the team notices, so fewer people know about it. Plan it with the red team’s networks, keep the stop contact to someone who knows, and have an owner authorise it. Add the techniques as plays: at the end, the plays show what was detected against what was missed, and the timeline shows when the team paused it, if it did. Tell the rest of the team afterwards with the report.

Findings and retests

A finding has a title, a level (or a CVSS 3.1 base vector that sets it), the asset, an optional ATT&CK technique, and what was found, how to reproduce it, its impact and how to fix it. Every finding starts New, including ones the team records itself. Each finding has its own thread; a note can be shared with the testers or kept to the team.

Open and retest findings are in the vulnerability inventory as Pentest items, numbered E-4 F-2, with an owner, a fix-by date and accepted risk like any other item. They close as fixed once the retest passes.

Tester links

A tester link is made for one named tester and shown once. Its secret sits after the #, so it never reaches a server log or another site as a referrer. The tester needs no TillDev account. An engagement can have 10 live links, and a link stops working when it is revoked or the engagement is closed or cancelled.

Through the link a tester sees the state and window, the stop contact, the rules, the scope and the techniques. They can log when they ran a technique, report findings, confirm or reject fixes on retest, and write on the shared thread. They see the findings testers reported and the notes the team shared, never the team’s verdicts on plays, its private notes or findings it recorded itself. Runs are logged while testing is on; findings are taken while it is on or paused and after it ends.

The report

Export the engagement as Markdown at any time: the window, who authorised it and with what reference, the scope and rules, the techniques with their outcomes and detections, and the findings worst first, without rejected ones. Exporting is in the audit log.

Alerts

The workspace’s security alerts hear when testing starts, pauses, ends or is cancelled, and when a tester reports findings: email, Slack or the signed webhook set under Playbooks & security alerts. An alert carries the engagement and finding numbers, the level and the asset, and a link. What a finding says is never sent. The webhook body:

{
  "type": "tillshield.engagement.findings",
  "delivery_id": "9c1d4e7a-…",
  "findings": [
    { "engagement_id": "3f2a…", "engagement": 4, "number": 2, "level": "high", "asset": "api.acme.com" }
  ],
  "total": 1,
  "checked_at": "2026-11-04T14:02:00.000Z",
  "link": "https://tilldev.dev/acme/shield/engagements?id=3f2a…"
}

A state change has the type tillshield.engagement.state and a changes list, each with the engagement’s id, number, name, new state and any reason.

How engagements are kept

Finding titles and contents and every note are sealed with AES-256-GCM under a key derived from your workspace’s data key for that engagement and that field. A tester link is found by a hash of its secret. Rotating the workspace data key re-seals them; the cryptography inventory lists this use. The plan, the levels and assets are kept in the clear so the list and the inventory can show them.

Limits

The API is under /api/v1/shield/engagements for the team and /api/v1/engage for testers, in the API reference.