security.txt and Disclosure for Static Sites

A static site has a smaller attack surface than a web application, but not none. Researchers routinely find real problems on static sites: a .git directory or .env file copied into the build output, a subdomain pointing at a deleted hosting project that anyone can claim, a vulnerable version of a third-party library loaded on every page, a preview deployment exposing unreleased content, an API key committed to the site's repository. When they find one, the first question is who to tell. Without an answer, reports go to a generic support inbox, a social media account, or nowhere — or get published.

This guide gives a static documentation site a valid security.txt generated at build time, a short disclosure policy page, an intake address that actually reaches the right people, monitoring so the file never expires, and a simple process for handling reports. It is part of Security Headers and Hardening for Static Sites.

Prerequisites

• A static site whose build can emit files into /.well-known/.
• A mailbox or form for security reports that is monitored, and an owner for triage.
• Optionally, an OpenPGP key for signing and encrypted reports.

Step 1: Generate the File at Build Time

RFC 9116 requires Contact and Expires; Policy, Preferred-Languages, Canonical, Acknowledgments and Encryption are optional but useful. Generating the file in the build means every deploy renews the expiry:

// scripts/security-txt.mjs — runs after the build
import { writeFile, mkdir } from 'node:fs/promises';
const expires = new Date(Date.now() + 180 * 864e5).toISOString().replace(/\.\d+Z$/, 'Z');
const body = [
  'Contact: mailto:security@example.com',
  'Contact: https://example.com/security/report/',
  `Expires: ${expires}`,
  'Encryption: https://example.com/.well-known/pgp-key.txt',
  'Preferred-Languages: en, de',
  'Policy: https://example.com/security/policy/',
  'Acknowledgments: https://example.com/security/thanks/',
  'Canonical: https://example.com/.well-known/security.txt',
  ''
].join('\n');
await mkdir('dist/.well-known', { recursive: true });
await writeFile('dist/.well-known/security.txt', body);

An expiry 180 days ahead, renewed by every deploy, means the file is always valid while the site is actively maintained — and expires if deployments stop for six months, which is the right signal that the contact may no longer be monitored. Serve it with Content-Type: text/plain; charset=utf-8. Some generators ignore dot-directories when copying static files; check that /.well-known/security.txt exists in the build output and returns 200 on production.

Step 2: A Policy Page Researchers Can Act On

The Policy link points to a short page on the site itself, written in plain language:

• Scope: which domains and repositories are covered (the docs site, its subdomains, the public repository), and which are not (third-party services, the product itself, which has its own programme).
• How to report: the email address and form, what to include (URL, steps, impact), and that encrypted reports are welcome.
• What to expect: acknowledgement within two business days, an assessment within ten, and a note when it is fixed.
• Safe harbour: good-faith research within scope will not lead to legal action; no denial-of-service, no social engineering, no accessing data that is not yours.
• Recognition: reporters are credited on the acknowledgments page if they wish; there is no bug bounty.

A clear scope matters most for static sites, whose reports often concern things the docs team does not control — the product, a vendor. Saying so up front avoids frustration on both sides.

Step 3: An Intake That Reaches People

security@ addresses often forward to an unmonitored list. The intake here is a shared inbox in the team's ticketing system with an auto-reply confirming receipt, triaged daily by a rotating owner, plus a small form on the policy page that posts to an edge function and creates the same ticket (useful for researchers without email encryption set up). The form rate-limits submissions, as in Rate Limiting Edge Functions, because disclosure forms attract spam.

A test report is sent every quarter from an outside address to confirm the whole path — address, auto-reply, ticket creation, notification — still works.

Step 4: Monitor the File

The daily monitoring job used for certificates, described in Monitoring TLS Certificate Expiry, also fetches /.well-known/security.txt, checks the status and content type, parses the fields, and alerts if Expires is less than 60 days away or if a required field is missing. It caught one problem in a year: a generator upgrade that stopped copying dot-directories, which removed the file from the build without failing anything. A build-time assertion now fails the build if the file is missing from the output.

What Reports Looked Like

In the first year after publishing security.txt, the site received 12 in-scope reports and 31 out-of-scope or invalid ones (automated scanner output, reports about missing headers on third-party domains, "clickjacking" reports on pages with frame-ancestors 'none' already set). The in-scope ones:

The two subdomain takeover reports were the most valuable: both concerned event microsites whose hosting projects had been deleted while DNS records remained, the same class of problem found by the inventory in the TLS monitoring guide. The preview reports led to Access on previews, as in Branch Deploy Controls on Cloudflare Pages.

Handling Reports Well

Most of the value of a disclosure process is in how reports are handled, and a small static site team can do it well with a few rules. Every report gets a human reply, even the invalid ones, with a sentence explaining why it is out of scope or not a vulnerability; researchers talk to each other, and a reputation for polite, quick replies brings better reports. Valid reports get a severity from a simple three-level scale — high if readers or data could be harmed now, medium if an attacker needs further steps, low for hardening — and high issues are fixed before anything else that day. When a fix ships, the researcher is told and asked whether they want to be credited, and the acknowledgments page is updated in the same pull request. Internally, each valid report produces a check where possible — the subdomain takeover reports led to the hostname inventory, the source map reports to a build assertion that no .map files reach production — so the same class of issue is caught automatically next time.

Measured Impact

Pitfalls & Rollback

• A static file with a hard-coded expiry. It expires silently; generate it on every build.
• An unmonitored mailbox. Test the intake path regularly.
• No scope. Researchers report issues you cannot fix; say what is covered.
• Dot-directories dropped by the build. Assert that the file exists in the output.
• Rollback: the file and policy page are content; removing them is a deploy, though keeping a contact is strongly advisable.

Conclusion

A static site's security depends partly on people outside the team being able to tell you what they found. Generate a valid security.txt on every build, link a short policy with a clear scope and safe harbour, route reports to a monitored inbox with an owner, and watch the file like any other production dependency. In its first year this setup turned one late, accidental report into twelve timely ones — two of them about subdomain takeovers nobody inside had noticed.

FAQ

What is security.txt?

A small text file at /.well-known/security.txt, standardized in RFC 9116, that tells security researchers how to report vulnerabilities, with at least a Contact and an Expires field, and optionally links to a policy, acknowledgments, preferred languages and an encryption key.

Does a static site need a vulnerability disclosure process?

Yes. Static sites can still have problems worth reporting, such as exposed files in the build output, misconfigured headers, subdomain takeovers, vulnerable third-party scripts or leaked credentials in the repository. Without a clear contact, researchers either give up or publish without warning.

Why does security.txt have an expiry date?

So that stale contact information is not trusted indefinitely. RFC 9116 requires an Expires field, recommended to be less than a year ahead. A static site should generate it at build time so each deploy renews it, with monitoring in case deploys stop.

Should the file be signed?

Signing with OpenPGP lets researchers verify it was published by you, which matters if the site could be tampered with. It is optional. If you sign, automate signing in CI with a key stored as a secret and publish the public key at the URL in the Encryption or Canonical field.

Related

• Parent: Security Headers and Hardening for Static Sites — hardening a static site.
• Permissions-Policy and Cross-Origin Headers — headers researchers often check.
• Auditing npm Dependencies in SSG Pipelines — finding vulnerable libraries first.
• Monitoring TLS Certificate Expiry — the hostname inventory.
• Password-Protecting Preview Deployments — keeping previews private.