docs: clarify ClawHub vulnerability disclosure policy (#2567)

SECURITY.md

@@ -9,6 +9,19 @@ Good ClawHub advisory reports include bugs in:
 - authentication, authorization, or API tokens
 - scanning, moderation, or report handling
 
+Because ClawHub is a hosted cloud application, ClawHub service vulnerabilities
+are not publicly disclosed by default. They are publicly disclosed when there is
+evidence of real user impact or when users need to take action.
+
+Examples of real user impact include confirmed exploitation, exposure of user
+data or secrets, malicious content reaching users because of a platform failure,
+or any issue that requires users to rotate credentials, update local software, or
+take other protective action.
+
+Vulnerabilities in user-installed software are publicly disclosed, such as
+ClawHub CLI packages, binaries, libraries, or other release artifacts that users
+need to update locally.
+
 Do not use ClawHub advisories for vulnerabilities in a third-party skill or
 plugin's own source code. Report those directly to the publisher or source
 repository linked from the ClawHub listing.

docs/README.md

@@ -38,6 +38,7 @@ Policy, API, and trust docs:
 - `docs/acceptable-usage.md`: marketplace policy and enforcement boundaries.
 - `docs/api.md`: public REST API overview.
 - `docs/http-api.md`: detailed HTTP API reference.
+- `docs/security.md`: reporting ClawHub security issues and vulnerability disclosure policy.
 - `docs/security-audits.md`: user-facing security audit status, risk levels, findings, and interpretation.
 - `docs/moderation.md`: reports, moderation holds, hidden listings, bans, and account standing.
 

docs/clawhub.md

@@ -144,6 +144,7 @@ remaining visible to their owner in `/dashboard`.
 
 Signed-in users can report skills and packages. Moderators can review reports,
 hide or restore content, and ban abusive accounts. See
+[Security](./security.md),
 [Security Audits](./security-audits.md),
 [Moderation and Account Safety](./moderation.md), and
 [Acceptable usage](./acceptable-usage.md) for policy and enforcement details.

docs/how-it-works.md

@@ -90,7 +90,7 @@ Public pages show scan summaries when available. Content that is held, hidden,
 or blocked may disappear from public search and install flows while remaining
 visible to the owner for diagnostics.
 
-See [Security Audits](./security-audits.md),
+See [Security](./security.md), [Security Audits](./security-audits.md),
 [Moderation and Account Safety](./moderation.md), and
 [Acceptable usage](./acceptable-usage.md).
 

docs/moderation.md

@@ -19,7 +19,8 @@ This page covers moderation and account standing. For audit labels such as
 `Pass`, `Review`, `Warn`, `Malicious`, and risk level, see
 [Security Audits](./security-audits.md).
 
-See also [Acceptable usage](./acceptable-usage.md).
+See also [Security](./security.md) and
+[Acceptable usage](./acceptable-usage.md).
 
 ## Reports
 

docs/security-audits.md

@@ -18,8 +18,8 @@ credentials, code, or external services.
 Audits are strong safety signals, but they are not a guarantee that a release is
 risk-free. Always use judgment before granting sensitive access.
 
-See also [Acceptable usage](./acceptable-usage.md) and
-[Moderation and Account Safety](./moderation.md).
+See also [Security](./security.md), [Acceptable usage](./acceptable-usage.md),
+and [Moderation and Account Safety](./moderation.md).
 
 ## What to check before installing
 

docs/security.md

@@ -0,0 +1,49 @@
+---
+summary: "How to report ClawHub security issues and when vulnerabilities are publicly disclosed."
+read_when:
+  - Reporting a ClawHub security issue
+  - Understanding ClawHub vulnerability disclosure
+  - Distinguishing ClawHub platform issues from third-party skill or plugin issues
+title: "Security"
+sidebarTitle: "Security"
+---
+
+# Security
+
+ClawHub security issues can be reported through GitHub Security Advisories for
+`openclaw/clawhub`.
+
+Use GitHub Security Advisories for vulnerabilities in ClawHub itself. Good
+ClawHub advisory reports include bugs in:
+
+- the ClawHub website, API, or CLI
+- registry publishing, downloads, installs, or artifact integrity
+- authentication, authorization, or API tokens
+- scanning, moderation, or report handling
+
+Do not use ClawHub advisories for vulnerabilities in a third-party skill or
+plugin's own source code. Report those directly to the publisher or source
+repository linked from the ClawHub listing.
+
+## Vulnerability disclosure
+
+Because ClawHub is a hosted cloud application, ClawHub service vulnerabilities
+are not publicly disclosed by default. They are publicly disclosed when there is
+evidence of real user impact or when users need to take action.
+
+Examples of real user impact include confirmed exploitation, exposure of user
+data or secrets, malicious content reaching users because of a platform failure,
+or any issue that requires users to rotate credentials, update local software, or
+take other protective action.
+
+Vulnerabilities in user-installed software are publicly disclosed, such as
+ClawHub CLI packages, binaries, libraries, or other release artifacts that users
+need to update locally.
+
+## Related pages
+
+For install-time audit labels, risk levels, findings, and interpretation, see
+[Security Audits](./security-audits.md).
+
+For marketplace reports, moderation holds, hidden listings, bans, and account
+standing, see [Moderation and Account Safety](./moderation.md).