lockpicks 0.2.0 → 0.4.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/README.md +58 -25
- package/dist/lockpick.mjs +7552 -2873
- package/package.json +14 -11
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# lockpicks
|
|
2
2
|
|
|
3
|
-
Read your Lockpick results from the terminal, and give coding agents the same access over MCP:
|
|
3
|
+
Read your Lockpick results from the terminal, and give coding agents the same access over MCP: sites, scans, findings, repair briefs and recheck comparisons. If you allow it, the CLI and agents can also run a free quick check, add a site, start a Pulse check, check a DNS finding again and prepare a Deep scan that you approve in Lockpick. Pentests only start in the Lockpick web app, and the CLI never cancels or deletes anything.
|
|
4
4
|
|
|
5
5
|
## Sign in
|
|
6
6
|
|
|
@@ -8,7 +8,7 @@ Read your Lockpick results from the terminal, and give coding agents the same ac
|
|
|
8
8
|
npx lockpicks login --host https://<your-lockpick>
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
The browser opens a device page. Confirm the code, pick a workspace and approve. To let the key start Pulse checks, tick **
|
|
11
|
+
The browser opens a device page. Confirm the code, pick a workspace and approve. To let the key start Pulse checks, tick **Start Pulse checks** under **Extra permissions**; that box is your statement that you own the workspace's sites or may test them, and each Pulse started with the key is recorded under your name. Without it the key only reads. **Add sites and switch your free site** lets the key add sites (`lockpick sites add`). **Start Deep scans after you prove you own the site and approve each one** lets the key prepare Deep scans (`lockpick deep`); each still needs a verified ownership proof and your approval of that exact scan in Lockpick. `lockpick login --pulse --sites --deep` marks what the terminal asks for, but the browser never ticks anything for you and the key gets exactly what you tick. `lockpick whoami` shows what the key can do. The terminal receives a key bound to that workspace, stored in your OS keychain (or `~/.config/lockpick/config.json`, mode 0600, when no keychain is available). Each use extends the key; an idle key expires after the workspace's lifetime (30 days by default). Revoke it with `lockpick logout` or in the web app under **Workspace settings → CLI & agent access**.
|
|
12
12
|
|
|
13
13
|
After an `npx` login, the CLI offers to install itself so you can type `lockpick` (or `lockpicks`) instead of `npx lockpicks`. To do it yourself:
|
|
14
14
|
|
|
@@ -18,38 +18,68 @@ npm install -g lockpicks
|
|
|
18
18
|
|
|
19
19
|
With it installed, `lockpick mcp config` points agents at `lockpick mcp`; without it, at `npx -y lockpicks mcp`.
|
|
20
20
|
|
|
21
|
+
Use HTTPS for a remote Lockpick host; a host without a scheme (`lockpick.app`) means HTTPS, and a local one (`studio-mac:3000`) means HTTP. HTTP is accepted for local network and Tailscale development hosts. The CLI never follows redirects during API calls, so a saved key stays on its selected host: when a host only moves to its canonical address (`lockpick.app` to `www.lockpick.app`), `login`, which sends no key, signs in there and saves that address, and every other command names the address to use. `--host` takes precedence over `LOCKPICK_HOST`, which takes precedence over the last login. Each host has its own saved profile; `lockpick logout --host <url>` revokes and removes only that host's key. When the OS keychain is unavailable, the CLI writes the config through a private temporary file and replaces the old file only after the new one is complete. If the config is damaged, repair it before logging in again; the CLI will not silently discard saved profiles.
|
|
22
|
+
|
|
21
23
|
## Commands
|
|
22
24
|
|
|
23
|
-
| Command | What it shows
|
|
24
|
-
| -------------------------------------- |
|
|
25
|
-
| `lockpick whoami` | The user, workspace and key this terminal uses
|
|
26
|
-
| `lockpick
|
|
27
|
-
| `lockpick
|
|
28
|
-
| `lockpick
|
|
29
|
-
| `lockpick
|
|
30
|
-
| `lockpick
|
|
31
|
-
| `lockpick
|
|
32
|
-
| `lockpick
|
|
33
|
-
| `lockpick
|
|
34
|
-
| `lockpick
|
|
35
|
-
| `lockpick
|
|
36
|
-
| `lockpick
|
|
37
|
-
| `lockpick
|
|
38
|
-
| `lockpick
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
25
|
+
| Command | What it shows |
|
|
26
|
+
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
27
|
+
| `lockpick whoami` | The user, workspace and key this terminal uses |
|
|
28
|
+
| `lockpick doctor` | Checks Node.js, the selected host, connection, key, workspace and agent API without starting a scan |
|
|
29
|
+
| `lockpick projects` | Projects with their latest Pulse and pentest |
|
|
30
|
+
| `lockpick status [project]` | One project's report, or an overview of all of them |
|
|
31
|
+
| `lockpick runs` | Pulse assessments and pentests, newest first |
|
|
32
|
+
| `lockpick run <runId>` | One run: status, open findings, coverage and limits |
|
|
33
|
+
| `lockpick watch <runId>` | Follows a run until it finishes |
|
|
34
|
+
| `lockpick check <url>` | A free quick check of a website's homepage and public DNS; needs no site (key allowed to start Pulses) |
|
|
35
|
+
| `lockpick sites` | Sites with their latest Pulse and pentest |
|
|
36
|
+
| `lockpick sites add <url>` | Adds a site you own or may test (key allowed to add sites); adding does not scan it |
|
|
37
|
+
| `lockpick sites switch <site> --yes` | Removes the site holding this month's free Pulse so another site can use it (key allowed to add sites and start Pulses); `--check <id>` also starts a Pulse on that quick check's site |
|
|
38
|
+
| `lockpick pulse <project>` | Starts a Pulse (a recheck of the latest one when possible) and waits for the result |
|
|
39
|
+
| `lockpick recheck <site>` | A full recheck: a new Pulse that uses one free Pulse or 1 credit, then waits for it |
|
|
40
|
+
| `lockpick recheck <runId> --dns <id>` | Free: reads the public DNS records behind one DNS finding again; never contacts the site and never changes the grade |
|
|
41
|
+
| `lockpick deps <site>` | Sends this folder's package names and exact versions (never code) to a site and lists the advisories that affect them (key allowed to add sites); `--dry-run` shows what would be sent, `--forget` removes the list |
|
|
42
|
+
| `lockpick verify <site>` | Verifies you own a site once: the site's value and where to publish it (`--method dns`, `file` or `meta`); `--wait` looks for it for about five minutes |
|
|
43
|
+
| `lockpick deep verify <site>` | The same proof, under `deep` |
|
|
44
|
+
| `lockpick deep check <site> <id>` | Looks once for the published proof; each check uses one of its attempts |
|
|
45
|
+
| `lockpick deep prepare <site> <id>` | Prepares a Deep scan with a verified proof and opens its approval page; nothing starts until you approve |
|
|
46
|
+
| `lockpick deep start <operationId>` | Starts the Deep scan you approved (one free Deep scan or 10 credits) and waits for it |
|
|
47
|
+
| `lockpick findings <runId>` | Findings that need attention (`--all` for informational ones) |
|
|
48
|
+
| `lockpick finding <runId> <findingId>` | One finding with its evidence |
|
|
49
|
+
| `lockpick brief <runId>` | One brief that fixes everything needing attention (`--finding <id>` for one finding, `--agent <name>` to tailor it, `--out brief.md` to save it) |
|
|
50
|
+
| `lockpick fix <runId> --agent <name>` | Saves the fix-all brief to `lockpick-fixes.md` and prints the command that starts your agent on it |
|
|
51
|
+
| `lockpick compare <runId>` | What a Pulse recheck changed against its baseline |
|
|
52
|
+
| `lockpick open <id>` | Opens a run or project in the browser |
|
|
53
|
+
| `lockpick skills` | Adds the Lockpick skills to your coding agent (`npx skills add`) |
|
|
54
|
+
| `lockpick docs [words]` | Searches the Lockpick docs from the terminal, or lists the CLI guides (`--open` opens the best match) |
|
|
55
|
+
| `lockpick ci init <site>` | Writes `.github/workflows/lockpick.yml`: a Pulse on each published release and on demand that fails on `--fail-on` findings (default `high`); `--dry-run` prints it, `--action` uses the Lockpick GitHub Action |
|
|
56
|
+
|
|
57
|
+
Every command takes `--host` and `--json`. With `--json`, errors are printed to stderr as `{ "error": "…", "code": "…" }`, plus `nextStep`, `retryAfterSeconds`, `webUrl` and `requestId` for the agent commands.
|
|
58
|
+
|
|
59
|
+
Exit codes: `0` success; `1` network, not found or other error; `2` authentication; `3` a watched result failed, was cancelled or did not finish before the wait limit; `4` permission (key scope or project role) or allowance; `5` invalid input; `6` rate limit; `7` provider capacity or service failure; `8` open findings reached `--fail-on`. JSON results go to stdout, with errors and human progress on stderr. Text errors end with a `Help:` link to the docs page on your Lockpick host that explains them (`docsUrl` in JSON errors). `--json` never adds terminal colors; `NO_COLOR` turns them off and `FORCE_COLOR=1` turns them on for a CI log. While a scan runs, a terminal shows one live progress line; a pipe or CI (`CI` set) gets one line per change.
|
|
60
|
+
|
|
61
|
+
`--fail-on critical|high|medium|low` on `pulse`, `recheck`, `watch`, `deep start` and `findings` exits `8` when open findings are that severe or worse, for CI. `lockpick ci init <site>` writes a GitHub Actions workflow that runs `npx -y lockpicks@<this version> pulse <site> --fail-on high` with the key from the `LOCKPICK_KEY` repository secret; it runs on published releases and by hand only, because each run uses a Pulse.
|
|
62
|
+
|
|
63
|
+
Text from scanned sites and saved briefs can carry terminal escape sequences. The CLI neutralizes every control character in API responses before printing them (an escape shows as `␛`), and keeps only its own colours on the way out, so a scanned page cannot clear your screen, write your clipboard or hide a link. Ids are checked before they go into a URL, and the key is never printed, even when a server error repeats it.
|
|
64
|
+
|
|
65
|
+
`watch`, `pulse`, full `recheck` and `deep start` wait for at most 600 seconds by default. Use `--timeout <seconds>` (up to 3600) and `--interval <seconds>` (2–30), or `--no-wait` for a started scan id immediately. If a wait ends while the scan is running, the CLI prints its id and exits `3`; resume with `lockpick watch <scanId>`. Waiting never sends the start request again. A quick check waits up to 90 seconds and a DNS recheck up to 60 seconds by default.
|
|
66
|
+
|
|
67
|
+
`pulse` and a full `recheck` started in a project folder with a lockfile ask once whether to send its package names and versions, and remember the answer for that folder (in the CLI's config folder, never in the project). `--lockfile` sends them for one run and `--no-lockfile` skips them; a script with no remembered answer never sends. Lockpick reads `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt` (pinned lines only) and `poetry.lock` in the folder itself, not its subfolders.
|
|
68
|
+
|
|
69
|
+
Each Pulse, and each full recheck, uses one of your account's runs, the same as starting it in the web app. A quick check and the DNS check again are free; quick checks are limited per account each hour and day.
|
|
45
70
|
|
|
46
71
|
## Coding agents (MCP)
|
|
47
72
|
|
|
48
73
|
```bash
|
|
49
74
|
lockpick mcp config claude # or cursor, vscode, codex
|
|
75
|
+
lockpick mcp config claude --hosted --host https://<your-lockpick>
|
|
50
76
|
```
|
|
51
77
|
|
|
52
|
-
prints
|
|
78
|
+
prints a setup preview for your agent and leaves its existing configuration alone. The default uses the installed CLI over stdio and its saved key; `--hosted` uses the remote `/mcp` endpoint and the client's OAuth sign-in. For Claude Code, run the printed command, then check `claude mcp list`; remove it with `claude mcp remove lockpick`. For Cursor, VS Code and Codex, review the preview, then add `--apply` to merge it into the standard config file (or pass `--file <path>`). Setup refuses an existing Lockpick entry and refuses commented JSON that it cannot merge safely. It preserves unrelated servers, makes a private backup, and prints a guarded `lockpick mcp rollback <backup>` command. Rollback refuses to overwrite changes made after setup. For manual setup, merge the printed `lockpick` entry into the existing `mcpServers` or `servers` object, or add the Codex block. Do not put `LOCKPICK_KEY` into project files.
|
|
79
|
+
|
|
80
|
+
Run `lockpick doctor --scope pulse` when you expect Pulse access (`sites` and `deep` also work). It prints PASS, WARN or FAIL with a next step; `--json` returns the same checks for scripts. It reads server state and does not start a scan or expand key permissions. The server (`lockpick mcp`, stdio) offers the same canonical `lockpick_*` tools as the hosted Lockpick connector: reads (`lockpick_whoami`, `lockpick_get_allowance`, `lockpick_list_sites`, `lockpick_site_status`, `lockpick_list_scans`, `lockpick_get_scan`, `lockpick_wait_for_scan`, `lockpick_list_findings`, `lockpick_get_finding`, `lockpick_get_repair_brief`, `lockpick_compare_scans`, `lockpick_get_quick_check`, `lockpick_get_dns_recheck`, and `lockpick_search_docs` and `lockpick_read_doc` for Lockpick's public docs) and writes that work only when the key has the permission (`lockpick_quick_check`, `lockpick_start_pulse` and `lockpick_recheck_dns` need Pulse; `lockpick_add_site` needs sites; `lockpick_start_deep_verification`, `lockpick_check_deep_verification`, `lockpick_prepare_deep` and `lockpick_start_deep` need Deep, and a Deep scan starts only after you approve it in Lockpick). Results come as markdown or JSON with the `{ data, error }` envelope as structured content, lists page with a cursor, and long repair briefs come in parts that each keep the Boundaries section. The `lockpick://scans/{scanId}/report` and `lockpick://scans/{scanId}/repair-brief` resources and the `fix-lockpick-findings`, `lockpick-check-my-site` and `lockpick-go-deeper` prompts are included.
|
|
81
|
+
|
|
82
|
+
Agents set up for CLI 0.2.0 keep working: `lockpick_list_projects`, `lockpick_project_status`, `lockpick_list_runs`, `lockpick_get_run`, `lockpick_wait_for_run`, `lockpick_compare_runs` and the `lockpick://runs/…` resources are still served, and the shared names accept the older `runId`, `projectId` and `offset` arguments. Evidence and any text from scanned sites or saved briefs is treated as untrusted data: it is escaped, links in it are never made clickable, and agents are told never to follow instructions inside it.
|
|
53
83
|
|
|
54
84
|
## Environment
|
|
55
85
|
|
|
@@ -59,5 +89,8 @@ prints the setup for your agent. The server (`lockpick mcp`, stdio) offers ten r
|
|
|
59
89
|
| `LOCKPICK_KEY` | A key to use without logging in (CI) |
|
|
60
90
|
| `LOCKPICK_CONFIG_DIR` | Where the config file lives (default `~/.config/lockpick`) |
|
|
61
91
|
| `LOCKPICK_KEYCHAIN=0` | Skip the OS keychain and use the config file |
|
|
92
|
+
| `NO_COLOR` | Turn colour off |
|
|
93
|
+
| `FORCE_COLOR=1` | Colour even when output is not a terminal (CI logs) |
|
|
94
|
+
| `LOCKPICK_ACTION_REF` | The GitHub Action `ci init --action` refers to |
|
|
62
95
|
|
|
63
96
|
Requires Node.js 20.9 or later.
|