Introducing SECURITY.md and security.txt to Open Source Projects - Learning from Giselle
When running an open source project, documenting your security policy is crucial. This article explains how to effectively write SECURITY.md and security.txt, using PRs from the Giselle project as reference.
SECURITY.md is a file that contains your project’s security policy. On GitHub, placing a SECURITY.md file in the root directory of your repository automatically links it from the “Security” tab.
This file typically includes the following:
Documenting your security policy provides the following benefits:
Giselle is an open source AI app builder. Let’s examine the structure of the SECURITY.md introduced in this project.
## Supported Versions
As an open source product, we will only provide security patches for the latest major version.
Older versions will not receive retroactive security patches.For open source projects, it’s not realistic to continue supporting all versions. By clearly stating that only the latest major version is supported, users are encouraged to update to the latest version.
## Bug Bounty Program
Giselle does not currently operate a bug bounty program.
We do not offer monetary rewards for vulnerability reports.
We appreciate responsible disclosure and will acknowledge contributors in our release notes
(with permission), but submitting a report does not guarantee or imply any monetary compensation.This clearly states that no bug bounty program is in place. This is an important point. If reporters expect monetary rewards, you can prevent misaligned expectations upfront.
Instead, it offers to recognize contributions through acknowledgment in release notes.
Giselle provides two reporting methods.
### case1: Report via Email
1. **Email us** at oss@giselles.ai. Please do not create a public GitHub issue.
2. Include as much detail as possible, including steps to reproduce the vulnerability,
potential impact, and any other relevant information.
3. We will acknowledge your email within 3 business days and work with you to understand
the issue and address it promptly.A dedicated email address is provided, with a reminder not to create public Issues. By promising an initial response within 3 business days, reporters are given peace of mind.
### case2: Report via GitHub Private vulnerability reporting
To report a security issue, please use the GitHub Security Advisory
["Report a Vulnerability"](https://github.com/giselles-ai/giselle/security/advisories/new) tab.
**Do not open up a GitHub issue.**This also provides an option to use GitHub’s Private vulnerability reporting feature. Using this feature allows vulnerabilities to be reported privately, and information is not disclosed until the fix is complete.
## Handling Security Issues
We follow a responsible disclosure process:
1. We will investigate the reported vulnerability and work on a fix.
2. A fix will be developed, tested, and incorporated into the project.
3. Once the fix is ready, we will release a new version of the project with a detailed release note.
4. We will notify the reporter about the fix and acknowledge their contribution in the release notes,
if they wish to be credited.This clearly outlines the process from report to fix to release. It also mentions notification to reporters and acknowledgment.
## Out of Scope
The following items are generally considered out of scope:
- Missing or misconfigured DMARC/SPF/DKIM records
- Missing security headers (unless directly exploitable)
- Disclosure of software versions
- Reports from automated tools without demonstrated impact
- Social engineering attacks
- Denial of service attacksBy clearly stating what is out of scope for security reports, you can reduce irrelevant reports. Since there are many cases where automated tool scan results are reported as-is, “reports from automated tools without demonstrated impact” is listed as out of scope.
## Responsible Disclosure Guidelines
We kindly ask reporters to:
- Allow reasonable time for us to investigate and address the issue before public disclosure
- Avoid ultimatum-style deadlines or threats of public disclosure as a negotiation tactic
- Provide sufficient technical details (reproduction steps, PoC, headers, etc.) to validate the issueThis asks reporters to allow sufficient time for fixes. It also requests avoiding ultimatum-style deadlines or using public disclosure threats as a negotiation tactic.
In addition to SECURITY.md, it’s also recommended to introduce security.txt. security.txt is a file standardized in RFC 9116 that provides security contact information for websites in a machine-readable format.
Giselle updated security.txt in PR #2649.
Contact: mailto:security@giselles.ai
Expires: 2027-01-15T23:59:59Z
Preferred-Languages: en, ja
Policy: https://github.com/giselles-ai/giselle/security/policy
Canonical: https://studio.giselles.ai/.well-known/security.txtHere’s what each field means:
| Field | Description |
|---|---|
Contact | Where to report security issues (email address or URL) |
Expires | Expiration date of this file (required in RFC 9116) |
Preferred-Languages | Supported languages |
Policy | Link to security policy |
Canonical | Canonical URL of this file |
Place security.txt at .well-known/security.txt or /security.txt. The Expires field is required and needs periodic updates.
RFC 9116 recommends setting the Expires field value to less than one year in the future. This means periodic updates are necessary, but it’s easy to forget.
When Giselle introduced security.txt in PR #117, they also set up automatic reminders using GitHub Actions.
name: Create an issue to remind updating of security.txt
on:
workflow_dispatch:
schedule:
- cron: "0 0 1 6,12 *" # Every year on 6/1 and 12/1 at 9:00am JST
jobs:
create_issue:
runs-on: ubuntu-latest
steps:
- name: Create reminder issue
# Issue creation stepsThis workflow automatically creates an Issue on June 1st and December 1st each year, prompting updates to security.txt. The Issue template includes:
Expires field to a date within one yearThis automation helps prevent forgetting to update security.txt.
SECURITY.md file in the root of your repositoryEven for small projects, I recommend including the following:
# Security Policy
## Reporting a Vulnerability
If you discover a security vulnerability, please report it to [your-email@example.com].
Please do not create a public GitHub issue.
We will respond within [X] business days.This allows reporters to create private vulnerability reports on GitHub.
SECURITY.md and security.txt are important documents that formalize security handling for open source projects. Giselle has progressively developed its security policy through the following PRs:
Key takeaways:
Security policies aren’t something you create once and forget. It’s important to continuously update them as your project grows. If you’re running a project without a security policy, consider introducing SECURITY.md and security.txt.
That’s all from the Gemba, where we learned how to write SECURITY.md from Giselle’s example.