docs: Add secure GitHub access guide for cloud agents (deploy keys recommended)
This commit is contained in:
Danny Stocker
parent
ddac456e0a
commit
fa07454a51
1 changed files with 420 additions and 0 deletions
420
SECURE_GITHUB_ACCESS_FOR_CLOUD.md
Normal file
420
SECURE_GITHUB_ACCESS_FOR_CLOUD.md
Normal file
|
|
@ -0,0 +1,420 @@
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ============================================
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
Loading…
Add table
Reference in a new issue