docs(security): rewrite security policy and add RFC 9116 security.txt (#1394)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.github/workflows/ci-security-scan.yml

@@ -2,7 +2,8 @@ name: Security
 
 # CodeQL SAST scanning is handled by GitHub's Default Setup (enabled in repo settings).
 # This provides automatic scanning on push/PR with incremental analysis and zero maintenance.
-# This workflow handles dependency scanning (Trivy) and secret detection (TruffleHog).
+# This workflow handles dependency scanning (Trivy), secret detection (TruffleHog), and
+# a freshness check on the RFC 9116 security.txt Expires field.
 
 on:
   workflow_call:
@@ -27,6 +28,8 @@ jobs:
             display-name: "Dependencies"
           - scan-type: secrets
             display-name: "Secrets"
+          - scan-type: policy
+            display-name: "Policy"
     permissions:
       security-events: write
       contents: read
@@ -58,3 +61,21 @@ jobs:
           base: ${{ github.event_name == 'pull_request' && github.base_ref || '' }}
           head: ${{ github.event_name == 'pull_request' && 'HEAD' || '' }}
           extra_args: --debug --only-verified
+
+      # RFC 9116 requires a valid Expires date. Fail before it lapses so an
+      # active branch is forced to renew it — a stale file signals abandonment.
+      - name: security.txt freshness
+        if: matrix.scan-type == 'policy'
+        run: |
+          file="webapp/public/.well-known/security.txt"
+          expires="$(grep -i '^Expires:' "$file" | head -1 | cut -d' ' -f2)"
+          if [ -z "$expires" ]; then
+            echo "::error file=$file::Missing required RFC 9116 Expires field"
+            exit 1
+          fi
+          days=$(( ( $(date -u -d "$expires" +%s) - $(date -u +%s) ) / 86400 ))
+          echo "security.txt expires in $days day(s) ($expires)"
+          if [ "$days" -lt 30 ]; then
+            echo "::error file=$file::Expires is $days day(s) away (<30); renew it per RFC 9116"
+            exit 1
+          fi

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Read the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development) on how to set up your environment.
 
+## Maintenance Status
+
+Hephaestus is a research project at TUM, actively developed but maintained primarily by one person. Issues and pull requests are triaged on a best-effort basis. Security reports are the exception and get priority — see [SECURITY.md](SECURITY.md) for how to report vulnerabilities privately.
+
 ## Identity and Transparency
 
 To ensure a transparent and trustworthy environment, we have established different guidelines for members of our organization and external contributors.
@@ -45,28 +49,29 @@ We use **Semantic Release** to automatically version and release our application
 
 **❌ Will NOT Trigger Release** (Scope Overrides):
 
-| Pattern | Example | Why |
-|---------|---------|-----|
-| `*(ci):` | `fix(ci): update workflow` | CI/GitHub Actions only |
-| `*(config):` | `chore(config): update renovate.json` | **TOOLING only** (see warning below) |
-| `*(deps-dev):` | `chore(deps-dev): update test lib` | Dev dependencies only |
-| `*(scripts):` | `fix(scripts): fix build script` | Build/dev scripts only |
-| `*(no-release):`| `feat(no-release): internal feature` | Explicit opt-out |
+| Pattern          | Example                               | Why                                  |
+| ---------------- | ------------------------------------- | ------------------------------------ |
+| `*(ci):`         | `fix(ci): update workflow`            | CI/GitHub Actions only               |
+| `*(config):`     | `chore(config): update renovate.json` | **TOOLING only** (see warning below) |
+| `*(deps-dev):`   | `chore(deps-dev): update test lib`    | Dev dependencies only                |
+| `*(scripts):`    | `fix(scripts): fix build script`      | Build/dev scripts only               |
+| `*(no-release):` | `feat(no-release): internal feature`  | Explicit opt-out                     |
 
 > ⚠️ **`config` scope warning:** Only use for tooling config files like `.prettierrc`, `renovate.json`, `eslint.config.js`. Do NOT use for:
+>
 > - Runtime config (`application.yml`) → use `server`
 > - Dockerfiles → use service scope (`webapp`, `server`, etc.)
 > - Production compose files → use `docker`
 
 **✅ WILL Trigger Release**:
 
-| Type | Version | Example |
-|------|---------|---------|
-| `feat:` | **Minor** | `feat(webapp): add dark mode` |
-| `fix:` | **Patch** | `fix(api): handle null response` |
-| `perf:` | **Patch** | `perf: optimize query` |
-| `revert:` | **Patch** | `revert: undo change` |
-| `!:` | **Major** | `feat!: new api structure` |
+| Type      | Version   | Example                          |
+| --------- | --------- | -------------------------------- |
+| `feat:`   | **Minor** | `feat(webapp): add dark mode`    |
+| `fix:`    | **Patch** | `fix(api): handle null response` |
+| `perf:`   | **Patch** | `perf: optimize query`           |
+| `revert:` | **Patch** | `revert: undo change`            |
+| `!:`      | **Major** | `feat!: new api structure`       |
 
 **❌ Will NOT Trigger Release** (Type-Based):
 `docs:`, `style:`, `refactor:`, `test:`, `build:`, `chore:`, `ci:`

SECURITY.md

@@ -1,31 +1,54 @@
 # Security Policy
 
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Report privately via [GitHub private vulnerability reporting](https://github.com/ls1intum/Hephaestus/security/advisories/new) — it keeps the report confidential and credits you in the resulting advisory. If you cannot use GitHub, email [felixtj.dietrich@tum.de](mailto:felixtj.dietrich@tum.de) with the subject "Hephaestus Security Vulnerability Report".
+
+Please include as much as you can:
+
+- The affected component (application server, webapp, webhook receiver, deployment configuration, ...)
+- Steps to reproduce, ideally with a proof of concept
+- The impact — what an attacker could achieve
+- Any suggested fix or mitigation
+
+## What to Expect
+
+Security reports are triaged before other work.
+
+- **Initial response within 14 days.**
+- We follow **coordinated disclosure**: please give us time to ship a fix before disclosing publicly. If we cannot agree on a timeline, we treat **90 days** from your report as the default disclosure date, shortened when a vulnerability is being actively exploited.
+- Confirmed vulnerabilities are fixed as soon as feasible and published as [GitHub Security Advisories](https://github.com/ls1intum/Hephaestus/security/advisories). You are credited unless you prefer to stay anonymous.
+
+We do not run a bug bounty program.
+
+## Safe Harbor
+
+We consider good-faith security research conducted under this policy to be authorized, and we will not pursue or support legal action against you for it. If a third party takes action against you for such research, we will make our authorization known. In return, only access the minimum data needed to demonstrate an issue, and do not degrade, disrupt, or destroy data or service.
+
 ## Supported Versions
 
-At this time, there are no officially supported versions of this project for security updates. We are actively developing and improving the project. Please check back later for updates on supported versions.
+Hephaestus is pre-1.0 and released continuously from `main`; **only the latest release is supported**. There are no maintenance branches or backports.
 
-## Reporting a Vulnerability
+## Scope
 
-We take the security of our project seriously. If you discover a vulnerability, please follow the steps below to report it:
+In scope: the code in this repository — the Spring Boot application server (including the webhook receiver), the React webapp, and the deployment/Docker configuration we ship.
 
-1. **Contact Information**: Send an email to [felixtj.dietrich@tum.de] with the subject line "Security Vulnerability Report".
+Out of scope:
 
-2. **Details to Include**:
-   - A description of the vulnerability.
-   - Steps to reproduce the vulnerability.
-   - Potential impact of the vulnerability.
-   - Any available patches or suggestions for fixing the issue.
+- Vulnerabilities in third-party dependencies without a Hephaestus-specific exploit path — report those upstream
+- Denial-of-service, volumetric attacks, and scanner output without a demonstrated impact
+- Social engineering or phishing of maintainers or users
+- Testing against deployments you do not operate — **do not test against our production instances**; run your own (see the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development))
 
-3. **Response Time**:
-   - You can expect an initial acknowledgment of your report within 48 hours.
-   - We will provide regular updates on the status of your report as we investigate and address the issue.
+## Automated Security Measures
 
-4. **Handling of the Vulnerability**:
-   - If the vulnerability is confirmed, we will work to release a patch as soon as possible.
-   - You will be credited for your discovery if you wish, or you can remain anonymous.
-   - If the report is declined, we will provide a detailed explanation as to why it does not meet the criteria for a security vulnerability.
+Independent of this reporting channel, the project runs:
 
-5. **Confidentiality**:
-   - Please do not disclose the vulnerability publicly until we have had an opportunity to address it.
+- **Dependency updates**: [Renovate](https://docs.renovatebot.com/) (Mend-hosted) with vulnerability alerts prioritized and auto-merged ([`renovate.json`](renovate.json))
+- **Dependency & secret scanning in CI**: Trivy filesystem scan and TruffleHog ([`ci-security-scan.yml`](.github/workflows/ci-security-scan.yml))
+- **Static analysis**: GitHub CodeQL
+- **Native alerts**: GitHub secret scanning and Dependabot dependency alerts
 
-Thank you for helping us keep our project safe and secure!
+A machine-readable [`security.txt`](https://hephaestus.aet.cit.tum.de/.well-known/security.txt) ([RFC 9116](https://www.rfc-editor.org/info/rfc9116/)) points to this policy.

webapp/docker/nginx.conf

@@ -128,6 +128,20 @@ server {
         add_header Permissions-Policy "geolocation=(), camera=(), microphone=(), payment=()" always;
     }
 
+    # ==========================================================================
+    # RFC 9116 security.txt - plain text, must not fall through to the SPA shell
+    # ==========================================================================
+    location = /.well-known/security.txt {
+        types { } default_type "text/plain; charset=utf-8";
+        add_header Cache-Control "no-cache" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-Frame-Options "DENY" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+        add_header Cross-Origin-Opener-Policy "same-origin" always;
+        add_header Permissions-Policy "geolocation=(), camera=(), microphone=(), payment=()" always;
+        try_files $uri =404;
+    }
+
     # ==========================================================================
     # SPA routing - using error_page pattern to avoid duplicate headers
     # ==========================================================================

webapp/public/.well-known/security.txt

@@ -0,0 +1,7 @@
+# Hephaestus security policy: https://github.com/ls1intum/Hephaestus/blob/main/SECURITY.md
+Contact: https://github.com/ls1intum/Hephaestus/security/advisories/new
+Contact: mailto:felixtj.dietrich@tum.de
+Policy: https://github.com/ls1intum/Hephaestus/blob/main/SECURITY.md
+Canonical: https://hephaestus.aet.cit.tum.de/.well-known/security.txt
+Preferred-Languages: en, de
+Expires: 2027-07-16T00:00:00Z