diff --git a/.claude/skills/wiki-docs.md b/.claude/skills/wiki-docs.md index 0b580ee..5fc799d 100644 --- a/.claude/skills/wiki-docs.md +++ b/.claude/skills/wiki-docs.md @@ -56,16 +56,37 @@ When creating wiki documentation: - Use clear, descriptive filenames (lowercase-with-dashes.md) - Include proper frontmatter - Use standard markdown formatting - - Organize in subdirectories as needed (e.g., `homelab/services/service-name.md`) + - Organize in subdirectories as needed (e.g., `home/containers/services/service-name.md`) -4. **Commit and push:** +4. **Scan for secrets with Gitleaks:** + ```bash + # Install gitleaks if not already installed + # On Ubuntu/Debian: apt install gitleaks + # Or download from: https://github.com/gitleaks/gitleaks/releases + + # Scan staged files before commit + gitleaks detect --source . --verbose --no-git + + # Or scan specific files + gitleaks detect --source . --verbose --no-git --log-opts="" + ``` + + **If secrets are found:** + - **Remove them immediately** - replace with environment variables or placeholders + - Use patterns like `${SECRET_KEY}`, `YOUR_KEY_HERE`, or `TBD` + - Never commit actual passwords, API keys, tokens, or credentials + - Check `.gitleaks.toml` for allowlist patterns + +5. **Commit and push:** ```bash git add git commit -m "Add/Update: brief description" git push ``` -5. **Verify:** Changes will appear at https://wiki.fig.systems after sync + **Note:** Gitleaks CI/CD will automatically scan on push and fail if secrets detected + +6. **Verify:** Changes will appear at https://wiki.fig.systems after sync ## File Organization @@ -142,12 +163,102 @@ The repository is already configured: ## Best Practices 1. **Always pull before writing** to avoid conflicts -2. **Use descriptive commit messages** following the pattern: "Add: X" or "Update: Y" -3. **Include proper frontmatter** - pages without it won't render correctly -4. **Use semantic filenames** - lowercase with dashes instead of spaces -5. **Organize logically** - use subdirectories for categories -6. **Add relevant tags** - helps with wiki navigation and search -7. **Set published: true** - pages with `published: false` won't be visible +2. **Scan for secrets with Gitleaks** before committing +3. **Use descriptive commit messages** following the pattern: "Add: X" or "Update: Y" +4. **Include proper frontmatter** - pages without it won't render correctly +5. **Use semantic filenames** - lowercase with dashes instead of spaces +6. **Organize logically** - use subdirectories for categories +7. **Add relevant tags** - helps with wiki navigation and search +8. **Set published: true** - pages with `published: false` won't be visible +9. **Never commit secrets** - use placeholders like `TBD`, `${VAR}`, or `YOUR_KEY_HERE` + +## Secret Management with Gitleaks + +### What is Gitleaks? + +Gitleaks is a secret scanner that detects hardcoded secrets, passwords, API keys, and tokens in Git repositories. + +### CI/CD Integration + +The wiki repository has automated Gitleaks scanning: +- **Workflow**: `.forgejo/workflows/gitleaks.yaml` +- **Config**: `.gitleaks.toml` +- **Triggers**: Every push to main, all pull requests +- **Action**: Fails build if secrets detected + +### Local Scanning + +**Before committing:** +```bash +cd /mnt/media/wikijs-content + +# Scan all files +gitleaks detect --source . --verbose --no-git + +# Scan specific files +gitleaks detect --source . --verbose --no-git --log-opts="path/to/file.md" + +# Scan uncommitted changes only +gitleaks protect --staged --verbose +``` + +### Handling Detected Secrets + +**If Gitleaks finds secrets:** + +1. **Immediate action:** + - DO NOT commit + - Replace secret with placeholder + - Use `TBD`, `${SECRET_KEY}`, or `YOUR_KEY_HERE` + +2. **Examples of safe placeholders:** + ```markdown + API_KEY=YOUR_API_KEY_HERE + PASSWORD=${DB_PASSWORD} + TOKEN=TBD + ``` + +3. **Allowlisted patterns** (in `.gitleaks.toml`): + - `example.com` domains + - `localhost` and `127.0.0.1` + - `TBD` placeholders + - Environment variable syntax `${VAR}` + +### What Gitleaks Detects + +- AWS keys (AKIA...) +- GitHub tokens (ghp_...) +- GitLab tokens (glpat-...) +- Private keys (-----BEGIN PRIVATE KEY-----) +- Generic API keys and secrets +- Passwords in configuration files + +### False Positives + +If Gitleaks flags safe content: + +1. **Update `.gitleaks.toml` allowlist:** + ```toml + [allowlist] + regexes = [ + '''safe-pattern-here''', + ] + ``` + +2. **Commit the config update:** + ```bash + git add .gitleaks.toml + git commit -m "chore: Update Gitleaks allowlist" + ``` + +### Git History Scanning + +To scan entire git history: +```bash +gitleaks detect --source . --verbose +``` + +This checks all commits, not just current files. ## Troubleshooting @@ -162,6 +273,24 @@ The repository is already configured: - Verify network connectivity to git.fig.systems - Try pulling first to resolve conflicts +**If Gitleaks CI/CD fails:** +- View Forgejo Actions logs at https://git.fig.systems/eddie/wiki/actions +- Identify detected secrets in the workflow output +- Remove or replace secrets with placeholders +- Update `.gitleaks.toml` if false positive +- Commit and push again + +**If Gitleaks not installed locally:** +```bash +# Ubuntu/Debian +sudo apt install gitleaks + +# Or download latest release +wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_linux_amd64.tar.gz +tar -xzf gitleaks_linux_amd64.tar.gz +sudo mv gitleaks /usr/local/bin/ +``` + ## Integration with Other Services This wiki can document: