navidocs/SECURE_GITHUB_ACCESS_FOR_CLOUD.md

Secure GitHub Access for Cloud Agents

Problem: Cloud agents on StackCP need read access to private repo dannystocker/navidocs Security Goal: No exposure of main GitHub credentials, revokable access, minimal permissions

---

Option 1: GitHub Deploy Keys (RECOMMENDED)

Best for: Read-only access to a single private repo Security: Excellent - key only works for one repo, easily revokable

How It Works

1. Generate SSH key pair on StackCP
2. Add public key to GitHub repo as "Deploy Key" (read-only)
3. Cloud agents use private key to clone/pull
4. Key never leaves StackCP server

Setup Steps (10 minutes)

Step 1: Generate Deploy Key on StackCP

# SSH to StackCP
ssh stackcp

# Generate dedicated key (no passphrase for automation)
ssh-keygen -t ed25519 -C "navidocs-cloud-deploy" -f ~/.ssh/navidocs_deploy_key -N ""

# This creates:
# ~/.ssh/navidocs_deploy_key (private - keep secure!)
# ~/.ssh/navidocs_deploy_key.pub (public - add to GitHub)

# Display public key to copy
cat ~/.ssh/navidocs_deploy_key.pub

Step 2: Add Deploy Key to GitHub

1. Go to: https://github.com/dannystocker/navidocs/settings/keys
2. Click "Add deploy key"
3. Title: StackCP Cloud Agents (Read-Only)
4. Key: Paste the contents of navidocs_deploy_key.pub
5. ✅ IMPORTANT: Leave "Allow write access" UNCHECKED (read-only)
6. Click "Add key"

Step 3: Configure Git on StackCP

# Still on StackCP
cat >> ~/.ssh/config << 'EOF'
Host github.com-navidocs
    HostName github.com
    User git
    IdentityFile ~/.ssh/navidocs_deploy_key
    IdentitiesOnly yes
EOF

chmod 600 ~/.ssh/config

# Test connection
ssh -T git@github.com-navidocs
# Should see: "Hi dannystocker/navidocs! You've successfully authenticated..."

Step 4: Clone Repo Using Deploy Key

# Clone using the deploy key
git clone git@github.com-navidocs:dannystocker/navidocs.git ~/navidocs-cloud

# Or if already cloned, update remote
cd ~/navidocs-cloud
git remote set-url origin git@github.com-navidocs:dannystocker/navidocs.git

# Test pull
git pull

Step 5: Cloud Agents Use It

# In cloud agent script
cd ~/navidocs-cloud
git fetch origin
git checkout mvp-demo-build
git pull

# Private key is automatically used via SSH config

Security Benefits

• ✅ Key only works for dannystocker/navidocs (not other repos)
• ✅ Read-only access (agents can't push)
• ✅ Revokable instantly from GitHub UI
• ✅ No main GitHub credentials exposed
• ✅ Key never transmitted (stays on StackCP)

Revocation (if compromised)

1. Go to: https://github.com/dannystocker/navidocs/settings/keys
2. Find "StackCP Cloud Agents (Read-Only)"
3. Click "Delete"
4. Access immediately revoked

---

Option 2: GitHub Personal Access Token (Fine-Grained)

Best for: More control over permissions and expiration Security: Good - token can be scoped and expires

How It Works

1. Create fine-grained token with read-only access to navidocs repo
2. Store token in StackCP environment variable
3. Use HTTPS clone with token authentication

Setup Steps

Step 1: Create Fine-Grained Token

1. Go to: https://github.com/settings/tokens?type=beta
2. Click "Generate new token" → "Generate new token (Beta)"
3. Settings:
   • Token name: NaviDocs Cloud Agents (Read-Only)
   • Expiration: 90 days (or custom)
   • Repository access: Only select repositories → dannystocker/navidocs
   • Permissions:
     • Repository permissions:
       • Contents: Read-only ✅
       • Metadata: Read-only ✅ (auto-selected)
     • DO NOT grant any write permissions
4. Click "Generate token"
5. COPY TOKEN IMMEDIATELY (you won't see it again!)

Step 2: Store Token Securely on StackCP

ssh stackcp

# Store in secure file (readable only by you)
echo "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" > ~/.navidocs_github_token
chmod 600 ~/.navidocs_github_token

# Or in environment variable
echo 'export NAVIDOCS_GITHUB_TOKEN="ghp_xxxxx..."' >> ~/.bashrc
source ~/.bashrc

Step 3: Clone with Token

# Read token from file
TOKEN=$(cat ~/.navidocs_github_token)

# Clone using token
git clone https://x-access-token:${TOKEN}@github.com/dannystocker/navidocs.git ~/navidocs-cloud

# Or configure credential helper
git config --global credential.helper store
echo "https://x-access-token:${TOKEN}@github.com" > ~/.git-credentials
chmod 600 ~/.git-credentials

Step 4: Cloud Agents Use It

# Token is automatically used
cd ~/navidocs-cloud
git pull origin mvp-demo-build

Security Benefits

• ✅ Fine-grained permissions (only Contents: Read)
• ✅ Auto-expires after 90 days
• ✅ Can be scoped to specific repos
• ✅ Revokable from GitHub settings

Revocation

1. Go to: https://github.com/settings/tokens?type=beta
2. Find "NaviDocs Cloud Agents (Read-Only)"
3. Click "Delete"

---

Option 3: SSH Agent Forwarding (MOST SECURE)

Best for: Using your local credentials without storing on StackCP Security: Excellent - no keys stored on cloud server

How It Works

1. Your local SSH key is forwarded through SSH connection
2. Cloud agent uses YOUR credentials via the tunnel
3. No keys stored on StackCP

Setup Steps

Step 1: Enable SSH Agent Forwarding Locally

# On your local machine
# Ensure SSH agent is running
eval "$(ssh-agent -s)"

# Add your GitHub key
ssh-add ~/.ssh/id_ed25519  # or your GitHub key

# Verify
ssh-add -l

Step 2: Configure SSH Forwarding

# Edit ~/.ssh/config on local machine
cat >> ~/.ssh/config << 'EOF'
Host stackcp
    HostName ssh.gb.stackcp.com
    User digital-lab.ca
    ForwardAgent yes
EOF

Step 3: Test Forwarding

# SSH to StackCP with agent forwarding
ssh stackcp

# From StackCP, test GitHub access (using YOUR local key!)
ssh -T git@github.com
# Should see: "Hi dannystocker! You've successfully authenticated..."

Step 4: Clone Repo

# On StackCP (using forwarded credentials)
git clone git@github.com:dannystocker/navidocs.git ~/navidocs-cloud

Security Benefits

• ✅ No keys stored on StackCP
• ✅ Uses your existing GitHub access
• ✅ Automatic when you SSH to StackCP
• ✅ Stops working when you disconnect

Limitations

• ❌ Only works while you're SSH'd in
• ❌ Cloud agents can't run autonomously
• ❌ Not suitable for automated background tasks

NOT RECOMMENDED for this use case (agents need to run autonomously)

---

Comparison Table

Feature	Deploy Keys	Fine-Grained Token	SSH Forwarding
Setup Time	10 min	5 min	2 min
Autonomous Use	✅ Yes	✅ Yes	❌ No (requires SSH session)
Read-Only	✅ Enforced	✅ Configurable	❌ Uses your full access
Revokable	✅ Instant	✅ Instant	✅ Auto (on disconnect)
Repo-Specific	✅ Yes	✅ Yes	❌ All repos you access
Key Storage	StackCP only	StackCP only	Local only
Expiration	None	Configurable	Per session
Best For	Cloud agents	Temp access	Interactive use

---

RECOMMENDED SOLUTION: Deploy Keys + Environment Security

Complete Secure Setup (15 minutes)

# ============================================
# STEP 1: Generate deploy key on StackCP
# ============================================
ssh stackcp << 'SETUP'
  # Generate key
  ssh-keygen -t ed25519 -C "navidocs-cloud-$(date +%Y%m%d)" \
    -f ~/.ssh/navidocs_deploy_key -N ""

  # Secure permissions
  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/navidocs_deploy_key
  chmod 644 ~/.ssh/navidocs_deploy_key.pub

  # Configure SSH
  cat >> ~/.ssh/config << 'EOF'
Host github.com-navidocs
    HostName github.com
    User git
    IdentityFile ~/.ssh/navidocs_deploy_key
    IdentitiesOnly yes
    StrictHostKeyChecking no
EOF
  chmod 600 ~/.ssh/config

  # Display public key
  echo "========================================"
  echo "ADD THIS PUBLIC KEY TO GITHUB:"
  echo "https://github.com/dannystocker/navidocs/settings/keys"
  echo "========================================"
  cat ~/.ssh/navidocs_deploy_key.pub
  echo "========================================"
SETUP

# ============================================
# STEP 2: Add public key to GitHub manually
# ============================================
# (You must do this in browser - see above)

# ============================================
# STEP 3: Test and clone on StackCP
# ============================================
ssh stackcp << 'TEST'
  # Test connection
  ssh -T git@github.com-navidocs

  # Clone repo
  git clone git@github.com-navidocs:dannystocker/navidocs.git ~/navidocs-cloud

  # Verify
  cd ~/navidocs-cloud
  git remote -v
  git branch -a

  echo "✅ Secure GitHub access configured!"
TEST

Additional Security Hardening

# On StackCP: Restrict file permissions
ssh stackcp << 'SECURE'
  # Ensure home directory is not world-readable
  chmod 750 ~

  # Secure SSH directory
  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/navidocs_deploy_key

  # Secure navidocs directory
  chmod 750 ~/navidocs-cloud

  # Create audit log
  echo "$(date): Deploy key created for navidocs cloud agents" >> ~/.security_audit.log
  chmod 600 ~/.security_audit.log
SECURE

---

Security Checklist

Before deploying cloud agents:

• Deploy key generated on StackCP (not local machine)
• Public key added to GitHub with Read-only access
• Private key permissions set to 600
• SSH config uses IdentitiesOnly yes
• Test clone/pull works
• Document key creation in security audit log
• Set calendar reminder to rotate key in 6 months
• Store backup of public key locally (for audit trail)

---

Key Rotation Schedule

Recommended: Rotate deploy keys every 6 months

# Create calendar reminder
echo "2025-05-13: Rotate NaviDocs StackCP deploy key" >> ~/security-reminders.txt

Rotation process:

1. Generate new deploy key on StackCP
2. Add new public key to GitHub (keep old key active)
3. Update git config to use new key
4. Test clone/pull with new key
5. Remove old deploy key from GitHub
6. Delete old private key from StackCP

---

Emergency Revocation

If you suspect the deploy key is compromised:

# 1. Revoke from GitHub immediately
# Go to: https://github.com/dannystocker/navidocs/settings/keys
# Delete the deploy key

# 2. Rotate key on StackCP
ssh stackcp "rm ~/.ssh/navidocs_deploy_key*"

# 3. Generate new key (follow setup steps above)

# 4. Update security audit log
ssh stackcp "echo '$(date): EMERGENCY - Deploy key revoked and rotated' >> ~/.security_audit.log"

---

Status: READY TO IMPLEMENT

Recommended: Deploy Keys (Option 1)

Next steps:

1. Run the complete setup script above (15 min)
2. Test clone/pull from StackCP
3. Document in security audit log
4. Deploy cloud agents

Security level: ✅ Production-ready