lock family docs GitHub

Locks · locklog

locklog

Let any AI agent investigate your logs: counts, patterns and traces come back
with emails, IPs and secrets masked, and a value in clear waits for you.

An agent (here Claude Code) asks when the PDF errors started on a staging profile. locklog_count shows the step at 14:02, locklog_patterns finds the new pattern with the email and the IP masked, and locklog_trace follows order 4812: all free and masked. The agent then asks locklog_unmask for the email. lox run, lockhub's terminal outside the agent, shows the read-pii ticket with the masked record and the span marked; the human answers n. The agent gets denied and carries on without the address; the audit records every call with pseudonyms only.

An agent (here Claude Code, left) and lox run (right, outside the agent): free calls come back masked, an unmask waits for you.

locklog is a Lock of the Lock Family, harness security for AI agents. A console held by a human reads your logs; the agent asks over MCP and gets masked, bounded, typed answers: counts, patterns, traces, lines around a hit.

Note

Pre-release (v0.3.x). The console is started by lox run only, from lockhub v0.10.0. See the install status.

Why locklog #

  • Masked before the model. Emails, IPs, card numbers, national ids and the other values locklog detects become pseudonyms (⟦email:7F3KQ2M9ZD4X⟧); secrets become ⟦secret⟧.
  • The agent never holds the logs. It never reads files, the Docker socket or a backend's credentials: the console does, in its own account and container.
  • Approval outside the agent. Reads within budgets are free. A scan beyond a budget or a value in clear is a ticket that waits for you in lox run, and unmask is off by default on production.
  • Read-only. No write path to any log or backend, and every call is audited without clear values.

Install #

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamily

That installs the Lock Family, locklog included. For locklog alone: brew install davidgodefroid/tap/locklog (with lox for lox add locklog and lox run), or the signed install script, which installs the launcher:

curl -fsSL https://locklog.dev/install.sh | sh

A Linux host with the logs, Docker ≥ 19.03 and cosign. Status, the script read first, and production placement: docs/install.md.

Quick start #

On a non-production profile first (a host agent runs on your own account, where it could still read the logs directly):

  1. In your project, add the lock. lox add builds a profile from the logs this host has (never a secret), wires your agent and checks the setup:

    cd ~/projects/shop
lox add locklog

  2. In a terminal of its own, outside any agent, keep lox run open. It starts the console, and every ticket shows up there:

    lox run

  3. Start your agent in the project (claude, codex, gemini, …) and ask: "when did the 502s start?"

lox add wires Claude Code; for Codex, Cursor or Gemini CLI, also run locklog init codex (or cursor, gemini). On production, run the agent in lea or in its own container (docs/setup.md).

Highlights #

🕶️ Masked by construction
Every record is masked before any predicate runs. A clear email in a query is refused; equality on a pseudonym still finds one user's records.

🔎 Investigation tools, not a query language
locklog_count, locklog_patterns, locklog_trace, locklog_context, locklog_search, locklog_tail. Text never goes to a backend.

⚖️ Free within budgets, approved beyond
Reads are bounded per call and per hour. locklog_scan asks you once for its whole plan.

📚 Your sources
Files (rotation, gzip, zstd), journald, Docker container logs and Loki; Elasticsearch and OpenSearch as a preview.

More: the highlights in full and a comparison.

How it works #

 host (you)
   lox run (lockhub): the hub and the decisions, in a terminal of its own
     └─ console container   uid 10051, no capability, read-only root,
          read-only binds of the approved log directories,
          pseudonym keys, index and audit in its own volume
 agent (lea, your own container, or the host for the trial)
   MCP server `locklog mcp` → the console's socket (peer uid checked by the kernel)
  1. The console reads the approved sources, and only those.
  2. Each call gets a byte plan from the time range and trusted selectors only; admission and stopping points never depend on what matched.
  3. Every record is masked first; then the agent's predicates run on the masked view.
  4. The answer leaves capped, as JSON under an "untrusted content" header.

Reads within budgets are free and audited. A scan beyond a budget, an unmask or an approved lookup is a ticket at lox run; a profile's auto rules (auto, ask, deny) decide which lox run may approve alone, and the default asks you. The full layout, the decision table, the sources and the masking benchmark: docs/architecture.md.