security-page

---
name: security-page
description: Build a credible security/trust page for a developer tool before SOC 2 — concrete controls, encryption specifics, subprocessor list, responsible disclosure, data lifecycle, and honest scoping of what you can claim. Use when the user wants a security page, trust page, or trust center, asks "do we need SOC 2", got a vendor security questionnaire, or is losing deals to security review. Also use when they mention a DPA, subprocessors, security.txt, responsible disclosure, or "enterprise readiness", even if they never say "security page".
---

# Security Page

A security page is the sales asset engineering can ship in a week. Buyers' security reviewers read it before they email you, and a concrete one closes early- and mid-market deals that a badge wall never will. The bar is Tailscale: their page leads with their actual trust model and gets technical fast, because their audience can tell the difference. This skill produces a page that survives vendor review without an auditor.

## Before you start

Check for `.agents/devtool-context.md` and read it if present (stage, stack, and buyer persona decide how deep the page goes). If absent, ask:

1. What customer data do you hold, and what's the *worst* thing you could leak or break for a customer?
2. What's actually true today: cloud provider, encryption defaults, who on the team can touch production, which vendors see customer data?
3. Has anyone asked for SOC 2 yet, or is this preemptive?

Question 2 matters most: this page can only contain things that are true. The interview surfaces both the claims you can make and the gaps that become the backlog artifact.

## The page, in order of consequence

### 1. Lead with your most sensitive surface

Every generic security page opens with "we take security seriously." That phrase is a tell, because reviewers pattern-match it to "nothing specific to say." Ban it. Instead, identify the worst thing you could leak or break for a customer, and open the page with exactly how you protect *that*:

- A feature-flag service leads with flag-evaluation integrity: "a wrong flag value in your production is our worst failure, here's the isolation and rollback story."
- An image-resizing API leads with customer-image storage and deletion: where originals live, who can read them, how deletion propagates to caches.
- An auth provider leads with credential storage; a data pipeline leads with tenant isolation.

This ordering is the whole trick. It signals you've thought about *your* threat model rather than pasted a template, which is precisely what a reviewer is probing for. Everything below hangs off this opening.

### 2. Concrete controls over vague claims

Every sentence on the page should be checkable or specific enough to be falsifiable. "Bank-level encryption" is marketing; "TLS 1.2+ everywhere; AES-256-GCM at rest; keys in AWS KMS with annual rotation" is a claim a reviewer can verify and score. Rewrite ruthlessly:

| Vague claim | Concrete replacement |
|---|---|
| Bank-level / military-grade encryption | TLS 1.2+ in transit; AES-256-GCM at rest; keys in AWS KMS, rotated annually |
| Your data is safe with us | Customer data lives in Postgres (RDS, `us-east-1`) with encrypted storage and 30-day PITR backups |
| We follow industry best practices | Staff access requires SSO + MFA; production access is limited to 2 named engineers and logged |
| Regular security audits | Dependabot + weekly `npm audit` in CI; annual third-party pentest planned Q1 (say "planned" only if scheduled) |
| We never share your data | Subprocessors are listed below; none receive customer data except those marked, under DPA |
| 24/7 monitoring | Alerts page us via PagerDuty on error-rate and auth-anomaly thresholds; status at status.example.com |

If a sentence can't be rewritten into the right column, it belongs in the gap backlog, not on the page.

### 3. Encryption and key management

The section reviewers screenshot into their questionnaire. State plainly:

- In transit: TLS version floor, HSTS, whether internal service-to-service traffic is also encrypted.
- At rest: algorithm and where it's applied (database, object storage, and backups; backups get forgotten).
- Key custody: who holds the keys, and the rotation policy. Cloud KMS is the honest, correct default answer; say so, and don't imply you run HSMs.
- Secrets management: where app secrets live (KMS/SSM/Vault/Doppler), not in env files in the repo.
- API credentials: stored hashed, displayed once at creation, prefixed and rotatable. This is a headline control for a devtool, and the [api-keys](../api-keys/SKILL.md) skill defines the implementation the page describes. Signed webhooks are another demonstrable control worth a line ([webhook-delivery](../webhook-delivery/SKILL.md)).

### 4. Internal access controls

Buyers fear your intern more than your firewall. Cover: SSO + MFA required for all staff tooling; least-privilege roles; a production access policy (who, why, how it's granted and revoked); audit logging of production access. If the honest answer is "two founders, both with admin," write a policy *now*. "Production access is limited to named engineers, granted per-incident, and logged" is achievable at any size and is not the same claim as "we have a SOC 2 access review."

### 5. Subprocessor list

Name your vendors (cloud, email, analytics, error tracking, payments) with purpose and region. GDPR/DPA reviewers look for this list *first*, and publishing it builds more trust than hiding it (everyone knows you use AWS; pretending otherwise reads as either naive or evasive). Commit to updating it, with a date:

```markdown
## Subprocessors
_Last updated: 2026-08-10. We update this list before adding a subprocessor that handles customer data._

| Vendor | Purpose | Region | Customer data? |
|---|---|---|---|
| AWS | Hosting, storage, KMS | us-east-1 | Yes |
| Resend | Transactional email | US | Email addresses only |
| Sentry | Error tracking | US | Scrubbed — no payloads |
| Stripe | Billing | US | Billing contact + usage |
| PostHog | Product analytics | EU | Pseudonymous IDs |
```

The "Customer data?" column with honest scoping ("scrubbed", "email addresses only") is what separates a real list from a logo dump.

### 6. Responsible disclosure

You don't need a paid bounty program; you need a way to be told. Two artifacts:

- `/.well-known/security.txt` ([RFC 9116](https://www.rfc-editor.org/rfc/rfc9116)):

```
Contact: mailto:security@example.com
Expires: 2027-08-10T00:00:00.000Z
Policy: https://example.com/security#disclosure
Preferred-Languages: en
```

- A disclosure policy on the page: scope (what's in and what's out: production domains in, customer instances and DoS out), a safe-harbor statement ("good-faith research within scope will not result in legal action"), the contact, and a response SLA (acknowledge in 3 business days is enough; commit only to what you'll hit). Researchers who find something *will* email someone; the policy decides whether it's you or your customers.

### 7. Data lifecycle

Retention ("logs 30 days, customer data for the life of the account"), deletion on request and on churn with a concrete window ("within 30 days of account deletion, including backups within 90"), backup cadence and encryption, and region(s). If you can't yet delete from backups on a schedule, say what actually happens ("backups expire on a 35-day rolling window"). Precision about a modest control beats vagueness about a strong one.

### 8. When SOC 2 is actually worth it

Take a position: get SOC 2 when a specific enterprise deal, or a repeated pattern of deal-blocking asks, demands it, and not before. It costs real money and months of engineering time, and a concrete security page plus a willingness to fill questionnaires closes early- and mid-market deals without it. In practice startups get asked for "your security page or a completed questionnaire" far more often than for the actual report. Short version for the page's FAQ: *Type I attests your controls exist at a point in time; Type II attests they operated over a period, usually 6 to 12 months. Buyers who care want Type II.* When you do start, "SOC 2 Type II in progress" is a legitimate line (see the honesty rule).

### The honesty rule

Never claim a control you don't have. This page is a legal-ish document: it gets attached to vendor reviews, quoted in DPAs, and dug up after incidents, and a false claim converts an incident into a misrepresentation problem. "SOC 2 Type II in progress" is fine *only if an audit is actually engaged*. The gap between what you wish were true and what is true goes in the backlog artifact: dated, ordered, and off the page.

### Calibration

Read three pages before writing. Tailscale is the ceiling: deeply technical, and it leads with their actual trust model. Vercel is where you're heading post-SOC 2: an enterprise-polished trust center. PostHog is the most reproducible register for a startup: transparent, plain-spoken, and it publishes the messy specifics. Match PostHog's honesty with Tailscale's ordering.

## Artifacts to produce

1. The security page (`security.md`/`.mdx` for the user's site): sections 1 through 8 above. Open with the most-sensitive-surface section, and verify every claim against the user in the interview.
2. `security.txt` for `/.well-known/`, with a real contact and a 1-year `Expires`.
3. Subprocessor table: the actual vendors from their stack, with purpose/region/data-scope columns and a last-updated date.
4. Gap backlog: every claim they *couldn't* make yet, rewritten as engineering tasks in priority order (e.g. "no audit logging on prod access → ship access log, ~2 days"), so the page has a growth path instead of lies.

## Related Skills

- [api-keys](../api-keys/SKILL.md): hashed, display-once credential storage is a headline control this page advertises.
- [webhook-delivery](../webhook-delivery/SKILL.md): signed webhooks are a concrete, demonstrable control worth naming on the page.
- [integration-pages](../integration-pages/SKILL.md): trust pages and integration pages are both buyer-facing surfaces, so keep the register consistent.
- [devtool-context](../devtool-context/SKILL.md): create the context file first if it doesn't exist; stage and stack shape every claim here.