keyspill 0.1.0 → 0.1.1

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.
Files changed (3) hide show
  1. package/README.md +182 -51
  2. package/package.json +2 -2
  3. package/src/rules.js +12 -1
package/README.md CHANGED
@@ -1,17 +1,63 @@
1
- # keyspill
1
+ <div align="center">
2
2
 
3
- [![npm](https://img.shields.io/npm/v/keyspill)](https://www.npmjs.com/package/keyspill) [![test](https://github.com/kazbekaskarov/keyspill/actions/workflows/test.yml/badge.svg)](https://github.com/kazbekaskarov/keyspill/actions/workflows/test.yml) ![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
3
+ # keyspill
4
4
 
5
5
  **Find the secrets your AI coding agents have already seen.**
6
6
 
7
- ![keyspill output in a terminal](docs/terminal.png)
7
+ [![npm version](https://img.shields.io/npm/v/keyspill?color=FFCF33&labelColor=121417)](https://www.npmjs.com/package/keyspill)
8
+ [![tests](https://github.com/kazbekaskarov/keyspill/actions/workflows/test.yml/badge.svg)](https://github.com/kazbekaskarov/keyspill/actions/workflows/test.yml)
9
+ [![dependencies](https://img.shields.io/badge/dependencies-0-FFCF33?labelColor=121417)](package.json)
10
+ [![license](https://img.shields.io/npm/l/keyspill?color=FFCF33&labelColor=121417)](LICENSE)
11
+
12
+ [Website](https://kazbekaskarov.github.io/keyspill/) · [npm](https://www.npmjs.com/package/keyspill) · [Changelog](CHANGELOG.md) · [Report a false positive](https://github.com/kazbekaskarov/keyspill/issues/new?template=false-positive.yml)
13
+
14
+ <img src="docs/terminal.png" alt="keyspill output in a terminal" width="760">
8
15
 
9
- Every time Claude Code reads your `.env`, Codex runs `cat ~/.aws/credentials`, or you paste a key into Cursor to "just debug this one thing", that secret goes to a model provider and stays in a session log on your disk. keyspill reads those logs and tells you exactly which keys to rotate.
16
+ </div>
17
+
18
+ Coding agents read files to do their job, and your `.env` is a file. Every time Claude Code reads it, Codex runs `cat ~/.aws/credentials`, or you paste a key into Cursor to "just debug this one thing", that secret is sent to a model provider and stays in plain text in a session log on your disk.
19
+
20
+ keyspill reads those logs locally and tells you which keys to rotate, where they came from, and how they got there.
10
21
 
11
22
  ```bash
12
23
  npx keyspill
13
24
  ```
14
25
 
26
+ No install, no config, no account. Requires Node.js 18 or later.
27
+
28
+ ## Contents
29
+
30
+ - [Features](#features)
31
+ - [Usage](#usage)
32
+ - [Supported agents](#supported-agents)
33
+ - [What it detects](#what-it-detects)
34
+ - [Prevent future leaks](#prevent-future-leaks)
35
+ - [Privacy and security](#privacy-and-security)
36
+ - [Scripting and CI](#scripting-and-ci)
37
+ - [FAQ](#faq)
38
+ - [Contributing](#contributing)
39
+ - [License](#license)
40
+
41
+ ## Features
42
+
43
+ - **Seven agents in one command.** Claude Code, Codex, Cursor, GitHub Copilot CLI, Gemini CLI, opencode, and Cline / Roo Code / Kilo Code, on macOS, Linux and Windows.
44
+ - **Tells you how each secret leaked.** The agent read it from a file, you pasted it into chat, or the agent wrote it into a command.
45
+ - **Actionable output.** Severity, agent, project, last-seen date, and a direct link to rotate each key.
46
+ - **Low noise by design.** Documentation example keys, placeholders, public keys and code references are filtered out.
47
+ - **Private.** Runs entirely offline, never shows a full secret, never modifies your files.
48
+ - **Small and auditable.** Zero dependencies and about 850 lines of plain JavaScript.
49
+
50
+ ## Usage
51
+
52
+ ```bash
53
+ npx keyspill # scan and print a report
54
+ npx keyspill --card # also write an HTML report with a shareable card, and open it
55
+ npx keyspill protect # preview rules that stop agents reading secrets
56
+ npx keyspill protect --apply # write those rules
57
+ ```
58
+
59
+ ### Example output
60
+
15
61
  ```
16
62
  keyspill · what your AI agents have already seen
17
63
  Scanned 1,284 session files (412 MB) from Claude Code, Codex, Cursor in 3.1s · 100% local, nothing uploaded
@@ -23,88 +69,173 @@ npx keyspill
23
69
  1× · Claude Code · ~/work/shop · last 2026-11-02
24
70
  agent read it 1×
25
71
  → rotate: https://dashboard.stripe.com/apikeys
26
- ● Database URL with password postgres://app:••••••Ri@db.prod.acme-internal.net:5432
72
+ ● Database URL with password postgres://•••:••••••@••••.acme-internal.net
27
73
  1× · Claude Code · ~/work/shop · last 2026-11-02
28
- ● Supabase service_role key ••••••••4cmU
29
- ...
74
+ agent read it 1×
75
+
30
76
  HIGH
31
77
  ● GitHub token ghp_••••••••VKby
32
78
  1× · Codex · ~/oss/nanotab · last 2026-11-05
79
+ agent read it 1×
80
+ → rotate: https://github.com/settings/tokens
33
81
  ● OpenAI API key sk-proj-••••••••u9Bn
82
+ 1× · Claude Code · ~/work/shop · last 2026-11-02
34
83
  you pasted it 1×
84
+ → rotate: https://platform.openai.com/api-keys
85
+ ```
86
+
87
+ ### Options
88
+
89
+ | Option | Description |
90
+ |---|---|
91
+ | `--card` | Write `keyspill-report.html` with the full masked report and a share card, then open it |
92
+ | `--html <file>` | Write the HTML report to a specific path |
93
+ | `--json` | Print machine-readable JSON (masked values only) |
94
+ | `--path <dir>` | Also scan another file or folder. Repeatable |
95
+ | `--all` | List every finding instead of the top ones per severity |
96
+ | `--no-open` | Don't open the HTML report automatically |
97
+ | `--no-color` | Plain output. `NO_COLOR` is also respected |
98
+ | `-v`, `--version` | Print the version |
99
+ | `-h`, `--help` | Print help |
100
+
101
+ ### Share card
102
+
103
+ `npx keyspill --card` produces a local HTML report. Click **Download share card** to get a PNG that shows the number of findings and key types only, never values.
104
+
105
+ <img src="docs/card.png" alt="keyspill share card: 11 secrets my AI agents have already seen" width="560">
106
+
107
+ ## Supported agents
108
+
109
+ | Agent | Where keyspill looks |
110
+ |---|---|
111
+ | Claude Code | `~/.claude/projects/**/*.jsonl` (respects `CLAUDE_CONFIG_DIR`) |
112
+ | Codex | `~/.codex/sessions/**`, `~/.codex/history.jsonl` (respects `CODEX_HOME`) |
113
+ | Cursor | `state.vscdb` in Cursor's global and workspace storage, `~/.cursor/chats` |
114
+ | GitHub Copilot CLI | `~/.copilot/session-state`, `~/.copilot/history-session-state` |
115
+ | Gemini CLI | `~/.gemini/tmp/**` |
116
+ | opencode | `~/.local/share/opencode/storage` (respects `XDG_DATA_HOME`) |
117
+ | Cline / Roo Code / Kilo Code | `globalStorage/<extension>/tasks/*` in VS Code, VS Code Insiders, Cursor, Windsurf and VSCodium |
118
+
119
+ Editor storage resolves to `~/Library/Application Support` on macOS, `%APPDATA%` on Windows and `~/.config` on Linux.
120
+
121
+ Missing your agent? [Open an issue](https://github.com/kazbekaskarov/keyspill/issues/new?template=new-agent.yml) with where it keeps its history.
122
+
123
+ ## What it detects
124
+
125
+ 30 rules, grouped by severity.
126
+
127
+ | Severity | Secrets |
128
+ |---|---|
129
+ | **Critical** | AWS access keys, AWS secret keys, private keys (PEM), Stripe live keys, database URLs with passwords (Postgres, MySQL, MongoDB, Redis, AMQP, MSSQL), Supabase `service_role` keys |
130
+ | **High** | OpenAI, Anthropic, GitHub, GitLab, Google API, Slack tokens and webhooks, Telegram, Discord, SendGrid, Twilio, npm, PyPI, Hugging Face, Shopify, DigitalOcean, Stripe webhook secrets, Groq, Replicate, Supabase access tokens, Mailgun, AWS temporary keys |
131
+ | **Medium** | Unexpired JWTs, Stripe test keys, local database passwords, `*_SECRET` / `*_PASSWORD` / `*_TOKEN` / `*_API_KEY` values in env and config files |
132
+
133
+ ### What it ignores on purpose
134
+
135
+ A false alarm in a security tool costs more trust than a miss, so keyspill skips:
136
+
137
+ - documentation example keys such as `AKIAIOSFODNN7EXAMPLE`
138
+ - placeholders: `your_api_key`, `xxxx`, `<token>`, `${SECRET}`, `USER:PASSWORD@HOST`
139
+ - Supabase `anon` keys, which are public by design
140
+ - expired JWTs
141
+ - default local credentials such as `postgres:postgres@localhost`
142
+ - code references such as `API_KEY = process.env.API_KEY`
143
+ - `NEXT_PUBLIC_*`, `VITE_*` and other public-by-convention variables
144
+
145
+ The same credential seen many times is reported once, with a count.
146
+
147
+ ## Prevent future leaks
148
+
149
+ ```bash
150
+ npx keyspill protect # show what would change
151
+ npx keyspill protect --apply # write it
35
152
  ```
36
153
 
37
- ## Why
154
+ This adds `permissions.deny` rules to `~/.claude/settings.json` so Claude Code can't read `.env*`, `*.pem`, `*.key`, `secrets/`, `~/.aws`, `~/.ssh` or `~/.config/gcloud`, and adds a `.cursorignore` to the current project. Your existing settings are merged, not replaced, and backed up first. Running it twice changes nothing.
38
155
 
39
- Coding agents read files to do their job. Your `.env` is a file. Once a key is in a session it was sent to the model provider, sits in plain text in `~/.claude`, `~/.codex` and friends, and often gets synced to backups. Most people have never looked.
156
+ > [!NOTE]
157
+ > Deny rules cover file reads, not shell commands like `cat .env`. Keep reading the commands you approve.
40
158
 
41
- ## What it does
159
+ ## Privacy and security
42
160
 
43
- - **Scans 7 agents**: Claude Code, Codex, Cursor, Gemini CLI, opencode, Copilot CLI, Cline / Roo Code / Kilo Code (VS Code, Cursor, Windsurf).
44
- - **30 high-signal rules**: AWS, Stripe, OpenAI, Anthropic, GitHub, GitLab, Google, Slack, Telegram, Discord, SendGrid, Twilio, npm, PyPI, Hugging Face, Supabase, DigitalOcean, database URLs, private keys, and `SECRET=`/`PASSWORD=` lines in env files.
45
- - **Tells you how it got there**: the agent read it from a file, you pasted it, or the agent wrote it into a command.
46
- - **Tells you where**: which agent, which project, when it was last seen, and a direct link to rotate it.
47
- - **Low noise**: ignores documentation example keys, placeholders, Supabase anon keys (public by design), expired JWTs, local `postgres:postgres@localhost`, and code like `API_KEY = process.env.API_KEY`. Tested against 216 MB of real Python and Node source with zero false positives.
161
+ - **Offline.** keyspill makes no network requests. The HTML report loads no fonts, scripts or analytics.
162
+ - **Never shows a full secret.** Terminal, JSON and HTML output show a masked value (`sk_live_••••••••fnwh`) and a short SHA-256 fingerprint. The test suite checks that no 10-character fragment of a secret reaches any output.
163
+ - **Read-only.** Session files are never modified, copied or uploaded. keyspill writes only what you ask for: the HTML report with `--card` / `--html`, and the two files listed above with `protect --apply`.
164
+ - **Auditable.** Zero runtime dependencies. Read [`src/`](src) in about fifteen minutes.
48
165
 
49
- ## Privacy
166
+ Found a security issue? Please report it privately, see [SECURITY.md](SECURITY.md).
50
167
 
51
- - Runs entirely on your machine. No network requests. Zero dependencies, under 900 lines you can read in fifteen minutes.
52
- - Never prints, stores or uploads a full secret. Output shows a masked value (`sk_live_••••••••fnwh`) and a short SHA-256 fingerprint.
53
- - Never modifies your session files.
168
+ ## Scripting and CI
54
169
 
55
- ## Share card
170
+ keyspill exits with code `1` when it finds a critical or high secret, `0` otherwise, and `2` on usage errors.
56
171
 
57
172
  ```bash
58
- npx keyspill --card
173
+ npx keyspill --json > keyspill.json
59
174
  ```
60
175
 
61
- Writes `keyspill-report.html` and opens it: the full masked report plus a share card with counts and key types only. Click **Download share card** to get a PNG.
176
+ ```json
177
+ {
178
+ "version": 1,
179
+ "summary": { "total": 9, "critical": 3, "high": 5, "medium": 1 },
180
+ "findings": [
181
+ {
182
+ "rule": "stripe-live",
183
+ "label": "Stripe live secret key",
184
+ "severity": "critical",
185
+ "masked": "sk_live_••••••••fnwh",
186
+ "fingerprint": "3f9a1c0b7e21",
187
+ "count": 1,
188
+ "tools": ["Claude Code"],
189
+ "origins": { "tool": 1, "user": 0, "assistant": 0, "unknown": 0 },
190
+ "lastSeen": "2026-11-02",
191
+ "rotate": "https://dashboard.stripe.com/apikeys"
192
+ }
193
+ ]
194
+ }
195
+ ```
62
196
 
63
- ## Stop it happening again
197
+ Use `--path` to scan exported transcripts or logs anywhere on disk:
64
198
 
65
199
  ```bash
66
- npx keyspill protect # show what it would change
67
- npx keyspill protect --apply # write it
200
+ npx keyspill --path ./exported-sessions --json
68
201
  ```
69
202
 
70
- Adds `permissions.deny` rules to `~/.claude/settings.json` so Claude Code can't read `.env*`, `*.pem`, `*.key`, `secrets/`, `~/.aws` or `~/.ssh`, and adds a `.cursorignore` to the current project. Your old settings are backed up first. Deny rules cover file reads, not shell commands such as `cat .env`, so keep reading what you approve.
203
+ ## FAQ
71
204
 
72
- ## Options
205
+ <details>
206
+ <summary><b>It found a key. What should I do?</b></summary>
73
207
 
74
- | Flag | |
75
- |---|---|
76
- | `--card` | write and open the HTML report with the share card |
77
- | `--html <file>` | write the HTML report to a specific file |
78
- | `--json` | machine-readable output (masked values only) |
79
- | `--path <dir>` | also scan another folder or file, repeatable |
80
- | `--all` | list every finding |
81
- | `--no-open`, `--no-color` | |
208
+ Rotate it with the provider. Deleting the session log does not undo what the provider already received. Each critical and high finding includes a link to the right settings page.
209
+ </details>
82
210
 
83
- Exit code is `1` when a critical or high secret is found, so it works in scripts.
211
+ <details>
212
+ <summary><b>Does keyspill send my data anywhere?</b></summary>
84
213
 
85
- ## Where it looks
214
+ No. It reads local files and prints to your terminal. There is no telemetry and no network code.
215
+ </details>
86
216
 
87
- | Agent | Location |
88
- |---|---|
89
- | Claude Code | `~/.claude/projects/**/*.jsonl` (respects `CLAUDE_CONFIG_DIR`) |
90
- | Codex | `~/.codex/sessions/**`, `~/.codex/history.jsonl` (respects `CODEX_HOME`) |
91
- | Cursor | `state.vscdb` in Cursor's global and workspace storage, `~/.cursor/chats` |
92
- | Gemini CLI | `~/.gemini/tmp/**` |
93
- | opencode | `~/.local/share/opencode/storage` |
94
- | Copilot CLI | `~/.copilot/session-state` |
95
- | Cline / Roo / Kilo | `globalStorage/<extension>/tasks/*` in VS Code, Cursor, Windsurf |
217
+ <details>
218
+ <summary><b>Why wasn't my secret detected?</b></summary>
219
+
220
+ keyspill only reports formats it can identify with high confidence. If a real secret was missed, [open an issue](https://github.com/kazbekaskarov/keyspill/issues/new?template=false-positive.yml) describing its format. Never paste the secret itself.
221
+ </details>
96
222
 
97
- Missing your agent? Open an issue with where it keeps its history, or a PR adding a source in `src/sources.js`.
223
+ <details>
224
+ <summary><b>How long does a scan take?</b></summary>
225
+
226
+ Usually seconds. Large histories (around 800 MB) take 20–30 seconds. Progress is shown while it runs.
227
+ </details>
98
228
 
99
229
  ## Contributing
100
230
 
231
+ Contributions are welcome, especially new agents, new rules and false-positive fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and guidelines.
232
+
101
233
  ```bash
102
- git clone https://github.com/kazbekaskarov/keyspill && cd keyspill
234
+ git clone https://github.com/kazbekaskarov/keyspill.git
235
+ cd keyspill
103
236
  npm test
104
237
  ```
105
238
 
106
- Rules live in `src/rules.js`. A new rule needs a test in `test/`. Test fixtures build fake keys at runtime, so please don't commit token-shaped strings.
107
-
108
239
  ## License
109
240
 
110
- MIT
241
+ [MIT](LICENSE) © Kazbek Askarov
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "keyspill",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Find the secrets your AI coding agents have already seen. Scans Claude Code, Codex, Cursor, Gemini CLI, opencode and more. 100% local, zero dependencies.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -20,7 +20,7 @@
20
20
  "node": ">=18"
21
21
  },
22
22
  "author": "Kazbek Askarov",
23
- "homepage": "https://github.com/kazbekaskarov/keyspill#readme",
23
+ "homepage": "https://kazbekaskarov.github.io/keyspill/",
24
24
  "repository": {
25
25
  "type": "git",
26
26
  "url": "git+https://github.com/kazbekaskarov/keyspill.git"
package/src/rules.js CHANGED
@@ -148,10 +148,21 @@ function checkDbUrl(value) {
148
148
  return true;
149
149
  }
150
150
 
151
+ // Reports get screenshotted and shared, so only the provider's domain stays readable:
152
+ // mongodb+srv://kaz_db:••••••@••••.mongodb.net postgres://ap•••:••••••@••••.acme-internal.net
151
153
  function displayDbUrl(value) {
152
154
  const m = parseDbUrl(value);
153
155
  if (!m) return maskTail(value);
154
- return `${m.scheme}://${m.user}:${'•'.repeat(6)}${m.pass.length >= 16 ? m.pass.slice(-2) : ''}@${m.host}`;
156
+ const user = m.user.length > 3 ? m.user.slice(0, 2) + '•••' : '•••';
157
+ return `${m.scheme}://${user}:${'•'.repeat(6)}@${maskHost(m.host)}`;
158
+ }
159
+
160
+ function maskHost(host) {
161
+ const name = host.replace(/:\d+$/, '');
162
+ if (LOCAL_HOSTS.test(name)) return name;
163
+ if (/^[\d.]+$/.test(name) || name.startsWith('[')) return '••••'; // IP address
164
+ const labels = name.split('.');
165
+ return labels.length >= 2 ? '••••.' + labels.slice(-2).join('.') : '••••';
155
166
  }
156
167
 
157
168
  function checkJwt(value) {