From 8cc84ac08bfbaa19de37694929824c33a238df1a Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Wed, 29 Apr 2026 23:05:29 +0200 Subject: [PATCH 1/4] docs: add SECURITY.md and GitHub issue templates Add a security policy directing private vulnerability reports to security@astrolabecloud.com instead of public issues, and update the README's Security section to point at it. Add structured issue forms under .github/ISSUE_TEMPLATE/ covering bugs, feature requests, questions, and documentation, plus a config.yml that disables blank issues and routes security reports and open-ended questions to the appropriate channels. The bug template captures fields most commonly missing from past reports (server/Nextcloud/app versions, deployment mode, transport, MCP client). Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 141 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/documentation.yml | 29 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 58 +++++++++ .github/ISSUE_TEMPLATE/question.yml | 56 ++++++++ README.md | 2 +- SECURITY.md | 18 +++ 7 files changed, 311 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..e7c87181 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,141 @@ +name: Bug report +description: Report a bug, crash, or unexpected behavior in nextcloud-mcp-server +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. + + **Before submitting**, please check that: + - You're running a recent version (`uvx nextcloud-mcp-server --version` or check the Docker tag). + - The issue isn't already reported in [open issues](https://github.com/cbcoutinho/nextcloud-mcp-server/issues). + - Security issues should **not** be filed here — see [SECURITY.md](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/SECURITY.md). + + - type: textarea + id: summary + attributes: + label: Summary + description: One or two sentences describing what went wrong. + placeholder: "nc_contacts_create silently drops EMAIL/TEL/ORG fields — only the full name is saved." + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: Minimal steps to trigger the bug. Include the exact MCP tool call(s) and arguments where relevant. + placeholder: | + 1. Call `nc_contacts_create` with `full_name`, `email`, `phone` + 2. Inspect the contact in the Nextcloud web UI + 3. Only the name is present + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected vs actual behavior + placeholder: | + Expected: All provided fields are written to the vCard. + Actual: Only FN is saved; EMAIL, TEL, ORG are silently dropped. + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs and error output + description: | + Include the full error message / stack trace from the MCP server, and any relevant entries from + `docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail` (Nextcloud side). + Redact tokens, passwords, and personal data. + render: shell + validations: + required: false + + - type: input + id: mcp_server_version + attributes: + label: nextcloud-mcp-server version + description: e.g. `0.73.0`, Docker tag, or git SHA. + placeholder: "0.73.0" + validations: + required: true + + - type: input + id: nextcloud_version + attributes: + label: Nextcloud server version + placeholder: "Nextcloud 30.0.2" + validations: + required: true + + - type: input + id: nextcloud_app_versions + attributes: + label: Affected Nextcloud app version(s) + description: | + For bugs in a specific app integration, list the installed app version(s) — e.g. Notes 5.0.0, Deck 1.13.0, + Cookbook 0.11.2. Run `docker compose exec app php occ app:list` or check Apps in the Nextcloud UI. + placeholder: "Notes 5.0.0" + validations: + required: false + + - type: dropdown + id: deployment_mode + attributes: + label: Deployment mode + options: + - Single-user (BasicAuth) + - Multi-user BasicAuth (pass-through) + - Login Flow v2 + - OAuth / OIDC (Nextcloud user_oidc) + - OAuth / OIDC (external IdP, e.g. Keycloak) + - Other / not sure + validations: + required: true + + - type: dropdown + id: transport + attributes: + label: MCP transport + options: + - stdio + - streamable-http + - sse (legacy) + - Other / not sure + validations: + required: true + + - type: dropdown + id: install_method + attributes: + label: How are you running the server? + options: + - uvx + - Docker / docker compose + - Helm chart on Kubernetes + - Local checkout (`uv run`) + - Other + validations: + required: true + + - type: input + id: mcp_client + attributes: + label: MCP client + description: e.g. Claude Desktop, Claude Code, an IDE extension, custom client + LLM. + placeholder: "Claude Code" + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional context + description: Anything else that might help — workarounds you found, related issues, suspected root cause, etc. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..820dc0af --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/SECURITY.md + about: Do not file security issues publicly. Email security@astrolabecloud.com — see SECURITY.md. + - name: Question or discussion + url: https://github.com/cbcoutinho/nextcloud-mcp-server/discussions + about: For general questions, deployment help, or open-ended discussion, please use Discussions instead of opening an issue. diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 00000000..2e35f859 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,29 @@ +name: Documentation issue +description: Report unclear, missing, or incorrect documentation +title: "[Docs]: " +labels: ["documentation"] +body: + - type: input + id: location + attributes: + label: Where is the issue? + description: File path, doc URL, or section heading. + placeholder: "docs/authentication.md — 'Multi-User OAuth' section" + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What's wrong or missing? + description: Describe what was confusing, incorrect, or absent. If something didn't work as documented, include what you tried. + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested improvement + description: Optional — proposed wording, missing example, or a link to a better explanation. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..c32baf6b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,58 @@ +name: Feature request +description: Suggest a new Nextcloud app integration, MCP tool, or capability +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement! See the [Supported Apps table](https://github.com/cbcoutinho/nextcloud-mcp-server#supported-apps) + for what's already covered. + + - type: textarea + id: problem + attributes: + label: What problem are you trying to solve? + description: Describe the use case from the user's perspective. What can't you do today? + placeholder: "I want to start Nextcloud Talk calls and post messages to rooms from an AI assistant." + validations: + required: true + + - type: input + id: nextcloud_app + attributes: + label: Nextcloud app or feature involved + description: If this is about a specific Nextcloud app (Talk, Photos, Mail, etc.) or API, name it here. + placeholder: "Talk (spreed)" + validations: + required: false + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: | + What would the MCP tool(s) look like? Include suggested tool names, inputs/outputs, and any relevant + Nextcloud API endpoints if you've researched them. + placeholder: | + - `nc_talk_list_rooms()` — returns rooms the user is a member of + - `nc_talk_send_message(room_token, message)` + - Backed by the OCS Talk API: /ocs/v2.php/apps/spreed/api/v4/... + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any workarounds you've tried, or other tools/projects that solve a similar problem. + validations: + required: false + + - type: textarea + id: additional + attributes: + label: Additional context + description: Screenshots, links to Nextcloud API docs, related issues, etc. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 00000000..56f2be2a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,56 @@ +name: Question / setup help +description: Configuration, deployment, or "how do I…" questions +title: "[Question]: " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + For open-ended discussion, please consider [GitHub Discussions](https://github.com/cbcoutinho/nextcloud-mcp-server/discussions) instead. + Use this template for specific, answerable questions about configuration or behavior. + + - type: textarea + id: question + attributes: + label: Your question + description: What are you trying to do, and what's not working or unclear? + validations: + required: true + + - type: textarea + id: tried + attributes: + label: What have you tried? + description: Commands run, config files, docs you've already read. + validations: + required: false + + - type: input + id: mcp_server_version + attributes: + label: nextcloud-mcp-server version + placeholder: "0.73.0" + validations: + required: true + + - type: input + id: nextcloud_version + attributes: + label: Nextcloud server version + placeholder: "Nextcloud 30.0.2" + validations: + required: false + + - type: dropdown + id: deployment_mode + attributes: + label: Deployment mode + options: + - Single-user (BasicAuth) + - Multi-user BasicAuth (pass-through) + - Login Flow v2 + - OAuth / OIDC (Nextcloud user_oidc) + - OAuth / OIDC (external IdP, e.g. Keycloak) + - Not yet decided + validations: + required: true diff --git a/README.md b/README.md index 396cb33b..b87c0d20 100644 --- a/README.md +++ b/README.md @@ -248,7 +248,7 @@ This project takes security seriously: - No credential storage in OAuth mode - Regular security assessments -Found a security issue? Please report it privately to the maintainers. +Found a security issue? **Do not open a public GitHub issue.** Please report it privately by emailing **security@astrolabecloud.com**. See [SECURITY.md](./SECURITY.md) for details. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..4fd8448f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,18 @@ +# Security Policy + +## Reporting a Vulnerability + +**Please do not report security vulnerabilities through public GitHub issues.** + +If you discover a security vulnerability in this project, report it privately by emailing: + +**security@astrolabecloud.com** + +Please include as much of the following information as possible to help us triage your report: + +- A description of the vulnerability and its potential impact +- Steps to reproduce the issue (proof-of-concept code, if applicable) +- The version(s) of the project affected +- Any known mitigations or workarounds + +We will acknowledge receipt of your report and work with you on coordinated disclosure. From d6362dc77363985f777f75633ab6dd336616e0f3 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Wed, 29 Apr 2026 23:09:39 +0200 Subject: [PATCH 2/4] docs(security): prefer GitHub private vulnerability reporting Surface GitHub's native private reporting workflow as the primary disclosure channel, with security@astrolabecloud.com kept as a fallback for reporters without a GitHub account. Updates SECURITY.md, the README Security section, the issue-template config link, and the bug-template warning banner. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 6 +++--- README.md | 2 +- SECURITY.md | 22 +++++++++++++++++----- 4 files changed, 22 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index e7c87181..56ac08e9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -11,7 +11,7 @@ body: **Before submitting**, please check that: - You're running a recent version (`uvx nextcloud-mcp-server --version` or check the Docker tag). - The issue isn't already reported in [open issues](https://github.com/cbcoutinho/nextcloud-mcp-server/issues). - - Security issues should **not** be filed here — see [SECURITY.md](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/SECURITY.md). + - Security issues should **not** be filed here — use [private vulnerability reporting](https://github.com/cbcoutinho/nextcloud-mcp-server/security/advisories/new) or see [SECURITY.md](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/SECURITY.md). - type: textarea id: summary diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 820dc0af..22632cc8 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,8 @@ blank_issues_enabled: false contact_links: - - name: Security vulnerability - url: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/SECURITY.md - about: Do not file security issues publicly. Email security@astrolabecloud.com — see SECURITY.md. + - name: Security vulnerability (private report) + url: https://github.com/cbcoutinho/nextcloud-mcp-server/security/advisories/new + about: Do not file security issues publicly. Use GitHub's private vulnerability reporting, or see SECURITY.md for the email fallback. - name: Question or discussion url: https://github.com/cbcoutinho/nextcloud-mcp-server/discussions about: For general questions, deployment help, or open-ended discussion, please use Discussions instead of opening an issue. diff --git a/README.md b/README.md index b87c0d20..f0443e5c 100644 --- a/README.md +++ b/README.md @@ -248,7 +248,7 @@ This project takes security seriously: - No credential storage in OAuth mode - Regular security assessments -Found a security issue? **Do not open a public GitHub issue.** Please report it privately by emailing **security@astrolabecloud.com**. See [SECURITY.md](./SECURITY.md) for details. +Found a security issue? **Do not open a public GitHub issue.** Use GitHub's [private vulnerability reporting](https://github.com/cbcoutinho/nextcloud-mcp-server/security/advisories/new), or email **security@astrolabecloud.com** if you can't use GitHub. See [SECURITY.md](./SECURITY.md) for details. ## License diff --git a/SECURITY.md b/SECURITY.md index 4fd8448f..1ada7961 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,17 +2,29 @@ ## Reporting a Vulnerability -**Please do not report security vulnerabilities through public GitHub issues.** +**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.** -If you discover a security vulnerability in this project, report it privately by emailing: +### Preferred: GitHub Private Vulnerability Reporting + +Use GitHub's built-in private reporting workflow: + +➡️ **[Report a vulnerability](https://github.com/cbcoutinho/nextcloud-mcp-server/security/advisories/new)** + +This opens a private draft security advisory visible only to the repository maintainers. You can also reach the same form from the **Security** tab → **Report a vulnerability**. + +### Fallback: Email + +If you cannot use GitHub's private reporting (for example, you don't have a GitHub account), email: **security@astrolabecloud.com** -Please include as much of the following information as possible to help us triage your report: +### What to include + +Whichever channel you use, please include as much of the following as you can to help us triage: - A description of the vulnerability and its potential impact -- Steps to reproduce the issue (proof-of-concept code, if applicable) +- Steps to reproduce (proof-of-concept code, if applicable) - The version(s) of the project affected - Any known mitigations or workarounds -We will acknowledge receipt of your report and work with you on coordinated disclosure. +We will acknowledge receipt and work with you on coordinated disclosure. From dc820aaa4c05ccbf610a13e06f483021047b9bbb Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Wed, 29 Apr 2026 23:22:07 +0200 Subject: [PATCH 3/4] docs(security): address review feedback on PR #740 - SECURITY.md: add response SLA (5 business days / 30 days) - bug_report.yml: scope the Docker log command to Docker installs - question.yml: align deployment_mode catch-all wording with bug_report.yml Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 7 +++++-- .github/ISSUE_TEMPLATE/question.yml | 2 +- SECURITY.md | 2 +- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 56ac08e9..99e9c078 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -49,8 +49,11 @@ body: attributes: label: Logs and error output description: | - Include the full error message / stack trace from the MCP server, and any relevant entries from - `docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail` (Nextcloud side). + Include the full error message / stack trace from the MCP server. + If running with Docker, also include any relevant entries from + `docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail` + (Nextcloud side). For other install methods, attach the equivalent + Nextcloud log excerpt if available. Redact tokens, passwords, and personal data. render: shell validations: diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml index 56f2be2a..fad314b5 100644 --- a/.github/ISSUE_TEMPLATE/question.yml +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -51,6 +51,6 @@ body: - Login Flow v2 - OAuth / OIDC (Nextcloud user_oidc) - OAuth / OIDC (external IdP, e.g. Keycloak) - - Not yet decided + - Other / not sure validations: required: true diff --git a/SECURITY.md b/SECURITY.md index 1ada7961..583a2b4c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -27,4 +27,4 @@ Whichever channel you use, please include as much of the following as you can to - The version(s) of the project affected - Any known mitigations or workarounds -We will acknowledge receipt and work with you on coordinated disclosure. +We aim to acknowledge within 5 business days and provide a fix or mitigation timeline within 30 days, and will work with you on coordinated disclosure. From bd4921091ed120d5695bdaac47f747b8b72cc528 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Wed, 29 Apr 2026 23:45:25 +0200 Subject: [PATCH 4/4] docs(security): address second round of review feedback - SECURITY.md: add Supported Versions table; reword SLA paragraph as a bullet list per reviewer suggestion - bug_report.yml: render reproduction textarea as shell so commands and JSON get syntax highlighting, matching the logs field - question.yml: add transport and install_method dropdowns mirroring bug_report.yml so setup questions capture the same context Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 1 + .github/ISSUE_TEMPLATE/question.yml | 25 +++++++++++++++++++++++++ SECURITY.md | 17 ++++++++++++++++- 3 files changed, 42 insertions(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 99e9c078..778041b1 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -31,6 +31,7 @@ body: 1. Call `nc_contacts_create` with `full_name`, `email`, `phone` 2. Inspect the contact in the Nextcloud web UI 3. Only the name is present + render: shell validations: required: true diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml index fad314b5..abf7ff5c 100644 --- a/.github/ISSUE_TEMPLATE/question.yml +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -54,3 +54,28 @@ body: - Other / not sure validations: required: true + + - type: dropdown + id: transport + attributes: + label: MCP transport + options: + - stdio + - streamable-http + - sse (legacy) + - Other / not sure + validations: + required: true + + - type: dropdown + id: install_method + attributes: + label: How are you running the server? + options: + - uvx + - Docker / docker compose + - Helm chart on Kubernetes + - Local checkout (`uv run`) + - Other + validations: + required: true diff --git a/SECURITY.md b/SECURITY.md index 583a2b4c..e050a290 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,16 @@ # Security Policy +## Supported Versions + +Security fixes are issued only against the latest released version. Older +versions do not receive backported patches — please upgrade before reporting, +and confirm the issue still reproduces on the latest release where possible. + +| Version | Supported | +|----------|-----------| +| latest | ✅ | +| < latest | ❌ | + ## Reporting a Vulnerability **Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.** @@ -27,4 +38,8 @@ Whichever channel you use, please include as much of the following as you can to - The version(s) of the project affected - Any known mitigations or workarounds -We aim to acknowledge within 5 business days and provide a fix or mitigation timeline within 30 days, and will work with you on coordinated disclosure. +We aim to: + +- Acknowledge reports within 5 business days. +- Provide a fix or mitigation timeline within 30 days. +- Work with you on coordinated disclosure.