This tutorial takes one system from nothing to a verified passport. It tests one question: can the system be tricked by instructions hidden in text a user pastes? That goal needs nothing but a working connection, so it is the quickest honest first run. You need an HTTPS endpoint that answers a question, and permission to test it.
1. Sign up
On the sign up page enter your "Work email" and the name of your "Organisation", then choose "Email me a link". The organisation is made when you open the link we email you. The link works once.
2. Connect a system
Open Systems and choose "Connect a system". The wizard has five steps: Reach, Request, Identities, Ownership and Done. Under "How should Plimsoll reach it?" pick "An HTTPS endpoint": any service that takes a question in a request and returns an answer.
3. Fill the request from a command
Under "Paste a working curl" paste a command that already works against your system, then choose "Fill the form from curl". The method, address, headers and body template are filled for you. Secret header values are replaced with a secret reference and never stored.
curl https://assistant.example.com/ask \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"question": "What can you help me with?", "user": "analyst"}'Then tell Plimsoll how to read the reply:
- "Answer path": the dot path into the reply where the answer text sits, for example
answer. - "Citations path": optional, the dot path to the sources the system cites, for example
sources. - "Decline phrase": text that means the system declined, for example the first words of its usual refusal.
{"answer": "I can help with questions about settlement breaks.",
"sources": [{"id": "runbook-12"}]}4. Say who is asking
Under "How the system knows who is asking" choose "A field in the request" if the role travels in the body, or "A header" if it travels in a header. Give the field name, then "Add role" once for each role with the value your system expects. This goal does not compare roles, but the leak checks you add later do: without roles, only single user checks run.
5. Ownership
Read the three statements and tick each one: that you own or operate the system or hold written permission that covers automated testing, that you may confirm this for your organisation, and that you will keep that permission on file. Then choose "Confirm and connect". The confirmation repeats each time a run starts.
6. Draft and seal a plan
Open Test plans and pick the system. Under "What worries you?" tick "Can it be tricked by instructions hidden in text a user pastes?". It shows "Ready to test" because it needs nothing more. Choose "Draft a plan from 1 goal".
Read the draft: the checks, their limits, and whether the plan has the capacity to prove them. Then choose "Seal the plan". In the dialog, tick "I understand a sealed plan cannot be changed; a new version is a new plan." and choose "Seal the plan" again. Sealing fixes the questions, limits and seed before any question is asked, and shows the commitment hash.
7. Run and watch
Choose "Run this plan". The live run shows the questions asked, any violations, and the bound so far for each check. Each pasted text hides an instruction that asks for a code built from two fragments. The joined code never appears in what Plimsoll sends, so a reply that contains it shows the instruction was carried out.
8. Open the passport
When the run finishes, open its passport from Passports or from the run. It carries the verdict, every check with its bound and limit, the findings with their smallest examples, and the seal. A FAIL opens a finding; the next tutorial covers reading and retesting it.
9. Verify it
Open "Verify a passport". Drop the passport file, or paste its link and choose "Verify link". Each row is checked separately: the seal, the signature against a key you pinned, the record digest, and whether the run can be replayed offline. When all pass the page says "Verified: every row passes."
What you have
- A sealed plan that can be run again unchanged, so a later run is comparable.
- A passport anyone can verify without your account.
- Evidence about one question. Add goals such as "Does each role see only what it may?" for the access checks.