Reef · for your CTO
What Reef can touch, what it never does, and where your data goes.
The technical facts behind Reef, checked line by line against its code. Including the things we don't have yet.
- Read-onlyIt finds, explains and alerts. It never changes, deploys or runs anything.
- Two tokensOne for your code, one for your hosting. Revoke them and Reef is blind straight away.
- Secrets maskedKeys, passwords, emails and phone numbers are masked before anything is stored or sent.
- Zero packagesReef uses no third-party code libraries, so there's no supply chain to compromise.
1 · Access
What Reef needs from you
Two tokens, both optional. Without either, Reef still checks everything a visitor can see.
| Access | Scope | What it's used for | Without it |
|---|---|---|---|
| Your public web addresses | None needed | Uptime, speed, page content, certificates, exposed files, privacy checks | Required: this is the starting point |
| GitHub | Fine-grained token, Contents: Read-only, only the repositories you pick | Settings your code needs but your host is missing, change summaries with a risk label, known holes in the packages you use | Code checks switch off |
| Railway (hosting) | Project token, limited to one environment | Deploy status, storage and backups, setting names, usage and cost, the last 300 log lines per service | Hosting checks switch off |
One honest caveat about RailwayRailway doesn't offer a read-only token type, so the token itself could make changes. Reef's code can only send read requests: anything that would change something is blocked before it leaves Reef, and an automated test checks that on every build. Limit the token to one environment, and you can revoke it at any time.
How you give them: on your Reef's What to watch page (owners only). Each token is tested before it's saved: a GitHub token that could change your code is refused. Tokens are stored encrypted (AES-256-GCM), never shown again (only the last 4 characters), and every change is logged and emailed to the owner. Remove them there, or revoke them at GitHub or Railway, at any time. Web addresses must be public https addresses: private and internal networks are refused.
No database access. No server login, shell or SSH. No cloud console accounts. Nothing is installed in your systems: no agent, no SDK, no code change.
2 · What it checks
Four layers, each on its own clock
Intervals are the defaults and can be changed per business.
| Layer | Every | What it checks |
|---|---|---|
| Outside | 5 min | Pages up and the right content on them, speed, scripts and styles loading, health endpoints, cross-site settings (CORS), certificate expiry, domain expiry, and your providers' public status pages ("it's not you, it's them") |
| Hosting | 15 min | Failed deploys, settings that were removed, storage not attached or filling up, missing backups, known errors in recent logs (AI credit, rejected keys, email failures and more), idle services costing money |
| Security & GDPR | 60 min | Exposed files (.env, .git, database backups), admin pages open without a login, endpoints that leak errors or personal data, trackers without consent, missing or out-of-date privacy policy |
| Code | 60 min | Settings the code needs that the host doesn't have, each new change summarised with a Safe / Test first / Risky label, packages with known security holes (checked against osv.dev), Node.js versions past end of life |
An exposed file is only flagged when its content really is that file, not your friendly 404 page. Reef shows the exact file and line, or the exact address, behind every finding.
How light is it?
About as much traffic as a handful of visitors an hour. Measured by counting every request in a full run of each layer on our own setup: one website and three back-end services.
| Layer | Requests to your systems | How often |
|---|---|---|
| Outside | 10 (pages, their scripts and styles, health checks) | Every 5 min |
| Security & GDPR | 82 small GET requests, mostly to addresses that should return "not found" | Every hour |
| Hosting and code | None. These go to GitHub's and Railway's APIs, not to your servers. Only changed files are downloaded again. | 15 / 60 min |
| Total | About 200 requests an hour across all four services, roughly 3 a minute. About 2 MB an hour of data for our pages, before compression. |
- Reef runs on its own server. It uses none of your CPU, memory or database.
- It scales with what you ask it to watch: more pages and services mean more requests, in proportion.
- Intervals can be slowed down for any layer if you'd like even less.
- Every request identifies itself as
ReefWatch/1.0 (+lagoona). The hourly security checks look for files like/.env, so your firewall or logs may flag them as a scan: filter on that name.
3 · Boundaries
What Reef never does
Never
- Changes, deploys, restarts or runs anything
- Calls an endpoint that changes data. It only sends safe read requests (GET, plus the browser's CORS pre-check). Endpoints that change things are only read in your code.
- Logs in to your site, guesses passwords or attacks anything
- Reads your database
- Keeps the values of your settings. Only their names are kept; values are dropped the moment they arrive.
- Writes your code to disk. It's held in memory to check, then discarded.
Always
- Shows its evidence: the file and line, the address, or the log line
- Says how sure it is: Safe, Test first, Risky or Can't tell
- Confirms an outage twice in a row before alerting, so one blip doesn't wake anyone
- Names the outside company when the fault is theirs, not yours
- Runs as its own instance for each business: its own server, storage and password, shared with no one
4 · Data flow
What goes in, what comes out
Everything passes through the masking step before it's stored or sent anywhere. Dashed boxes are optional.
Reef reads
Your website & APIsPublic addresses, read requests only
GitHubRead-only token, chosen repos
RailwayRead queries, setting names, recent logs
Your Reef instance
1. Mask keys, passwords, emails, phone numbers
2. Check four layers, evidence attached
3. Confirm before alerting
4. Explain in plain English (optional)
Reef sends
DashboardPassword protected
EmailVia Resend, to people you choose
Slack, Discord, webhooksSigned, to addresses you add
Read-only APIFor keys you issue
| Leaves Reef | Goes to | Exactly what |
|---|---|---|
| Plain-English explanations (optional) | Anthropic's API | One verified finding with its masked evidence. For change summaries: the commit message and short masked diffs, capped at 6,000 characters. Anthropic's commercial terms say it may not train models on this content. Switch it off and Reef uses rule-based labels instead. |
| Package check | osv.dev | The names and versions of the packages your code uses. No code. |
| Domain expiry (if set) | rdap.org | Your domain name |
| Alerts | The people and channels you choose | The finding, its masked evidence, the fix and the estimated value |
5 · Secrets & personal data
Masked before anything is kept or sent
Every piece of text that comes out of a check goes through one masking step first.
| Masked | Examples |
|---|---|
| API keys and tokens | Anthropic, GitHub, Resend, ElevenLabs, Stripe, AWS access keys, JWTs, bearer tokens |
| Passwords and secrets in text | password=…, secret: …, token=…, api_key=… |
| Personal details | Email addresses, UK mobile numbers, private calendar links |
| Setting values | Never kept at all. Only setting names are stored. |
| Log lines | Only a short, masked example of a known problem is stored, not your logs |
Masking works on known patterns. A secret in an unusual format could slip through, which is why setting values are never read into storage in the first place.
6 · Storage & retention
What's stored, and how much
Everything lives on your Reef instance's own storage. History is capped by count, so it never grows without limit.
| Stored | How much |
|---|---|
| Open problems | Until fixed or muted |
| Problems caught (for savings) | The latest 300 |
| Fixed problems | The latest 50 |
| Alerts sent | The latest 50 (subject line and whether it was delivered) |
| Code change summaries | The latest 40 |
| Response times | The latest 48 per endpoint |
| Your code | Not stored. Held in memory only. |
| What to watch | Your list of websites, services and repositories. Read-only tokens encrypted with a key kept in the host's secret settings. |
| API keys | Only as SHA-256 hashes. The key is shown once, then can't be recovered. |
| Webhook addresses | Kept with their signing secrets, in a file only Reef can read |
Hosting: our Reef instances run on Railway in its EU West region (Netherlands). Delete the instance and its storage, and everything Reef knew about you is gone.
7 · Outside services
Every outside company involved
| Company | Role | Needed? |
|---|---|---|
| Railway | Hosts your Reef instance and its storage | Yes |
| Anthropic | Plain-English explanations and change summaries | Optional |
| Resend | Sends alert emails | Optional |
| osv.dev | Public database of known security holes in packages | Only with code checks |
| rdap.org | Public domain registration lookups | Only if you want domain expiry checks |
| GitHub, Railway APIs | Where Reef reads your code and hosting, with your tokens | Only if you grant access |
8 · Alerts, webhooks & API
Into your own tools, on your terms
When it alerts
- Only problems rated urgent or attention. Low ones stay on the dashboard.
- Outages must fail twice in a row first
- Each problem alerts once, then again when it's fixed
- Log problems stay open until the logs have been quiet for an hour
- Each person or channel chooses: Everything, Urgent only, or the Monthly savings report
- At most 10 alert emails an hour per person
Webhooks
- Email, Slack, Discord or your own system
- Events:
problem.opened,problem.fixed,test - Signed:
X-Reef-Signature: sha256=HMAC(secret, timestamp.body) - 5-second timeout, 3 tries (now, after 30 s, after 2 min), redirects not followed
- HTTPS only. Private, internal and cloud-metadata addresses are refused, checked after DNS lookup.
Read-only API
| GET | Returns |
|---|---|
/api/v1/status | urgent / attention / all_ok, counts, last checked |
/api/v1/findings | Open problems with fix, likely cause and plain English. ?level=urgent to filter. |
/api/v1/caught | Problems caught: when, minutes to detect, when fixed, estimated value |
/api/v1/value | The month's estimated value, broken down |
curl -H "Authorization: Bearer reef_YOUR_KEY" https://your-reef/api/v1/status
GET only: anything else gets 405. Keys are issued and revoked by the owner, stored only as hashes, and limited to 60 requests a minute each. Your Reef has a full developer guide at /api.
9 · Dashboard security
Who can see the dashboard
| Control | How it works |
|---|---|
| Sign in | Each person from their own Lagoona account, with their own role (Viewer, Manager or Owner). Plus one owner password per Reef instance, 12 characters minimum, set by you |
| Session | Signed cookie: HttpOnly, Secure, SameSite=Strict. A Lagoona sign-in lasts 12 hours; the owner password lasts 30 days, or until you sign out. |
| Wrong passwords | 8 tries, then that address waits 15 minutes |
| Page protection | Content Security Policy, no framing, no caching, same-origin checks on every action |
| Change log | Every change on the dashboard (sign-ins, muted alerts, recipients, keys) is recorded with when and from where. It can't be edited or deleted from the dashboard. |
| Watch the watcher | Muting an alert, adding or removing a recipient, or making an API key emails the owner straight away, one email per burst of changes. Nobody can quietly switch Reef off. |
| Daily snapshots | A copy of all Reef's data every night, the last 14 days kept |
| Everyone else | People you add get alerts without needing a login at all |
10 · Switching it off
Three steps, no trace left in your systems
| Step | Effect |
|---|---|
| 1. Revoke the GitHub token | Reef can't see your code, straight away |
| 2. Revoke the Railway token | Reef can't see your hosting, straight away |
| 3. Ask us to delete your Reef | The instance and its storage are deleted, and with them every finding, alert and setting |
Nothing was installed in your systems, so there's nothing to uninstall.
11 · Straight answers
What we don't have yet
Better you hear it here than find it later.
| Question | Answer |
|---|---|
| SOC 2 or ISO 27001? | No. Lagoona is a small UK business and isn't certified. This page is our answer instead: specific, and checkable against what Reef actually does. |
| Independent penetration test? | Not yet. Reef's own code has 132 automated tests, which we run before every update (never against your systems). They include ones that prove it never sends a change request, keeps API keys only as hashes and refuses private webhook addresses. |
| Single sign-on, per-user logins? | Yes, through Lagoona. Each person opens Reef from their own Lagoona account as Viewer (looks), Manager (also mutes and checks) or Owner (also manages API keys and alert recipients). The change log shows each person's email. Remove someone in Lagoona and they're signed out of Reef straight away. A single owner password also exists for set-up. Not yet: signing in with your own Microsoft or Google identity provider. |
| Hosts other than Railway? | Partly. Outside, security and code checks work whatever your host. The hosting layer (deploys, storage, backups, logs) supports Railway today. |
| GitLab or Bitbucket? | Not yet. Code checks use GitHub. |
| Run it in our own cloud? | Yes, if you buy it. Reef is a single Node.js service with no dependencies. Buy it and you get the source code, it runs on your own cloud, and the first 12 months of updates are included. |
| Can the AI see our data? | Only the masked finding, or the masked change summary, it's asked to explain. Never your database or your setting values. You can switch the AI off completely. |
Questions this page didn't answer?
A 15-minute technical call with the person who built Reef. Bring your hardest question.