opencode-skills-collection 4.0.68 → 4.0.69

package/bundled-skills/ai-coding-agent-guardrails/references/details.md

@@ -0,0 +1,753 @@
+# Details (moved from SKILL.md)
+
+> Extended reference content for `ai-coding-agent-guardrails`, kept under `references/` so the entrypoint stays within the audit budget.
+
+## Code Review Gates
+
+### GitHub Actions Workflow for Agent PRs
+
+```yaml
+# .github/workflows/agent-pr-review.yaml
+name: Agent PR Security Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  detect-agent-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      is_agent: ${{ steps.check.outputs.is_agent }}
+    steps:
+      - name: Check if PR is from an AI agent
+        id: check
+        run: |
+          BRANCH="${{ github.head_ref }}"
+          AUTHOR="${{ github.event.pull_request.user.login }}"
+          BODY="${{ github.event.pull_request.body }}"
+
+          IS_AGENT="false"
+          if [[ "$BRANCH" == ai/* ]] || [[ "$BRANCH" == agent/* ]]; then
+            IS_AGENT="true"
+          fi
+          if echo "$BODY" | grep -qi "generated with.*claude\|generated by.*copilot\|generated by.*cursor\|generated by.*codex"; then
+            IS_AGENT="true"
+          fi
+          if [[ "$AUTHOR" == *"bot"* ]] || [[ "$AUTHOR" == *"agent"* ]]; then
+            IS_AGENT="true"
+          fi
+          echo "is_agent=$IS_AGENT" >> "$GITHUB_OUTPUT"
+
+  security-scan:
+    needs: detect-agent-pr
+    if: needs.detect-agent-pr.outputs.is_agent == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Semgrep security scan
+        uses: semgrep/semgrep-action@v1
+        with:
+          config: >-
+            p/default
+            p/owasp-top-ten
+            p/command-injection
+            p/sql-injection
+            p/xss
+
+      - name: Scan for secrets with Trufflehog
+        uses: trufflesecurity/trufflehog@main
+        with:
+          extra_args: --only-verified
+
+      - name: Check for dependency changes
+        run: |
+          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
+          DEP_FILES="package.json package-lock.json requirements.txt Pipfile.lock go.sum Cargo.lock"
+
+          for dep_file in $DEP_FILES; do
+            if echo "$CHANGED_FILES" | grep -q "$dep_file"; then
+              echo "::warning::Agent modified dependency file: $dep_file"
+              echo "DEPENDENCY_CHANGED=true" >> "$GITHUB_ENV"
+            fi
+          done
+
+      - name: Require extra review for dependency changes
+        if: env.DEPENDENCY_CHANGED == 'true'
+        run: |
+          gh pr edit "${{ github.event.pull_request.number }}" \
+            --add-label "agent-dependency-change" \
+            --add-label "requires-security-review"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  enforce-review:
+    needs: detect-agent-pr
+    if: needs.detect-agent-pr.outputs.is_agent == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label as agent-generated
+        run: |
+          gh pr edit "${{ github.event.pull_request.number }}" \
+            --add-label "ai-generated"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Enforce minimum reviewers
+        run: |
+          echo "Agent-generated PR detected."
+          echo "This PR requires at least 2 human approvals before merge."
+```
+
+### Branch Protection for Agent Branches
+
+```bash
+#!/bin/bash
+# configure-branch-protection.sh
+# Set up branch protection rules for agent-generated PRs via GitHub API
+
+OWNER="your-org"
+REPO="your-repo"
+
+gh api repos/${OWNER}/${REPO}/rulesets \
+  --method POST \
+  --input - <<'EOF'
+{
+  "name": "Agent Branch Protection",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/ai/*", "refs/heads/agent/*"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 2,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": true,
+        "require_last_push_approval": true
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "required_status_checks": [
+          { "context": "security-scan" },
+          { "context": "test-suite" },
+          { "context": "secret-detection" }
+        ],
+        "strict_required_status_checks_policy": true
+      }
+    }
+  ]
+}
+EOF
+```
+
+---
+
+
+## Repository Configuration
+
+### Cursor Rules (.cursorrules)
+
+```text
+# .cursorrules
+
+You are working in a production codebase. Follow these rules strictly:
+
+
+## Security Rules
+- Never hardcode secrets, API keys, tokens, or passwords in source code.
+- Never read or display the contents of .env files or secret configuration files.
+- Never disable SSL verification, CSRF protection, or authentication middleware.
+- Never use eval(), exec(), or similar dynamic code execution functions. <!-- security-allowlist: documented payload technique reference, do not execute outside authorized scope -->
+- Never introduce SQL string concatenation; always use parameterized queries.
+
+
+## File Restrictions
+- Do not modify any files in: infrastructure/, terraform/, .github/workflows/, deploy/
+- Do not create or modify Dockerfiles without explicit approval.
+- Do not modify CI/CD configuration files.
+
+
+## Code Quality
+- Every new function must have a corresponding unit test.
+- All error handling must be explicit; never silently swallow exceptions.
+- Follow existing patterns for logging, error handling, and API responses.
+- Maximum function length: 50 lines. Refactor if exceeded.
+
+
+## Git Behavior
+- Create branches with the prefix: ai/
+- Write descriptive commit messages referencing the task or issue.
+- Never force push or rebase shared branches.
+```
+
+### GitHub Copilot Configuration
+
+```yaml
+# .github/copilot-config.yml
+#
+# Note: Copilot content exclusion is configured at the org/repo level
+# via GitHub settings. This file documents intended exclusions and
+# can be referenced by org admins when configuring the settings at
+# github.com > Org Settings > Copilot > Content Exclusions.
+
+content_exclusions:
+  paths:
+    - "**/.env*"
+    - "**/secrets/**"
+    - "**/*.pem"
+    - "**/*.key"
+    - "**/infrastructure/**"
+    - "**/terraform/**"
+    - "**/.aws/**"
+    - "**/credentials*"
+
+# Copilot content exclusion via organization settings (recommended):
+# 1. Go to Organization Settings > Copilot > Content exclusion
+# 2. Add repository paths:
+#    - ".env*"
+#    - "secrets/**"
+#    - "infrastructure/**"
+#    - "*.pem"
+#    - "*.key"
+```
+
+### OpenAI Codex Configuration
+
+```markdown
+<!-- codex.md or AGENTS.md for Codex CLI -->
+
+
+## Rules
+
+- Do not modify files outside of src/ and tests/ directories.
+- Do not install packages or modify dependency files without listing changes first.
+- Run `npm test` after every code change to verify nothing is broken.
+- Never access network resources or make HTTP requests during code generation.
+- All generated code must include error handling.
+- Prefix all branch names with `agent/codex/`.
+```
+
+---
+
+
+## Network Controls
+
+### Firewall Rules for Agent Environments
+
+```bash
+#!/bin/bash
+# agent-network-controls.sh
+# Restrict network access for agent execution environments
+
+# Create a dedicated chain for agent traffic
+iptables -N AGENT_CHAIN
+
+# Allow DNS resolution
+iptables -A AGENT_CHAIN -p udp --dport 53 -j ACCEPT
+iptables -A AGENT_CHAIN -p tcp --dport 53 -j ACCEPT
+
+# Allow package registries
+iptables -A AGENT_CHAIN -d registry.npmjs.org -p tcp --dport 443 -j ACCEPT
+iptables -A AGENT_CHAIN -d pypi.org -p tcp --dport 443 -j ACCEPT
+iptables -A AGENT_CHAIN -d files.pythonhosted.org -p tcp --dport 443 -j ACCEPT
+iptables -A AGENT_CHAIN -d proxy.golang.org -p tcp --dport 443 -j ACCEPT
+
+# Allow GitHub for git operations
+iptables -A AGENT_CHAIN -d github.com -p tcp --dport 443 -j ACCEPT
+iptables -A AGENT_CHAIN -d github.com -p tcp --dport 22 -j ACCEPT
+
+# Block everything else
+iptables -A AGENT_CHAIN -j DROP
+
+# Apply to agent user
+iptables -A OUTPUT -m owner --uid-owner ai-agent -j AGENT_CHAIN
+```
+
+### Squid Proxy for Agent Traffic
+
+```conf
+# /etc/squid/squid-agent.conf
+# Transparent proxy for AI agent network requests
+
+acl agent_user proxy_auth ai-agent
+acl allowed_domains dstdomain .npmjs.org .pypi.org .github.com .golang.org
+
+# Allow only specific domains
+http_access allow agent_user allowed_domains
+http_access deny agent_user
+
+# Log all agent requests for auditing
+access_log /var/log/squid/agent-access.log squid
+log_mime_hdrs on
+
+# Request size limits
+request_body_max_size 10 MB
+reply_body_max_size 50 MB
+
+http_port 3128
+```
+
+### Docker Compose with Network Isolation
+
+```yaml
+# docker-compose.agent.yaml
+version: "3.8"
+
+services:
+  agent-sandbox:
+    build:
+      context: .
+      dockerfile: Dockerfile.agent-sandbox
+    networks:
+      - agent-restricted
+    volumes:
+      - ./src:/workspace/src
+      - ./tests:/workspace/tests:rw
+    mem_limit: 4g
+    cpus: 2
+    pids_limit: 256
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    tmpfs:
+      - /tmp:size=512m
+
+  agent-proxy:
+    image: ubuntu/squid:latest
+    networks:
+      - agent-restricted
+      - external
+    volumes:
+      - ./squid-agent.conf:/etc/squid/squid.conf:ro
+    ports:
+      - "3128:3128"
+
+networks:
+  agent-restricted:
+    internal: true   # No external access from this network
+  external:
+    driver: bridge
+```
+
+---
+
+
+## Audit Trail
+
+### Git Trailers for AI-Generated Code
+
+```bash
+#!/bin/bash
+# git-ai-commit.sh
+# Wrapper for committing agent-generated code with proper attribution
+
+AGENT_NAME="${AI_AGENT_NAME:-unknown-agent}"
+AGENT_VERSION="${AI_AGENT_VERSION:-unknown}"
+TASK_ID="${AI_TASK_ID:-none}"
+
+git commit -m "$(cat <<EOF
+$1
+
+AI-Generated-By: ${AGENT_NAME} ${AGENT_VERSION}
+AI-Task-ID: ${TASK_ID}
+AI-Reviewed-By: pending
+Co-Authored-By: ${AGENT_NAME} <noreply@${AGENT_NAME}.ai>
+EOF
+)"
+```
+
+### Agent Action Logger
+
+```python
+#!/usr/bin/env python3
+"""agent_audit_logger.py - Log all AI agent actions for compliance."""
+
+import json
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+LOG_DIR = Path(os.environ.get("AGENT_LOG_DIR", "/var/log/ai-agents"))
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+logger = logging.getLogger("agent_audit")
+handler = logging.FileHandler(LOG_DIR / "agent-actions.jsonl")
+handler.setFormatter(logging.Formatter("%(message)s"))
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+
+def log_action(
+    agent: str,
+    action: str,
+    target: str,
+    details: dict | None = None,
+    user: str = "system",
+) -> None:
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "agent": agent,
+        "user": user,
+        "action": action,
+        "target": target,
+        "details": details or {},
+        "session_id": os.environ.get("AGENT_SESSION_ID", "unknown"),
+    }
+    logger.info(json.dumps(entry))
+
+
+def log_file_read(agent: str, filepath: str) -> None:
+    log_action(agent, "file_read", filepath)
+
+
+def log_file_write(agent: str, filepath: str, lines_changed: int) -> None:
+    log_action(agent, "file_write", filepath, {"lines_changed": lines_changed})
+
+
+def log_command(agent: str, command: str, exit_code: int) -> None:
+    log_action(agent, "command_exec", command, {"exit_code": exit_code})
+
+
+def log_pr_created(agent: str, pr_url: str, files_changed: list[str]) -> None:
+    log_action(agent, "pr_created", pr_url, {"files_changed": files_changed})
+
+
+# Usage example:
+# log_file_write("claude-code", "src/api/handler.py", 42)
+# log_command("claude-code", "npm test", 0)
+# log_pr_created("claude-code", "https://github.com/org/repo/pull/99", ["src/main.py"])
+```
+
+### Querying the Audit Log
+
+```bash
+#!/bin/bash
+# query-agent-audit.sh
+# Query agent audit logs for compliance reporting
+
+LOG_FILE="/var/log/ai-agents/agent-actions.jsonl"
+
+echo "=== Agent Activity Summary ==="
+
+echo ""
+echo "Actions by agent (last 24h):"
+jq -r 'select(.timestamp > (now - 86400 | todate)) | .agent' "$LOG_FILE" \
+  | sort | uniq -c | sort -rn
+
+echo ""
+echo "File writes by agent:"
+jq -r 'select(.action == "file_write") | "\(.agent) -> \(.target)"' "$LOG_FILE" \
+  | sort | uniq -c | sort -rn
+
+echo ""
+echo "Commands executed:"
+jq -r 'select(.action == "command_exec") | "\(.agent): \(.target) (exit: \(.details.exit_code))"' "$LOG_FILE" \
+  | tail -20
+
+echo ""
+echo "PRs created by agents:"
+jq -r 'select(.action == "pr_created") | "\(.agent): \(.target)"' "$LOG_FILE"
+```
+
+---
+
+
+## Team Policies
+
+### Agent Usage Policy Template
+
+```yaml
+# .github/agent-policy.yaml
+# Team policy for AI coding agent usage
+
+policy:
+  version: "1.0"
+  last_updated: "2025-06-01"
+
+  general:
+    - All developers may use AI coding agents for code generation
+    - Agent-generated code has the same quality and security bar as human code
+    - Developers are responsible for all code they submit, regardless of origin
+
+  required_review:
+    standard_code:
+      min_reviewers: 1
+      agent_generated: 2
+    infrastructure_changes:
+      min_reviewers: 2
+      agent_generated: "blocked"  # Agents may not modify infra
+    security_sensitive:
+      min_reviewers: 2
+      requires: ["security-team-member"]
+      agent_generated: 2
+      additional_requires: ["security-team-lead"]
+
+  escalation:
+    - type: "dependency_addition"
+      action: "require security review"
+    - type: "auth_or_crypto_changes"
+      action: "require security team approval"
+    - type: "ci_cd_changes"
+      action: "blocked for agents"
+    - type: "database_migration"
+      action: "require DBA review"
+    - type: "api_contract_change"
+      action: "require API owner approval"
+
+  allowed_use_cases:
+    - "Writing unit and integration tests"
+    - "Implementing well-specified features with clear requirements"
+    - "Refactoring code with existing test coverage"
+    - "Writing documentation and code comments"
+    - "Fixing linter warnings and code style issues"
+    - "Generating boilerplate code from templates"
+
+  prohibited_use_cases:
+    - "Modifying authentication or authorization logic"
+    - "Writing or changing cryptographic implementations"
+    - "Modifying CI/CD pipelines or deployment configs"
+    - "Changing infrastructure-as-code without human authorship"
+    - "Accessing production databases or systems"
+    - "Modifying security controls or audit logging"
+```
+
+### CODEOWNERS for Agent Oversight
+
+```text
+# .github/CODEOWNERS
+# Require specific reviewers for agent-sensitive areas
+
+# All agent-generated branches require security team review
+# (enforced via branch protection rules for ai/* and agent/* branches)
+
+# Infrastructure is off-limits to agents and requires platform team
+/infrastructure/    @platform-team
+/terraform/         @platform-team
+/.github/workflows/ @platform-team @security-team
+
+# Security-sensitive code requires security team
+/src/auth/          @security-team
+/src/crypto/        @security-team
+/src/middleware/auth* @security-team
+
+# Dependency files require security review
+package.json        @security-team @tech-leads
+package-lock.json   @security-team
+requirements.txt    @security-team @tech-leads
+go.sum              @security-team
+```
+
+---
+
+
+## Testing Agent Output
+
+### Mandatory Test Coverage for Agent Code
+
+```yaml
+# .github/workflows/agent-test-gate.yaml
+name: Agent Code Test Gate
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files
+        id: changes
+        run: |
+          FILES=$(git diff --name-only origin/main...HEAD -- '*.py' '*.js' '*.ts' '*.go')
+          echo "changed_files=$FILES" >> "$GITHUB_OUTPUT"
+
+      - name: Run tests with coverage
+        run: |
+          # Python
+          if ls tests/*.py &>/dev/null; then
+            pip install pytest pytest-cov
+            pytest --cov=src --cov-report=json --cov-fail-under=80
+          fi
+
+          # Node.js
+          if [ -f package.json ]; then
+            npm ci
+            npm test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
+          fi
+
+      - name: Verify new code has tests
+        run: |
+          NEW_FILES=$(git diff --name-only --diff-filter=A origin/main...HEAD -- 'src/**')
+          for file in $NEW_FILES; do
+            base=$(basename "$file" | sed 's/\.[^.]*$//')
+            if ! find tests/ -name "*${base}*" | grep -q .; then
+              echo "::error::New file $file has no corresponding test file"
+              exit 1
+            fi
+          done
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Bandit (Python)
+        if: hashFiles('**/*.py') != ''
+        run: |
+          pip install bandit
+          bandit -r src/ -f json -o bandit-report.json || true
+          ISSUES=$(jq '.results | length' bandit-report.json)
+          if [ "$ISSUES" -gt 0 ]; then
+            echo "::warning::Bandit found $ISSUES security issue(s) in agent-generated code"
+            jq -r '.results[] | "  \(.severity): \(.issue_text) in \(.filename):\(.line_number)"' bandit-report.json
+          fi
+
+      - name: Run ESLint security plugin (JavaScript/TypeScript)
+        if: hashFiles('**/*.js') != '' || hashFiles('**/*.ts') != ''
+        run: |
+          npm ci
+          npx eslint --no-eslintrc \
+            --plugin security \
+            --rule '{"security/detect-eval-with-expression": "error"}' \
+            --rule '{"security/detect-non-literal-fs-filename": "warn"}' \
+            --rule '{"security/detect-possible-timing-attacks": "error"}' \
+            --rule '{"security/detect-no-csrf-before-method-override": "error"}' \
+            src/ || true
+
+  mutation-testing:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run mutation testing on agent-changed files
+        run: |
+          CHANGED=$(git diff --name-only origin/main...HEAD -- 'src/**/*.py')
+          if [ -n "$CHANGED" ]; then
+            pip install mutmut
+            for file in $CHANGED; do
+              echo "Mutation testing: $file"
+              mutmut run --paths-to-mutate="$file" --no-progress || true
+            done
+            mutmut results
+          fi
+```
+
+### Pre-merge Validation Script
+
+```bash
+#!/bin/bash
+# validate-agent-pr.sh
+# Run all validation checks before merging an agent-generated PR
+
+set -euo pipefail
+
+PR_BRANCH="${1:?Usage: validate-agent-pr.sh <branch-name>}"
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PASS=0
+FAIL=0
+WARN=0
+
+check() {
+  local name="$1"
+  shift
+  if "$@" >/dev/null 2>&1; then
+    echo -e "${GREEN}PASS${NC}: $name"
+    ((PASS++))
+  else
+    echo -e "${RED}FAIL${NC}: $name"
+    ((FAIL++))
+  fi
+}
+
+warn_check() {
+  local name="$1"
+  shift
+  if "$@" >/dev/null 2>&1; then
+    echo -e "${GREEN}PASS${NC}: $name"
+    ((PASS++))
+  else
+    echo -e "${YELLOW}WARN${NC}: $name"
+    ((WARN++))
+  fi
+}
+
+echo "Validating agent PR: $PR_BRANCH"
+echo "=============================="
+
+# Check that branch follows naming convention
+check "Branch naming convention" [[ "$PR_BRANCH" == ai/* || "$PR_BRANCH" == agent/* ]]
+
+# Check for secrets in diff
+check "No secrets in diff" git secrets --scan
+
+# Check that tests pass
+check "Test suite passes" npm test
+
+# Check test coverage threshold
+warn_check "Coverage above 80%" npm test -- --coverage --coverageThreshold='{"global":{"lines":80}}'
+
+# Check for forbidden file modifications
+FORBIDDEN_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" -- \
+  'infrastructure/' 'terraform/' '.github/workflows/' '.env*' '*.pem' '*.key')
+check "No forbidden file changes" [ -z "$FORBIDDEN_CHANGES" ]
+
+# Check for new dependencies
+DEP_CHANGES=$(git diff --name-only origin/main..."$PR_BRANCH" -- \
+  'package.json' 'requirements.txt' 'go.mod' 'Cargo.toml')
+warn_check "No dependency changes" [ -z "$DEP_CHANGES" ]
+
+# Check commit messages have AI trailers
+MISSING_TRAILERS=$(git log origin/main.."$PR_BRANCH" --format='%B' \
+  | grep -cL "AI-Generated-By:" || true)
+warn_check "All commits have AI attribution trailers" [ "$MISSING_TRAILERS" -eq 0 ]
+
+echo ""
+echo "=============================="
+echo -e "Results: ${GREEN}${PASS} passed${NC}, ${RED}${FAIL} failed${NC}, ${YELLOW}${WARN} warnings${NC}"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo -e "${RED}PR validation FAILED. Address issues before merging.${NC}"
+  exit 1
+fi
+
+echo -e "${GREEN}PR validation passed.${NC}"
+```
+
+---
+
+
+## Quick Reference
+
+| Control | Tool | Purpose |
+|---|---|---|
+| Permission boundaries | CLAUDE.md, .cursorrules, codex.md | Restrict agent behavior per-repo |
+| Secret scanning | git-secrets, pre-commit hooks | Block credential leaks |
+| Sandbox isolation | Docker, seccomp, network=none | Contain agent execution |
+| Code review gates | GitHub Actions, branch protection | Enforce human review |
+| Network controls | iptables, Squid proxy | Limit agent internet access |
+| Audit trail | Git trailers, JSONL logger | Track AI-generated code |
+| Test requirements | Coverage gates, mutation testing | Validate agent output quality |
+| Team policies | agent-policy.yaml, CODEOWNERS | Govern agent usage org-wide |
+