Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

docs: make security review part of every change

spacesdrive1b1df4762158
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 714c0ce..4203753 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -6,9 +6,15 @@
Closes #
+## Security
+
+<!-- What the change exposes and to whom, the checks that ran and their results (docs/workflows/SECURITY_REVIEW.md), or why none were needed. -->
+
## Verification
+- [ ] `npm run typecheck`
- [ ] `npm run lint`
- [ ] `npm test`
- [ ] `npm run build`
+- [ ] Security checks for the change's size (`docs/workflows/SECURITY_REVIEW.md`)
- [ ] Docs updated per the Documentation Maintenance Policy in `CLAUDE.md`
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ab3cd19..035546a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Documentation
+- A security review workflow: every change states its security effect, substantial changes get targeted checks with the Cloudflare and Trail of Bits skills and Semgrep while they are built, and pull requests carry a Security section (`docs/workflows/SECURITY_REVIEW.md`, #148)
- Research and an implementation plan for platform v2: removing Reddit, an MCP server for Claude clients, YouTube publishing and security auditing in the workflow, in `docs/platform-v2/` (#143)
## [1.4.0] - 2026-11-05
diff --git a/CLAUDE.md b/CLAUDE.md
index 51b12da..c7ed956 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -149,6 +149,7 @@ docs/
DEPLOYMENT.md Backend deploy, frontend deploy, verification
RECOVERY.md Incidents: find the failure, stop the damage, roll back, back up and restore
SCHEDULING_SETUP.md Five-step GitHub Actions scheduling setup for self-hosters
+ SECURITY_REVIEW.md Security checks per change size, the Cloudflare and Trail of Bits skills, commands, recording results
features/
NEW_ANALYTICS_PAGE.md Add analytics view for a new platform
NEW_API_ENDPOINT.md Add a route to the Hono backend
@@ -306,6 +307,8 @@ This is not optional for features that touch new UI patterns, new APIs, or new i
**Apply the UI/UX guide to every interface change.** Any task that adds or changes something people see or use, in `frontend/` or `site/`, follows `docs/guidelines/UI_UX.md`, including small updates such as a new button, message or column: name the users, tasks and states, pick the laws that apply, reuse the design system, design every state, and run its checks and checklist before committing. With the ProfileBox MCP available, also load the `ui-ux-design-intelligence` system for the task (`get_system_instructions_for_task`). WCAG 2.2 AA is the floor; the project's design system and brand win over any reference.
+**Review security as part of the change, not before a release.** Every change states its security effect, and every substantial change to a feature, service, route, authentication or token flow, database operation, integration, background job, dependency or anything that handles secrets or another person's data gets a security pass while it is built: (1) name what the change exposes and to whom; (2) apply the Cloudflare `security-audit` skill in guidance mode to the touched code; (3) apply the relevant Trail of Bits skills (`insecure-defaults`, `sharp-edges`, `supply-chain-risk-auditor` for a dependency, `variant-analysis` after a fix, `differential-review` on the pull request); (4) run Semgrep on the changed files and `npm audit` when the lockfile changed; (5) check every connected caller and dependency of the touched code; (6) confirm each input is validated and each query and action is scoped to the verified user; (7) add or update a regression test for each risk found; (8) record any risk left open in `docs/philosophy/SECURITY.md` (Known Risks). A small change runs only the targeted checks; a major change (a new platform, public endpoint or security model change) gets a full audit. The tools, commands and recording rules are in `docs/workflows/SECURITY_REVIEW.md`. Never say a scan ran unless it ran, and report each one's actual result. Confirmed vulnerabilities go into a private GitHub security advisory, never a public issue.
+
**Always read before writing.** Read every file you will modify. Read all files in the same directory that might be affected. Read sibling files to understand conventions before adding new ones.
**Match the existing pattern.** This project has established conventions for route tables, controllers, services, repositories, validators, context hooks and api.ts methods. Find the nearest existing example and follow it exactly before introducing anything new.
@@ -428,6 +431,8 @@ When anything changes, update every relevant docs file from the table below. The
| MCP usage rule changed | `docs/mcp/OVERVIEW.md`, this file (MCP Usage Rules section) |
| Engineering standard changed | `docs/philosophy/ARCHITECTURE.md`, this file (Engineering Standards section) |
| Security model changed | `docs/philosophy/SECURITY.md`, `docs/architecture/database/SECURITY.md` |
+| Security review workflow, skills or scanners changed | `docs/workflows/SECURITY_REVIEW.md`, `.claude/settings.json` (and `.claude/marketplaces/`), this file (AI Operating Rules) |
+| Security risk found and left open | `docs/philosophy/SECURITY.md` (Known Risks), with the reason and what would remove it |
| Caching strategy changed | `docs/philosophy/PERFORMANCE.md`, `docs/architecture/backend/CACHING.md` |
| New integration (platform) | `docs/architecture/backend/SERVICES.md`, `docs/architecture/backend/ROUTES.md`, `docs/architecture/backend/CACHING.md`, `docs/architecture/frontend/FEATURES.md`, `docs/architecture/frontend/ROUTING.md`, `DECISIONS.md`, `CHANGELOG.md` |
| Feature guide added or changed | `docs/features/` (relevant file) |
diff --git a/docs/philosophy/SECURITY.md b/docs/philosophy/SECURITY.md
index a884f9f..02b2d63 100644
--- a/docs/philosophy/SECURITY.md
+++ b/docs/philosophy/SECURITY.md
@@ -150,3 +150,11 @@ If a credential is compromised:
7. Instagram webhook verify token: `wrangler secret put INSTAGRAM_WEBHOOK_VERIFY_TOKEN` with a new value, then enter the same value in the Meta dashboard's webhook settings and verify again
There is no automated secrets rotation. This is a known gap.
+
+## Known Risks
+
+Risks found by a security review and left open on purpose, each with the reason and what would remove it. The review process is in `docs/workflows/SECURITY_REVIEW.md`.
+
+| Risk | Why it stays | What would remove it |
+|---|---|---|
+| No automated secrets rotation | Rotation needs the owner in the Meta, Google and Supabase dashboards | A rotation runbook with a reminder, or provider APIs that rotate in place |
diff --git a/docs/workflows/SECURITY_REVIEW.md b/docs/workflows/SECURITY_REVIEW.md
new file mode 100644
index 0000000..c7f849a
--- /dev/null
+++ b/docs/workflows/SECURITY_REVIEW.md
@@ -0,0 +1,83 @@
+# Security Review
+
+Security review is part of building a change, not a step before a release. This page says which checks a change needs, how to run them, and how to record the result. The rule that requires it is in `CLAUDE.md` (AI Operating Rules, "Review security as part of the change"); the security model it protects is in `docs/philosophy/SECURITY.md`.
+
+---
+
+## The tools
+
+| Tool | What it is | Where it comes from |
+|---|---|---|
+| `security-audit` | Cloudflare's source-first audit skill: guidance mode for focused questions, full audit mode with six phases and independent verifiers | `security-audit@cloudflare-security`, declared in `.claude/settings.json` through the small marketplace file in `.claude/marketplaces/cloudflare-security/`, pinned to a reviewed commit (MIT, nothing copied) |
+| `differential-review` | Reviews a diff or pull request for security regressions | Trail of Bits plugin (CC-BY-SA-4.0, installed from their marketplace, nothing copied) |
+| `insecure-defaults` | Finds fail-open configuration, hardcoded secrets, weak defaults | Trail of Bits plugin |
+| `sharp-edges` | Finds APIs and settings that are easy to misuse | Trail of Bits plugin |
+| `static-analysis` | Runs Semgrep (and CodeQL when installed) and triages the results | Trail of Bits plugin |
+| `supply-chain-risk-auditor` | Reviews dependencies for maintenance, ownership and known-vulnerability risk | Trail of Bits plugin |
+| `variant-analysis` | After a fix, finds the same bug elsewhere | Trail of Bits plugin |
+| `audit-context-building` | Builds a map of the code before a deep audit | Trail of Bits plugin |
+| `/security-review` | Claude Code's built-in review of the branch's pending changes | Built in |
+| Semgrep | Static analysis CLI (`semgrep --version`) | `pip install semgrep`; jq is needed by the Trail of Bits scripts (`winget install jqlang.jq`) |
+| `npm audit` | Known advisories in the dependency tree | npm |
+
+### Setting them up
+
+1. Open the repository in Claude Code and accept the workspace trust prompt; the marketplaces in `.claude/settings.json` only apply after it.
+2. Install the plugins once (they stay enabled for this project):
+
+ ```bash
+ claude plugin marketplace add ./.claude/marketplaces/cloudflare-security --scope project
+ claude plugin install security-audit@cloudflare-security --scope project
+ claude plugin install differential-review@trailofbits --scope project
+ ```
+
+ Repeat the last line for each `@trailofbits` plugin listed in `enabledPlugins`.
+3. Install Semgrep (`pip install semgrep`) and jq. CodeQL is optional.
+4. Do not enable `fp-check`, `gh-cli` or `modern-python` at project scope: they install hooks that change every session.
+
+A contributor can switch a plugin off for themselves with `false` in `.claude/settings.local.json`.
+
+---
+
+## Which checks a change needs
+
+| Change | Checks |
+|---|---|
+| Small: a fix, copy, styling, a field, a test | Name the security effect in one line (often "none"). If it touches input handling, auth, a query, a secret, an external call or HTML output, run `security-audit` in guidance mode on the changed files and Semgrep on them |
+| Substantial: a feature, route, service, migration, integration, auth or token flow, background job, dependency | Everything for a small change, plus `insecure-defaults` and `sharp-edges` on the touched area, `supply-chain-risk-auditor` when a dependency changes, a check of every connected caller and permission, and a regression test for each risk found |
+| Pull request | `/security-review` or `differential-review` on the diff, Semgrep on the changed files, `npm audit` when the lockfile changed |
+| Major: a new platform, a new public endpoint, a change to the security model, or before a major version | A full audit with `security-audit` in full audit mode, Semgrep over the repository, `supply-chain-risk-auditor`, `npm audit`, and a write-up |
+
+A fix gets `variant-analysis` (or a manual search) for the same pattern elsewhere.
+
+### Commands
+
+```bash
+# Semgrep on changed files (no telemetry); the registry rule sets need network access
+semgrep scan --metrics=off --config p/typescript --config p/javascript --config p/secrets --config p/github-actions $(git diff --name-only main...HEAD)
+
+# the whole repository
+semgrep scan --metrics=off --config p/typescript --config p/javascript --config p/secrets --config p/github-actions --exclude node_modules --exclude dist .
+
+# dependency advisories
+npm audit --omit=dev
+npm audit
+```
+
+In Claude Code: `/security-review`, `/differential-review:diff-review <pull request url>`, and the skills by name ("use the security-audit skill in guidance mode on backend/routes/mcpRoutes.ts").
+
+### Rules for running them
+
+- **Never run project code outside a sandbox for an audit.** Claude Code has no sandbox on native Windows, so on Windows the audit reads source only, and a lead that needs running code is recorded as "needs validation" with a plan. Run Claude Code in WSL2 to validate by execution.
+- **Never probe production.** No requests to the deployed app or Worker, other people's data, or paid API quota.
+- **Keep audit output out of the repository.** The full audit writes to `~/security-audit-skill/twiligent/run-<N>`; Semgrep and other tools write to a temporary folder. `differential-review` runs `git checkout`, so run it in a separate worktree.
+- **Never claim a check that did not run.** A write-up names each tool, the command or scope, and its actual result.
+
+---
+
+## Recording the result
+
+- **In the pull request:** a "Security" line with what was checked and found, or why no check was needed.
+- **Confirmed vulnerability:** a private GitHub security advisory (Security, Advisories) until the fix is released, never a public issue, because the repository is public. The fix's commit and changelog entry describe the effect in plain words without a recipe.
+- **Unresolved risk:** a line in `docs/philosophy/SECURITY.md` (Known risks) or the relevant architecture doc, with the reason it stays and what would remove it.
+- **Severity:** critical, high, medium, low or informational, from the impact on a real trust boundary (another user's data, a secret, publishing as someone, running up quota) and how easy it is to reach. A finding is never downgraded to make a report look clean.