Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,20 @@ This file records the changes a user or an agent has to know about.

## Unreleased

### Fixed

- The docs, the site and the agent-facing texts say what the code does
(#249): reads are approved by `lox run`'s default auto rule, a
k-anonymity warning included, unless `auto.read = "ask"` or `lox run
--manual`; `locksql_run` waits at most 2 s, then answers `pending` (no
5-minute approval timeout); `lox run` asks the console's questions in its
cards (`lox attach` is for debugging); the audit log is hash-chained; the
managed-file example of `docs/configuration.md` now loads (a test parses
it); the `init` next steps, the doctor hint and the MCP server texts no
longer name `lox attach` or a human decision for every ticket. Known gaps
are filed: `locksql grant` through the host launcher (#250), warned reads
auto-approved (#251, lockhub#224).

## v0.20.0 (2026-11-14)

Supported lockhub: v0.9.0 or later (unchanged). Built on lockkit v0.20.0.
Expand Down Expand Up @@ -265,7 +279,7 @@ Supported lockhub: as v0.16.0. Built on lockkit v0.14.1.

- Every user- and agent-facing text names `lox run`, which starts the hub
and the locks and serves the decisions in a terminal of its own, outside
the agent, instead of `lox up`, deprecated since lockhub v0.10.0 (#192):
the agent, instead of `lox up`, deprecated since lockhub v0.9.0 (#192):
the docs and the site, the agent assets `locksql init` writes (skill,
AGENTS.md, config.toml), the MCP server's instructions, the launcher's
errors, `doctor`, `init` and the console's messages. The shared texts
Expand Down
22 changes: 13 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,16 @@ MariaDB, MySQL, PostgreSQL or SQLite: it holds the credentials, weighs every
statement and masks personal data. The agent only asks.

> [!NOTE]
> **Pre-release** (`v0.17.x`): a release may still change the config files,
> **Pre-release** (`v0.x`): a release may still change the config files,
> the MCP tools or the CLI. See [the path to 1.0](docs/1.0.md).

## Why locksql

- **The agent never holds a password.** Credentials are typed at console
start or read from Vault, in an account and a container the agent cannot reach.
- **Approval outside the agent.** Each statement becomes a ticket on
[lockhub](https://github.com/DavidGodefroid/lockhub), decided in `lox run`.
[lockhub](https://github.com/DavidGodefroid/lockhub), decided in `lox run`
(or runs inside a grant you approved once).
Reads pass on your rules; connections, writes and schema changes wait for you.
- **Personal data stays masked.** Every output column is traced to its source
column and masked there, whatever the query calls it.
Expand All @@ -64,7 +65,8 @@ locksql runs in Docker: Homebrew installs the `locksql` launcher, which runs
every command in the release's image. `lox` is lockhub's CLI. The whole
family instead: `brew install davidgodefroid/tap/lockfamily`.

Without Homebrew, the signed install script of a release:
Without Homebrew, the install script of a release tag (it verifies the
release's cosign signatures, so it needs `cosign` on PATH):

```sh
V=vX.Y.Z
Expand Down Expand Up @@ -108,8 +110,9 @@ directory, then `lea stop` and `lea`. Step by step, by hand:
<td width="50%" valign="top">

**🔑 One key holder**<br>
Credentials live in the console only: never in argv, env, files, logs, the
socket or an error message.
Credentials live in the console only: the database password is never in
argv, env, files, logs, the socket or an error message (a Vault token goes
only to the `vault` child's environment).

</td>
<td width="50%" valign="top">
Expand Down Expand Up @@ -172,7 +175,7 @@ sequenceDiagram
3. `lox run` decides, on your profile's rules or by asking you. The console
checks the signed decision, runs the statement, masks and caps the rows.

Engines: MariaDB 10.1+, MySQL 8.0+, PostgreSQL 13+, SQLite 3, all pure Go,
Engines: MariaDB 10.11+, MySQL 8.0+, PostgreSQL 13+, SQLite 3, all pure Go,
on amd64 and arm64. The approval screen, the process layout and the engines
table: [docs/architecture.md](docs/architecture.md).

Expand All @@ -184,9 +187,10 @@ table: [docs/architecture.md](docs/architecture.md).
container; the kernel checks every peer on the socket.
- **The AI tightens, the human loosens.** Agents may add mask rules; any
loosening of the policy waits for your confirmation in the console.
- **Audit.** Every decision, refusal and run goes to an append-only JSONL log,
never with secrets or row data.
- **Known limits.** Masking is best effort, k-anonymity is a warning, and
- **Audit.** Every decision, refusal and run goes to a hash-chained JSONL
log, never with secrets or result rows.
- **Known limits.** Masking is best effort, k-anonymity is a warning (on a
read the default auto rule approves without asking), and
whoever can run `docker` commands can reach the console's container.

Every rule and limit: [docs/safety.md](docs/safety.md). Threat model:
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ cosign verify ghcr.io/davidgodefroid/locksql:X.Y.Z \
The actions the workflows run are pinned to full commit SHAs, and the
release job pins the versions of GoReleaser, cosign and syft.

Release tags are annotated, not yet signed (`v0.1.0` to `v0.8.1`). From
Release tags are not signed yet (none is, up to v0.20.0). From
the first signed tag on, its key is published on the maintainer's GitHub
profile (<https://github.com/DavidGodefroid.gpg>, or the SSH signing keys),
and a tag can be checked before you build from it:
Expand Down
2 changes: 1 addition & 1 deletion cmd/locksql/doctor.go
Original file line number Diff line number Diff line change
Expand Up @@ -787,7 +787,7 @@ func profileChecks(d doctorEnv, p config.Profile, sys *sysconf.Config, cwd strin
if err != nil {
if errors.Is(err, client.ErrNoConsole) {
add(checkWarn, "console", "not running: connectivity, privileges and EXPLAIN are checked by a running console",
"start it: "+startCommandOf(err, p.Name)+" (then `lox attach INSTANCE` answers its questions)")
"start it: "+startCommandOf(err, p.Name)+" (lox run asks its questions)")
} else {
add(checkFail, "console", err.Error(), "")
}
Expand Down
2 changes: 1 addition & 1 deletion cmd/locksql/init.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,6 @@ func runInit(e env, args []string) int {
// project has a .locksql/config.toml now, so its agents dial the project's
// socket key: only a console started on the project serves them.
func initNextSteps(root string) string {
return fmt.Sprintf("Next: add the database profile to %s (locksql profile add),\nthen start the console with lockhub, from %s: lox run, in a terminal of its own outside the agent,\nstarts the hub and the console and serves the decisions (keep it open while the agent works);\nlox attach, in another terminal, answers the console's questions (the policy, the PII rules, the password):\n lox add locksql <instance>\n lox run\n lox attach <instance>\n",
return fmt.Sprintf("Next: add the database profile to %s (locksql profile add),\nthen start the console with lockhub, from %s: lox run, in a terminal of its own outside the agent,\nstarts the hub and the console, asks the console's questions (the policy, the PII rules, the password)\nin its cards and serves the decisions (keep it open while the agent works):\n lox add locksql <instance>\n lox run\n",
filepath.Join(root, ".locksql", "config.toml"), root)
}
2 changes: 1 addition & 1 deletion docs/1.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ checked off in the pull request that completes it.
are listed in one reference and frozen for 1.x.
- [ ] **MCP tool schema.** The tool names (`locksql_status`,
`locksql_list_tables`, `locksql_describe`, `locksql_plan`, `locksql_run`,
`locksql_pii_list`, `locksql_pii_add`, `locksql_request_change`), their
`locksql_grant`, `locksql_pii_list`, `locksql_pii_add`, `locksql_request_change`), their
input fields and their result shapes are frozen for 1.x, with a test that
fails when one changes.
- [ ] **CLI and exit codes.** Command names, flags, `--json` output and the
Expand Down
10 changes: 7 additions & 3 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ sequenceDiagram
C->>D: k-anonymity counts
C-->>A: pending, ticket T
C->>H: ticket T in lockhub (warns of a count under k)
H-->>C: lox approve: signed decision
H-->>C: lox run: signed decision (auto rule or you)
A->>C: run T
C->>D: the statement
D-->>C: rows
Expand Down Expand Up @@ -55,7 +55,11 @@ sequenceDiagram
╰─ pending: ticket 01J…
```

3. You decide the ticket in lockhub (`lox approve`). The agent runs the
3. `lox run` decides the ticket by the profile's auto rules: by default a
read is approved without asking (a k-anonymity warning included; set
`auto.read = "ask"` or run `lox run --manual` to see it first), while
writes, DDL, unmasked reads and grants are asked of you (`lox approve`
answers too). The agent runs the
ticket (`locksql run TICKET`); the console checks the hub's signed
decision, plans the statement again, runs it, masks PII, caps the output
and hands the rows back to the agent, framed as untrusted data.
Expand Down Expand Up @@ -92,7 +96,7 @@ Full walkthrough: [docs/usage.md](usage.md).

| Engine | Versions | Read-only session (tier `read`) | Server-side timeout | Plan source |
|---|---|---|---|---|
| `mariadb` | 10.1+ (tested 10.11, 11.4) | `SET SESSION TRANSACTION READ ONLY` + `START TRANSACTION READ ONLY` | `max_statement_time` + `KILL QUERY` | `EXPLAIN FORMAT=JSON` |
| `mariadb` | 10.11+ (tested 10.11, 11.4) | `SET SESSION TRANSACTION READ ONLY` + `START TRANSACTION READ ONLY` | `max_statement_time` + `KILL QUERY` | `EXPLAIN FORMAT=JSON` |
| `mysql` | 8.0+ (tested 8.0, 8.4) | same as MariaDB | `max_execution_time` (SELECT only; writes rely on `KILL QUERY`) + `KILL QUERY` | `EXPLAIN FORMAT=JSON` |
| `postgres` | 13+ (tested 13, 17) | `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` + `BEGIN READ ONLY` … `ROLLBACK` | `statement_timeout` + cancel request | `EXPLAIN (FORMAT JSON, VERBOSE)` |
| `sqlite` | 3 (pure Go, in-process) | `mode=ro` + `query_only` | interrupt on deadline | `EXPLAIN QUERY PLAN` + `sqlite_stat1` (run `ANALYZE` once, or every full scan is a WARN of unknown size) |
Expand Down
14 changes: 13 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ credentials = "ask" # passphrase or SSH password; default: the p
|---|---|---|
| `engine` | required | `mariadb`, `mysql`, `postgres`, `sqlite` |
| `host`, `port` | required host; port 3306 / 5432 | a host starting with `/` is a Unix socket (MariaDB/MySQL) |
| `path` | required for sqlite | relative to the project root; the file is never created |
| `path` | required for sqlite | relative to the project root (for a profile of the user config, to the user config directory); the file is never created |
| `user` | asked at start | with `credentials = "vault"`: the secret's `username`; set it only for a secret without one |
| `database` | none | the only database served (and scanned for PII); empty: every database the account can see, chosen per query with `--db` |
| `credentials` | `ask` | `keychain` (not in a container) offers to save the secret after the first successful login; `locksql forget --profile P` removes it. `vault` reads the login from `vault_path` at every connection |
Expand All @@ -132,7 +132,12 @@ credentials = "ask" # passphrase or SSH password; default: the p
| `ssh.host`, `ssh.port`, `ssh.user` | required host and user; port 22 | the bastion; not with sqlite or a Unix socket `host` |
| `ssh.auth` | required | `key`, `agent` (`SSH_AUTH_SOCK` of the console) or `password` |
| `ssh.key` | required with `auth = "key"` | private key of the console account, mode 0600 |
| `tls` | `prefer` | the driver's TLS mode, libpq's names (`disable`, `prefer`, `require`, `verify-ca`, `verify-full`) ([TLS to the database](usage.md#tls-to-the-database)) |
| `tls_server_name` | none | the name `verify-full` checks instead of `host` |
| `tls_ca`, `tls_cert`, `tls_key` | none | PEM files read by the console account ([TLS to the database](usage.md#tls-to-the-database)) |
| `write_functions` | `denylist` | `allowlist` applies the read function allowlist to writes ([Functions in writes](usage.md#functions-in-writes-write_functions)); back to `denylist` is a loosening |
| `auto` | reads `auto`, the rest `ask` | how `lox run` decides this profile's tickets: a preset (`auto = "full-auto"`) or a table of `connect`, `read`, `write`, `ddl`, `unmask` set to `auto`, `ask` or `deny` ([Auto mode per profile](usage.md#auto-mode-per-profile)); a move toward `auto` is a loosening |
| `limits.grant_max_duration`, `limits.grant_max_statements`, `limits.grant_max_rows`, `limits.grant_max_bytes` | `1h`, 200, 10 000, 1 MiB | the most a grant may ask for; `grant_max_duration = "0"` turns grants off ([Grants](usage.md#grants)) |
| `ssh.credentials` | the profile's `credentials` (`ask` when that is `vault`) | `ask` or `keychain` for the passphrase or SSH password; `locksql forget --profile P` removes it too |
| `proxy_command` | none | argv run without a shell, as the console account, once per connection; its stdin and stdout carry it (`docker exec`, `kubectl exec`, `ssh ... socat`). Not with `ssh`, sqlite or a Unix socket `host`; any change is a loosening |

Expand Down Expand Up @@ -274,10 +279,17 @@ engine = "postgres"
host = "erp.db.acme.internal"
database = "erp"
production = true
tls = "verify-full"
auto = { ddl = "deny" }
credentials = "vault"
vault_path = "database/creds/erp-ro"
```

A managed profile must itself be within the bounds: a key it and the managed
defaults leave unset takes the built-in default (`tls = "prefer"`, `auto.ddl = "ask"`), which a
stricter bound refuses, so the profile above sets `tls` and `auto` as the
bounds require.

The precedence is: the hard-coded floor > the managed bounds and profiles >
the project file > the user file > the managed defaults > the built-in
defaults. The merged result is checked against the bounds at the console's
Expand Down
24 changes: 13 additions & 11 deletions docs/console.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@ What you can switch in the console while it runs. The console is started by lock

An agent can ask for unmasked PII output (`locksql plan --unmask`, or
`unmask` in the MCP `locksql_plan` tool) only when the human allowed it in
the console: `--allow-unmask` at start (from the lock's settings in `lox
up`), or `:unmask` while it runs (confirmed with `y` at the console's
terminal; `:unmask` again turns it off). Without it, the console refuses
every unmask request before anything runs and audits the refusal. It is
console-only: no client or config file can turn it on, and each change is
audited (`unmask` record). With it, each unmasked query is still decided by
the human in lockhub, shown as `PII: UNMASKED` in red. The console then
the console: `:unmask` while it runs (confirmed with `y` at the console's
terminal, or the profile name typed on production; `:unmask` again turns
it off). `lox run` does not pass `--allow-unmask`, the console's start-up
flag. Without it, the console refuses every unmask request before anything
runs and audits the refusal. It is console-only: no client or config file
can turn it on, and each change is audited (`unmask` record). With it, each
unmasked query still needs a ticket, shown as `PII: UNMASKED` in red and
asked of the human unless the approved policy sets `auto.unmask = "auto"`
(e.g. `auto = "full-auto"`). The console then
prints the clear result, so you see exactly what the agent received (the
audit log still holds no row data).

Expand All @@ -27,18 +29,18 @@ environment variable can set them) and each change is audited.

| Key | Typed | Effect |
|---|---|---|
| Ctrl-P Ctrl-Q | | detach (`lox attach`'s key): the console keeps running; the Ready box shows it, and so does each question asked after the console served (a reconnect, a loosened policy) |
| Ctrl-P Ctrl-Q | | detach (`lox attach`'s key, when you reach the console's terminal for debugging): the console keeps running; the Ready box shows it, and so does each question asked after the console served (a reconnect, a loosened policy) |
| Ctrl-O | `:results` | results masked ⇄ shown here in clear |
| | `:unmask` | unmasked output off ⇄ allowed (allowing asks for `y`) |
| | `:unmask` | unmasked output off ⇄ allowed (allowing asks for `y`, the profile name on production) |
| | `:revoke` | end every active grant (`:revoke ID`: one) |

## Clear results (Ctrl-O)

Ctrl-O (or the console's `--show-results`, which `lox run` does not pass) prints in
the console, in clear, the result of each masked query it runs, as an
aligned table, so you see who the rows are while the agent still gets the
masked cells. The cells the agent got masked are yellow and carry their
reference (`‹r1.1.2›`); the output caps apply as for the agent. Off by
masked cells. The cells the agent got masked are yellow; the output caps
apply as for the agent. Off by
default. The console warns when it goes on (in red on production), the
status row reads `results clear`, every approval screen says `result:
shown here in clear`, and `locksql status` reports `show results on`. The
Expand Down
Loading
Loading