Security

Pinwren runs on other people's websites (the widget) and holds their feedback, screenshots and console output (the server). This page summarises the threat model, what is implemented today and how to harden your instance.

Threat modelCopy Anchor Link

Pre-release hardeningCopy Anchor Link

Before the first release, an independent review led to these changes (ADR 0021):

• SSRF protection. Webhooks, Slack and Discord channels, webhook panel actions and per-integration tracker URLs all go through one outbound guard. It resolves the host, refuses loopback, private, CGNAT, link-local, cloud metadata, unique-local, multicast and reserved addresses (including IPv6 forms that embed them), connects only to the address it checked, never follows redirects, and caps time and response size. Test buttons and delivery logs show a status code and an error category, never the remote response. Internal targets need PINWREN_OUTBOUND_ALLOWLIST.
• Trusted-proxy client IPs. PINWREN_TRUST_PROXY is a hop count, the address comes from the right of X-Forwarded-For, and X-Real-IP is ignored — see client addresses. The sign-in limiter uses the same address and keeps its counters in Postgres, shared by all workers.
• First account. The first account created on a server is its administrator (there is no setup token), so keep a new server private until you have signed up. PINWREN_ADMIN_EMAILS names more; sign-up closes after the first account by default. See the first account.
• Accounts. Password reset links work once and sign every device out; two-factor authentication (TOTP with backup codes) is available to everyone; reset, verification, two-factor and sign-in endpoints are rate limited.
• CSRF and CSP. Cookie-authenticated writes must be same-origin JSON. Dashboard pages send a fixed Content-Security-Policy (no third-party origins, object-src 'none', base-uri 'none', frame-ancestors 'none'), which also keeps session replays from loading remote resources. Inline scripts stay allowed because the prerendered page shells can't carry nonces; XSS defence rests on escaping, the Markdown sanitiser and http(s)-only links.
• Body caps. Every limit is enforced while the body streams in, before parsing — see bug report limits and API limits.
• Interactive Slack. Every request from Slack is checked against the app's signing secret (HMAC-SHA256 of the raw body, constant-time compare, five-minute replay window) before anything is read from it, and each trigger id is acted on once. A button acts as the Pinwren member found by confirmed email (or linked by the member after a confirmation), with that member's role, and can only reach the workspace its Slack team is connected to. See Slack.
• Encrypted chat webhook URLs. Slack and Discord URLs are encrypted at rest (existing ones on the first start of the new version) and only ever shown masked.
• Token brute-force limit. 20 failed API tokens per address in 10 minutes lock that address out of /api/v1 and /mcp for the rest of the window.
• Relays and admin-only configuration. Template test emails go only to the sender's own address, invitations are rate-limited, and project settings (including panel actions and trackers) can be changed by organisation admins only.
• Smaller fixes. Page URLs must be http(s), the replay viewer stops decompressing at 64 MB, the widget no longer serves threads of deleted items, and the CSV export neutralises formulas hidden behind whitespace.

Privacy by designCopy Anchor Link

• Masking. Password fields, payment-card fields (autocomplete="cc-…") and anything marked data-pinwren-mask are always blocked out of captures as solid boxes; data-pinwren-ignore removes an element from the capture entirely.
• Privacy mode (per project) masks every text field, drops page-timing data, reduces the user agent to the browser and OS family, keeps only errors in console capture, truncates stored IP addresses (/24 for IPv4, /48 for IPv6), asks for consent and turns off the instance's outbound update check. The server enforces the same rules for old or modified widgets. See Privacy & masking.
• Retention. Each project can delete feedback older than a number of days; the trash is purged after 30 days.
• No phone-home. Telemetry does not exist; the only outbound call the server makes on its own is the optional daily update check.

Hardening checklistCopy Anchor Link

• Use a long random PINWREN_SECRET (openssl rand -base64 48) and keep it out of version control.
• Serve over HTTPS behind a reverse proxy. Set PINWREN_TRUST_PROXY to the exact number of proxies in front of Pinwren (0 when there is none), and consider PINWREN_ENFORCE_HTTPS=true.
• Limit each project's allowed sites to the origins that really embed the widget. The origin allowlist and the rate limits are what protect ingest, not the key.
• Create the first account before anyone else can reach the server (or set PINWREN_ADMIN_EMAILS first), and turn on two-factor authentication for administrators. Keep sign-up at its default (first account, then invitations only) unless you really want PINWREN_DISABLE_SIGNUP=false.
• Allowlist only what you need. Add internal webhook receivers or a self-managed GitLab to PINWREN_OUTBOUND_ALLOWLIST by host name or a narrow CIDR, and never set PINWREN_OUTBOUND_ALLOW_PRIVATE outside development.
• Keep uploads private. With STORAGE_DRIVER=s3, keep the bucket private; Pinwren streams every file itself.
• Turn on privacy mode for projects whose pages show personal data, and mark sensitive elements with data-pinwren-mask.
• Mind where integrations send data. Issue sync and webhooks copy feedback text and links into other systems; use private repositories and tokens scoped to one repository.
• Upgrade promptly — instance admins see Update available — and back up the database and files.

Reporting a vulnerabilityCopy Anchor Link

Include what an attacker can do and who is affected (site visitors, workspace members, instance admins), the component and version (widget, dashboard, API, Docker image) and how Pinwren was deployed, steps or a proof of concept against your own instance, and any suggested fix.

We follow coordinated disclosure and credit reporters in the advisory and release notes unless they prefer to stay anonymous. Good-faith research that follows the policy, avoids privacy violations and service disruption, and only touches your own instance is welcome.

In scope: the server and dashboard, the widget (including the published @pinwren/widget), and the Docker image and compose files — especially anything that breaks out of the widget's Shadow DOM, crosses workspaces, bypasses authentication or API tokens, stores XSS, enables SSRF through webhooks, tracker URLs or the update check, or exposes secrets or personal data that should be masked.

Out of scope: findings that need an already compromised admin account or server, missing hardening headers without demonstrated impact, denial of service by sheer volume, and dependency vulnerabilities with no path to exploit them through Pinwren.

The full policy is in SECURITY.md.