shipclear 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +104 -0
- package/adapters/claude-code/.claude-plugin/plugin.json +7 -0
- package/adapters/claude-code/commands/safe-to-ship.md +37 -0
- package/adapters/claude-code/hooks/guard.cjs +49 -0
- package/adapters/claude-code/hooks/hooks.json +15 -0
- package/adapters/claude-code/skills/shipclear-prevention/SKILL.md +40 -0
- package/adapters/codex/AGENTS.md +40 -0
- package/adapters/cursor/shipclear.mdc +40 -0
- package/adapters/gemini/GEMINI.md +40 -0
- package/adapters/generic/INSTRUCTIONS.md +66 -0
- package/cli/bin/shipclear.js +182 -0
- package/cli/lib/checks.js +414 -0
- package/cli/lib/fix.js +160 -0
- package/cli/lib/git.js +112 -0
- package/cli/lib/ignore.js +33 -0
- package/cli/lib/patterns.js +215 -0
- package/cli/lib/report.js +316 -0
- package/cli/lib/scan.js +51 -0
- package/core/gate-checklist.md +44 -0
- package/core/prevention.md +33 -0
- package/docs/quickstart.md +87 -0
- package/docs/troubleshooting.md +75 -0
- package/package.json +45 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Adam Timmerberg
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 🛡️ ShipClear
|
|
4
|
+
|
|
5
|
+
**The last command before you launch.**
|
|
6
|
+
|
|
7
|
+
Your AI writes code fast. ShipClear makes sure it's safe to ship —
|
|
8
|
+
free, open source, runs 100% locally, works with every AI coding tool.
|
|
9
|
+
|
|
10
|
+
[](https://github.com/adamtimmerberg/ShipClear/actions/workflows/ci.yml)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](package.json)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
You built something with AI — Claude Code, Cursor, Codex, Bolt, Lovable, a local model. It works! But before you deploy it or make the repo public, one question matters:
|
|
19
|
+
|
|
20
|
+
> **Is there anything in here that will hurt me the moment it's public?**
|
|
21
|
+
|
|
22
|
+
A scan of 5,600 AI-built apps found 2,000+ vulnerabilities and 400 exposed API keys. Leaked keys turn into real bills; the `admin@test.com / password123` account your AI made "for testing" turns into a real breach. ShipClear exists so that never happens to you.
|
|
23
|
+
|
|
24
|
+
## One command
|
|
25
|
+
|
|
26
|
+
*(Never typed a command before? [Start here](docs/quickstart.md#first-time-typing-a-command-start-here) — it takes two minutes.)*
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npx shipclear ship
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
That runs the full gate and gives you a verdict:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
ShipClear v0.2.0 — ship report
|
|
36
|
+
|
|
37
|
+
🛑 CRITICAL A secret key is written directly in your code
|
|
38
|
+
where: server.js:7 — OpenAI API key: `sk-FAKE0…`
|
|
39
|
+
why it matters: Anyone who sees this code — on GitHub, in a screenshot, in
|
|
40
|
+
your deployed app — can use this key as you, and you get the bill.
|
|
41
|
+
what to do: Move the value into your .env file and read it from an
|
|
42
|
+
environment variable. Then rotate the key: log in to the provider and
|
|
43
|
+
generate a new one, because this one is burned.
|
|
44
|
+
|
|
45
|
+
Fixed for you:
|
|
46
|
+
✔ Added `.env` protection to .gitignore (created it if missing).
|
|
47
|
+
|
|
48
|
+
🛑 DO NOT SHIP — fix the critical findings first.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Every finding answers three questions in plain English: **what is this, why does it matter, what do I do.** Safe fixes are applied for you. No security background needed.
|
|
52
|
+
|
|
53
|
+
## Three layers, not just a scanner
|
|
54
|
+
|
|
55
|
+
Most tools scan your app *after* you've made the mistake. ShipClear rides along the whole time:
|
|
56
|
+
|
|
57
|
+
| Layer | What it does |
|
|
58
|
+
|---|---|
|
|
59
|
+
| 🧠 **Prevention** | Rules for your AI assistant so secrets never get hardcoded in the first place — `.env` from the first line of code, no test accounts, no real data in the repo. |
|
|
60
|
+
| 🚫 **Enforcement** | A git commit guard (`shipclear setup`) that blocks any commit containing secrets or a `.env` file. Deterministic — it isn't the AI deciding to be careful. (If the scanner itself can't run — you're offline, say — it lets the commit through with a warning rather than blocking your work; it fails safe, not stuck.) |
|
|
61
|
+
| ✅ **The gate** | `shipclear ship`: 13 deterministic checks + a semantic checklist for your AI, ending in one verdict — cleared to ship, or not. Found a secret in old commits? `shipclear ship --fix-history` erases that history safely (never-pushed repos only; it refuses if it would lose anything). |
|
|
62
|
+
|
|
63
|
+
## Works with every AI coding tool
|
|
64
|
+
|
|
65
|
+
One canonical rule set, generated into every format ([how](scripts/build-adapters.mjs)):
|
|
66
|
+
|
|
67
|
+
| Tool | Setup |
|
|
68
|
+
|---|---|
|
|
69
|
+
| **Claude Code** | `/plugin marketplace add adamtimmerberg/ShipClear` then install `shipclear` — you get the prevention skill, a hook that blocks secret-bearing commits, and the `/safe-to-ship` command |
|
|
70
|
+
| **Codex CLI** | Append [`adapters/codex/AGENTS.md`](adapters/codex/AGENTS.md) to your project's `AGENTS.md` |
|
|
71
|
+
| **Cursor** | Copy [`adapters/cursor/shipclear.mdc`](adapters/cursor/shipclear.mdc) into `.cursor/rules/` |
|
|
72
|
+
| **Gemini CLI** | Append [`adapters/gemini/GEMINI.md`](adapters/gemini/GEMINI.md) to your `GEMINI.md` |
|
|
73
|
+
| **Any local model / other tool** | Paste [`adapters/generic/INSTRUCTIONS.md`](adapters/generic/INSTRUCTIONS.md) into your system prompt |
|
|
74
|
+
| **No AI at all** | The CLI works standalone: `npx shipclear setup && npx shipclear ship` |
|
|
75
|
+
|
|
76
|
+
Full walkthroughs: [docs/quickstart.md](docs/quickstart.md). Stuck on anything? [docs/troubleshooting.md](docs/troubleshooting.md) answers the questions first-timers actually hit, in plain English.
|
|
77
|
+
|
|
78
|
+
## What the gate checks
|
|
79
|
+
|
|
80
|
+
Secrets in your code **and in your entire git history** (deleting a key doesn't un-leak it) · committed `.env` and private key files · real-looking values in `.env.example` · `.gitignore` coverage · personal data (emails, SSNs) in tracked data files · hardcoded login accounts · known-vulnerable dependencies · your local paths and AI-session artifacts leaking into the repo.
|
|
81
|
+
|
|
82
|
+
Provider keys covered: AWS, Anthropic, OpenAI, OpenRouter, Groq, xAI, Hugging Face, Stripe, GitHub, Google, Slack, SendGrid, npm, DigitalOcean, Azure, private keys, database URLs with real passwords — and Supabase JWTs done right: service-role keys are flagged, anon keys (public by design) are left alone.
|
|
83
|
+
|
|
84
|
+
Detection is tuned against real-world starter repos, with a false-positive regression test for every fix. And if you have `gitleaks` or `osv-scanner` installed, ShipClear automatically uses them for extra depth — it just never *requires* them.
|
|
85
|
+
|
|
86
|
+
Plus a ten-point semantic checklist your AI assistant runs — the checks a regex can't do: auth **and ownership** on every route, database rules, client-side leakage, injection/XSS/uploads, server-side trust (prices, roles, webhook signatures), session hygiene and rate limiting, debug surface, and an AI-surface review for apps that call LLMs themselves (prompt injection, unvalidated model output, overprivileged tools).
|
|
87
|
+
|
|
88
|
+
Pass the gate and you'll get a badge for your README: 
|
|
89
|
+
|
|
90
|
+
## Privacy, by architecture
|
|
91
|
+
|
|
92
|
+
ShipClear runs entirely on your machine. **No account. No server. No telemetry. Nothing is uploaded, ever.** It has zero runtime dependencies — what you install is what's in this repo, and CI enforces that by not having an install step.
|
|
93
|
+
|
|
94
|
+
## What ShipClear can't do
|
|
95
|
+
|
|
96
|
+
Honesty is a feature in a security tool. ShipClear does **not**: audit your business logic, test your deployed infrastructure, protect against DDoS, review your cloud console settings, or replace a professional security audit for high-stakes products. It also can't catch a secret format nobody has taught it — if you find one it misses, [that's a security bug and we treat it like one](SECURITY.md).
|
|
97
|
+
|
|
98
|
+
## Contributing
|
|
99
|
+
|
|
100
|
+
Detection gaps, better plain-English explanations, and new adapters are all welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). ShipClear runs its own gate in CI on every commit; it will never ask you to ship what it wouldn't.
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
[MIT](LICENSE) © Adam Timmerberg
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "shipclear",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Security companion for AI-assisted coding: prevention rules applied to every task, a commit guard that blocks leaked secrets, and the /safe-to-ship gate.",
|
|
5
|
+
"author": { "name": "Adam Timmerberg" },
|
|
6
|
+
"homepage": "https://github.com/adamtimmerberg/ShipClear"
|
|
7
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Run the full ShipClear gate — deterministic scan plus semantic security review — and deliver a plain-English safe-to-ship verdict.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
<!-- GENERATED from core/gate-checklist.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
6
|
+
|
|
7
|
+
# Safe to ship?
|
|
8
|
+
|
|
9
|
+
The user wants to know whether this project is safe to deploy or share publicly. Run the complete ShipClear gate.
|
|
10
|
+
|
|
11
|
+
## How to run the gate
|
|
12
|
+
|
|
13
|
+
1. Run the deterministic scan: `npx --yes shipclear ship` (it writes `SHIP-REPORT.md` and applies safe fixes automatically).
|
|
14
|
+
2. Read `SHIP-REPORT.md` and walk the user through each finding in plain English.
|
|
15
|
+
- **Never run `shipclear ship --fix-history` on the user's behalf.** It erases git history. If a finding recommends it, explain what it does, confirm the other findings are fixed first, and let the user run it — or run it only after they explicitly say to.
|
|
16
|
+
3. Perform the semantic checks below yourself — these need code understanding and are your responsibility:
|
|
17
|
+
|
|
18
|
+
1. **Hidden accounts:** search for any route, seed, migration, or conditional that grants access via a fixed credential, magic string, or special email — including ones the AI itself created during this project. Check `.shipclear/test-accounts.json` and confirm every listed credential is absent from code and the production database plan.
|
|
19
|
+
2. **Auth and ownership:** enumerate every route/endpoint; confirm each one either requires authentication or is intentionally public (list the public ones). For every authenticated resource access, confirm the code checks the resource *belongs to the requester* — an ID in a URL or request body must never be enough on its own.
|
|
20
|
+
3. **Database exposure:** review Firebase rules / Supabase RLS / equivalent for world-readable or world-writable access. Deny-by-default expected.
|
|
21
|
+
4. **Client-side leakage:** confirm no server secret is imported, bundled, or rendered into anything delivered to the browser.
|
|
22
|
+
5. **Input handling:** user input reaching SQL/NoSQL/shell must be parameterized; user content rendered into HTML must be escaped or sanitized; file uploads must validate type and enforce a size limit.
|
|
23
|
+
6. **Server-side trust:** anything with consequences must be computed or verified server-side — prices and entitlements (never trust totals from the client), roles and privileged fields (no mass-assignment of `role`/`isAdmin` from request bodies), and incoming webhooks (verify the signature before processing).
|
|
24
|
+
7. **Session and abuse surface:** session tokens in httpOnly cookies rather than localStorage; rate limiting (or provider-equivalent) on login, signup, and password-reset endpoints.
|
|
25
|
+
8. **Debug surface:** look for debug endpoints, verbose stack traces returned to users, `console.log` of sensitive values, and permissive CORS on authenticated APIs.
|
|
26
|
+
9. **AI surface** (when the app itself calls LLMs or runs agents/MCP tools): treat user input and any external content entering prompts as untrusted; never execute, render as HTML, or write to the database unvalidated model output; give agent/MCP tools the narrowest permissions that work, and keep agents away from production resources during testing.
|
|
27
|
+
10. **Report merge:** append semantic findings to `SHIP-REPORT.md` in the same *What / Why / Fix* format, then restate the final verdict — a semantic critical downgrades the overall verdict to DO NOT SHIP.
|
|
28
|
+
|
|
29
|
+
## Verdict rules
|
|
30
|
+
|
|
31
|
+
- Any **critical** finding → 🛑 **DO NOT SHIP**
|
|
32
|
+
- Any **high** or **medium** finding (no criticals) → 🟡 **SHIP WITH FIXES**
|
|
33
|
+
- Only low/info notes → ✅ **CLEARED TO SHIP**
|
|
34
|
+
|
|
35
|
+
A false ✅ is the worst possible outcome and always takes priority over false-positive comfort.
|
|
36
|
+
|
|
37
|
+
Finish by telling the user the final verdict in one clear sentence, and exactly what stands between them and ✅ if they are not there yet.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// ShipClear commit guard (Claude Code PreToolUse hook).
|
|
3
|
+
// If the agent is about to run `git commit` or `git push`, scan the staged
|
|
4
|
+
// changes for secrets first. Exit 2 blocks the tool call; the message on
|
|
5
|
+
// stderr is shown to the agent so it can fix the problem instead.
|
|
6
|
+
//
|
|
7
|
+
// Written in Node (.cjs so it runs under any package "type") for Windows/
|
|
8
|
+
// macOS/Linux parity. Fails closed on findings, but open — with a warning —
|
|
9
|
+
// when the scanner itself can't run (offline npx, missing install): a guard
|
|
10
|
+
// that blocks every commit when the network is down gets uninstalled.
|
|
11
|
+
const { spawnSync } = require('child_process');
|
|
12
|
+
const fs = require('fs');
|
|
13
|
+
const path = require('path');
|
|
14
|
+
|
|
15
|
+
let input = '';
|
|
16
|
+
process.stdin.on('data', (d) => { input += d; });
|
|
17
|
+
process.stdin.on('end', () => {
|
|
18
|
+
let command = '';
|
|
19
|
+
try {
|
|
20
|
+
command = JSON.parse(input)?.tool_input?.command || '';
|
|
21
|
+
} catch {
|
|
22
|
+
process.exit(0); // unparseable payload — never block on our own failure
|
|
23
|
+
}
|
|
24
|
+
if (!/\bgit\b[\s\S]*\b(commit|push)\b/.test(command)) process.exit(0);
|
|
25
|
+
|
|
26
|
+
const win = process.platform === 'win32';
|
|
27
|
+
const local = path.join('node_modules', '.bin', win ? 'shipclear.cmd' : 'shipclear');
|
|
28
|
+
const [bin, args] = fs.existsSync(local)
|
|
29
|
+
? [local, ['scan', '--staged']]
|
|
30
|
+
: ['npx', ['--yes', 'shipclear', 'scan', '--staged']];
|
|
31
|
+
const result = spawnSync(bin, args, { shell: win, encoding: 'utf8' });
|
|
32
|
+
|
|
33
|
+
if (result.status === 0) process.exit(0);
|
|
34
|
+
|
|
35
|
+
const stderr = result.stderr || '';
|
|
36
|
+
if (stderr.includes('ShipClear blocked')) {
|
|
37
|
+
console.error(
|
|
38
|
+
'ShipClear blocked this command: the staged changes contain secrets or a .env file.\n' +
|
|
39
|
+
stderr.trim() + '\n' +
|
|
40
|
+
'Move the secrets to .env, restage, then try again. Never bypass this by disabling the guard — fix the leak.'
|
|
41
|
+
);
|
|
42
|
+
process.exit(2);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
// The scanner itself failed to run (offline, not installed, etc.) — warn,
|
|
46
|
+
// don't brick every commit.
|
|
47
|
+
console.error('ShipClear guard: could not run the staged scan (is shipclear installed?). Proceeding without it — run `npx shipclear scan --staged` manually when possible.');
|
|
48
|
+
process.exit(0);
|
|
49
|
+
});
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shipclear-prevention
|
|
3
|
+
description: Secure-by-default rules for AI-assisted coding. Use for EVERY coding task in every project — creating files, writing features, testing, seeding data. Covers secrets handling, .env/.gitignore setup, no hardcoded accounts, no real data in repos, and secure stack defaults.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- GENERATED from core/prevention.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
7
|
+
|
|
8
|
+
# ShipClear prevention rules
|
|
9
|
+
|
|
10
|
+
These rules are for AI coding agents and assistants. Follow them on every task, in every project, from the first line of code. They exist so the human you're helping never ships a leaked secret, an exposed database, or a forgotten test account. When a rule conflicts with speed, the rule wins.
|
|
11
|
+
|
|
12
|
+
## 1. Secrets never touch source code
|
|
13
|
+
|
|
14
|
+
- Before writing the first line of application code in a new project, create three files: `.env` (real values, never committed), `.env.example` (same keys, empty or placeholder values), and `.gitignore` containing at minimum `.env`, `.env.*` (with an exception for `.env.example`), and your dependency directory.
|
|
15
|
+
- Never write an API key, password, token, connection string, or any credential directly in source code, config files, notebooks, HTML, or client-side JavaScript — not even "temporarily", not even in comments. Use environment variables (`process.env.X`, `os.environ["X"]`) from the very first draft.
|
|
16
|
+
- Server-side secrets must never reach frontend code. Anything shipped to a browser is public. If the frontend needs data that requires a secret, put the secret behind a server endpoint.
|
|
17
|
+
- If a secret was ever written into a tracked file — even if deleted afterwards — tell the user plainly: the key must be **rotated** (regenerated at the provider), because git history preserves it.
|
|
18
|
+
|
|
19
|
+
## 2. No hardcoded accounts, ever
|
|
20
|
+
|
|
21
|
+
- Never create hardcoded login credentials, "temporary" admin accounts, magic bypass strings, or backdoor routes while building or testing — not in code, not in seed scripts, not in database migrations.
|
|
22
|
+
- If testing requires an account, generate random credentials at seed time, store them only in a git-ignored file (`.shipclear/test-accounts.json`), and tell the user it exists so it can be deleted before launch.
|
|
23
|
+
- Never weaken authentication to make a test pass. Fix the test.
|
|
24
|
+
|
|
25
|
+
## 3. Real data stays out of the repository
|
|
26
|
+
|
|
27
|
+
- Never commit data files (CSV, JSON, SQL dumps, database files, exports) containing real names, emails, phone numbers, or any personal information. Generate synthetic data for development and seeding.
|
|
28
|
+
- If the user provides a real data file, keep it git-ignored and say so explicitly.
|
|
29
|
+
|
|
30
|
+
## 4. Secure defaults for common stacks
|
|
31
|
+
|
|
32
|
+
- Every non-public API route gets an authentication check — deny by default. Do not defer auth "until later".
|
|
33
|
+
- Database access rules (Firebase rules, Supabase RLS, and similar) start locked: no world-readable or world-writable tables. Enable row-level security before inserting the first row.
|
|
34
|
+
- Validate and parameterize all user input touching a database (no string-built SQL). Escape output rendered into HTML.
|
|
35
|
+
- Don't disable security to fix an error (CORS `*` on authenticated APIs, `rejectUnauthorized: false`, disabled CSRF) — solve the actual problem, and say what it was.
|
|
36
|
+
|
|
37
|
+
## 5. Be honest about security state
|
|
38
|
+
|
|
39
|
+
- When you take a shortcut or leave something unfinished that has security implications, say so out loud and record it — never let the user believe the project is more secure than it is.
|
|
40
|
+
- Before the user shares the repository publicly or deploys, recommend running the ShipClear gate: `npx shipclear ship`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
<!-- GENERATED from core/prevention.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
2
|
+
<!-- Append this file's contents to your project's AGENTS.md (or drop it in as-is). -->
|
|
3
|
+
|
|
4
|
+
# ShipClear security rules
|
|
5
|
+
|
|
6
|
+
These rules are for AI coding agents and assistants. Follow them on every task, in every project, from the first line of code. They exist so the human you're helping never ships a leaked secret, an exposed database, or a forgotten test account. When a rule conflicts with speed, the rule wins.
|
|
7
|
+
|
|
8
|
+
## 1. Secrets never touch source code
|
|
9
|
+
|
|
10
|
+
- Before writing the first line of application code in a new project, create three files: `.env` (real values, never committed), `.env.example` (same keys, empty or placeholder values), and `.gitignore` containing at minimum `.env`, `.env.*` (with an exception for `.env.example`), and your dependency directory.
|
|
11
|
+
- Never write an API key, password, token, connection string, or any credential directly in source code, config files, notebooks, HTML, or client-side JavaScript — not even "temporarily", not even in comments. Use environment variables (`process.env.X`, `os.environ["X"]`) from the very first draft.
|
|
12
|
+
- Server-side secrets must never reach frontend code. Anything shipped to a browser is public. If the frontend needs data that requires a secret, put the secret behind a server endpoint.
|
|
13
|
+
- If a secret was ever written into a tracked file — even if deleted afterwards — tell the user plainly: the key must be **rotated** (regenerated at the provider), because git history preserves it.
|
|
14
|
+
|
|
15
|
+
## 2. No hardcoded accounts, ever
|
|
16
|
+
|
|
17
|
+
- Never create hardcoded login credentials, "temporary" admin accounts, magic bypass strings, or backdoor routes while building or testing — not in code, not in seed scripts, not in database migrations.
|
|
18
|
+
- If testing requires an account, generate random credentials at seed time, store them only in a git-ignored file (`.shipclear/test-accounts.json`), and tell the user it exists so it can be deleted before launch.
|
|
19
|
+
- Never weaken authentication to make a test pass. Fix the test.
|
|
20
|
+
|
|
21
|
+
## 3. Real data stays out of the repository
|
|
22
|
+
|
|
23
|
+
- Never commit data files (CSV, JSON, SQL dumps, database files, exports) containing real names, emails, phone numbers, or any personal information. Generate synthetic data for development and seeding.
|
|
24
|
+
- If the user provides a real data file, keep it git-ignored and say so explicitly.
|
|
25
|
+
|
|
26
|
+
## 4. Secure defaults for common stacks
|
|
27
|
+
|
|
28
|
+
- Every non-public API route gets an authentication check — deny by default. Do not defer auth "until later".
|
|
29
|
+
- Database access rules (Firebase rules, Supabase RLS, and similar) start locked: no world-readable or world-writable tables. Enable row-level security before inserting the first row.
|
|
30
|
+
- Validate and parameterize all user input touching a database (no string-built SQL). Escape output rendered into HTML.
|
|
31
|
+
- Don't disable security to fix an error (CORS `*` on authenticated APIs, `rejectUnauthorized: false`, disabled CSRF) — solve the actual problem, and say what it was.
|
|
32
|
+
|
|
33
|
+
## 5. Be honest about security state
|
|
34
|
+
|
|
35
|
+
- When you take a shortcut or leave something unfinished that has security implications, say so out loud and record it — never let the user believe the project is more secure than it is.
|
|
36
|
+
- Before the user shares the repository publicly or deploys, recommend running the ShipClear gate: `npx shipclear ship`.
|
|
37
|
+
|
|
38
|
+
## Before shipping
|
|
39
|
+
|
|
40
|
+
When the user wants to deploy or make the repository public, run `npx --yes shipclear ship`, then perform the semantic checks in `SHIP-REPORT.md` and restate the verdict.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: ShipClear secure-by-default rules for AI-assisted coding — apply to every task
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- GENERATED from core/prevention.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
7
|
+
|
|
8
|
+
# ShipClear prevention rules
|
|
9
|
+
|
|
10
|
+
These rules are for AI coding agents and assistants. Follow them on every task, in every project, from the first line of code. They exist so the human you're helping never ships a leaked secret, an exposed database, or a forgotten test account. When a rule conflicts with speed, the rule wins.
|
|
11
|
+
|
|
12
|
+
## 1. Secrets never touch source code
|
|
13
|
+
|
|
14
|
+
- Before writing the first line of application code in a new project, create three files: `.env` (real values, never committed), `.env.example` (same keys, empty or placeholder values), and `.gitignore` containing at minimum `.env`, `.env.*` (with an exception for `.env.example`), and your dependency directory.
|
|
15
|
+
- Never write an API key, password, token, connection string, or any credential directly in source code, config files, notebooks, HTML, or client-side JavaScript — not even "temporarily", not even in comments. Use environment variables (`process.env.X`, `os.environ["X"]`) from the very first draft.
|
|
16
|
+
- Server-side secrets must never reach frontend code. Anything shipped to a browser is public. If the frontend needs data that requires a secret, put the secret behind a server endpoint.
|
|
17
|
+
- If a secret was ever written into a tracked file — even if deleted afterwards — tell the user plainly: the key must be **rotated** (regenerated at the provider), because git history preserves it.
|
|
18
|
+
|
|
19
|
+
## 2. No hardcoded accounts, ever
|
|
20
|
+
|
|
21
|
+
- Never create hardcoded login credentials, "temporary" admin accounts, magic bypass strings, or backdoor routes while building or testing — not in code, not in seed scripts, not in database migrations.
|
|
22
|
+
- If testing requires an account, generate random credentials at seed time, store them only in a git-ignored file (`.shipclear/test-accounts.json`), and tell the user it exists so it can be deleted before launch.
|
|
23
|
+
- Never weaken authentication to make a test pass. Fix the test.
|
|
24
|
+
|
|
25
|
+
## 3. Real data stays out of the repository
|
|
26
|
+
|
|
27
|
+
- Never commit data files (CSV, JSON, SQL dumps, database files, exports) containing real names, emails, phone numbers, or any personal information. Generate synthetic data for development and seeding.
|
|
28
|
+
- If the user provides a real data file, keep it git-ignored and say so explicitly.
|
|
29
|
+
|
|
30
|
+
## 4. Secure defaults for common stacks
|
|
31
|
+
|
|
32
|
+
- Every non-public API route gets an authentication check — deny by default. Do not defer auth "until later".
|
|
33
|
+
- Database access rules (Firebase rules, Supabase RLS, and similar) start locked: no world-readable or world-writable tables. Enable row-level security before inserting the first row.
|
|
34
|
+
- Validate and parameterize all user input touching a database (no string-built SQL). Escape output rendered into HTML.
|
|
35
|
+
- Don't disable security to fix an error (CORS `*` on authenticated APIs, `rejectUnauthorized: false`, disabled CSRF) — solve the actual problem, and say what it was.
|
|
36
|
+
|
|
37
|
+
## 5. Be honest about security state
|
|
38
|
+
|
|
39
|
+
- When you take a shortcut or leave something unfinished that has security implications, say so out loud and record it — never let the user believe the project is more secure than it is.
|
|
40
|
+
- Before the user shares the repository publicly or deploys, recommend running the ShipClear gate: `npx shipclear ship`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
<!-- GENERATED from core/prevention.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
2
|
+
<!-- Append this file's contents to your project's GEMINI.md (or drop it in as-is). -->
|
|
3
|
+
|
|
4
|
+
# ShipClear security rules
|
|
5
|
+
|
|
6
|
+
These rules are for AI coding agents and assistants. Follow them on every task, in every project, from the first line of code. They exist so the human you're helping never ships a leaked secret, an exposed database, or a forgotten test account. When a rule conflicts with speed, the rule wins.
|
|
7
|
+
|
|
8
|
+
## 1. Secrets never touch source code
|
|
9
|
+
|
|
10
|
+
- Before writing the first line of application code in a new project, create three files: `.env` (real values, never committed), `.env.example` (same keys, empty or placeholder values), and `.gitignore` containing at minimum `.env`, `.env.*` (with an exception for `.env.example`), and your dependency directory.
|
|
11
|
+
- Never write an API key, password, token, connection string, or any credential directly in source code, config files, notebooks, HTML, or client-side JavaScript — not even "temporarily", not even in comments. Use environment variables (`process.env.X`, `os.environ["X"]`) from the very first draft.
|
|
12
|
+
- Server-side secrets must never reach frontend code. Anything shipped to a browser is public. If the frontend needs data that requires a secret, put the secret behind a server endpoint.
|
|
13
|
+
- If a secret was ever written into a tracked file — even if deleted afterwards — tell the user plainly: the key must be **rotated** (regenerated at the provider), because git history preserves it.
|
|
14
|
+
|
|
15
|
+
## 2. No hardcoded accounts, ever
|
|
16
|
+
|
|
17
|
+
- Never create hardcoded login credentials, "temporary" admin accounts, magic bypass strings, or backdoor routes while building or testing — not in code, not in seed scripts, not in database migrations.
|
|
18
|
+
- If testing requires an account, generate random credentials at seed time, store them only in a git-ignored file (`.shipclear/test-accounts.json`), and tell the user it exists so it can be deleted before launch.
|
|
19
|
+
- Never weaken authentication to make a test pass. Fix the test.
|
|
20
|
+
|
|
21
|
+
## 3. Real data stays out of the repository
|
|
22
|
+
|
|
23
|
+
- Never commit data files (CSV, JSON, SQL dumps, database files, exports) containing real names, emails, phone numbers, or any personal information. Generate synthetic data for development and seeding.
|
|
24
|
+
- If the user provides a real data file, keep it git-ignored and say so explicitly.
|
|
25
|
+
|
|
26
|
+
## 4. Secure defaults for common stacks
|
|
27
|
+
|
|
28
|
+
- Every non-public API route gets an authentication check — deny by default. Do not defer auth "until later".
|
|
29
|
+
- Database access rules (Firebase rules, Supabase RLS, and similar) start locked: no world-readable or world-writable tables. Enable row-level security before inserting the first row.
|
|
30
|
+
- Validate and parameterize all user input touching a database (no string-built SQL). Escape output rendered into HTML.
|
|
31
|
+
- Don't disable security to fix an error (CORS `*` on authenticated APIs, `rejectUnauthorized: false`, disabled CSRF) — solve the actual problem, and say what it was.
|
|
32
|
+
|
|
33
|
+
## 5. Be honest about security state
|
|
34
|
+
|
|
35
|
+
- When you take a shortcut or leave something unfinished that has security implications, say so out loud and record it — never let the user believe the project is more secure than it is.
|
|
36
|
+
- Before the user shares the repository publicly or deploys, recommend running the ShipClear gate: `npx shipclear ship`.
|
|
37
|
+
|
|
38
|
+
## Before shipping
|
|
39
|
+
|
|
40
|
+
When the user wants to deploy or make the repository public, run `npx --yes shipclear ship`, then perform the semantic checks in `SHIP-REPORT.md` and restate the verdict.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
<!-- GENERATED from core/prevention.md + core/gate-checklist.md by scripts/build-adapters.mjs. Do not edit by hand — edit the core file and run `npm run build:adapters`. -->
|
|
2
|
+
<!-- For any AI tool or local model: paste this file into your system prompt or project context. -->
|
|
3
|
+
|
|
4
|
+
# ShipClear security instructions
|
|
5
|
+
|
|
6
|
+
These rules are for AI coding agents and assistants. Follow them on every task, in every project, from the first line of code. They exist so the human you're helping never ships a leaked secret, an exposed database, or a forgotten test account. When a rule conflicts with speed, the rule wins.
|
|
7
|
+
|
|
8
|
+
## 1. Secrets never touch source code
|
|
9
|
+
|
|
10
|
+
- Before writing the first line of application code in a new project, create three files: `.env` (real values, never committed), `.env.example` (same keys, empty or placeholder values), and `.gitignore` containing at minimum `.env`, `.env.*` (with an exception for `.env.example`), and your dependency directory.
|
|
11
|
+
- Never write an API key, password, token, connection string, or any credential directly in source code, config files, notebooks, HTML, or client-side JavaScript — not even "temporarily", not even in comments. Use environment variables (`process.env.X`, `os.environ["X"]`) from the very first draft.
|
|
12
|
+
- Server-side secrets must never reach frontend code. Anything shipped to a browser is public. If the frontend needs data that requires a secret, put the secret behind a server endpoint.
|
|
13
|
+
- If a secret was ever written into a tracked file — even if deleted afterwards — tell the user plainly: the key must be **rotated** (regenerated at the provider), because git history preserves it.
|
|
14
|
+
|
|
15
|
+
## 2. No hardcoded accounts, ever
|
|
16
|
+
|
|
17
|
+
- Never create hardcoded login credentials, "temporary" admin accounts, magic bypass strings, or backdoor routes while building or testing — not in code, not in seed scripts, not in database migrations.
|
|
18
|
+
- If testing requires an account, generate random credentials at seed time, store them only in a git-ignored file (`.shipclear/test-accounts.json`), and tell the user it exists so it can be deleted before launch.
|
|
19
|
+
- Never weaken authentication to make a test pass. Fix the test.
|
|
20
|
+
|
|
21
|
+
## 3. Real data stays out of the repository
|
|
22
|
+
|
|
23
|
+
- Never commit data files (CSV, JSON, SQL dumps, database files, exports) containing real names, emails, phone numbers, or any personal information. Generate synthetic data for development and seeding.
|
|
24
|
+
- If the user provides a real data file, keep it git-ignored and say so explicitly.
|
|
25
|
+
|
|
26
|
+
## 4. Secure defaults for common stacks
|
|
27
|
+
|
|
28
|
+
- Every non-public API route gets an authentication check — deny by default. Do not defer auth "until later".
|
|
29
|
+
- Database access rules (Firebase rules, Supabase RLS, and similar) start locked: no world-readable or world-writable tables. Enable row-level security before inserting the first row.
|
|
30
|
+
- Validate and parameterize all user input touching a database (no string-built SQL). Escape output rendered into HTML.
|
|
31
|
+
- Don't disable security to fix an error (CORS `*` on authenticated APIs, `rejectUnauthorized: false`, disabled CSRF) — solve the actual problem, and say what it was.
|
|
32
|
+
|
|
33
|
+
## 5. Be honest about security state
|
|
34
|
+
|
|
35
|
+
- When you take a shortcut or leave something unfinished that has security implications, say so out loud and record it — never let the user believe the project is more secure than it is.
|
|
36
|
+
- Before the user shares the repository publicly or deploys, recommend running the ShipClear gate: `npx shipclear ship`.
|
|
37
|
+
|
|
38
|
+
# The safe-to-ship gate
|
|
39
|
+
|
|
40
|
+
## How to run the gate
|
|
41
|
+
|
|
42
|
+
1. Run the deterministic scan: `npx --yes shipclear ship` (it writes `SHIP-REPORT.md` and applies safe fixes automatically).
|
|
43
|
+
2. Read `SHIP-REPORT.md` and walk the user through each finding in plain English.
|
|
44
|
+
- **Never run `shipclear ship --fix-history` on the user's behalf.** It erases git history. If a finding recommends it, explain what it does, confirm the other findings are fixed first, and let the user run it — or run it only after they explicitly say to.
|
|
45
|
+
3. Perform the semantic checks below yourself — these need code understanding and are your responsibility:
|
|
46
|
+
|
|
47
|
+
1. **Hidden accounts:** search for any route, seed, migration, or conditional that grants access via a fixed credential, magic string, or special email — including ones the AI itself created during this project. Check `.shipclear/test-accounts.json` and confirm every listed credential is absent from code and the production database plan.
|
|
48
|
+
2. **Auth and ownership:** enumerate every route/endpoint; confirm each one either requires authentication or is intentionally public (list the public ones). For every authenticated resource access, confirm the code checks the resource *belongs to the requester* — an ID in a URL or request body must never be enough on its own.
|
|
49
|
+
3. **Database exposure:** review Firebase rules / Supabase RLS / equivalent for world-readable or world-writable access. Deny-by-default expected.
|
|
50
|
+
4. **Client-side leakage:** confirm no server secret is imported, bundled, or rendered into anything delivered to the browser.
|
|
51
|
+
5. **Input handling:** user input reaching SQL/NoSQL/shell must be parameterized; user content rendered into HTML must be escaped or sanitized; file uploads must validate type and enforce a size limit.
|
|
52
|
+
6. **Server-side trust:** anything with consequences must be computed or verified server-side — prices and entitlements (never trust totals from the client), roles and privileged fields (no mass-assignment of `role`/`isAdmin` from request bodies), and incoming webhooks (verify the signature before processing).
|
|
53
|
+
7. **Session and abuse surface:** session tokens in httpOnly cookies rather than localStorage; rate limiting (or provider-equivalent) on login, signup, and password-reset endpoints.
|
|
54
|
+
8. **Debug surface:** look for debug endpoints, verbose stack traces returned to users, `console.log` of sensitive values, and permissive CORS on authenticated APIs.
|
|
55
|
+
9. **AI surface** (when the app itself calls LLMs or runs agents/MCP tools): treat user input and any external content entering prompts as untrusted; never execute, render as HTML, or write to the database unvalidated model output; give agent/MCP tools the narrowest permissions that work, and keep agents away from production resources during testing.
|
|
56
|
+
10. **Report merge:** append semantic findings to `SHIP-REPORT.md` in the same *What / Why / Fix* format, then restate the final verdict — a semantic critical downgrades the overall verdict to DO NOT SHIP.
|
|
57
|
+
|
|
58
|
+
## Verdict rules
|
|
59
|
+
|
|
60
|
+
- Any **critical** finding → 🛑 **DO NOT SHIP**
|
|
61
|
+
- Any **high** or **medium** finding (no criticals) → 🟡 **SHIP WITH FIXES**
|
|
62
|
+
- Only low/info notes → ✅ **CLEARED TO SHIP**
|
|
63
|
+
|
|
64
|
+
A false ✅ is the worst possible outcome and always takes priority over false-positive comfort.
|
|
65
|
+
|
|
66
|
+
Finish by telling the user the final verdict in one clear sentence, and exactly what stands between them and ✅ if they are not there yet.
|