STACIO WIKI · Security Guide

Stacio Security and Governance Guide

1. Security boundaries

Stacio is designed to place remote work in a local workflow that is visible, confirmable, redacted, and traceable. It is not:

• a remote-host identity and access-management system;
• a replacement for a firewall, bastion approval workflow, or zero-trust gateway;
• a centralized SIEM, tamper-proof audit trail, or compliance archive;
• a database backup, disaster-recovery, or business-continuity platform;
• an OS sandbox that can guarantee every internal behavior of a third-party local Agent.

Security responsibility is shared by the Mac, Stacio, remote accounts, network, and organizational process.

2. Local data and sensitive assets

2.1 Data location

The default Application Support directory is:

~/Library/Application Support/Stacio/

Major data in the current implementation includes:

Use Settings > Security > Local Storage to copy the active path. Do not hard-code a user-data path solely from this guide.

2.2 Local credential store

Current Stacio connection credentials are kept in a local encrypted credential store. Settings do not reveal secret plaintext. Operating rules:

• the session database stores credential IDs and account references only;
• lists show type, label, and account, not the secret;
• deleting a session does not automatically delete a credential so shared credentials are not removed accidentally;
• before deleting a credential reference, confirm no other session uses it;
• when migrating, backing up, or restoring Application Support, treat the credential store and session database as one protected dataset;
• if the credential-store key is lost or its files are damaged, credentials may need to be saved again.

The Stacio local credential store is not a remote key-management system. Organizations still need credential rotation, least privilege, offboarding, and emergency revocation.

2.3 Private keys

Stacio stores a private-key path and reads key contents from the local file during authentication. Governance requirements:

• private-key permissions allow only authorized users to read it;
• never copy a private key into a project repository, session export, log, or feedback report;
• keep its passphrase in the credential store, not in a connection script;
• revoke the corresponding public key and rotate it immediately when a device is lost, a person leaves, or exposure is suspected.

3. SSH host identity

Stacio probes and validates an SSH host key before authentication. A first connection needs user confirmation; a changed saved fingerprint is blocked by default.

3.1 Address and port are identity boundaries too

Stacio saves SSH trust by configured host string plus port. Record common IP connections as complete endpoints:

192.168.1.20:22
192.168.1.20:2222
server.example.com:22

These are independent connection identities. Different ports on the same IP can use different NAT rules or reach different SSH services; connecting to the same server by IP and hostname also creates separate trust prompts. Do not copy trust from one endpoint to bypass fingerprint verification for another.

Direct IP reduces DNS dependence but does not eliminate address reuse, NAT changes, or man-in-the-middle risk. Hostnames help address migration but require DNS governance. In either case, decide from a host fingerprint supplied through an independent trusted channel.

3.2 Trust workflow

1. Obtain the expected fingerprint from a cloud console, CMDB, asset administrator, or independent trusted channel.
2. Compare host, port, algorithm, and SHA-256 fingerprint.
3. Accept only after confirming the target is genuine.
4. Include the first trust decision in asset onboarding or session-delivery records.

3.3 Fingerprint-change governance

Treat a fingerprint change as a security incident until it is proven to be authorized:

• pause connection and automation;
• inspect DNS, IP, VPN, ProxyJump, and asset rebuild records;
• verify the new fingerprint through an independent channel;
• record old/new fingerprint summaries, change request, confirmer, and time;
• update trust only after confirmation; there is no silent "connect first" path.

ProxyJump verifies the jump host and target host separately. Do not validate only one side.

4. Protocol and network governance

4.1 Protocol choice

4.2 Tunnel listening

• Local and Dynamic tunnels bind to 127.0.0.1 by default;
• binding 0.0.0.0, ::, or a LAN address increases exposure;
• a Dynamic tunnel is a SOCKS5 proxy and a non-local listener can become a LAN proxy entry point;
• a Remote tunnel can expose a local or private-network service to the SSH-server side;
• before starting, record purpose, listening address, port, target, owner, and stop time;
• stop tunnels as soon as they are no longer needed and check running-tunnel prompts before quitting Stacio.

5. Command risk and approvals

5.1 Risk categories

Stacio classifies AI/Agent commands into four risks:

Classification reduces mistakes; it does not prove any command has no side effects. Even a read-only command can create load, read sensitive data, or activate remote-tool behavior.

5.2 Global policy

Settings > AI and Execution and Settings > Security provide command-confirmation policies:

• Automatic for All;
• Automatic for Low Risk;
• Automatic for Read-only;
• Confirm Every Time.

Recommended defaults:

• personal development: Automatic for Read-only or Low Risk;
• shared testing: Automatic for Read-only;
• production: Confirm Every Time.

Automatic for All is not suitable as a production default.

5.3 Session overrides

A session can further set:

• Block Execution;
• Command Cards Only;
• Automatic for Read-only;
• Confirm Every Command;
• Follow Global.

Denies, production environment, and stricter session policy can override ordinary global allowance. A session policy only tightens authority; it must not become a way around organizational approval.

5.4 Allow and deny patterns

Automatic-allow and deny patterns match command prefixes case-insensitively and skip common wrappers such as sudo and env. Governance requirements:

• deny patterns take precedence;
• keep patterns specific, such as a complete read-only subcommand;
• do not allow broad prefixes for entire shells, interpreters, or package managers;
• verify changes in a development session before applying them to production;
• periodically review patterns that are no longer used.

6. MultiExec governance

MultiExec synchronizes input to several terminals and is a high-impact capability:

1. Confirm the complete target list and each target's environment before use.
2. Select at least two executable terminals before entering the MultiExec workspace.
3. Any production target requires explicit confirmation.
4. The UI keeps a visible broadcast state and can pause one terminal individually.
5. Broadcast events record target count, success count, failure count, and redacted input.
6. Report results by target; "sent" never means every host succeeded.

Do not bypass production confirmation by mislabeling an environment, copying a production session as development, or editing local records.

7. AI and Agent governance

7.1 Terminal context

An AI request can contain current terminal title, directory, and recent output. Before sending, consider:

• whether output contains customer data, secrets, database results, or internal addresses;
• the model provider, Base URL, and data-processing policy;
• whether the context-character limit exceeds what the task needs;
• whether Recent Terminal Output can be disabled and only necessary summaries supplied.

API keys are stored only in the Stacio local credential store. Exporting AI configuration or diagnostics must not include an API key.

7.2 Troubleshooting assistant versus local Agent

• The troubleshooting assistant can use Stacio's code-enforced gates for backup, validation, rollback, and result checks.
• A local Agent is an independent CLI; Stacio controls remote commands issued through Agent Bridge, their approvals, and audit.
• Stacio cannot guarantee that every local file operation, network request, or inference step of a third-party Agent enters the same state machine.
• Operational contracts such as AGENTS.md, CLAUDE.md, and QWEN.md are guidance, not OS-level mandatory sandboxes.

For that reason, a local Agent workspace must not have more Mac-file or remote-account permission than the task needs.

7.3 Backup and validation gate

For a change to configuration, deployment, data, or remote files:

1. Create a new backup for each change; do not reuse evidence from an earlier backup.
2. Verify that the backup path exists and is recoverable.
3. Run targeted validation after the change.
4. Stop further changes as soon as validation fails.
5. Roll back after approval and validate the recovered state again.
6. Include backup location, validation result, rollback method, and residual risk in the final report.

8. File and data governance

8.1 Remote file operations

• The local user chooses the download target to prevent an untrusted remote path from controlling local placement.
• Confirm the complete path before delete, overwrite, rename, or chmod.
• Before Remote Edit saves, check whether somebody else changed the remote file.
• Use Files backup or a platform-native backup for important files; do not rely only on edit cache.
• Local copies created by an external editor can contain business data and must follow its data classification.

8.2 Transfer conflicts

Use Ask Every Time by default. Automatic overwrite can suit controlled build artifacts, but not configuration, database files, customer data, or directories edited by several people.

8.3 Cache cleanup

Settings > Files > Cache Maintenance clears Stacio-managed Remote Edit and temporary-remote-file cache only. It does not delete the session database, credentials, download folders, or real user files. If unsaved edits exist, Stacio explicitly warns that they will be lost.

9. Logs, audit, and diagnostics

9.1 Recorded scope

Local Stacio audit helps answer:

• what kind of initiator performed an operation;
• which target session or runtime was involved;
• risk level and approval outcome;
• whether execution started, completed, failed, or was cancelled;
• how many MultiExec targets sent successfully or failed.

Audit content is redacted; it is not intended to preserve secrets or complete business logs.

9.2 Diagnostic export

In Settings > Security, configure:

• audit records to export;
• application-log lines to export;
• whether a diagnostic bundle includes application logs.

Preview manually before exporting through View > Diagnostics. Automatic redaction reduces risk but cannot guarantee that every business-sensitive item is recognized.

9.3 Feedback

Help > Feedback shows proposed cleaned diagnostic information and requires user consent. Before submission, still inspect title, description, and preview; do not paste raw terminal output, file content, environment variables, or credentials.

10. Data retention and deletion

Define clear team retention periods:

Deleting a session, clearing cache, deleting a credential reference, and clearing AI history are different actions. Do not assume one performs the others.

11. License governance

License state controls advanced capabilities such as MultiExec, AI Agent, bastion-host integration, SSH tunnels, device dashboard, file sync, ProxyJump, and batch session import/export.

• Use Help > License to check state, edition, expiration, and grace period.
• After a valid entitlement is persisted, it can be used offline until state or validity no longer permits it.
• An offline authorization file must validate signature, device, and identity.
• The client contains public verification material only; backend signing keys must never enter the client, Git, logs, or an installer.
• A License is neither remote permission nor organizational change approval.

12. Security incident response

12.1 Suspected credential exposure

1. Stop using related sessions, Agents, and tunnels.
2. Revoke affected passwords, tokens, keys, or certificates in the remote or identity system.
3. Inspect audit records, login logs, and anomalous sources.
4. Preserve necessary evidence, then clear local credential references and cache.
5. Create new credentials with minimum privilege.
6. Verify the old credentials can no longer be used.

12.2 Lost device or compromised Mac

1. Lock or wipe the device remotely where organizational capability permits.
2. Revoke every remote credential that could have been stored on the Mac.
3. Review SSH public keys, API keys, tokens, bastion sessions, and License sessions.
4. Review remote login and change records.
5. Do not treat local credential encryption as a reason not to revoke.

12.3 Host-key anomaly

Stop connecting immediately and perform the independent verification in section 3. Escalate to security and asset owners if authorized rotation cannot be proven.

12.4 Suspicious Agent or MultiExec operation

1. Pause or cancel the task.
2. Stop related tunnels and further broadcast.
3. Preserve redacted request ID, target, approval, and execution state.
4. Check whether the remote system actually changed.
5. Restore from a verified backup and run targeted validation.
6. Tighten session policy, global approvals, and allow patterns.

13. Team-governance baseline

• Every production session has an owner, environment, purpose, and least-privilege account.
• Every jump host, tunnel, and automation has a defined scope and stop condition.
• Initial host-fingerprint trust and rotation have independent verification records.
• Production MultiExec and Agent changes are confirmed command by command.
• Important configuration changes are backed up first, validated afterward, and rollbackable when they fail.
• Credentials, sessions, cache, logs, and diagnostic bundles have retention and destruction periods.
• Review License, credential references, automatic-allow patterns, and stale sessions every quarter.
• The team documents which controls are code-enforced by Stacio and which depend on a local Agent following an operational contract.

For the corresponding user-facing controls, see this guide and Agent Capabilities and Security.