Skip to content

Security

Stout implements defense-in-depth security to protect your system.

Security Model Overview

Stout's security is built on multiple layers:

  1. Transport Security - HTTPS with TLS 1.2+
  2. Index Integrity - Ed25519 cryptographic signatures
  3. Package Integrity - SHA256 checksums
  4. Installation Security - Sandboxed extraction

Transport Security

HTTPS Required

All network operations use HTTPS:

  • Package index downloads
  • Bottle (binary package) downloads
  • Cask downloads

HTTP URLs are automatically upgraded to HTTPS.

TLS Requirements

  • Minimum TLS 1.2
  • Modern cipher suites only
  • Certificate validation enforced

Index Integrity

Ed25519 Signatures

The package index is cryptographically signed using Ed25519:

  • Every index update includes a signature
  • Signatures are verified before the index is used
  • The public key is embedded in the Stout binary

Signature Verification

Index File → SHA256 Hash → Ed25519 Verify → Public Key

If verification fails, Stout refuses to use the index.

Signature Freshness

Signatures include a timestamp. Stout rejects signatures older than the configured maximum age (default: 7 days):

[security]
max_signature_age = 604800  # 7 days in seconds

This prevents replay attacks with old, potentially compromised indexes.

Package Integrity

SHA256 Checksums

Every package download is verified:

  1. Index contains expected SHA256 hash
  2. Package is downloaded
  3. SHA256 hash is computed
  4. Hashes are compared

If hashes don't match, installation is aborted.

Verification Flow

Download → Compute SHA256 → Compare with Index → Install or Abort

Installation Security

Sandboxed Extraction

Package extraction is sandboxed:

  • No arbitrary code execution during install
  • Files extracted only to designated directories
  • Symlinks validated before creation

No Post-Install Scripts

Unlike Homebrew, Stout doesn't execute Ruby scripts during installation. Package installation is purely file extraction and symlinking.

Configuration

Security Settings

[security]
# Require signatures (recommended: true)
require_signature = true

# Allow unsigned packages (recommended: false)
allow_unsigned = false

# Maximum signature age in seconds
max_signature_age = 604800

# Additional trusted public keys
trusted_keys = []

For production environments:

[security]
require_signature = true
allow_unsigned = false
max_signature_age = 604800

Never Disable Signature Verification

Setting require_signature = false or allow_unsigned = true removes critical security protections. Only do this in isolated development environments.

Trust Model

Default Trust

Stout trusts:

  1. The embedded Neul Labs public key
  2. Any additional keys in trusted_keys configuration
  3. HTTPS certificates from standard CA roots

Custom Trust (Enterprise)

For private indexes, add your organization's public key:

[security]
trusted_keys = [
    "your-base64-encoded-ed25519-public-key"
]

Generate a key pair:

# Generate private key
openssl genpkey -algorithm ED25519 -out private.pem

# Extract public key
openssl pkey -in private.pem -pubout -out public.pem

# Convert to base64 for config
base64 -w0 public.pem

Vulnerability Scanning

Audit Command

Scan installed packages for known vulnerabilities:

stout audit

Filter by Severity

stout audit --severity=high
stout audit --severity=critical

Severity Levels

Level Description
low Minor issues, low impact
medium Moderate issues
high Serious vulnerabilities
critical Severe, actively exploited

CVE Database

Stout maintains a vulnerability database synced from public sources. Update it with:

stout update

Comparison with Homebrew

Feature Homebrew Stout
Transport HTTPS HTTPS
Index integrity Git commit hashes Ed25519 signatures
Package integrity SHA256 SHA256
Post-install scripts Ruby execution None
Signature verification No Yes
CVE scanning No Built-in

Security Best Practices

Keep Stout Updated

# Update stout itself
stout upgrade stout

Regular Audits

# Weekly vulnerability scan
stout audit

Review Before Install

Check package details before installing:

stout info suspicious-package

Use Pinning for Stability

Pin critical packages to prevent unexpected updates:

stout pin openssl
stout pin [email protected]

Monitor Outdated Packages

Old packages may have unpatched vulnerabilities:

stout outdated

Reporting Security Issues

Report security vulnerabilities to:

Please do not open public issues for security vulnerabilities.