Security Best Practices¶

Guidelines for using Orb securely.

Passcode Management¶

Choose Strong Passcodes¶

Good passcodes:

Long and random (20+ characters)
Generated by password manager
Include special characters
Unpredictable

Bad passcodes:

Short and simple ("password123")
Dictionary words
Personal information
Predictable patterns

Example:

# Good: Generated randomly
orb share ~/files
# Passcode: kJ8#mN2$pQ5&xR9^zA4!

# Bad: Weak passcode (don't use)
# Passcode: mypassword

Secure Passcode Transmission¶

Good methods:

Encrypted messaging (Signal, WhatsApp, Telegram)
Password manager shared vault
In-person communication
Encrypted email (PGP)
Phone call

Bad methods:

Plain SMS
Email without encryption
Public chat channels
Social media DMs
Shared documents

Best practice:

# Share via encrypted channel
1. Start share: orb share ~/files
2. Copy session ID and passcode
3. Send via Signal/WhatsApp
4. Confirm receipt with recipient

Passcode Lifecycle¶

Creation:

# Orb generates random passcode
orb share ~/files
# Note passcode immediately

Usage:

# Use once, then discard
# Don't reuse across sessions

Deletion:

# Delete from clipboard after use
# Clear from terminal history
# Remove from notes

Safe to share:

Public documents
Project files (non-sensitive)
Photos for review
Deliverables for clients

Share with caution:

Work documents
Personal files
Database backups
Configuration files

Never share:

System directories (/, /etc, /usr)
Home directory root (~)
Directories with credentials
Private keys or certificates

# Good: Specific directory
orb share ~/projects/client-deliverables

# Risky: Entire projects folder
orb share ~/projects

# Bad: Entire home directory
orb share ~

# Create temporary directory for sharing
mkdir /tmp/share-$(date +%Y%m%d)
cp files-to-share/* /tmp/share-$(date +%Y%m%d)/

# Share temporarily
orb share /tmp/share-$(date +%Y%m%d)

# After download, cleanup
rm -rf /tmp/share-$(date +%Y%m%d)

Review Directory Contents¶

# Before sharing, review contents
tree ~/directory-to-share

# Check for sensitive files
grep -r "password" ~/directory-to-share
grep -r "api_key" ~/directory-to-share
grep -r "private_key" ~/directory-to-share

# Remove sensitive files
rm sensitive-file.txt

Network Security¶

Use Trusted Relay Servers¶

Self-hosted relay (best):

# Run your own relay
orb relay --host 0.0.0.0 --port 8080

# Use it
orb share ~/files --relay ws://your-server.com:8080

Public relay (acceptable):

Only for non-sensitive data
Understand relay can see metadata
Prefer well-known relays

Untrusted relay (avoid):

Random servers on internet
Unknown operators
No HTTPS/WSS

Enable TLS (Production)¶

For production relays, use TLS:

# Use wss:// instead of ws://
orb share ~/files --relay wss://relay.example.com:443
orb connect --session <ID> --passcode <CODE> --relay wss://relay.example.com:443

Benefits:

Encrypted WebSocket connection
Prevents relay metadata leakage
Protects session ID in transit

Network Isolation¶

Trusted networks:

# Local network (office, home)
orb relay --host 192.168.1.10
orb share ~/files --relay ws://192.168.1.10:8080

Untrusted networks:

# Public WiFi: Use VPN + TLS
# Connect to VPN first
# Then use wss:// relay

Firewall Configuration¶

Relay server:

# Open only necessary ports
sudo ufw allow 8080/tcp

# Or use reverse proxy
# nginx/caddy → orb relay

Client:

# No inbound ports needed
# Only outbound to relay

Session Security¶

Limit Session Duration¶

# Time-limited sharing
timeout 1h orb share ~/files

# Stop when download complete
# Press Ctrl+C immediately

Monitor Active Sessions¶

# Watch sharing terminal for activity
[INFO] Client connected
[INFO] Handshake complete
[INFO] Serving file: document.pdf
[INFO] Connection closed

# Investigate unexpected activity

Single-Use Sessions¶

# Create session for one-time use
orb share ~/deliverable

# After recipient downloads:
# 1. Press Ctrl+C
# 2. Don't reuse credentials

Session Expiration¶

Understanding expiration:

Sessions expire after 24 hours
Can't be extended
Create new session if needed

Best practice:

# For long-term access, consider alternatives:
# - SFTP server
# - Cloud storage
# - VPN + file share

File Download Security¶

Verify File Integrity¶

After download:

# Check file size
ls -lh downloaded-file.pdf

# Compare with expected size
# Or use checksums if available
sha256sum downloaded-file.pdf

Scan for Malware¶

# Scan downloaded files
clamscan downloaded-file.pdf

# Or use cloud scanner
# VirusTotal, etc.

Download to Isolated Directory¶

# Quarantine downloads
mkdir ~/Downloads/orb-quarantine
cd ~/Downloads/orb-quarantine
orb connect --session <ID> --passcode <CODE>

# Review before moving to main directories

Verify Sender Identity¶

Before trusting files:

Confirm sender via separate channel
Verify session credentials out-of-band
Check file types match expectations

Operational Security¶

Clean Terminal History¶

# Clear history after sensitive operations
history -c

# Or use space prefix (some shells)
 orb connect --session abc123 --passcode xyz789

# Disable history temporarily
set +o history
orb share ~/sensitive
set -o history

Secure Relay Logs¶

# If running relay, don't log sensitive data
orb relay 2>&1 | tee relay.log

# Review logs for sensitive info
# Remove passcodes, session IDs

Access Control¶

File permissions:

# Ensure shared files have correct permissions
chmod 600 sensitive-file.txt  # Only owner
chmod 644 public-file.txt     # Owner write, others read

Process isolation:

# Run as dedicated user (production)
sudo -u orbuser orb relay

# Use systemd service
# Limit capabilities, resources

Update Regularly¶

# Check for updates
orb version

# Update when available
# Security fixes released promptly

Compliance Considerations¶

Data Residency¶

Know where data transits:

Relay server location
Network routing
Jurisdiction implications

For sensitive data:

Use relay in appropriate jurisdiction
Self-host relay in compliant region
Document data flow

Logging and Auditing¶

What to log:

Session creation times
Connection events
File access (if required)
Security events

What NOT to log:

Passcodes
File contents
Decrypted data

Example:

# Log share events
orb share ~/files 2>&1 | tee -a share.log

# Review logs
grep "Session created" share.log

Data Retention¶

After use:

Delete shared directories
Clear session logs
Remove temporary files

# Cleanup after sharing
rm -rf /tmp/share-*
history -c

Incident Response¶

If Passcode Compromised¶

Immediate actions:

Stop sharing (Ctrl+C)
Create new session with new passcode
Share new credentials securely
Notify intended recipient

If Files Accessed by Unauthorized Party¶

Steps:

Stop sharing immediately
Assess what was accessed
Change related credentials
Notify affected parties
Review security practices

If Relay Compromised¶

Remember:

Relay cannot decrypt files
Files remain confidential
Metadata may be exposed

Actions:

Switch to different relay
Create new sessions
Monitor for suspicious activity

Checklists¶

Monitor for connections
Watch for unexpected activity
Stop immediately when done
Don't leave unattended

Stop sharing
Clear terminal history
Delete temporary files
Verify intended recipient received files

Recipient Checklist¶

Threat-Specific Mitigations¶

Against Eavesdropping¶

End-to-end encryption (ChaCha20-Poly1305) Use TLS relay (wss://) Avoid untrusted networks

Against Man-in-the-Middle¶

Mutual authentication (Noise Protocol) Verify credentials out-of-band Use known relay servers

Against Brute Force¶

Strong passcodes Argon2id rate limiting 5-attempt lockout

Against Malicious Files¶

Scan downloads Verify sender Isolate downloads

Against Insider Threats¶

Least privilege access Audit logs Time-limited sessions

Security Training¶

For Administrators¶

Topics:

Relay deployment security
TLS configuration
Monitoring and logging
Incident response

For Users¶