Use cases

Secronyx is one binary with 530 read-only tools, nineteen scopes and six ways to authenticate a caller. Which subset you turn on depends on who is asking questions and what they are allowed to learn. This page works through five situations the server was built for. For each it names the tools involved (every name below is registered by the current build and appears in the Tool reference), the scopes those tools carry, and the authentication that suits the population of callers. Flags are from cmd/secronyx/main.go; the full list is on the Configuration reference.

How to read the recommendations

Two controls shape every deployment:

• --scopes decides which tools exist at all. A tool outside the list is never registered, is absent from tools/list on every transport, and answers Tool not found if called. sensitive is never registered without --enable-sensitive, and when --scopes is given the flag does not widen that list: sensitive must also appear in it.
• The identity's scope grants decide what an authenticated HTTP caller may invoke. API keys carry scopes in their record, SSH keys carry scopes= on their authorized_keys line, OIDC and introspected tokens carry scope claims, and a static --token always carries *.

The first control is the safety net; the second is where you differentiate callers. See Scopes and authorization for the mechanics.

Managed service provider with regulated clients

An MSP runs hosts for several clients, some of whom are audited. Engineers rotate, clients ask who looked at what, and a client's data must never appear in another client's ticket. The model answers a support question by reading the host; a human still makes any change.

Configuration. One server per host, so there is no tenant concept to get wrong: a credential is valid for the host it was issued on and nowhere else. Give each engineer their own credential rather than sharing a token:

# On the host: a key per engineer, expiring, pinned to the bastion range
secronyx apikey create --file /etc/secronyx/keys.json \
  --name alice --scopes core,logs,hooks,triage,security --expires 90d --cidr 10.20.0.0/16

secronyx --transport http --listen 0.0.0.0:8443 \
  --tls-cert /etc/secronyx/cert.pem --tls-key /etc/secronyx/key.pem \
  --api-keys-file /etc/secronyx/keys.json \
  --scopes core,logs,hooks,triage,security,software,storage \
  --audit-output /var/log/secronyx/audit.jsonl --audit-sync-write

The key's name becomes the identity on every audit event, allowed_cidrs refuses the key from anywhere but the MSP's own network, and apikey revoke takes effect on the next reload without a restart. Engineers who already hold SSH keys can instead sign requests with them (--ssh-authorized-keys, with scopes=, from= and expires= options on each line); see Tutorial: SSH key request signing. Leave sensitive off on client hosts: nothing in a routine support conversation needs get_env_vars or get_sudo_config. Hosts behind a client firewall can run the outbound-only hybrid mode instead of listening; see Hybrid and SaaS mode and Fleet deployment.

Tools. The triage summaries do most of the work: get_incident_triage_snapshot, get_security_posture_snapshot, get_os_info, get_system_profile, get_exposed_services_summary, get_recent_service_failures, get_failed_units and get_recently_installed_software (all triage). Patch state comes from get_windows_update_health, get_linux_auto_updates (security) and get_macos_software_update_config (state); package inventory from get_system_packages and get_windows_hotfixes (software). Note the descriptions of the two snapshot tools: on macOS they can take one to five minutes because they query the unified log.

Evidence for the client. Ship audit.jsonl to the client's SIEM as well as your own, and run secronyx --audit-verify --audit-output <file> when a client asks whether the trail is intact; it prints the number of events verified and exits non-zero on a broken chain. The check reads the one file named by --audit-output, so rotated files are verified a file at a time. Audit logging explains the hash chain.

Enterprise SRE on-call

An on-call engineer is paged at 03:00. The model is the first responder: it reads the host, narrows the cause, and hands the engineer a hypothesis with evidence. Callers are employees with a corporate identity, tokens are short-lived, and nobody wants to manage another credential store.

Configuration. Use the IdP the engineers already log in with. The server validates JWTs locally against the issuer's JWKS, so the IdP is not on the request path once keys are cached:

secronyx --transport http --listen 0.0.0.0:8443 \
  --tls-cert /etc/secronyx/cert.pem --tls-key /etc/secronyx/key.pem \
  --oidc-issuer https://login.example.com --oidc-audience secronyx \
  --oidc-max-token-lifetime 8h --oidc-require-jti \
  --scopes core,logs,hooks,resources,triage,storage,network,enhanced,alerts

Have the IdP issue scope claims in the namespaced form (mcp:tools:core, mcp:tools:logs) so they do not collide with other resources; the bare mcp:tools grants nothing. --oidc-require-jti makes every token single-use, which is the right property for a diagnostic session but means the client must mint a token per request. Details are under Authentication.

Tools. For a slow or unresponsive host: get_cpu_info, get_processes_sampled (CPU percentages from a real time-delta sample), get_memory_info, get_disk_info (core); get_disk_io (hooks), get_io_latency (storage); get_cgroups, get_process_tree, get_file_descriptor_usage, get_blocked_processes (resources); get_oom_events (enhanced). For a failing service: get_recent_service_failures, get_failed_units, get_service_log_view, get_deployment_events, get_recent_config_changes, get_recent_reboots, get_recent_kernel_events (triage) and get_journal_logs or get_event_log (logs). For "is it the network": get_listening_ports (hooks), get_socket_summary, get_connection_tracking and get_network_latency (network); the last reaches out to its targets, and every target is resolved and checked against the probe policy before the connection is made, as described on the Network and path policy page. get_alert_status and get_runbook_recommendations (alerts) give the model a starting point. Tutorial: diagnose a slow Linux host walks through this sequence.

Compliance evidence collection

A control owner needs a repeatable, dated statement of each host's configuration: hardening checks against a named framework, an inventory of installed software, and a record of who collected it. The collector is a scheduled job, not a person.

Configuration. A job wants a credential that does not depend on an IdP being reachable at 02:00 on a Sunday. Issue an API key with exactly the scopes the job needs and a CIDR pin to the scheduler:

secronyx apikey create --file /etc/secronyx/keys.json \
  --name compliance-runner --scopes compliance,security,software,triage,state \
  --expires 30d --cidr 10.0.5.10/32

Run the server with --audit-sync-write so the audit event for each collection is durable before the result is returned, and keep --audit-max-files high enough for your retention period. Large results are the main practical issue: an SBOM for a host with many packages can exceed the 4 MiB result cap and come back as result too large; raise --max-result-bytes for the collection listener or use the per-ecosystem package tools instead.

Tools. get_compliance_check with framework set to cis, pci or hipaa on Linux, cis or stig on Windows, cis or apple on macOS (anything else runs the "Basic Security" set); get_security_scan, get_hardening_recommendations and get_audit_trail (all compliance). Platform controls: get_linux_auditd_status, get_windows_audit_policy, get_windows_local_security_policy, get_windows_gpo_applied, get_bitlocker_status, get_macos_filevault_status, get_macos_mdm_profiles (security); get_password_policy (state); get_admin_account_summary and get_ssh_security_summary (triage). Inventory: get_sbom_cyclonedx, get_sbom_spdx, get_system_packages, get_windows_hotfixes (software). Be aware that get_vulnerabilities_osv, get_vulnerabilities_nvd and get_vulnerabilities_debian query api.osv.dev, services.nvd.nist.gov and security-tracker.debian.org respectively; if the host must not make outbound calls, omit them. What the checks cover and how their results map to frameworks is on the Compliance mapping page.

{"jsonrpc":"2.0","id":7,"method":"tools/call",
 "params":{"name":"get_compliance_check","arguments":{"framework":"cis"}}}

Security incident triage

A host is suspected of compromise. The responder needs a snapshot of processes, connections, logins and persistence mechanisms before anything is touched, and needs the collection itself to be attributable and tamper-evident. Some of what they need lives in the sensitive scope.

Configuration. Run a separate listener for incident response, or restart the host's server with --enable-sensitive for the duration, so that the default support configuration never exposes accounts and sudo rules. Responders should authenticate with something that proves possession of a key and resists replay: SSH request signing or mutual TLS.

secronyx --transport http --listen 0.0.0.0:8444 \
  --tls-cert /etc/secronyx/cert.pem --tls-key /etc/secronyx/key.pem \
  --ssh-ca-keys /etc/secronyx/ir-ca.pub \
  --scopes core,logs,hooks,resources,state,security,triage,compliance,network,windows,sensitive \
  --enable-sensitive \
  --audit-output /var/log/secronyx/ir-audit.jsonl --audit-sync-write

sensitive appears in --scopes as well as --enable-sensitive, because a non-empty --scopes list is the whole set of scopes that get registered and the flag does not add to it.

Every signed request carries a timestamp and nonce; the verifier rejects timestamps outside a five-minute window and any nonce seen in the last ten minutes, so a captured request cannot be replayed. With --ssh-ca-keys the responder presents a short-lived SSH certificate whose principals and secronyx-scopes extension the CA controls. Tutorial: mutual TLS end to end covers the certificate alternative.

Tools. Start with get_forensic_snapshot (compliance): system facts, users, processes with redacted command lines, network connections, open files and recent logins under one snapshot_id. Then get_audit_trail with hours (default 24) for authentication, privilege-escalation and service events; the sources differ by platform (sshd, sudo, systemd and auditd on Linux, the Security, System and Application event logs on Windows, Authorization, sudo and installer on macOS). Persistence: get_scheduled_tasks, get_cron_jobs, get_startup_items, get_kernel_modules (hooks); get_macos_launchd_jobs, get_macos_login_items (state). Privilege and exposure: get_setuid_binaries, get_world_writable_paths, get_ssh_host_keys (security); get_admin_account_summary, get_auth_failure_summary, get_exposed_services_summary (triage); get_login_history, get_login_sessions (state). With --enable-sensitive: get_auth_logs, get_user_accounts, get_sudo_config, get_ssh_config, get_process_environ. On Windows add get_event_log (logs), get_windows_defender_status (security) and get_wer_reports (windows); on macOS get_macos_security_log_events (security).

Nothing here contains the incident. There is no tool that kills a process, blocks an address or disables an account; containment goes through your existing change path with the snapshot attached. See Tutorial: verify the audit chain for preserving the collection record.

Capacity review

A quarterly review asks whether hosts are heading for exhaustion and whether the current sizing is justified. Callers are a scheduled report and, occasionally, an engineer asking a follow-up.

Configuration. A read-only API key limited to the analytics and storage scopes is enough; there is no reason for this credential to see logs or processes:

secronyx apikey create --file /etc/secronyx/keys.json \
  --name capacity-report --scopes core,analytics,storage,hooks,state,report --expires 365d

Tools. get_historical_metrics, get_trend_analysis (both take period of 1h, 24h or 7d), get_capacity_forecast and get_anomaly_detection (analytics); get_disk_info, get_memory_info, get_cpu_info (core); get_inode_usage, get_disk_io (hooks); get_smart_health, get_volume_status, get_log_directory_usage, get_quota_info (storage); get_numa_topology (state) and get_resource_limits (triage) for the sizing conversation; generate_system_report (report) collects its sections in parallel (all of them unless sections names a subset, under a timeout_seconds that defaults to 30) and returns JSON suitable for binding to a template.

Read the caveats the analytics tools attach before quoting a number. The history the server keeps is in-process, so a forecast produced shortly after start-up says current usage only: no trend evidence, do not infer time-to-full from this result, and one produced later says extrapolated from in-process samples, not from a persistent metrics store with a confidence capped at 90. A single reading is reported as single reading: direction and slope are not measured; this is a snapshot, not a trend. The tool tells you when it does not know; a review should repeat that rather than round it away.

Summary

In every case audit logging and redaction stay at their defaults (on), and the listener is either loopback or TLS with authentication: an unauthenticated listener, or an authenticated one without TLS, on a non-loopback address is refused at startup unless --allow-unauthenticated (or SECRONYX_ALLOW_UNAUTHENTICATED=1) is set, which is a development aid. Related pages: Security model, Compared with alternatives, FAQ, and the Secronyx homepage.