From e9563694ac829f37bdc81044fbc051dee65561a9 Mon Sep 17 00:00:00 2001
From: Kevin Tang <73975146+vt128@users.noreply.github.com>
Date: Sun, 20 Sep 2026 08:17:57 +0800
Subject: [PATCH] [doc] ship security reporting and support policy (ENG-11)

---
 .goreleaser.yaml      |  1 +
 README.md             |  7 +++++--
 SECURITY.md           | 40 ++++++++++++++++++++++++++++++++++++++++
 e2e/verify-release.py |  8 ++++++--
 4 files changed, 52 insertions(+), 4 deletions(-)
 create mode 100644 SECURITY.md

diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 95a0f2a..2489d9b 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -65,6 +65,7 @@ archives:
       {{- if eq .Os "darwin" }}macOS{{ else }}{{ .Os }}{{ end }}_{{ .Arch }}
     files:
       - README.md
+      - SECURITY.md
       - LICENSE*
 
 checksum:
diff --git a/README.md b/README.md
index b818e63..530320a 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,9 @@ StarCLI is a versatile tool that provides a convenient environment for running S
 
 Download the archive for your system and `checksums.txt` from the same
 [GitHub Release](https://github.com/1set/starcli/releases). No Go installation is
-needed to run a release binary.
+needed to run a release binary. Starting with v0.1.3, each archive includes the README, license, and
+[security policy](SECURITY.md), including the supported execution boundary and
+private vulnerability reporting instructions.
 
 | System | Architecture | Archive suffix |
 |---|---|---|
@@ -423,7 +425,8 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Contact
 
-For any questions or support, please open an issue on [GitHub](https://github.com/1set/starcli/issues).
+For ordinary bugs, questions, or support, please open an issue on [GitHub](https://github.com/1set/starcli/issues).
+For vulnerabilities, follow the private reporting instructions in [SECURITY.md](SECURITY.md).
 
 ### HTTP execution limits
 
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..78a8fb8
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,40 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please use [GitHub private vulnerability reporting](https://github.com/1set/starcli/security/advisories/new)
+for security issues. Include the affected version or commit, operating system
+and architecture, relevant capability grants and configuration, and a minimal
+reproduction with the expected and actual behavior. For source builds, include
+the Go version. Use synthetic data and remove credentials from scripts, logs,
+and session recordings before sharing them.
+
+Use public issues for ordinary bugs and support. There is no guaranteed
+response time; keep vulnerability details private while coordinating a fix.
+
+## Supported versions
+
+Security fixes target the latest release through patch updates. Older releases
+are not maintained as separate security branches. Review release notes for
+behavior changes before upgrading, and keep a known working binary for rollback.
+
+The `go.mod` version is a compatibility floor. Build production binaries with
+a supported Go toolchain containing the latest security fixes, or use the
+prebuilt release binaries. See the README for checksum and provenance checks.
+
+## Execution boundary
+
+StarCLI is intended for host-selected, reviewed scripts in a controlled,
+single-tenant environment. Capability grants limit available operations; they
+do not provide process or memory isolation. The default `open` tier permits
+network and filesystem access. `--allow-cmd` authorizes arbitrary host commands
+and process environment access, including through `gum` and `runtime`.
+
+Use the narrowest capability grants and import directories that your script
+needs. HTTP execution has request and cooperative execution limits, but these
+do not preempt arbitrary Go builtins or impose a complete output-byte budget.
+Untrusted scripts or public multi-tenant services need a separate constrained
+worker, resource limits, and an independent security review.
+
+Treat transcripts from `--record` as sensitive output: they can include input,
+results, and errors. Control their access and retention at the host level.
diff --git a/e2e/verify-release.py b/e2e/verify-release.py
index 3fa556e..439f0d5 100644
--- a/e2e/verify-release.py
+++ b/e2e/verify-release.py
@@ -75,8 +75,12 @@ def verify_archives(directory, version, *, native_only=False):
                     if member.name == binary and not member.mode & 0o111:
                         raise ValueError(f"binary is not executable: {name}")
                     members[member.name] = package.extractfile(member).read()
-        if members.keys() != {binary, "README.md", "LICENSE"} or not all(members.values()):
-            raise ValueError(f"archive must contain only a binary, README and license: {name}")
+        required_members = {binary, "README.md", "LICENSE", "SECURITY.md"}
+        # The immutable rollback baseline predates the packaged security policy.
+        if version == "0.1.2":
+            required_members.remove("SECURITY.md")
+        if members.keys() != required_members or not all(members.values()):
+            raise ValueError(f"archive must contain exactly {sorted(required_members)}: {name}")
         if (system, arch) == target:
             native_binary = members[binary]
         print(f"verified {name}", flush=True)