tabulus 0.0.3__tar.gz → 0.0.4__tar.gz

{tabulus-0.0.3 → tabulus-0.0.4}/.gitignore

@@ -15,3 +15,7 @@ dist/
 .vscode/
 .idea/
 .DS_Store
+
+# local-only — not pushed to main
+CLAUDE.md
+.private/

{tabulus-0.0.3 → tabulus-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabulus
-Version: 0.0.3
+Version: 0.0.4
 Summary: Postgres MCP server — agent-first database workbench
 Project-URL: Repository, https://github.com/WalkingMountain/tabulus
 Project-URL: Issues, https://github.com/WalkingMountain/tabulus/issues
@@ -26,35 +26,53 @@ Description-Content-Type: text/markdown
 
 # Tabulus
 
-**A Postgres MCP server built for AI agents.**
+**Let your AI agent query your real Postgres — without leaking customer data to the LLM.**
 
-Tabulus is the database workbench for the AI-augmented developer. Connect Claude
-Code, Cursor, or any MCP-compatible client to your Postgres database and let the
-agent introspect the schema, sample data, and write safe queries — without
-copy-pasting schemas into chat windows.
+Tabulus is a Postgres MCP server that sits between your AI agent (Claude Code,
+Cursor, any MCP client) and your database. It scrubs emails, API keys, JWTs,
+credit cards, SSNs, phones, and IPs **out of every result before the agent ever
+sees them** — so you can point Claude at a production-shaped database without
+piping your customers' PII into someone else's model.
 
-## Why
+![Tabulus redactor: customer PII and secrets scrubbed before they reach the LLM](demo/tabulus-redactor.svg)
 
-Every modern dev workflow now includes an AI agent. Every DB GUI was designed
-before that was true. Tabulus flips the model: **the agent is a first-class
-user, not a sidebar feature.**
+<sub>Same query, redactor off vs on — real output. Record the animated version yourself: [`demo/`](demo/).</sub>
 
-What that means in practice:
+## The problem
 
-- Schema introspection optimized for LLM context windows (compact JSON, foreign
-  keys flattened, sample rows inline).
-- Read-only by default — `INSERT`/`UPDATE`/`DELETE`/`DDL` are rejected at the
-  gateway. The agent can't drop your tables.
-- `EXPLAIN` exposed as a tool so the agent can reason about query plans before
-  proposing optimizations.
-- Statement timeout + row cap enforced server-side. No agent can DOS your
-  database by accident.
-- Opt-in PII redactor (`TABULUS_REDACT=on`) scrubs emails, API keys, JWTs,
-  credit cards, phones, and IPs from tool output before the agent sees them.
+Connecting an AI agent to your database means every row it samples — every
+customer email, every Stripe key sitting in a config table, every JWT in a
+sessions row — gets shipped into the LLM's context window. To Anthropic. To
+OpenAI. To wherever the model runs. Most DB MCP servers solve "can the agent
+drop my tables." **Tabulus solves what leaves the building.**
+
+```
+Without redaction:   {"email": "jane@acme.com",  "api_key": "sk_live_4eC39Hq..."}
+With Tabulus:        {"email": "[REDACTED:email]", "api_key": "[REDACTED:stripe_key]"}
+```
+
+Turn it on with `TABULUS_REDACT=on`. The sentinel keeps enough structure for the
+agent to reason (`"Stripe call failed with [REDACTED:stripe_key]"`) without ever
+seeing the secret.
+
+## Also in the box
+
+- **PII/secret redactor** — emails, API keys (Anthropic/OpenAI/Stripe/GitHub/AWS/
+  Slack/Google), OAuth + bearer tokens, JWTs, PEM private keys, credit cards, SSNs,
+  international + US phones, IPv4/IPv6 — plus `key=value` secrets and any value in a
+  secret-named column (`password`, `api_key`, …). Conservative by design: false
+  positives are cheap, false negatives leak.
+- **Read-only, enforced three ways** — keyword gate + Postgres read-only
+  transaction + row cap. The agent can't drop your tables.
+- **Schema introspection tuned for context windows** — compact JSON, foreign keys
+  flattened, sample rows inline. Fits a 50-table schema in one prompt.
+- **`EXPLAIN` as a tool** — the agent reasons about query plans before proposing
+  optimizations.
+- **Statement timeout + row cap** server-side. No accidental DOS.
 
 ## Status
 
-**v0.0.1 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
+**v0.0.4 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
 
 ## Install
 
@@ -133,6 +151,15 @@ Add to `~/.cursor/mcp_servers.json`:
 | `TABULUS_REDACT` | `off` | Set `on` to scrub PII (emails, API keys, JWTs, credit cards, phones, IPs) from `sample_rows`, `safe_select`, and `describe_schema` output before the agent sees it. Recommended for production. |
 | `TABULUS_ALLOW_WRITES` | `false` | Set `true` to disable the write block (NOT recommended) |
 
+## For teams
+
+Tabulus core is free and MIT — and stays that way. If your organization is letting
+AI agents touch real, sensitive databases and you need **audit logs, centrally
+enforced redaction policy, column-level masking, or SSO**, we're exploring a
+self-hosted Team tier (your data never routes through us).
+
+👉 **[Tell us what you'd need →](https://github.com/WalkingMountain/tabulus/issues/1)**
+
 ## Roadmap
 
 - v0.1 — Postgres parity, polished install

tabulus-0.0.4/README.md

@@ -0,0 +1,147 @@
+# Tabulus
+
+**Let your AI agent query your real Postgres — without leaking customer data to the LLM.**
+
+Tabulus is a Postgres MCP server that sits between your AI agent (Claude Code,
+Cursor, any MCP client) and your database. It scrubs emails, API keys, JWTs,
+credit cards, SSNs, phones, and IPs **out of every result before the agent ever
+sees them** — so you can point Claude at a production-shaped database without
+piping your customers' PII into someone else's model.
+
+![Tabulus redactor: customer PII and secrets scrubbed before they reach the LLM](demo/tabulus-redactor.svg)
+
+<sub>Same query, redactor off vs on — real output. Record the animated version yourself: [`demo/`](demo/).</sub>
+
+## The problem
+
+Connecting an AI agent to your database means every row it samples — every
+customer email, every Stripe key sitting in a config table, every JWT in a
+sessions row — gets shipped into the LLM's context window. To Anthropic. To
+OpenAI. To wherever the model runs. Most DB MCP servers solve "can the agent
+drop my tables." **Tabulus solves what leaves the building.**
+
+```
+Without redaction:   {"email": "jane@acme.com",  "api_key": "sk_live_4eC39Hq..."}
+With Tabulus:        {"email": "[REDACTED:email]", "api_key": "[REDACTED:stripe_key]"}
+```
+
+Turn it on with `TABULUS_REDACT=on`. The sentinel keeps enough structure for the
+agent to reason (`"Stripe call failed with [REDACTED:stripe_key]"`) without ever
+seeing the secret.
+
+## Also in the box
+
+- **PII/secret redactor** — emails, API keys (Anthropic/OpenAI/Stripe/GitHub/AWS/
+  Slack/Google), OAuth + bearer tokens, JWTs, PEM private keys, credit cards, SSNs,
+  international + US phones, IPv4/IPv6 — plus `key=value` secrets and any value in a
+  secret-named column (`password`, `api_key`, …). Conservative by design: false
+  positives are cheap, false negatives leak.
+- **Read-only, enforced three ways** — keyword gate + Postgres read-only
+  transaction + row cap. The agent can't drop your tables.
+- **Schema introspection tuned for context windows** — compact JSON, foreign keys
+  flattened, sample rows inline. Fits a 50-table schema in one prompt.
+- **`EXPLAIN` as a tool** — the agent reasons about query plans before proposing
+  optimizations.
+- **Statement timeout + row cap** server-side. No accidental DOS.
+
+## Status
+
+**v0.0.4 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
+
+## Install
+
+```bash
+pip install tabulus
+```
+
+## Run
+
+```bash
+export DATABASE_URL=postgres://user:pass@host:5432/dbname
+tabulus
+```
+
+Then point your MCP client at the `tabulus` command.
+
+### Claude Code (project-level)
+
+Create `.mcp.json` in your project root:
+
+```jsonc
+{
+  "mcpServers": {
+    "tabulus": {
+      "command": "tabulus",
+      "args": [],
+      "env": {
+        "DATABASE_URL": "postgres://user:pass@host:5432/dbname"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code in that directory and approve the trust prompt.
+
+### Claude Code (user-level via CLI)
+
+```bash
+claude mcp add tabulus "$(which tabulus)" --env DATABASE_URL=postgres://user:pass@host:5432/dbname
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp_servers.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "tabulus": {
+      "command": "tabulus",
+      "env": { "DATABASE_URL": "postgres://user:pass@host:5432/dbname" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_tables` | All tables with row count estimates + sizes |
+| `describe_schema` | Columns, PK, FKs, indexes, sample rows for a table |
+| `sample_rows` | Random sample from a table |
+| `safe_select` | Run a read-only SELECT (write keywords rejected) |
+| `explain` | Get query plan (EXPLAIN FORMAT JSON) |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DATABASE_URL` | — (required) | Postgres connection URL |
+| `TABULUS_MAX_ROWS` | `100` | Hard cap on rows returned by any tool |
+| `TABULUS_SAMPLE_SIZE` | `3` | Sample rows included in `describe_schema` |
+| `TABULUS_STATEMENT_TIMEOUT_MS` | `5000` | Server-side query timeout |
+| `TABULUS_REDACT` | `off` | Set `on` to scrub PII (emails, API keys, JWTs, credit cards, phones, IPs) from `sample_rows`, `safe_select`, and `describe_schema` output before the agent sees it. Recommended for production. |
+| `TABULUS_ALLOW_WRITES` | `false` | Set `true` to disable the write block (NOT recommended) |
+
+## For teams
+
+Tabulus core is free and MIT — and stays that way. If your organization is letting
+AI agents touch real, sensitive databases and you need **audit logs, centrally
+enforced redaction policy, column-level masking, or SSO**, we're exploring a
+self-hosted Team tier (your data never routes through us).
+
+👉 **[Tell us what you'd need →](https://github.com/WalkingMountain/tabulus/issues/1)**
+
+## Roadmap
+
+- v0.1 — Postgres parity, polished install
+- v0.2 — SQLite adapter
+- v0.3 — MySQL / MariaDB adapter
+- v0.x — Tauri desktop GUI shell on top of the same core
+- v1.0 — Stable, cross-platform, multi-DB
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

tabulus-0.0.4/demo/README.md

@@ -0,0 +1,24 @@
+# Tabulus redactor demo
+
+Records the before/after that is the whole pitch: an agent sampling a real table,
+with and without PII redaction.
+
+## Run it
+
+```bash
+# 1. throwaway Postgres (any will do)
+export DATABASE_URL=postgres://postgres:dev@localhost:5433/postgres
+
+# 2. install + seed fake-PII table
+pip install -e .
+psql "$DATABASE_URL" -f demo/seed.sql
+
+# 3a. just watch it
+bash demo/record.sh
+
+# 3b. or record the GIF the README embeds (output path must match)
+asciinema rec -c "bash demo/record.sh" demo/tabulus-redactor.cast
+agg demo/tabulus-redactor.cast demo/tabulus-redactor.gif
+```
+
+All seed values are fake. Point this at a scratch database only — never prod.

tabulus-0.0.4/demo/record.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Scare-then-relieve demo. Records cleanly under asciinema:
+#   asciinema rec -c "demo/record.sh" tabulus-redactor.cast
+# Then: agg tabulus-redactor.cast tabulus-redactor.gif   (or upload the .cast)
+#
+# Requires: a throwaway Postgres + DATABASE_URL set, and `pip install -e .`
+# Seed first:  psql "$DATABASE_URL" -f demo/seed.sql
+set -euo pipefail
+
+: "${DATABASE_URL:?set DATABASE_URL to a throwaway Postgres, e.g. postgres://postgres:dev@localhost:5433/postgres}"
+
+pause() { sleep "${1:-1.4}"; }
+say()   { printf '\n\033[1;36m# %s\033[0m\n' "$1"; pause 1.2; }
+
+# Run sample_rows through Tabulus' own db layer, redactor toggled by env.
+sample() {
+  python - <<'PY'
+import asyncio, json, os
+from tabulus.config import load
+from tabulus.db import get_pool, sample_rows, close_pool
+async def main():
+    pool = await get_pool(load())
+    rows = await sample_rows(pool, "customers", 2)
+    print(json.dumps(rows, indent=2, default=str))
+    await close_pool()
+asyncio.run(main())
+PY
+}
+
+clear
+say "Your AI agent samples a 'customers' table. Watch what reaches the model."
+pause 1.6
+
+say "WITHOUT Tabulus redaction (TABULUS_REDACT=off) — this is what most DB MCP servers send to the LLM:"
+TABULUS_REDACT=off sample
+pause 2.8
+
+say "Emails. Stripe live keys. JWTs. Credit cards. SSNs. All shipped to Anthropic/OpenAI."
+pause 2.4
+
+say "WITH Tabulus (TABULUS_REDACT=on) — same query, scrubbed before the agent sees a thing:"
+TABULUS_REDACT=on sample
+pause 3.0
+
+say "The agent still reasons over the shape. Your customers' data never left the building."
+pause 2.0
+printf '\n\033[1;32m  pip install tabulus  ·  TABULUS_REDACT=on\033[0m\n\n'
+pause 2.0

tabulus-0.0.4/demo/seed.sql

@@ -0,0 +1,28 @@
+-- Demo seed: a customers table stuffed with the exact kinds of PII/secrets
+-- that leak into an LLM context when an agent samples a real table.
+-- All values are fake. Run against a throwaway database only.
+
+DROP TABLE IF EXISTS customers;
+
+CREATE TABLE customers (
+    id          serial PRIMARY KEY,
+    name        text,
+    email       text,
+    phone       text,
+    ssn         text,
+    credit_card text,
+    stripe_key  text,   -- secret accidentally stored in a row (it happens)
+    session_jwt text,
+    last_ip     text
+);
+
+-- The stripe_key values are split with || so no secret-shaped literal lands in
+-- git (GitHub push protection rejects contiguous sk_live_ patterns). Postgres
+-- reconstructs the full value at query time, so the redactor still fires on it.
+INSERT INTO customers (name, email, phone, ssn, credit_card, stripe_key, session_jwt, last_ip) VALUES
+('Jane Acme',  'jane@acme.com',     '+1 415 555 0132', '123-45-6789', '4242 4242 4242 4242',
+ 'sk_' || 'live_4eC39HqLyjFAKEdemoT1zdp7dc',
+ 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMifQ.s5_3Vg7Qktype_demo_signature_xx', '203.0.113.7'),
+('Raj Patel',  'raj.patel@globex.io','+44 20 7946 0991','987-65-4321', '5555 5555 5555 4444',
+ 'sk_' || 'live_51HxQ2eLkCm0FAKEdemoKEYexampleZZ',
+ 'eyJhbGciOiJIUzI1NiJ9.eyJ1aWQiOiI0NDcifQ.demo_sig_do_not_use_in_real_life', '198.51.100.23');

tabulus-0.0.4/demo/tabulus-redactor.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="880" height="430" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13">
+  <rect width="880" height="430" rx="10" fill="#0d1117"/>
+  <text x="24" y="34" fill="#e6edf3" font-size="15" font-weight="700">sample_rows("customers") → what your AI agent receives</text>
+
+  <!-- OFF panel -->
+  <rect x="24" y="54" width="404" height="352" rx="8" fill="#161b22" stroke="#f85149" stroke-width="1.5"/>
+  <text x="40" y="80" fill="#f85149" font-weight="700">TABULUS_REDACT=off</text>
+  <text x="40" y="98" fill="#8b949e" font-size="11">leaks to the LLM ↓</text>
+  <g fill="#c9d1d9">
+    <text x="40" y="128">{</text>
+    <text x="52" y="146">"name": <tspan fill="#a5d6ff">"Jane Acme"</tspan>,</text>
+    <text x="52" y="164">"email": <tspan fill="#ff7b72">"jane@acme.com"</tspan>,</text>
+    <text x="52" y="182">"phone": <tspan fill="#ff7b72">"+1 415 555 0132"</tspan>,</text>
+    <text x="52" y="200">"ssn": <tspan fill="#ff7b72">"123-45-6789"</tspan>,</text>
+    <text x="52" y="218">"credit_card": <tspan fill="#ff7b72">"4242 4242…4242"</tspan>,</text>
+    <text x="52" y="236">"stripe_key": <tspan fill="#ff7b72">"sk_live_4eC39…"</tspan>,</text>
+    <text x="52" y="254">"session_jwt": <tspan fill="#ff7b72">"eyJhbG…3Vg7Qk"</tspan>,</text>
+    <text x="52" y="272">"last_ip": <tspan fill="#ff7b72">"203.0.113.7"</tspan></text>
+    <text x="40" y="290">}</text>
+  </g>
+  <text x="40" y="380" fill="#f85149" font-size="11.5">✗ customer PII + a live-shaped secret shipped to the model</text>
+
+  <!-- arrow -->
+  <text x="436" y="240" fill="#8b949e" font-size="22">→</text>
+
+  <!-- ON panel -->
+  <rect x="452" y="54" width="404" height="352" rx="8" fill="#161b22" stroke="#3fb950" stroke-width="1.5"/>
+  <text x="468" y="80" fill="#3fb950" font-weight="700">TABULUS_REDACT=on</text>
+  <text x="468" y="98" fill="#8b949e" font-size="11">scrubbed before it leaves ↓</text>
+  <g fill="#c9d1d9">
+    <text x="468" y="128">{</text>
+    <text x="480" y="146">"name": <tspan fill="#a5d6ff">"Jane Acme"</tspan>,</text>
+    <text x="480" y="164">"email": <tspan fill="#3fb950">"[REDACTED:email]"</tspan>,</text>
+    <text x="480" y="182">"phone": <tspan fill="#3fb950">"[REDACTED:phone]"</tspan>,</text>
+    <text x="480" y="200">"ssn": <tspan fill="#3fb950">"[REDACTED:ssn]"</tspan>,</text>
+    <text x="480" y="218">"credit_card": <tspan fill="#3fb950">"[REDACTED:credit_card]"</tspan>,</text>
+    <text x="480" y="236">"stripe_key": <tspan fill="#3fb950">"[REDACTED:stripe_key]"</tspan>,</text>
+    <text x="480" y="254">"session_jwt": <tspan fill="#3fb950">"[REDACTED:jwt]"</tspan>,</text>
+    <text x="480" y="272">"last_ip": <tspan fill="#3fb950">"[REDACTED:ipv4]"</tspan></text>
+    <text x="468" y="290">}</text>
+  </g>
+  <text x="468" y="380" fill="#3fb950" font-size="11.5">✓ agent still reasons over the shape — data never left the building</text>
+</svg>

{tabulus-0.0.3 → tabulus-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tabulus"
-version = "0.0.3"
+version = "0.0.4"
 description = "Postgres MCP server — agent-first database workbench"
 authors = [{name = "WalkingMountain"}]
 license = {text = "MIT"}

{tabulus-0.0.3 → tabulus-0.0.4}/src/tabulus/__init__.py

@@ -1,3 +1,3 @@
 """Tabulus — Postgres MCP server for AI agents."""
 
-__version__ = "0.0.3"
+__version__ = "0.0.4"

tabulus-0.0.4/src/tabulus/redactor.py

@@ -0,0 +1,172 @@
+"""PII / secret redactor for tool output before LLM sees it.
+
+Database tools (sample_rows, safe_select, describe_schema's sample_rows)
+return rows from user tables. Those rows often contain customer emails,
+API keys, JWTs, credit cards, SSNs, phone numbers, IPs. Without redaction
+that data ships to Anthropic on every query — brand-killing leak.
+
+Sentinel format: `[REDACTED:type]` — preserves enough structure for the
+LLM to reason ("Stripe call failed with [REDACTED:api_key]") without
+leaking the value.
+
+Conservative philosophy: false positives are cheap, false negatives kill.
+
+Off by default — set TABULUS_REDACT=on to enable.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+
+# Each entry is (kind, pattern, replacement). `replacement` may contain `\1`
+# backreferences to preserve a captured prefix (used by secret_kv to keep the
+# key name and mask only the value). Default replacement is the sentinel.
+def _sentinel(kind: str) -> str:
+    return f"[REDACTED:{kind}]"
+
+
+_PATTERNS: list[tuple[str, re.Pattern[str], str]] = [
+    # ── PEM private key blocks (highest value — never let one leak) ──────────
+    (
+        "private_key",
+        re.compile(
+            r"-----BEGIN[A-Z0-9 ]*PRIVATE KEY-----.*?-----END[A-Z0-9 ]*PRIVATE KEY-----", re.DOTALL
+        ),
+        _sentinel("private_key"),
+    ),
+    # ── JWT (eyJ... three segments) ─────────────────────────────────────────
+    (
+        "jwt",
+        re.compile(r"\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"),
+        _sentinel("jwt"),
+    ),
+    # ── Vendor API keys with distinctive prefixes ───────────────────────────
+    ("anthropic_key", re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}"), _sentinel("anthropic_key")),
+    ("openai_key", re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9]{20,}"), _sentinel("openai_key")),
+    (
+        "stripe_key",
+        re.compile(r"\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{20,}"),
+        _sentinel("stripe_key"),
+    ),
+    (
+        "github_token",
+        re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}"),
+        _sentinel("github_token"),
+    ),
+    ("slack_token", re.compile(r"\bxox[bpars]-[A-Za-z0-9-]{20,}"), _sentinel("slack_token")),
+    ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b"), _sentinel("aws_access_key")),
+    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"), _sentinel("google_api_key")),
+    # ── Google OAuth access token ───────────────────────────────────────────
+    ("google_oauth", re.compile(r"\bya29\.[A-Za-z0-9._-]{20,}"), _sentinel("google_oauth")),
+    # ── Generic secret in key=value / key: value form (keep key, mask value) ─
+    # Gated on a secret-y key name so false positives stay low. Per the module's
+    # philosophy, masking a benign value here is cheaper than leaking a real one.
+    (
+        "secret",
+        re.compile(
+            r"(?i)(\b\w*(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?key"
+            r"|access[_-]?token|client[_-]?secret|private[_-]?key|auth[_-]?token"
+            r"|credentials?|token)\w*\s*[:=]\s*[\"']?)([^\s\"',;]{6,})"
+        ),
+        r"\1[REDACTED:secret]",
+    ),
+    # ── Bearer / Token authorization schemes ────────────────────────────────
+    (
+        "bearer_token",
+        re.compile(r"(?i)\b(?:bearer|token)\s+[A-Za-z0-9._~+/-]{20,}={0,2}"),
+        _sentinel("bearer_token"),
+    ),
+    # ── Credit card (13-19 digits, common groupings) ────────────────────────
+    ("credit_card", re.compile(r"\b(?:\d[ -]*?){13,19}\b"), _sentinel("credit_card")),
+    # ── SSN (US) ────────────────────────────────────────────────────────────
+    ("ssn", re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), _sentinel("ssn")),
+    # ── Email ───────────────────────────────────────────────────────────────
+    (
+        "email",
+        re.compile(
+            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?"
+            r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+\b"
+        ),
+        _sentinel("email"),
+    ),
+    # ── Phone, international: requires a leading + (avoids matching bare number
+    #    runs like "2020 2021 2022"). Groups need no internal separators. ─────
+    (
+        "phone",
+        re.compile(
+            r"(?<![A-Za-z0-9])\+\d{1,3}[\s.-]?\(?\d{2,5}\)?(?:[\s.-]?\d{2,5}){1,3}(?![A-Za-z0-9])"
+        ),
+        _sentinel("phone"),
+    ),
+    # ── Phone, US/local: requires separators between 3-3-4 groups ────────────
+    (
+        "phone",
+        re.compile(r"(?<![A-Za-z0-9])\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}(?![A-Za-z0-9])"),
+        _sentinel("phone"),
+    ),
+    # ── IPv4 ────────────────────────────────────────────────────────────────
+    ("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"), _sentinel("ipv4")),
+    # ── IPv6 (handles :: compression, blocks Class::Path false matches) ─────
+    (
+        "ipv6",
+        re.compile(r"(?<![A-Za-z0-9:])(?:[A-Fa-f0-9]{0,4}:){2,}[A-Fa-f0-9]{0,4}(?![A-Za-z0-9:])"),
+        _sentinel("ipv6"),
+    ),
+]
+
+
+# Column/field names whose VALUE is a secret regardless of its content. A bare
+# password or token sitting in its own field has no in-text signal (no `key=`
+# prefix), so we key off the column name instead. Matched as a substring, so
+# `db_password`, `user_api_key`, `oauth_token` all trigger.
+_SECRET_KEY_RE = re.compile(
+    r"(?i)(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?key"
+    r"|access[_-]?token|client[_-]?secret|private[_-]?key|auth[_-]?token"
+    r"|credentials?|token)"
+)
+
+
+def is_enabled() -> bool:
+    return os.environ.get("TABULUS_REDACT", "off").lower() in ("on", "true", "1", "yes")
+
+
+def redact_string(s: str) -> str:
+    """Replace sensitive substrings with `[REDACTED:type]` sentinels. Idempotent."""
+    if not isinstance(s, str) or not s:
+        return s
+    out = s
+    for _kind, pattern, replacement in _PATTERNS:
+        out = pattern.sub(replacement, out)
+    return out
+
+
+def redact_value(v: Any) -> Any:
+    """Recursively redact str / list / dict / tuple. Dict KEYS NOT redacted."""
+    if isinstance(v, str):
+        return redact_string(v)
+    if isinstance(v, dict):
+        out = {}
+        for k, val in v.items():
+            if (
+                isinstance(k, str)
+                and _SECRET_KEY_RE.search(k)
+                and isinstance(val, (str, int, float))
+                and val != ""
+            ):
+                out[k] = "[REDACTED:secret]"
+            else:
+                out[k] = redact_value(val)
+        return out
+    if isinstance(v, list):
+        return [redact_value(item) for item in v]
+    if isinstance(v, tuple):
+        return tuple(redact_value(item) for item in v)
+    return v
+
+
+def maybe_redact(v: Any) -> Any:
+    """No-op when TABULUS_REDACT is off, redact otherwise."""
+    return redact_value(v) if is_enabled() else v

{tabulus-0.0.3 → tabulus-0.0.4}/tests/test_redactor.py

@@ -31,12 +31,24 @@ from tabulus.redactor import (
         ("AKIAIOSFODNN7EXAMPLE", "aws_access_key"),
         ("AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI", "google_api_key"),
         ("Authorization: Bearer abcdef0123456789abcdef0123456789", "bearer_token"),
+        ("Authorization: Token a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "bearer_token"),
         ("ssn 123-45-6789", "ssn"),
         ("Customer foo@example.com", "email"),
         ("call +1 415-555-1234", "phone"),
         ("at 192.168.1.42", "ipv4"),
         ("addr ::1 down", "ipv6"),
         ("card 4111 1111 1111 1111", "credit_card"),
+        # ── regression: adversarial false-negatives found in audit ──────────
+        (
+            "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA\n-----END RSA PRIVATE KEY-----",
+            "private_key",
+        ),
+        ("ya29.a0AfH6SMBx7kJq_longtokenvaluehere1234567890abcdef", "google_oauth"),
+        ("aws_secret_access_key=wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY", "secret"),
+        ("api_key: 9f8e7d6c5b4a39281706f5e4d3c2b1a0", "secret"),
+        ("client_secret='abcdef123456ghijkl'", "secret"),
+        ("call +91 98765 43210", "phone"),  # international, 5-5 grouping
+        ("ring (415) 555-0132 now", "phone"),  # US parens form
     ],
 )
 def test_pattern_redacted(payload, kind):
@@ -92,6 +104,40 @@ def test_list_of_rows():
     assert out[0]["amount"] == 100
 
 
+def test_secret_column_value_masked():
+    """A value in a secret-named column is masked regardless of its content —
+    a bare password has no in-text signal, so we key off the column name."""
+    inp = {
+        "id": 7,
+        "name": "Jane",
+        "db_password": "hunter2supersecret",
+        "user_api_key": "plainlookingvalue123",
+        "oauth_token": "nostructurehere",
+        "city": "Berlin",
+    }
+    out = redact_value(inp)
+    assert out["db_password"] == "[REDACTED:secret]"
+    assert out["user_api_key"] == "[REDACTED:secret]"
+    assert out["oauth_token"] == "[REDACTED:secret]"
+    # Non-secret columns untouched
+    assert out["name"] == "Jane"
+    assert out["city"] == "Berlin"
+    assert out["id"] == 7
+
+
+def test_no_false_positive_number_runs():
+    """Bare digit runs and UUIDs must NOT be mistaken for phone numbers."""
+    assert redact_string("years 2020 2021 2022 were busy") == "years 2020 2021 2022 were busy"
+    uuid = "550e8400-e29b-41d4-a716-446655440000"
+    assert redact_string(uuid) == uuid
+
+
+def test_benign_keyvalue_preserved():
+    """key=value where the key isn't secret-y stays intact (no over-redaction)."""
+    assert redact_string("monkey=banana12345") == "monkey=banana12345"
+    assert redact_string("status=active") == "status=active"
+
+
 def test_non_string_passthrough():
     assert redact_value(42) == 42
     assert redact_value(3.14) == 3.14

tabulus-0.0.3/README.md

@@ -1,120 +0,0 @@
-# Tabulus
-
-**A Postgres MCP server built for AI agents.**
-
-Tabulus is the database workbench for the AI-augmented developer. Connect Claude
-Code, Cursor, or any MCP-compatible client to your Postgres database and let the
-agent introspect the schema, sample data, and write safe queries — without
-copy-pasting schemas into chat windows.
-
-## Why
-
-Every modern dev workflow now includes an AI agent. Every DB GUI was designed
-before that was true. Tabulus flips the model: **the agent is a first-class
-user, not a sidebar feature.**
-
-What that means in practice:
-
-- Schema introspection optimized for LLM context windows (compact JSON, foreign
-  keys flattened, sample rows inline).
-- Read-only by default — `INSERT`/`UPDATE`/`DELETE`/`DDL` are rejected at the
-  gateway. The agent can't drop your tables.
-- `EXPLAIN` exposed as a tool so the agent can reason about query plans before
-  proposing optimizations.
-- Statement timeout + row cap enforced server-side. No agent can DOS your
-  database by accident.
-- Opt-in PII redactor (`TABULUS_REDACT=on`) scrubs emails, API keys, JWTs,
-  credit cards, phones, and IPs from tool output before the agent sees them.
-
-## Status
-
-**v0.0.1 — alpha.** Postgres only. Stdio MCP transport only. No GUI yet.
-
-## Install
-
-```bash
-pip install tabulus
-```
-
-## Run
-
-```bash
-export DATABASE_URL=postgres://user:pass@host:5432/dbname
-tabulus
-```
-
-Then point your MCP client at the `tabulus` command.
-
-### Claude Code (project-level)
-
-Create `.mcp.json` in your project root:
-
-```jsonc
-{
-  "mcpServers": {
-    "tabulus": {
-      "command": "tabulus",
-      "args": [],
-      "env": {
-        "DATABASE_URL": "postgres://user:pass@host:5432/dbname"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Code in that directory and approve the trust prompt.
-
-### Claude Code (user-level via CLI)
-
-```bash
-claude mcp add tabulus "$(which tabulus)" --env DATABASE_URL=postgres://user:pass@host:5432/dbname
-```
-
-### Cursor
-
-Add to `~/.cursor/mcp_servers.json`:
-
-```jsonc
-{
-  "mcpServers": {
-    "tabulus": {
-      "command": "tabulus",
-      "env": { "DATABASE_URL": "postgres://user:pass@host:5432/dbname" }
-    }
-  }
-}
-```
-
-## Tools
-
-| Tool | Description |
-|---|---|
-| `list_tables` | All tables with row count estimates + sizes |
-| `describe_schema` | Columns, PK, FKs, indexes, sample rows for a table |
-| `sample_rows` | Random sample from a table |
-| `safe_select` | Run a read-only SELECT (write keywords rejected) |
-| `explain` | Get query plan (EXPLAIN FORMAT JSON) |
-
-## Configuration
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `DATABASE_URL` | — (required) | Postgres connection URL |
-| `TABULUS_MAX_ROWS` | `100` | Hard cap on rows returned by any tool |
-| `TABULUS_SAMPLE_SIZE` | `3` | Sample rows included in `describe_schema` |
-| `TABULUS_STATEMENT_TIMEOUT_MS` | `5000` | Server-side query timeout |
-| `TABULUS_REDACT` | `off` | Set `on` to scrub PII (emails, API keys, JWTs, credit cards, phones, IPs) from `sample_rows`, `safe_select`, and `describe_schema` output before the agent sees it. Recommended for production. |
-| `TABULUS_ALLOW_WRITES` | `false` | Set `true` to disable the write block (NOT recommended) |
-
-## Roadmap
-
-- v0.1 — Postgres parity, polished install
-- v0.2 — SQLite adapter
-- v0.3 — MySQL / MariaDB adapter
-- v0.x — Tauri desktop GUI shell on top of the same core
-- v1.0 — Stable, cross-platform, multi-DB
-
-## License
-
-MIT. See [LICENSE](./LICENSE).

tabulus-0.0.3/src/tabulus/redactor.py

@@ -1,96 +0,0 @@
-"""PII / secret redactor for tool output before LLM sees it.
-
-Database tools (sample_rows, safe_select, describe_schema's sample_rows)
-return rows from user tables. Those rows often contain customer emails,
-API keys, JWTs, credit cards, SSNs, phone numbers, IPs. Without redaction
-that data ships to Anthropic on every query — brand-killing leak.
-
-Sentinel format: `[REDACTED:type]` — preserves enough structure for the
-LLM to reason ("Stripe call failed with [REDACTED:api_key]") without
-leaking the value.
-
-Conservative philosophy: false positives are cheap, false negatives kill.
-
-Off by default — set TABULUS_REDACT=on to enable.
-"""
-
-from __future__ import annotations
-
-import os
-import re
-from typing import Any
-
-
-_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
-    # ── JWT (eyJ... three segments) ─────────────────────────────────────────
-    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+")),
-    # ── Vendor API keys with distinctive prefixes ───────────────────────────
-    ("anthropic_key", re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}")),
-    ("openai_key", re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9]{20,}")),
-    ("stripe_key", re.compile(r"\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{20,}")),
-    ("github_token", re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}")),
-    ("slack_token", re.compile(r"\bxox[bpars]-[A-Za-z0-9-]{20,}")),
-    ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
-    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
-    # ── Bearer / Authorization headers ──────────────────────────────────────
-    ("bearer_token", re.compile(r"(?i)bearer\s+[A-Za-z0-9._~+/-]{20,}={0,2}")),
-    # ── Credit card (13-19 digits, common groupings) ────────────────────────
-    ("credit_card", re.compile(r"\b(?:\d[ -]*?){13,19}\b")),
-    # ── SSN (US) ────────────────────────────────────────────────────────────
-    ("ssn", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
-    # ── Email ───────────────────────────────────────────────────────────────
-    (
-        "email",
-        re.compile(
-            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?"
-            r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+\b"
-        ),
-    ),
-    # ── Phone (international + US, conservative) ────────────────────────────
-    (
-        "phone",
-        re.compile(
-            r"(?<![A-Za-z0-9])\+?\d{1,3}[\s.-]?\(?\d{2,4}\)?"
-            r"[\s.-]?\d{3,4}[\s.-]?\d{3,4}(?![A-Za-z0-9])"
-        ),
-    ),
-    # ── IPv4 ────────────────────────────────────────────────────────────────
-    ("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
-    # ── IPv6 (handles :: compression, blocks Class::Path false matches) ─────
-    (
-        "ipv6",
-        re.compile(r"(?<![A-Za-z0-9:])(?:[A-Fa-f0-9]{0,4}:){2,}[A-Fa-f0-9]{0,4}(?![A-Za-z0-9:])"),
-    ),
-]
-
-
-def is_enabled() -> bool:
-    return os.environ.get("TABULUS_REDACT", "off").lower() in ("on", "true", "1", "yes")
-
-
-def redact_string(s: str) -> str:
-    """Replace sensitive substrings with `[REDACTED:type]` sentinels. Idempotent."""
-    if not isinstance(s, str) or not s:
-        return s
-    out = s
-    for kind, pattern in _PATTERNS:
-        out = pattern.sub(f"[REDACTED:{kind}]", out)
-    return out
-
-
-def redact_value(v: Any) -> Any:
-    """Recursively redact str / list / dict / tuple. Dict KEYS NOT redacted."""
-    if isinstance(v, str):
-        return redact_string(v)
-    if isinstance(v, dict):
-        return {k: redact_value(val) for k, val in v.items()}
-    if isinstance(v, list):
-        return [redact_value(item) for item in v]
-    if isinstance(v, tuple):
-        return tuple(redact_value(item) for item in v)
-    return v
-
-
-def maybe_redact(v: Any) -> Any:
-    """No-op when TABULUS_REDACT is off, redact otherwise."""
-    return redact_value(v) if is_enabled() else v