Manage SASY guard

SASY guard has two configuration levels: developer settings under ~/.sasy (or SASY_HOME) and an administrator-owned managed file. Managed settings constrain the running daemon. They do not install a system service or move it to another operating-system account.

Install and inspect

Install the platform wheel with uv tool install sasy-guard, then run sasy-guard install and sasy-guard enable /path/to/project. The enable command registers the four Claude Code hooks in the project’s .claude/settings.json. Use sasy-guard doctor to inspect the installed binaries and local configuration.

The installed daemon CLI lives under the guard home; it is not automatically added to PATH:

"${SASY_HOME:-$HOME/.sasy}/bin/sasy-watch" status

status reports the running daemon’s managed settings, rejected keys, active rule groups and configured static-analysis source. Exit zero means it received a well-shaped report; it does not authenticate the process answering on the port or certify enforcement. The daemon log is ${SASY_HOME:-$HOME/.sasy}/logs/daemon.log.

Configuration is read at daemon startup. After changing it, stop the daemon with sasy-watch stop, wait for it to exit, and start it with sasy-watch ensure (using the full path above if necessary). Coordinate this with active sessions. stop sends a termination signal; it does not wait for shutdown. There is no hot reload or fleet control service.

Run safe installation probes

After installing matching guard binaries and policy assets, run:

"${SASY_HOME:-$HOME/.sasy}/bin/sasy-watch" probe

The command starts the installed daemon code and its own engine under a temporary guard home, with fresh engine credentials and a loopback advisory fixture. It sends four fixed proposed package-install requests as data: clean, simulated malicious advisory, recent release, and unavailable advisory service. It never executes those install commands, installs a package, or connects to the ordinary daemon. The synthetic run uses its own configuration rather than the developer’s or organisation’s operational configuration.

The JSON report marks every scenario synthetic and gives expected/observed decisions. approval-required means the hook denies execution pending a user decision; the probe never supplies an approval. Exit zero means all four scenarios passed. A missing or incompatible engine, absent policy assets, timeout or unexpected decision fails the probe. Temporary state and the owned engine are removed on completion or a handled interrupt.

This checks the installed policy path with fixture data. It does not certify normal hook registration, managed settings, live advisory availability, or resistance to a process controlling the same operating-system account. The normal home is read for the installed engine and policy assets and is not changed.

Inspect scan observations

With the ordinary daemon already running:

"${SASY_HOME:-$HOME/.sasy}/bin/sasy-watch" scan-status

This sends an authenticated POST /v1/scan/status; it does not start a daemon or expose scan information through public /healthz. The response reports configured incremental scanning, effective background/enrichment settings, a bounded scanner-version availability check, whether a background pass is running, its last start/completion/outcome and counts, and hashed source/configuration identities. Scanner availability means the version command ran, not that a repository was scanned successfully.

not-run, no-repositories, incomplete and failed remain distinct from a completed pass. observationStale means no pass has completed or the observation is older than two background intervals. Even a fresh completed observation is not a clean-current-tree verdict: findings can remain, commits may have changed, and a push still runs its normal checks. SAST configuration is reported with outcome not-observed; this status collector does not claim to track SAST task completion. Restart clears the in-memory observations.

Requests use the existing private hook bearer. As with other hook requests, this authenticates the caller to an intact daemon but does not authenticate the HTTP response or establish separate-user isolation. The response contains no repository paths, scanner arguments, reports or finding contents.

Deploy managed settings

An administrator supplies JSON at the fixed path below. The file and its containing directory must be root-owned and not writable by group or others; use directory mode 0755 and file mode 0644. Symbolic links are rejected. The check covers the file and its immediate directory, not every ancestor directory.

Platform	Managed file
macOS	/Library/Application Support/SASY/managed.json
Linux and WSL	/etc/sasy/managed.json
Windows	Managed settings are not applied; the ownership check is not implemented.

Choose the engine configuration before deploying a managed file. Its presence suppresses local serve, mode, endpoint and plaintext insecure settings. For a local engine, include the intended serve configuration and connection settings in the managed file; otherwise its local binary will no longer be started. For a remote engine, pin mode: "remote" and your actual endpoint. Provision its certificate files separately through TLS_CA_PATH, TLS_CERT_PATH and TLS_KEY_PATH in the daemon service environment; certificate enrollment and managed-file certificate path fields are not implemented.

The following is a fragment to merge into that engine configuration, not a complete replacement for a working installation. It pins fail-closed daemon behavior and the dependency cooldown:

{
  "failMode": "closed",
  "cooldownDays": 14,
  "secretScanIncremental": true
}

Settings apply in order: defaults, developer configuration, environment variables, then the managed file. Merge behavior depends on the key. A longer local cooldown remains effective; local review thresholds may be lower; local severity actions may be stricter. Managed allowlists replace local allowlists. Presence of an accepted managed file also prevents local settings from switching off rule groups and several other gates, even when the payload omits those keys.

Malformed JSON or failed ownership checks cause the file to be refused. Unknown keys and unusable values are reported as locking nothing. Inspect status and the startup log after deployment; file existence alone does not establish that a setting applied. Compare the installed file’s contents with the administrator’s intended payload.

Local engine credentials and restart

Each daemon launch runs the installed engine’s guard-tls helper to generate a fresh private CA and client/server certificates. Files live in a new 0700 directory under ${SASY_HOME:-$HOME/.sasy}/run; keys are 0600. The CA signing key is never written. The engine accepts the launch client certificate, and the daemon trusts only that launch CA. Certificate identity maps to the installed auth_config.yaml roles; without that file the daemon receives its standard non-admin roles. Caller-supplied role metadata cannot add privileges.

The daemon never adopts an existing local engine. Missing binaries, incompatible versions and occupied ports leave local tool checks denied, including when availability fail-open was selected. Upgrade the daemon and engine together. Graceful stop terminates the child and removes its launch credentials before completing. After a crash, an old engine may still hold the port; identify and stop that known instance before restarting. The guard does not kill an unrelated listener or fall back to plaintext.

sasy-watch check and local bench send requests through the daemon so they use its engine credentials. A check during startup returns a denial until the authenticated engine is ready. Direct gRPC benchmarking remains available in remote mode.

Certificates expire after 30 days. Restart before expiry to issue fresh credentials; there is no in-place renewal. The normal idle shutdown also ends the engine. Readiness requires a successful authenticated health response, and child exit clears readiness. This authenticates the engine connection, not the correctness of a binary an administrator chose to install.

Hooks still use their separate HTTP authentication secret. Their secret authenticates requests to an intact daemon; it does not authenticate the daemon’s HTTP responses or stop a process running as the same user from reading the credentials. The status command remains a diagnostic report, not authenticated fleet attestation.

Static analysis and project settings

SAST is optional. Configure a SARIF input using sastSarifPath; a managed sastCommand is an argument array for an independently installed scanner. Pinning either scanner-source key also governs sastScope. A severity table alone does not configure a scanner. The daemon reports whose input and scanner command it uses.

Repositories may carry .sasy/project.json and .sasy/overrides.json. The guard reads their committed versions at HEAD; the scanner’s scan settings, severity actions and accepted findings have different effects. Managed severity floors prevent softer action tables, but do not prevent project exclusions, finding demotions or fingerprint overrides from removing findings. Pushes changing these project files are flagged for review.

This is not automatic human ratification of arbitrary project configuration. There is no general .sasy/config.json approval store keyed by project, setting and content hash.

Enforcement boundary

The daemon, binaries and hooks normally run as the developer. A process controlling that account can replace or bypass them. Local daemon-to-engine connections use launch-generated mutual TLS. Managed settings do not supply a separate service account or an authenticated fleet status channel.

A managed failMode: "closed" governs daemon decisions. When the daemon is unreachable, hooks consult their own environment; their SASY_FAIL_OPEN escape hatch is not governed by the managed file. Organisations must control hook registration, binaries, environment and service identity separately before treating this as mandatory enforcement. Shell rules interpret command text and assume an aligned agent; they do not establish the behavior of arbitrary programs.

See current limits and build and validation. Public guard information is at guard.sasy.ai.