Skip to content

CLI Safety and Audit

radix29 edited this page Oct 31, 2026 · 1 revision

← goSSMS Home · ← CLI

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.

The operation classes

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).

The check

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:

  1. a script above the allowed class — naming the statements above it;
  2. SET PARSEONLY, SET NOEXEC or SET SHOWPLAN_* ON — modes the command line runs itself, not from inside a script;
  3. with --transaction or --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 write layer

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 --allow capped by the ceiling, with query run's wording — a refusal is exit 7 with detectedClass/allowedClass and nothing dialed. A dry run is gated too: --dry-run --allow admin — a dry run still needs the class it previews.
  • --dry-run connects, reads everything the change checks, then runs the write under gosmo's WithScript, which captures the statements instead of sending them. Status OK; the record gains dryRun: "true" and tsql, gosmo's exact batch; the set is planned_change. A test (TestDryRunFidelity) runs every writer both ways and compares the dry run's tsql with the real run's writes statement for statement — what you reviewed is what would run. (query run/plan actual are the exempt pair: their --dry-run classifies and prints no T-SQL.)
  • Before and after: a real run reads the state again and answers the change set (before, requested, after — config adds after_configured/after_running/restart_required), so the answer is the server's, not the request echoed. An after that is not the request is a warning. Every writing run carries dryRun, "false" on a real one.
  • Failures: a write the server refuses is exit 5 (SQL_ERROR) with the change set 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 to PERMISSION_DENIED (exit 9), not exit 8. A refused ALTER DATABASE reports the error that says why, not the contentless Msg 5069. A value gosmo refuses before sending is exit 2.

The flags that lift a check

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 for

Audit log

Every 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}
  • class is what the call reached — the script's class for query run and plan actual, the command's for a writer, the detected class for a refusal. outcome is the envelope's status; exit the exit code.
  • server, database, login are the connection's, resolved without connecting, so a refusal has them too (login is the name, or (integrated)/(entra) for a method without one).
  • args is 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 as sha256:<hex>; sqlSha256 is 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 read connects — after its --allow check, its dry run included — the log is opened for appending; if that fails, the call is refused GENERAL_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".

The three layers together

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.

Clone this wiki locally