opencode-skills-collection 4.0.68 → 4.0.69

package/bundled-skills/mac-mini-llm-lab/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: mac-mini-llm-lab
+description: Configure a Mac mini as a reliable local LLM server with remote access,
+  observability, and power-safe operation. Use when building an always-on private
+  AI inference server on Apple Silicon.
+category: devops
+risk: critical
+source: https://github.com/BagelHole/DevOps-Security-Agent-Skills
+source_repo: BagelHole/DevOps-Security-Agent-Skills
+source_type: community
+date_added: '2026-09-20'
+license: MIT
+license_source: https://github.com/BagelHole/DevOps-Security-Agent-Skills/blob/main/LICENSE
+compatibility: Requires the relevant OS/platform tooling and privileged access where
+  noted. Docs-only; helper scripts and templates not bundled.
+metadata:
+  author: devops-skills
+  version: '1.0'
+---
+
+# Mac mini LLM Lab
+
+Turn a Mac mini into a low-noise, always-on local AI appliance.
+
+## When to Use This Skill
+
+Use this skill when:
+- Setting up a dedicated local LLM inference server
+- Building a private AI development environment
+- Need always-on model serving without cloud costs
+- Running models that require Apple Silicon unified memory (32-192GB)
+- Creating a home lab AI server for a small team
+
+## Prerequisites
+
+- Mac mini with Apple Silicon (M2/M3/M4, 16GB+ unified memory recommended)
+- macOS Sonoma 14+ or Sequoia 15+
+- Ethernet connection (recommended over Wi-Fi)
+- UPS for power protection (optional but recommended)
+
+## Initial System Setup
+
+```bash
+# Update macOS
+softwareupdate --install --all
+
+# Install Xcode command-line tools
+xcode-select --install
+
+# Install Homebrew
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Core packages
+brew install tmux htop btop wget jq git neovim
+
+# Python environment (for MLX and custom scripts)
+brew install python@3.12 uv
+
+# Monitoring
+brew install prometheus node_exporter
+```
+
+## Ollama Setup
+
+```bash
+# Install Ollama
+brew install ollama
+
+# Pull models based on your RAM
+# 16GB Mac mini:
+ollama pull llama3.1:8b
+ollama pull nomic-embed-text
+ollama pull codellama:7b
+
+# 32GB Mac mini:
+ollama pull llama3.1:8b
+ollama pull qwen2.5:14b
+ollama pull deepseek-coder-v2:16b
+ollama pull nomic-embed-text
+
+# 64GB+ Mac mini:
+ollama pull llama3.1:70b
+ollama pull qwen2.5:32b
+ollama pull codellama:34b
+
+# Verify Metal acceleration
+ollama run llama3.1:8b --verbose
+# Look for: "metal" in output
+```
+
+## MLX Framework (Apple Silicon Native)
+
+MLX runs models natively on Apple Silicon with excellent performance:
+
+```bash
+# Install MLX
+uv pip install mlx mlx-lm
+
+# Run a model
+python3 -c "
+from mlx_lm import load, generate
+model, tokenizer = load('mlx-community/Llama-3.1-8B-Instruct-4bit')
+response = generate(model, tokenizer, prompt='Explain Docker in 3 sentences', max_tokens=200)
+print(response)
+"
+
+# MLX server (OpenAI-compatible API)
+uv pip install mlx-lm[server]
+mlx_lm.server --model mlx-community/Llama-3.1-8B-Instruct-4bit --port 8080
+```
+
+## Auto-Start with launchd
+
+```xml
+<!-- ~/Library/LaunchAgents/com.ollama.serve.plist -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.ollama.serve</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/ollama</string>
+        <string>serve</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>OLLAMA_HOST</key>
+        <string>0.0.0.0</string>
+        <key>OLLAMA_NUM_PARALLEL</key>
+        <string>4</string>
+        <key>OLLAMA_MAX_LOADED_MODELS</key>
+        <string>2</string>
+        <key>OLLAMA_FLASH_ATTENTION</key>
+        <string>1</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/ollama.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/ollama.err</string>
+</dict>
+</plist>
+```
+
+```bash
+# Load the service
+launchctl load ~/Library/LaunchAgents/com.ollama.serve.plist
+
+# Check status
+launchctl list | grep ollama
+
+# Unload if needed
+launchctl unload ~/Library/LaunchAgents/com.ollama.serve.plist
+```
+
+## Power & Reliability
+
+```bash
+# Prevent sleep (keeps running with lid closed on Mac mini)
+sudo pmset -a disablesleep 1
+sudo pmset -a sleep 0
+
+# Auto-restart after power failure
+sudo pmset -a autorestart 1
+
+# Schedule weekly reboot (Sunday 4 AM)
+sudo pmset repeat shutdown MTWRFSU 03:55:00
+sudo pmset repeat poweron MTWRFSU 04:00:00
+
+# Check power settings
+pmset -g
+```
+
+## Remote Access
+
+### Tailscale (Recommended)
+
+```bash
+# Install Tailscale for easy secure remote access
+brew install --cask tailscale
+
+# Enable from menu bar, authenticate
+# Access your Mac mini from anywhere: http://mac-mini:11434
+```
+
+### SSH Hardening
+
+```bash
+# Enable remote login
+sudo systemsetup -setremotelogin on
+
+# Edit SSH config
+sudo nano /etc/ssh/sshd_config
+# Add:
+# PasswordAuthentication no
+# PubkeyAuthentication yes
+# PermitRootLogin no
+# AllowUsers yourusername
+
+# Restart SSH
+sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist
+sudo launchctl load /System/Library/LaunchDaemons/ssh.plist
+```
+
+### Reverse Proxy with Caddy
+
+```bash
+brew install caddy
+
+# Caddyfile
+cat > /opt/homebrew/etc/Caddyfile << 'EOF'
+llm.local:443 {
+    tls internal
+    reverse_proxy localhost:11434
+
+    @api path /v1/*
+    handle @api {
+        reverse_proxy localhost:11434
+    }
+}
+
+webui.local:443 {
+    tls internal
+    reverse_proxy localhost:3000
+}
+EOF
+
+brew services start caddy
+```
+
+## Open WebUI Setup
+
+```bash
+# Run Open WebUI via Docker
+docker run -d \
+  --name open-webui \
+  -p 3000:8080 \
+  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
+  -e WEBUI_AUTH=true \
+  -v open-webui:/app/backend/data \
+  --restart unless-stopped \
+  ghcr.io/open-webui/open-webui:main
+
+# Or install Docker first if not available
+brew install --cask docker
+```
+
+## Monitoring
+
+```bash
+# Health check script
+cat > ~/scripts/llm-health.sh << 'SCRIPT'
+#!/bin/bash
+# Check Ollama
+if curl -sf http://localhost:11434/api/tags > /dev/null; then
+    echo "$(date): Ollama OK"
+    curl -s http://localhost:11434/api/ps | python3 -m json.tool
+else
+    echo "$(date): Ollama DOWN"
+    # Restart
+    launchctl kickstart -k gui/$(id -u)/com.ollama.serve
+fi
+
+# System stats
+echo "CPU: $(top -l 1 -n 0 | grep 'CPU usage')"
+echo "Memory: $(vm_stat | head -5)"
+echo "Disk: $(df -h / | tail -1)"
+echo "Thermal: $(sudo powermetrics --samplers smc -n 1 2>/dev/null | grep 'CPU die' || echo 'N/A')"
+SCRIPT
+chmod +x ~/scripts/llm-health.sh
+
+# Schedule health check every 5 minutes
+# Add to crontab: crontab -e
+# */5 * * * * ~/scripts/llm-health.sh >> ~/logs/llm-health.log 2>&1
+```
+
+### Memory Usage by Model
+
+| Model | RAM Required | Tokens/sec (M2) | Tokens/sec (M4) |
+|-------|-------------|-----------------|-----------------|
+| llama3.1:8b (Q4) | ~5 GB | ~25 t/s | ~45 t/s |
+| qwen2.5:14b (Q4) | ~9 GB | ~15 t/s | ~30 t/s |
+| llama3.1:70b (Q4) | ~40 GB | ~5 t/s | ~10 t/s |
+| nomic-embed-text | ~300 MB | N/A | N/A |
+| codellama:13b | ~8 GB | ~18 t/s | ~35 t/s |
+
+## Security Checklist
+
+```bash
+# Enable FileVault disk encryption
+sudo fdesetup enable
+
+# Enable firewall
+sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on
+sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setstealthmode on
+
+# Disable unnecessary sharing services
+sudo launchctl disable system/com.apple.screensharing
+sudo launchctl disable system/com.apple.AirPlayXPCHelper
+
+# Set strong admin password
+# System Settings > Users & Groups
+
+# Restrict Ollama to local network only (if not using Tailscale)
+# Set OLLAMA_HOST=127.0.0.1 in launchd plist
+```
+
+## Performance Tuning
+
+```bash
+# Increase file descriptor limits for concurrent requests
+sudo launchctl limit maxfiles 65536 200000
+
+# Check unified memory pressure
+memory_pressure
+
+# Monitor GPU usage (Metal)
+sudo powermetrics --samplers gpu_power -n 1
+
+# Optimize for inference (disable Spotlight indexing on model dirs)
+mdutil -i off ~/.ollama
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|---------|
+| Model loading slow | First load caches to memory; subsequent loads are fast |
+| Out of memory | Use smaller quantization (Q4_K_M), reduce `OLLAMA_MAX_LOADED_MODELS` |
+| Mac sleeping | Run `sudo pmset -a disablesleep 1` |
+| Ollama not starting | Check `launchctl list | grep ollama`, view `/tmp/ollama.err` |
+| Slow over Wi-Fi | Use Ethernet; Wi-Fi adds latency to streaming responses |
+| Thermal throttling | Ensure adequate ventilation, check `powermetrics` |
+
+## Related Skills
+
+- ollama-stack (`ollama-stack`) — Software stack with Docker Compose and LiteLLM
+- ssh-configuration (`ssh-configuration`) — Secure remote access
+- vpn-setup (`vpn-setup`) — Remote access via WireGuard/Tailscale
+
+## Limitations
+
+- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
+- Docs-only import: upstream scripts and templates not bundled.
+

package/bundled-skills/mcp-server-security/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: mcp-server-security
+description: Secure Model Context Protocol (MCP) servers with transport encryption,
+  tool authorization, input validation, and audit logging for safe AI agent integrations.
+category: security
+risk: safe
+source: https://github.com/BagelHole/DevOps-Security-Agent-Skills
+source_repo: BagelHole/DevOps-Security-Agent-Skills
+source_type: community
+date_added: '2026-09-20'
+license: MIT
+license_source: https://github.com/BagelHole/DevOps-Security-Agent-Skills/blob/main/LICENSE
+compatibility: Requires the relevant security tooling (scanners, vault CLIs) and an
+  authorized scope for any active assessment. Docs-only; helper scripts and templates
+  not bundled.
+metadata:
+  author: devops-skills
+  version: '1.0'
+---
+
+# MCP Server Security
+
+Comprehensive hardening guide for Model Context Protocol (MCP) servers. MCP is the open
+standard for connecting AI agents to external tools, data sources, and services. Because
+MCP servers execute real actions on real infrastructure, they are a high-value attack
+surface. This skill covers every layer of defense you need before exposing an MCP server
+to agents in production.
+
+---
+
+## 2. MCP Threat Model
+
+Before hardening, understand what you are defending against.
+
+| Threat                        | Vector                                                        | Impact                              |
+|-------------------------------|---------------------------------------------------------------|-------------------------------------|
+| Unauthorized tool access      | Agent calls tools the user should not have access to          | Privilege escalation, data breach   |
+| Prompt injection via resources| Malicious content in MCP resources influences agent behavior  | Arbitrary tool execution            |
+| Data exfiltration via results | Tool results leak sensitive data back to an untrusted agent   | Data loss, compliance violation     |
+| SSRF via MCP tools            | Agent tricks a tool into making internal network requests      | Internal service compromise         |
+| Credential theft              | API keys or tokens stored insecurely on the MCP server        | Full account takeover               |
+| Denial of service             | Agent floods server with tool calls or huge payloads          | Service unavailability              |
+| Man-in-the-middle             | Unencrypted transport between agent and MCP server            | Eavesdropping, request tampering    |
+| Supply chain compromise       | Malicious MCP server package or plugin                        | Arbitrary code execution            |
+
+---
+
+## 3. Transport Security
+
+### 3.1 TLS for Streamable HTTP and SSE Transports
+
+Every MCP server exposed over HTTP must terminate TLS. Never run plain HTTP in
+production.
+
+**Nginx reverse proxy with TLS termination for an MCP server:**
+
+```nginx
+# /etc/nginx/sites-enabled/mcp-server.conf
+server {
+    listen 443 ssl http2;
+    server_name mcp.internal.example.com;
+
+    ssl_certificate     /etc/ssl/certs/mcp-server.crt;
+    ssl_certificate_key /etc/ssl/private/mcp-server.key;
+    ssl_protocols       TLSv1.3;
+    ssl_ciphers         TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
+    ssl_prefer_server_ciphers on;
+    ssl_session_timeout 1d;
+    ssl_session_tickets off;
+
+    # HSTS header
+    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
+
+    location / {
+        proxy_pass http://127.0.0.1:3001;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # SSE-specific: disable buffering so events stream immediately
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 86400s;
+    }
+}
+```
+
+### 3.2 mTLS Between Agent and Server
+
+For high-security environments, require the agent (client) to present a certificate.
+
+```nginx
+# Add to the server block above
+ssl_client_certificate /etc/ssl/certs/agent-ca.crt;
+ssl_verify_client on;
+ssl_verify_depth 2;
+```
+
+**Generate a client certificate for an agent:**
+
+```bash
+# Create CA (one-time)
+openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
+  -days 365 -noenc -keyout ca-key.pem -out ca-cert.pem \
+  -subj "/CN=MCP Agent CA"
+
+# Create agent client cert signed by the CA
+openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
+  -noenc -keyout agent-key.pem -out agent-csr.pem \
+  -subj "/CN=agent-orchestrator-01"
+
+openssl x509 -req -in agent-csr.pem -CA ca-cert.pem -CAkey ca-key.pem \
+  -CAcreateserial -out agent-cert.pem -days 90
+```
+
+### 3.3 Securing stdio Transport
+
+For local stdio-based servers, the attack surface is the process boundary itself:
+
+```jsonc
+// claude_desktop_config.json - restrict stdio server permissions
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/safe-dir"],
+      "env": {
+        "NODE_OPTIONS": "--experimental-permission --allow-fs-read=/home/user/safe-dir --allow-fs-write=/home/user/safe-dir"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. Authentication and Authorization
+
+### 4.1 OAuth 2.1 Integration
+
+MCP's Streamable HTTP transport supports OAuth 2.1 for client authentication. Configure
+your server to validate bearer tokens on every request.
+
+```typescript
+// src/auth.ts - OAuth 2.1 token validation middleware for an MCP server
+import { createServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import jwt from "jsonwebtoken";
+
+const app = express();
+
+// OAuth 2.1 token validation middleware
+function validateBearerToken(req: express.Request, res: express.Response, next: express.NextFunction) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader?.startsWith("Bearer ")) {
+    return res.status(401).json({ error: "missing_token" });
+  }
+
+  const token = authHeader.slice(7);
+  try {
+    const payload = jwt.verify(token, process.env.OAUTH_PUBLIC_KEY!, {
+      algorithms: ["RS256"],
+      issuer: "https://auth.example.com",
+      audience: "mcp-server",
+    });
+    // Attach scopes for downstream authorization
+    (req as any).tokenScopes = (payload as any).scope?.split(" ") || [];
+    (req as any).userId = (payload as any).sub;
+    next();
+  } catch {
+    return res.status(403).json({ error: "invalid_token" });
+  }
+}
+
+app.use("/mcp", validateBearerToken);
+```
+
+### 4.2 API Key Management
+
+For simpler deployments, use hashed API keys stored server-side:
+
+```typescript
+// src/apikeys.ts
+import { createHash, timingSafeEqual } from "crypto";
+
+interface ApiKeyRecord {
+  hashedKey: string;
+  userId: string;
+  allowedTools: string[];
+  rateLimit: number;        // requests per minute
+  expiresAt: Date;
+}
+
+// Store hashed keys, never plaintext
+const apiKeyStore: Map<string, ApiKeyRecord> = new Map();
+
+export function registerApiKey(plainKey: string, record: Omit<ApiKeyRecord, "hashedKey">) {
+  const hashed = createHash("sha256").update(plainKey).digest("hex");
+  apiKeyStore.set(hashed, { ...record, hashedKey: hashed });
+}
+
+export function validateApiKey(plainKey: string): ApiKeyRecord | null {
+  const hashed = createHash("sha256").update(plainKey).digest("hex");
+  const record = apiKeyStore.get(hashed);
+  if (!record) return null;
+  if (new Date() > record.expiresAt) {
+    apiKeyStore.delete(hashed);
+    return null;
+  }
+  return record;
+}
+```
+
+---
+
+## 5. Tool Authorization
+
+### 5.1 Allowlist Patterns
+
+Never expose every tool to every user. Define an explicit allowlist:
+
+```yaml
+# config/tool-policy.yaml
+policies:
+  - role: developer
+    allowed_tools:
+      - "read_file"
+      - "search_code"
+      - "run_tests"
+    denied_tools:
+      - "execute_command"
+      - "write_file"
+      - "delete_file"
+
+  - role: admin
+    allowed_tools: ["*"]
+    denied_tools: []
+
+  - role: readonly-agent
+    allowed_tools:
+      - "read_file"
+      - "list_directory"
+      - "query_database:SELECT"
+    denied_tools: ["*"]
+
+dangerous_tools:
+  - name: "execute_command"
+    risk: critical
+    requires_approval: true
+    max_executions_per_session: 5
+  - name: "write_file"
+    risk: high
+    requires_approval: true
+  - name: "query_database"
+    risk: medium
+    allowed_operations: ["SELECT"]
+```
+
+### 5.2 Per-User Tool Access Enforcement
+
+```typescript
+// src/toolAuth.ts
+import { readFileSync } from "fs";
+import { parse } from "yaml";
+
+interface ToolPolicy {
+  role: string;
+  allowed_tools: string[];
+  denied_tools: string[];
+}
+
+const config = parse(readFileSync("config/tool-policy.yaml", "utf-8"));
+const policies: ToolPolicy[] = config.policies;
+
+export function isToolAllowed(userRole: string, toolName: string): boolean {
+  const policy = policies.find((p) => p.role === userRole);
+  if (!policy) return false;
+
+  // Explicit deny takes precedence
+  if (policy.denied_tools.includes(toolName)) return false;
+  if (policy.denied_tools.includes("*") && !policy.allowed_tools.includes(toolName)) return false;
+
+  // Check allow
+  if (policy.allowed_tools.includes("*")) return true;
+  if (policy.allowed_tools.includes(toolName)) return true;
+
+  return false;
+}
+
+// MCP server integration: wrap the tool handler
+export function authorizedToolHandler(server: any) {
+  const originalCallTool = server.callTool.bind(server);
+
+  server.callTool = async (request: any, context: any) => {
+    const userRole = context.session?.userRole || "readonly-agent";
+    const toolName = request.params.name;
+
+    if (!isToolAllowed(userRole, toolName)) {
+      return {
+        content: [{ type: "text", text: `Access denied: tool "${toolName}" is not permitted for role "${userRole}".` }],
+        isError: true,
+      };
+    }
+    return originalCallTool(request, context);
+  };
+}
+```
+
+---
+
+
+## Contents
+
+- [6. Input Validation](references/details.md)
+- [7. Resource Access Control](references/details.md)
+- [8. Rate Limiting](references/details.md)
+- [9. Audit Logging](references/details.md)
+- [10. Deployment Hardening](references/details.md)
+- [11. Testing](references/details.md)
+- [Quick Reference Checklist](references/details.md)
+
+## When to Use This Skill
+
+Apply this skill whenever you are:
+
+- Deploying an MCP server that exposes tools (filesystem, database, API) to AI agents.
+- Connecting an agent runtime (Claude Desktop, Cursor, a custom orchestrator) to one or
+  more MCP servers over stdio, SSE, or Streamable HTTP transport.
+- Building a multi-tenant platform where multiple users share the same MCP server.
+- Passing sensitive data (PII, credentials, internal documents) through MCP resources.
+- Operating in a regulated environment (SOC 2, HIPAA, PCI-DSS) where tool invocations
+  must be auditable.
+
+If your MCP server only runs locally over stdio for a single developer with no network
+exposure, you can relax some transport-layer controls -- but input validation and audit
+logging still apply.
+
+---
+
+## Limitations
+
+- Apply guidance only within authorized scope; test destructive steps in non-production first.
+- Docs-only import: upstream scripts and templates not bundled.
+
+### Example
+
+```bash
+# Read-only first: inventory before any active step.
+which <tool> && <tool> --help | head -n 20
+```
+
+> Adapted from [BagelHole/DevOps-Security-Agent-Skills](https://github.com/BagelHole/DevOps-Security-Agent-Skills) (MIT); frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: helper scripts and templates not bundled.