Skip to content

Security: JoeGlenn1213/lgh

Security

docs/SECURITY.md

LGH Security Guide

δΈ­ζ–‡

This document describes how to securely deploy and use LGH.

πŸ”’ Security Model

LGH binds to 127.0.0.1 by default, meaning only the local machine can access it. When exposing to a network, additional security measures must be taken.

Security Levels

Level 1: Local Use (Default, Most Secure)

lgh serve  # Default 127.0.0.1:9418
  • βœ… Only accessible from local machine
  • βœ… No additional configuration needed
  • ❌ No remote access

Level 2: Built-in Basic Auth (Quick Setup)

# 1. Setup authentication
lgh auth setup

# 2. Start server (can bind to network)
lgh serve --bind 0.0.0.0

# 3. Client usage
git clone http://username:[email protected]:9418/repo.git

Configuration example (~/.localgithub/config.yaml):

port: 9418
bind_address: "0.0.0.0"
read_only: true  # Recommended: read-only mode
auth_enabled: true
auth_user: "git-user"
auth_password_hash: "salt:hash..."

Level 3: Reverse Proxy + TLS (Production Recommended)

This is the most secure approach, with LGH still binding to 127.0.0.1 and a mature reverse proxy handling authentication and TLS.

Caddy Configuration (Recommended)

# Caddyfile
git.example.com {
    # Automatic HTTPS
    basicauth * {
        git-user $2a$14$hashhere...
    }
    reverse_proxy localhost:9418
}
# Start LGH (local only)
lgh serve

# Start Caddy
caddy run

Nginx Configuration

server {
    listen 443 ssl;
    server_name git.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    auth_basic "Git Access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:9418;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # Large timeouts needed for Git
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
        client_max_body_size 0;  # Unlimited
    }
}

Generate htpasswd:

htpasswd -c /etc/nginx/.htpasswd git-user

Level 4: Tunnel Services (Temporary Sharing)

Cloudflare Tunnel + Access

# 1. Install cloudflared
brew install cloudflare/cloudflare/cloudflared

# 2. Create tunnel
cloudflared tunnel create lgh

# 3. Configure Access policy (in Cloudflare dashboard)
# 4. Run tunnel
cloudflared tunnel --url http://localhost:9418

ngrok + Basic Auth

# ngrok supports built-in auth
ngrok http 9418 --auth="user:password"

πŸ›‘οΈ Security Checklist

Before Deployment

  • Use strong passwords (at least 12 characters)
  • Config file permissions set to 0600
  • Consider using read-only mode
  • Check firewall rules

After Deployment

  • Regularly update LGH
  • Monitor access logs
  • Rotate passwords periodically

🚫 Not Recommended

# ❌ Wrong: Direct exposure without auth
lgh serve --bind 0.0.0.0

# ❌ Wrong: Tunnel without auth
ngrok http 9418

# ❌ Wrong: Weak password
lgh auth hash "123456"

βœ… Recommended Practices

# βœ… Correct: Local use
lgh serve

# βœ… Correct: Network exposure + auth + read-only
lgh auth setup
lgh serve --bind 0.0.0.0 --read-only

# βœ… Correct: Reverse proxy (best)
lgh serve  # Listen only on localhost
caddy run  # Handle TLS and auth

πŸ“‹ Configuration Templates

Minimal Secure Config

# ~/.localgithub/config.yaml
port: 9418
bind_address: "127.0.0.1"
read_only: false

Internal Network Sharing

port: 9418
bind_address: "0.0.0.0"
read_only: true
auth_enabled: true
auth_user: "team"
auth_password_hash: "your-hash-here"

Production Config

port: 9418
bind_address: "127.0.0.1"  # Local only, reverse proxy handles network
read_only: false
# Authentication handled by reverse proxy
auth_enabled: false

πŸ” Password Hashing

LGH uses HMAC-SHA256 with salt for password hashing:

# Generate password hash
lgh auth hash

# Hash format: salt:hash
# Example: a1b2c3d4e5:f6a7b8c9d0e1f2...

πŸ“ž Reporting Security Issues

If you discover a security vulnerability, please email [email protected]. Do not disclose publicly.

There aren’t any published security advisories