CSE Roadmap

Core tier · about 5 hours · 14 parts

Part 8 of 14 · 2 min read

The cost of narrow tools, and a linter that catches design smells first

Narrow tools have a real cost in what they cannot do, and many of their failure modes can be spotted by reading the tool list, before any run.

Design C does 6 of 7 honest tasks. The seventh, "how many tickets are open on each plan," needs a report, and there is no tool for it. That is a real cost of narrow tools. It has four honest fixes: add a narrow tool for that specific report, expose a prepared view with only safe columns, hand the task off to a person or a more privileged workflow, or offer a broad tool behind a strong gate to a different, trusted audience.

Many of the problems a narrow design avoids can be caught even earlier, by reading the tool list itself. lint.py checks a tool list for known design smells. These include a free-form parameter such as sql or command, a description that promises "any" or "arbitrary" power, a tool with no scope at all, money moved with no cap or no approval, a write with no approval step, or an action on an id with no row check.

# from code/mini-privilege/lint.py
if set(t.params) & FREE_FORM_PARAMS:
    out.append(Finding(t.name, "free-form-input", "high", f"{t.name} takes free-form {sorted(set(t.params) & FREE_FORM_PARAMS)[0]}: the model can express anything the backend can do."))
if t.scope is None:
    out.append(Finding(t.name, "no-scope", "high", f"{t.name} needs no permission: every caller can use it."))
if t.effect == "money" and not t.capped:
    out.append(Finding(t.name, "money-without-cap", "high", f"{t.name} moves money with no limit enforced in code."))

Running the linter on the three tool designs: the SQL tool trips three rules (free-form-input, broad-description, and for the read-write version write-without-approval); the narrow set trips none. A deliberately bad tool list (transfer, run_shell, delete_ticket, get_user, each missing a scope, a cap or a row check) trips ten findings, six of them rated high. A linter is not a proof. It finds the shape of a problem, not whether a tool's own code is correct. But it is a cheap first review, and it belongs in continuous integration so a new tool cannot arrive without a scope and a row check.