Skip to content
DavidGodefroidPublic

About

Harness security for AI agents, for SQL databases: a Lock of the Lock Family. PII-masked queries; connections and writes approved in lox run (CLI + MCP).

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

locksql: your agent writes the query, you hold the key.

CI Latest release License: Apache 2.0 Go version

Let any AI agent query your SQL databases: personal data comes back masked,
connections and writes wait for you, and the agent never holds a password.

Demo, two terminals side by side. 1. Left, an agent (here Claude Code) is asked for the 3 Belgian customers with the highest total spend, with their name and email. 2. The agent plans a query through locksql and says it is pending. 3. Right, lox run (here in manual mode) shows the ticket as a question: the SQL, class READ, masked columns email and name. 4. The human presses y in lox run, then tells the agent it is approved. 5. The agent runs the ticket and shows three rows whose name and email are <redacted>.

An agent (here Claude Code, left) and lox run (right, in manual mode: every ticket is asked).

Quick start · How it works · Docs · Lock Family · locksql.com


locksql is a Lock of the Lock Family, harness security for AI agents. A console sits between your agent and MariaDB, MySQL, PostgreSQL or SQLite: it holds the credentials, weighs every statement and masks personal data. The agent only asks.

Note

Pre-release (v0.x): a release may still change the config files, the MCP tools or the CLI. See the path to 1.0.

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, 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.
  • Fail closed. What the classifier cannot classify with certainty is refused, with a code the agent can act on.

In-agent approval is a convenience; a separate approval process is a boundary.

Install

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/locksql davidgodefroid/tap/lox cosign

locksql runs in Docker: Homebrew installs the locksql launcher, which runs every command in the release's image. It also takes lockhub's CLI lox v0.12.0 or later and cosign v2.5.0 or later: lox add and lox run verify every image with cosign. The whole family instead, lox and cosign included: brew install davidgodefroid/tap/lockfamily.

Without Homebrew, the install script of a release tag (it verifies the release's cosign signatures, so it needs cosign v2.5.0 or later on PATH; install lockhub's lox v0.12.0 or later beside it):

V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/locksql/$V/scripts/install.sh"
less install.sh
LOCKSQL_VERSION=$V sh install.sh

Linux and macOS; on Windows, WSL 2 with Docker Desktop. Launcher, image, Vault image, lea and building from source: docs/install.md.

Quick start

  1. In your project, add the database. lox add asks where it is (never the password), writes the profile, wires your agent and starts the console:

    lox add locksql
  2. In a terminal of its own, outside any agent, keep lox run open. Every ticket shows up there:

    lox run
  3. Start your agent in the project (claude, codex, gemini, …) and ask: "how many orders were placed yesterday?"

lox add wires Claude Code; for Codex, Cursor or Gemini CLI, also run locksql init codex (or cursor, gemini). With lea, run lox add in lea's projects directory, then lea stop and lea. Step by step, by hand: docs/install.md.

Highlights

🔑 One key holder
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).

👤 Your rules, your decisions
Per profile, each action is auto, ask or deny. By default reads pass; writes, DDL and unmasked reads are asked every time.

🕶️ PII masked at the source
Columns are traced through aliases, CTEs, unions and joins, then masked (redact, partial, email); detectors catch the rest.

⚖️ Weighed before it runs
LIMIT is mandatory, EXPLAIN runs first, and plans that would scan too many rows are refused.

More: OS separation, grants, writes, remote databases, and the console's switches.

How it works

Two processes in two containers. Only the console holds the key.

sequenceDiagram
    autonumber
    participant A as 🤖 AI agent<br/>(locksql mcp / CLI)
    participant C as 🔐 locksql console
    participant L as 🎫 lockhub (lox run)
    participant D as 🗄️ Database
    A->>C: plan "SELECT … LIMIT 20"
    C->>D: EXPLAIN
    C-->>A: plan id + verdict (OK / WARN / REFUSE)
    A->>C: run PLAN_ID
    C->>L: ticket, every literal masked
    C-->>A: pending, ticket T
    L-->>C: signed decision (your rule, or you)
    A->>C: run T
    C->>D: the statement
    C-->>A: masked, capped rows (untrusted data)
Loading
  1. The agent plans a statement (locksql plan, or the locksql_plan MCP tool). The console classifies it, traces every output column, runs EXPLAIN and answers with a verdict.
  2. The agent runs the plan. The console sends lockhub a ticket and answers pending.
  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.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.

Safety model

  • The console is the enforcement point. Skills, rules and MCP tool descriptions only guide the agent; the console's checks are the guarantee.
  • OS separation. The console runs as its own account in its own 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 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. Threat model: docs/security-model.md.

Documentation

Doc What it covers
docs/install.md install paths, the launcher and its image, the first query by hand, building
docs/docker.md what runs where in Docker, Vault, an agent in its own container
docs/usage.md the console, client commands, MCP server, agent wiring, grants, auto mode
docs/configuration.md every profile key, TLS, SSH, PII rule sets, sharing a configuration, the company's managed configuration ([locksql] of lockfamily's managed.toml)
docs/console.md --allow-unmask, console keys, clear results (Ctrl-O)
docs/architecture.md the life of a query, the approval screen, engines
docs/safety.md the safety model and the limitations, in full
docs/security-model.md threat model, mitigations, upstream recommendation
docs/pii-analysis.md how the PII analysis works (for contributors)
docs/1.0.md the 1.0 criteria and the versioning policy
CHANGELOG.md what changed, release by release

The site, locksql.com, is built from site/.

The Lock Family

Repo What it does
lockfamily The family site (lockfamily.dev) and the one-line installer.
locksql SQL databases: the agent queries, PII comes back masked; connections and writes wait for you.
lockmq RabbitMQ: masked queue inspection; connections, peeks and unmasked reads wait for you.
lockfile Files (S3, SFTP, disk): the agent asks yes/no questions about files it never reads.
lockhttp Outbound HTTP(S): reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you.
locklog Logs: masked, bounded log search; the agent reads the logs, not the people in them.
lockssh Commands over SSH: allow-listed commands run at once, the rest waits for you; the key never leaves the console.
lockhub The approval hub and its lox CLI: lox run approves outside the agent's harness and never sees values in clear.
lockkit The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP.
lea Runs many agents in containers, wired to the Locks.

Contributing · Security · License

  • Contributing: CONTRIBUTING.md. Build with CGO_ENABLED=0 go build ./cmd/locksql (Go 1.26+).
  • Security: report a vulnerability privately, see SECURITY.md.
  • License: Apache License 2.0, see LICENSE and NOTICE.

About

Harness security for AI agents, for SQL databases: a Lock of the Lock Family. PII-masked queries; connections and writes approved in lox run (CLI + MCP).

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages