Configuration

Engine options, identity mappings, client settings and policy facts serve different purposes. Changing one does not automatically change the others: a working connection does not grant an action permission, and a policy role check does not configure who receives that role.

Engine process

Prepare the engine binary, certificates and local files using building and local setup. Configure an independent full API key for each principal as described in authentication; the example below assumes config/auth/apikey.json contains those literal keys.

Start the full engine explicitly:

unset SASY_API_KEY_SUFFIX
sasy-services/target/debug/sasy serve \
  --addr 127.0.0.1:50051 \
  --auth-provider config/auth/apikey.json \
  --auth-config config/auth_config.yaml \
  --transforms config/transforms.json \
  --tls-cert certs/server.crt \
  --tls-key certs/server.key \
  --data-dir data/graph \
  --credentials-db data/credentials.db

Keep suffix composition disabled on the server when using literal keys. Paths are relative to the process’s working directory. Use a persistent data directory if policy bindings and observations must survive restarts.

Setting	Purpose and direct CLI default
--addr	gRPC listener; 127.0.0.1:50051.
--data-dir	Graph and engine state; data/graph.
--auth-provider	Provider JSON file; no implicit authenticated provider. Startup refuses missing authentication unless local no-auth mode is explicitly enabled.
--auth-config	Entity-to-role and tenant mappings in YAML.
--tls-cert, --tls-key	Enable server TLS; not automatically enabled by bare sasy serve.
--tls-ca	Trust root for verifying client certificates when using mTLS.
--evaluator	Full-engine policy backend; souffle.
--query-timeout-secs	Query deadline; 10. An overrun fails closed.
--evaluator-stall-secs	Unresponsive evaluator recovery threshold; 60, and must be at least the query deadline.
--proxy-port	Separate HTTP forward proxy; 0 disables it.

--policy-metadata and --policy are aliases for the same source-file option. The full engine compiles that source for Soufflé backends and reads its annotations; they are not separate logic and metadata inputs. See the engine environment reference for runtime variables and the engine CLI reference for every sasy serve option. The restricted guard engine runs its baked profiles; it does not acquire arbitrary policy compilation support by changing --evaluator or passing a source file. The forward proxy is a separate, unauthenticated-per-request listener; enabling it requires deliberate network and tenant configuration.

Raw forward proxy

The raw HTTP forward proxy does not authenticate callers. Anyone who can reach its listener can use the configured tenant’s stored credentials against hosts allowed by policy. Keep the loopback default (--proxy-bind 127.0.0.1), or isolate access at the network boundary; --proxy-tenant pins one tenant per listener, not a caller identity. Raw requests have no input-message ancestry.

For plain HTTP forwarding, the raw proxy returns the upstream status and body but drops upstream response headers, including content type, cookies and cache controls. It is not a transparent general-purpose HTTP proxy. CONNECT relays encrypted bytes without credential injection or inspection of inner requests. These limitations concern the separate raw listener, not the authenticated gRPC ProxyHTTP API.

Identity and roles

The provider file maps each full key to its authenticated identity, such as worker. The role file then describes what that identity may do:

default_tenant: default
entities:
  worker:
    tenant: default
    roles:
      - reference-monitor-user
      - observability-writer
      - observability-reader

Use the provider’s authenticated identity value as the entity key. A missing mapping has no configured roles; omitting an entity’s tenant uses default_tenant. Role names such as reference-monitor-user authorize service APIs. A policy can impose additional action-specific requirements with HasRole(...).

JWT claim mapping and mTLS identity configuration are described in authentication. Credential sources and --transforms configure secrets used for approved request transforms; they do not replace caller authentication.

Python client and session policy

Configure the SDK endpoint and trust explicitly. Set SASY_API_KEY to the complete key provisioned for this client; do not send a key name or construct another principal’s credential. This example connects to the engine above:

from pathlib import Path
import os
import sasy
from sasy.auth.hooks import APIKeyAuthHook

sasy.configure(
    sasy_url="localhost:50051",
    ca_path="certs/server.crt",
    auth_hook=APIKeyAuthHook(api_key=os.environ["SASY_API_KEY"]),
)

with sasy.session(policy=Path("read-only.dl")):
    # Record context and check actions through the instrumentation APIs.
    pass

A Path loads a policy file; a plain string is interpreted as policy source. Omitting policy uses the tenant default. A session’s policy binding and its recorded graph are separate from the SDK’s connection settings. Supply policy_metadata=[("setting", "value", "")] when entering the session to provide policy configuration facts; those facts matter only if the policy reads them. ActionMetadata instead belongs to a particular proposed action.

The SDK also accepts SASY_URL for the endpoint. Supplying an actor through entity= does not change the authenticated principal or grant roles. For mTLS, configure the client’s cert_path and key_path as well as its trusted ca_path.

Guard settings and managed configuration

The guard uses its own settings file, normally ~/.sasy/config.json (SASY_HOME can relocate it). For example:

{
  "mode": "local",
  "policyProfile": "security",
  "failMode": "closed"
}

Local mode manages an engine child and uses mTLS for that connection. Remote mode connects to an externally managed engine. The guard’s hook listener is separate from the engine’s gRPC endpoint: their defaults are ports 51711 and 50051, respectively. failMode: "closed" is the default when the engine is unavailable. Settings such as ruleOn, ruleOff and cooldownDays configure the guard policy; they are not engine CLI flags.

Settings are combined from defaults, the local file, supported environment variables and an administrator-owned managed file. Managed settings can lock or constrain lower layers; this is not unrestricted last-value-wins merging. The managed path is /etc/sasy/managed.json on Linux and /Library/Application Support/SASY/managed.json on macOS. Invalid managed configuration is reported and handled conservatively. Inspect sasy-watch status to see the effective policy and managed state after setup.

Managed configuration does not provide separate operating-system user isolation. See the guard documentation for setup, rule groups and deployment controls, and limits for current isolation and resource boundaries.