If you discover a security vulnerability in ghscaff, please report it responsibly.

Do not open a public GitHub issue for security vulnerabilities.

Instead, email: jheison.mb@univerlab.org

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

You should receive an initial response within 72 hours. We will work with you to understand and address the issue before any public disclosure.

ghscaff stores GitHub tokens and template secrets in an encrypted local vault at ~/.ghscaff/vault.enc.

The encryption key is derived from four factors:

Note: The binary path was intentionally removed from key derivation to allow the vault to survive binary relocation (e.g., after cargo install or self-update).

• Theft of ~/.ghscaff/vault.enc — ciphertext is useless without the key factors
• Copying vault to another machine — hostname mismatch prevents decryption
• Other users on the same machine — file permissions restrict access
• Nonce reuse — fresh random nonce generated on every write
• Tampering — Poly1305 authentication tag detects any modification

• Root access — root can read any file regardless of permissions
• Keyloggers / memory dumps — if the passphrase is captured at input time
• Compromised OS — if the attacker controls the machine, they control the vault
• Weak passphrases — the tool warns but allows passphrases under 5 characters

When configuring repository secrets, ghscaff uses NaCl sealed box encryption (libsodium-compatible):

1. GITHUB_TOKEN environment variable (for CI/CD)
2. Encrypted vault (~/.ghscaff/vault.enc)
3. Interactive prompt (first run only, saves to vault)

The tool never prints, logs, or transmits tokens. Token input uses inquire::Password which disables terminal echo.

• All GitHub API calls use HTTPS (via rustls-tls)
• User-Agent is set to ghscaff (no identifying information beyond the tool name)
• The only outbound call besides GitHub API is the update check (GET /repos/UniverLab/ghscaff/releases/latest), which can be disabled with GHSCAFF_NO_UPDATE_CHECK=1

The update checker fetches the latest release tag from GitHub API. If the user approves, it runs the install script from raw.githubusercontent.com. This is the same script used for initial installation.

Mitigation: The update only runs with explicit user confirmation via interactive prompt.

1. Use a scoped token — grant only repo, workflow, and optionally read:org. Do not use a token with admin:org or delete_repo unless necessary.

2. Enable the optional passphrase — it adds a factor that protects the vault even if someone gains read access to ~/.ghscaff/.

3. Use a strong passphrase — the tool warns about passphrases under 5 characters. Use a unique, random passphrase for maximum protection.

4. Restrict vault directory permissions — the tool sets 0700 on the directory, but verify after manual operations:

   chmod 700 ~/.ghscaff
   chmod 600 ~/.ghscaff/vault.enc

5. Rotate tokens periodically — if you suspect compromise, run ghscaff config to wipe the vault and start fresh with a new token.

6. Disable update checks in CI — set GHSCAFF_NO_UPDATE_CHECK=1 in automated environments.

7. Audit token scopes — review your token at https://github.com/settings/tokens regularly and revoke unused tokens.

All three are well-audited crates from the RustCrypto project.

This security policy applies to the ghscaff CLI tool published on crates.io and the GitHub releases. It does not apply to third-party forks or modifications.