# Security runbook Deterministic security workflow for Blit-Tech repos when MCP scanners are healthy, degraded, or unavailable. Use with the `/security-run` skill and `pnpm security:mcp-preflight`. ## Maintainers | Role | Contact / owner | Notes | | ------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- | | Primary security | [@vancura](https://github.com/vancura) (`CODEOWNERS`) | Sole maintainer for `blit-tech` and `blit-tech-demos` (May 2026). | | Backup / escalation | _None_ (solo project) | No secondary on-call; treat delayed response as accepted project risk. | **Incident triage (solo maintainer):** 1. Open or triage a [GitHub issue](https://github.com/vancura/blit-tech/issues): apply label `security` if that label exists in the repository and you have permission; if it does not exist, create the issue and add the label when you can edit repository labels. If you cannot create or label issues, contact [@vancura](https://github.com/vancura) (primary security owner) and record the incident in Linear. 2. Run [Repo-native commands](#repo-native-commands) for the affected repo (`pnpm security:audit`, `pnpm preflight`). 3. Follow [dependency-policy.md](./dependency-policy.md) for CI failures or temporary risk acceptance. 4. Record findings using the [Report template](#report-template) (Linear comment or issue body). Bus-factor evidence (optional): run the `security-ownership-map` skill and attach `summary.json` to hardening reviews. VV-522 (backup-owner process) was canceled; the **Maintainers** section above (including incident triage) is the documented fallback instead of a fictional backup owner. ## When to run - Before a comprehensive security assessment or hardening pass. - Before `/deep-review` when security tooling is in scope. - Monthly MCP governance audit (see [Periodic governance](#periodic-governance-monthly)). ## MCP preflight (required first step) Agents must pass the Cursor project MCP descriptor path from the session (for example `~/.cursor/projects//mcps`). ```bash cd # blit-tech: directory containing this repo's package.json pnpm security:mcp-preflight -- \ --mcps-dir "" \ --repo-root . \ --allow-fallback \ --output-json security-reports/mcp-preflight-latest.json ``` Governance-only (monthly): ```bash pnpm security:mcp-preflight -- \ --mcps-dir "" \ --repo-root . \ --governance-only \ --include-user-config \ --output-json security-reports/mcp-governance-$(date +%Y-%m).json ``` Exit codes: - `0` — proceed (critical MCP healthy, or `--allow-fallback` with documented fallbacks). - `1` — missing `--mcps-dir`, invalid path, or critical MCP down without `--allow-fallback`. Never skip the preflight silently. If a tier is unavailable, run the fallback row from the matrix below and record it in the report. ## Fallback matrix | Capability | Primary MCP | Fallback (always available) | | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dependency / SCA | Opsera `security-scan`, JFrog | `pnpm security:audit`, `pnpm security:audit:prod` (per repo); CI gate in blit-tech [dependency-policy.md](./dependency-policy.md) | | SAST / code patterns | Opsera, Semgrep MCP | `pnpm lint` (eslint-plugin-security), targeted `rg` patterns (below), optional `semgrep --config auto` only if CLI is already installed (do not install) | | Compliance | Opsera `compliance-audit` | Manual checklist below | | Architecture | Opsera `architecture-analyze` | `security-threat-model` and `security-ownership-map` skills under `~/.codex/skills/` | | Supply chain metadata | JFrog MCP | `pnpm outdated --format json`, `npm view version time.modified license` for key direct deps | | MCP governance | — | `pnpm security:mcp-preflight --governance-only` plus Runlayer MCP governance rules | ### SAST `rg` patterns (fallback) Run from each repo root when Semgrep/Opsera SAST is unavailable: ```bash rg -n "innerHTML|outerHTML|insertAdjacentHTML|document\\.write\\(|eval\\(|new Function|postMessage\\(|localStorage|sessionStorage" src/ rg -n "CSP|Content-Security-Policy|X-Frame-Options|frame-ancestors|Referrer-Policy" . ``` ## Compliance fallback checklist When Opsera `compliance-audit` MCP is unavailable, gather evidence manually: | Control area | Evidence source | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | Dependency vulnerabilities | `pnpm security:audit`, `pnpm security:audit:prod` — see [dependency-policy.md](./dependency-policy.md) | | CI dependency gate | `.github/workflows/ci.yml` job **Dependency Security Audit** (moderate+, every PR and `main`) | | Code quality / static checks | `pnpm preflight`, `pnpm lint` | | Secrets in repo | `.gitignore`, hooks blocking `.env`; `rg` for hardcoded tokens (no secret values in reports) | | CI integrity | `.github/workflows/*.yml` — pinned actions, least privilege | | Deploy headers (demos) | `blit-tech-demos/public/_headers`, `curl -I` on deployed URLs | | Ownership / bus factor | [Maintainers](#maintainers) (solo); optional `security-ownership-map` skill output (`summary.json`) | | MCP governance | `pnpm security:mcp-preflight --governance-only` | ## Repo-native commands ### blit-tech ```bash cd # or: cd "$PWD" after cloning blit-tech pnpm security:mcp-preflight -- --mcps-dir "" --repo-root . --allow-fallback pnpm security:audit pnpm security:audit:prod pnpm audit --dev --audit-level=moderate pnpm preflight ``` Key direct dependencies for supply-chain spot checks: `vite`, `typescript`, `eslint`, `vitest`, `happy-dom`. ```bash npm view vite version time.modified license npm view typescript version time.modified license ``` ### blit-tech-demos ```bash cd # blit-tech-demos: directory containing this repo's package.json pnpm security:mcp-preflight -- \ --mcps-dir "" \ --repo-root . \ --allow-fallback pnpm security:audit pnpm security:audit:prod pnpm audit --dev --audit-level=moderate pnpm preflight pnpm build ``` After toolchain or dependency upgrades, always run `pnpm build` as a smoke test. Demos can invoke the canonical preflight script from the library repo (prefer `pnpm security:mcp-preflight` when the sibling layout matches `package.json`). If invoking the script directly, set `` to the blit-tech repo path (or export `BLIT_TECH_ROOT` and use `"$BLIT_TECH_ROOT"`): ```bash node "/scripts/security/mcp-preflight.mjs" \ --mcps-dir "" \ --repo-root . \ --allow-fallback # Example: export BLIT_TECH_ROOT=/path/to/blit-tech # node "$BLIT_TECH_ROOT/scripts/security/mcp-preflight.mjs" --mcps-dir "" --repo-root . --allow-fallback ``` ## Periodic governance (monthly) 1. Run governance-only preflight for **both** repos (use each repo as `--repo-root`). 2. Review shadow MCP flags; migrate or remove unmanaged servers per organizational policy. 3. Re-authenticate critical MCPs (Opsera) if status is `auth_required`. 4. Store reports under `security-reports/` (gitignored). ## Report template Use this structure in agent output or Linear comments: ```md ## Security run report ### MCP preflight - Opsera: - JFrog: - Semgrep: - Fallbacks used: ### blit-tech - security:audit: - prod audit: - preflight: ### blit-tech-demos - security:audit: - prod audit: - preflight: - build: ### Governance - Shadow MCPs: - Config paths scanned: ```