Security.txt

Implementing a security.txt file is essentially the "bat-signal" for ethical hackers, ensuring that if someone finds a vulnerability, they know exactly how to tell you without it getting lost in a generic support inbox.

According to the RFC 9116 standard, this file should be placed in the /.well-known/ directory of a web server (e.g., https://example.com/.well-known/security.txt).

See the template file "security.txt".

Best Practices

• The Expiration Date: The Expires field is mandatory. Security researchers ignore expired files because it suggests the contact info might be stale. Set it for about a year into the future and put a reminder in your calendar to update it.
• The PGP Key: To provide an Encryption link. It allows researchers to send sensitive vulnerability details without worrying about the email being intercepted in transit.
• Digital Signatures: For high-security sites, it is common practice to sign the security.txt file using GPG, creating a cleartext signature. This proves the file hasn't been tampered with by an attacker.

PGP

1.1 Generate a PGP Key pair:

gpg --full-generate-key

• Select Algorithm: (1) RSA and RSA (or ECC for modern, shorter keys).
• Key Size: 4096 bits for maximum security.
• Validity: How long the key should last (e.g., 1y for one year).
• Identity: Enter the Name and the Email address used in the security.txt file.
• Passphrase: Pick a strong password. Do not lose this, or you won't be able to sign files or decrypt reports.

2.1 Export the Public Key

The Public Key needs to be hosted on the website so researchers can encrypt their messages.

gpg --armor --export your-email@example.com > pgp-key.asc

Upload pgp-key.asc to the server and ensure the Encryption: field in the security.txt points to its URL.

3.1 Sign the security.txt file

To create a "Cleartext Signature," which keeps the text readable but adds a cryptographic signature at the bottom:

gpg --output security.txt.sig --clearsign security.txt

GPG will create a new file named security.txt.sig. In the file the original text is wrapped in -----BEGIN PGP SIGNED MESSAGE----- and a block of code at the bottom. Rename the file to security.txt and upload it to the /.well-known/ directory.

4.1 Verification (The "Trust" Check)

Once uploaded, anyone can verify the file is authentic by downloading the public key and running:

gpg --verify security.txt

If it says "Good signature," it is successfully secured for the vulnerability disclosure process.

5.1 PGP keys maintenance

Managing PGP keys can be a bit of a "manual labor" task. If the private key is lost or the passphrase forgotten, it is not possible to rotate or update the signed file. It is recommended to keep a backup of the private key in a secure physical location (like an encrypted USB drive in a safe).

6.1 Backup of the private PGP key

• Identify the Key ID

gpg --list-secret-keys --keyid-format LONG

The line starting with sec is the string of characters after the slash (e.g., 3AA5C34371567BD2), this is the Key ID.

• Export the Private Key

To create an "armored" (text-based) backup of the private key:

gpg --armor --export-secret-keys KEY_ID > private-key-backup.asc

• Export the Trust Database (Optional but Recommended)

GPG also tracks how much other keys are trusted. To keep the full environment consistent across machines, export the "ownertrust":

gpg --export-ownertrust > trustdb.txt

• To restore a backup:

gpg --import private-key-backup.asc

gpg --import-ownertrust trustdb.txt

Security policy

A Vulnerability Disclosure Policy (VDP) is the legal and procedural "instruction manual" for the security.txt. It tells researchers what they are allowed to test, the reaction, and crucially provides a Safe Harbor clause that protects ethical hackers from legal action.

See the template file "security-policy.html".

Make sure the URL matches the Policy: field in the security.txt file.

Hall of Fame

A Security Hall of Fame (sometimes called an Acknowledgments page) is the "currency" of the ethical hacking world. For many independent researchers, public recognition from a company is just as valuable as a cash bounty because it builds their professional portfolio.

For a template which can be hosted at yourdomain.com/security/thanks see hall-of-fame.html.

• Ask Before Posting: Always ask the researcher how they would like to be credited (Real name, Handle, or Anonymous) and if they want a link to their LinkedIn, Twitter/X, or GitHub.
• Be Specific but Vague: Note the type of vulnerability (e.g., "SQL Injection") but never the specific URL or internal system name where it was found. This prevents copycat attacks while the fix is being monitored.
• Keep it Simple: No fancy design. A simple, searchable table is usually preferred by researchers so they can easily show it to potential employers.

Server configuration

For a setup on a server with nginx, the following files need to be placed:

• /var/www/html/.well-known/security.txt
• /var/www/html/static/pgp-key.asc
• /var/www/html/static/security-policy.html
• /var/www/html/static/hall-of-fame.html

See the configuration template in nginx.conf as reference.