Repository navigation
CLI Safety and Audit
The command line is safe by default in three layers: every statement is
classified before anything connects; the command's class is gated
against --allow and the profile's ceiling; and every above-read call and
every refusal is recorded in an audit log that cannot be turned off. None
of it replaces the login's permissions — the classifier is a guardrail, the
server is the boundary.
internal/cli/safety puts every statement into a class by its leading
keywords, read with gossms's one T-SQL lexer — a keyword in a comment, literal
or quoted identifier means nothing:
| Class | Examples | Needs |
|---|---|---|
read |
SELECT, USE, SET session options, DECLARE, PRINT, EXECUTE AS; catalog procedures on the read allow-list (sp_help, sp_helptext, sp_spaceused, sp_who2, …); DBCC SHOW_STATISTICS/SQLPERF/OPENTRAN/INPUTBUFFER/TRACESTATUS/USEROPTIONS
|
nothing — the default |
write |
INSERT, UPDATE, DELETE, MERGE, transaction control; a procedure not on the read allow-list; dynamic SQL; OPENQUERY/OPENROWSET
|
--allow write |
ddl |
CREATE/ALTER/DROP of objects, TRUNCATE, SELECT … INTO, DISABLE/ENABLE TRIGGER, UPDATE STATISTICS
|
--allow ddl |
admin |
ALTER DATABASE, ALTER SERVER, logins/users/roles/keys/certificates, GRANT/DENY/REVOKE, BACKUP, RESTORE, KILL, SHUTDOWN, RECONFIGURE, sp_configure, xp_ and msdb procedures off the read list, DBCC off the read list |
--allow admin |
It fails closed: an unrecognised statement, dynamic SQL and a procedure off
the read list are write at least, and a class keyword anywhere in a
statement raises it — a SELECT 1 followed by DISABLE TRIGGER on the next
line (which the splitter merges) is ddl; so is a merged UPDATE STATISTICS,
never UPDATE's write.
gossms query classify --file fix.sql prints each statement's class and why,
without connecting (see
Query and plans).
A run's allowed class is the lower of --allow (default read) and the
profile's ceiling (max_allow, set in the TUI's Connect dialog — no
--allow raises it; an ad hoc call has no ceiling beyond what --allow
asks). The check refuses, before anything connects, the first of:
- a script above the allowed class — naming the statements above it;
-
SET PARSEONLY,SET NOEXECorSET SHOWPLAN_*ON— modes the command line runs itself, not from inside a script; - with
--transactionor--max-rows-affected, anything the wrapper cannot hold or count.
A refusal is BLOCKED, exit 7, with the record carrying detectedClass,
allowedClass and statements (live output):
$ gossms query run --sql "UPDATE Sales.Customer SET X=1 WHERE 1=1;"
STATUS: BLOCKED
COMMAND: query run
DURATION_MS: 0
DETECTED_CLASS: write
ALLOWED_CLASS: read
STATEMENTS: UPDATE Sales.Customer (line 1)
ERROR_CODE: BLOCKED
MESSAGE: the script is write; the allowed class is read
HINT: Re-run with --allow write if the change is intended.
gossms: BLOCKED: the script is write; the allowed class is read
$ echo $?
7
When the ceiling is what refuses, the hint says so instead of pointing at
--allow — raising --allow would not help, and an agent must not try.
Which commands take --allow: query run, plan actual, and every writing
command below. Reads never take it (data export's T-SQL form is fixed at
read — a script above read is refused with a hint pointing at
query run --allow).
The commands that change the server through gosmo share one implementation:
| Command | Class |
|---|---|
server config set / reset
|
admin |
server traceflag on / off
|
admin |
db set · db create · db drop
|
admin |
db scoped-config set |
admin |
monitor kill |
admin |
xevent capture |
admin (it creates a server object) |
data import |
write — ddl with --truncate-first
|
Their shared contract:
-
The gate runs before connecting: the class against
--allowcapped by the ceiling, withquery run's wording — a refusal is exit 7 withdetectedClass/allowedClassand nothing dialed. A dry run is gated too:--dry-run --allow admin— a dry run still needs the class it previews. -
--dry-runconnects, reads everything the change checks, then runs the write under gosmo'sWithScript, which captures the statements instead of sending them. StatusOK; the record gainsdryRun: "true"andtsql, gosmo's exact batch; the set isplanned_change. A test (TestDryRunFidelity) runs every writer both ways and compares the dry run'stsqlwith the real run's writes statement for statement — what you reviewed is what would run. (query run/plan actualare the exempt pair: their--dry-runclassifies and prints no T-SQL.) -
Before and after: a real run reads the state again and answers the
changeset (before,requested,after— config addsafter_configured/after_running/restart_required), so the answer is the server's, not the request echoed. Anafterthat is not the request is a warning. Every writing run carriesdryRun,"false"on a real one. -
Failures: a write the server refuses is exit 5 (
SQL_ERROR) with thechangeset still read back, so what landed shows; the first failure stops a multi-step run. Msg 15247 ("does not exist or you do not have permissions") on a writing command — which has just read the name — maps toPERMISSION_DENIED(exit 9), not exit 8. A refusedALTER DATABASEreports the error that says why, not the contentless Msg 5069. A value gosmo refuses before sending is exit 2.
They lift gossms's own checks — never the server's:
| Flag | Where | Lifts |
|---|---|---|
--accept-risk |
server config set/reset |
A value blocked as risky: memory above physical, max below min, MAXDOP above the CPUs (it fails closed when the figure is unreadable — blocked then too) |
--override |
server config set/reset |
RECONFIGURE WITH OVERRIDE (e.g. recovery interval (min) above 60) |
--confirm <name> |
db set (with --rollback-immediate), data import (with --truncate-first), db drop and monitor kill (always) |
Nothing — its absence blocks. The name/spid must match exactly as given (087 is not 87), or BLOCKED exit 7 before connecting. --close-connections does not stand in for db drop's |
--force |
Global, one meaning | Replace an existing file the command writes: --out-file, --plan-file, --script-file, the .xdl files |
The designed workflow for any change (agent guide rule 3):
gossms server config set maxdop 4 -p prod --allow admin --dry-run # 1. see the exact batch
# show a human; get approval
gossms server config set maxdop 4 -p prod --allow admin # 2. run; the change set is read back
gossms query classify --file fix.sql --allow write # 1. is it really a write?
gossms query run -p dev --file fix.sql --allow write \
--transaction rollback # 2. run it, keep nothing
gossms query run -p dev --file fix.sql --allow write \
--max-rows-affected 10 # 3. commit a change you sized forEvery call that reaches a class above read, and every refusal
(BLOCKED), appends one JSON line to audit.jsonl beside config.json
(os.UserConfigDir()/gossms/), created owner-only (0600). Reads are not
logged. The log is always on: no option, environment variable or profile
field turns it off.
{"ts":"2026-10-30T09:12:44.031Z","profile":"dev","server":"devsrv,1500","database":"app","login":"agent","command":"query run","class":"write","dryRun":false,"args":["--sql=sha256:5f1c…","--profile=dev","--allow=write"],"sqlSha256":"5f1c…","outcome":"ok","exit":0}-
classis what the call reached — the script's class forquery runandplan actual, the command's for a writer, the detected class for a refusal.outcomeis the envelope's status;exitthe exit code. -
server,database,loginare the connection's, resolved without connecting, so a refusal has them too (loginis the name, or(integrated)/(entra)for a method without one). -
argsis the command line rebuilt from the parse — positionals, then each option given (command line or environment) as--name=value— so a response file or a short alias records alike. Options carrying T-SQL or data (--sql,--sql-base64,--param,--where) are recorded assha256:<hex>;sqlSha256is the hash of the script as read (the file's text for--file, whose path is recorded as given). A password never reaches the command line, so it never reaches the log. - Lines are appended under the file's lock, so concurrent calls never interleave. The log is never rotated or trimmed by gossms.
-
A change the log cannot record is not made. Before a call above
readconnects — after its--allowcheck, its dry run included — the log is opened for appending; if that fails, the call is refusedGENERAL_ERROR(exit 1) naming the reason. Reads still run; if the append itself fails after the call ran, the result carries a warning.
Reviewing it: audit.jsonl is one JSON object per line — tail -f, jq,
your cron mailer. command, class, outcome and exit are all you need
for "what did the agent do, and what did it get refused".
| Layer | Question it answers | Fails how |
|---|---|---|
| Classifier | What is this script? | Fails closed to write+; exit 7 at the check |
Gate (--allow ∧ ceiling) |
Is this call allowed to do that? | exit 7 before connecting; hints name --allow or the ceiling |
| Server permissions | May this login at all? | exit 5/9 mid-run; the hint names the permission (agent context predicts it) |
Plus the audit line for anything above read, and the change set for anything
that ran — so a refused write leaves a record, and an applied one leaves
proof in the server's own values.
- Getting connected
- Browsing and editing
- Diagnosing and tuning
- Server features