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

Do not open a public GitHub issue for security vulnerabilities.

Instead, email: [email protected]

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 ghscaff for GitHub API calls and ghscaff-update for update paths (no identifying information beyond the tool name)
• The startup notice fetches the release list (GET /repos/UniverLab/ghscaff/releases?per_page=100) and silently does nothing on any failure; it can be disabled with GHSCAFF_NO_UPDATE_CHECK=1 (which never affects the explicit ghscaff update command). Only the explicit command downloads release assets (https://github.com/UniverLab/ghscaff/releases/download/{tag}/{asset} plus SHA256SUMS.txt).

Updating is always explicit: only ghscaff update downloads anything, and only after consent (prompt defaults to NO; --yes skips it). It selects the newest stable release strictly newer than the running binary (drafts, prereleases and non-semver tags excluded), downloads the ghscaff-{tag}-{arch}-{os}.tar.gz asset for the current target, verifies its SHA256 against the release's SHA256SUMS.txt when present (missing file skips verification; missing entry or mismatch aborts), then atomically replaces the running binary (std::env::current_exe(), same-directory temp file plus rename). Binaries under ~/.cargo/bin are refused with cargo install --force ghscaff. The update never touches ~/.ghscaff state. ghscaff update --check only reports (exit 1 = available, 0 = current) and downloads nothing; both modes exit 2 when the release check itself cannot be completed (network, DNS, TLS, HTTP ≥ 400, unparsable response), with the cause printed on stderr.

Mitigation: The update only runs via the explicit ghscaff update command with user consent (default NO); the startup notice never prompts and never installs.

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.