security: add comprehensive vulnerability prevention framework

.github/workflows/security-audit.yml

@@ -0,0 +1,144 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'scripts/**'
+      - '*.md'
+      - 'package*.json'
+  pull_request:
+    branches: [main]
+  schedule:
+    # Run weekly dependency audit
+    - cron: '0 0 * * 0'
+
+jobs:
+  shellcheck:
+    name: Shell Script Linting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get install -y shellcheck
+
+      - name: Lint shell scripts
+        run: |
+          find scripts -name "*.sh" -type f | while read script; do
+            echo "Linting: $script"
+            shellcheck -x "$script" || exit 1
+          done
+
+  npm-audit:
+    name: Dependency Vulnerability Scan
+    runs-on: ubuntu-latest
+    # Don't fail on audit warnings (advisory info only)
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+        if: hashFiles('package.json') != ''
+
+      - name: Check for package.json
+        id: check-pkg
+        run: |
+          if [[ -f package.json ]]; then
+            echo "has_package=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run npm audit
+        if: steps.check-pkg.outputs.has_package == 'true'
+        run: npm audit --audit-level=moderate
+        continue-on-error: true
+
+      - name: Generate audit report
+        if: steps.check-pkg.outputs.has_package == 'true'
+        run: npm audit --json > audit-report.json 2>&1 || true
+
+      - name: Upload audit report
+        if: steps.check-pkg.outputs.has_package == 'true'
+        uses: actions/upload-artifact@v3
+        with:
+          name: npm-audit-report
+          path: audit-report.json
+
+  secret-scan:
+    name: Secret Detection
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install git-secrets
+        run: |
+          git clone https://github.com/awslabs/git-secrets.git /tmp/git-secrets
+          cd /tmp/git-secrets && sudo make install
+
+      - name: Configure git-secrets patterns
+        run: |
+          git secrets --register-aws
+          # Add custom patterns for common secrets
+          git secrets --add-provider -- echo 'API[_-]?KEY|SECRET[_-]?KEY|PASSWORD'
+
+      - name: Scan for secrets
+        run: git secrets --scan
+
+  security-headers:
+    name: Security Best Practices Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for dangerous patterns
+        run: |
+          echo "Scanning for dangerous patterns..."
+
+          # Check for eval, which is extremely dangerous
+          if grep -r "eval " scripts/*.sh 2>/dev/null; then
+            echo "❌ ERROR: eval() found in scripts (security risk)"
+            exit 1
+          fi
+
+          # Check for hardcoded credentials patterns
+          if grep -rE '(password|token|api[_-]?key|secret)=["\047]' . \
+            --include="*.sh" --include="*.js" --include="*.json" \
+            --exclude-dir=node_modules --exclude-dir=.git; then
+            echo "⚠️  WARNING: Potential hardcoded credentials found"
+            exit 1
+          fi
+
+          # Check shell scripts for set -euo pipefail
+          for script in scripts/*.sh; do
+            if ! head -20 "$script" | grep -q "set -euo pipefail"; then
+              echo "⚠️  WARNING: $script missing 'set -euo pipefail'"
+            fi
+          done
+
+  compliance-check:
+    name: Security Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify SECURITY.md exists
+        run: |
+          if [[ ! -f SECURITY.md ]]; then
+            echo "ERROR: SECURITY.md not found"
+            exit 1
+          fi
+          echo "✓ SECURITY.md is present"
+
+      - name: Check SECURITY.md completeness
+        run: |
+          for section in "Prompt Injection" "GitHub Actions" "Credential"; do
+            if ! grep -q "$section" SECURITY.md; then
+              echo "WARNING: Section '$section' missing from SECURITY.md"
+            fi
+          done

SECURITY.md

@@ -0,0 +1,190 @@
+# Security Policy & Best Practices
+
+## Overview
+
+This document outlines security considerations and best practices for agency-agents and its integration with AI tools.
+
+## Known Security Considerations
+
+### 1. Prompt Injection Prevention
+
+**Issue**: Agent prompts may process untrusted user input (GitHub issues, comments, user messages).
+
+**Risk**: Malicious users can embed hidden directives in issues or messages to manipulate agent behavior, potentially:
+- Leaking sensitive information
+- Bypassing security checks
+- Executing unauthorized actions
+
+**Mitigation**:
+- Use `sanitizePromptInput()` utility (see below) for any user-provided data
+- Never interpolate raw user input directly into prompts
+- Validate and escape special characters before agent processing
+- Use allowlists for acceptable input patterns when possible
+
+**Example - BEFORE (unsafe)**:
+```javascript
+const agentPrompt = `Process this issue: ${userSubmittedIssue}`;
+```
+
+**Example - AFTER (safe)**:
+```javascript
+const sanitized = sanitizePromptInput(userSubmittedIssue);
+const agentPrompt = `Process this issue: ${sanitized}`;
+```
+
+### 2. GitHub Actions Security
+
+**Issue**: Shell scripts in CI/CD environments have access to high-privilege tokens.
+
+**Risk**: 
+- Prompt injection in GitHub Actions → token exfiltration
+- Shell command injection → arbitrary code execution
+- Credential leakage in logs
+
+**Mitigation**:
+- Never use `--yolo` mode in production workflows
+- Restrict token permissions with `permissions:` in workflow files
+- Use environment variables (GitHub Secrets) instead of hardcoding credentials
+- Sanitize any AI-generated shell commands before execution
+- Log only non-sensitive output
+
+**Example - Secure workflow**:
+```yaml
+jobs:
+  safe-agent:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read  # ← Minimal needed
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run agent
+        run: |
+          # Use secrets via environment, never in command line
+          my-agent-tool --safe-mode
+```
+
+### 3. Shell Script Injection Protection
+
+**Issue**: Dynamic shell commands without proper escaping are vulnerable to injection.
+
+**Risk**: Attackers can break out of intended command structure to execute arbitrary commands.
+
+**Mitigation**:
+- Use `escapeShellArg()` for any variable that becomes a shell argument
+- Prefer structured APIs over shell interpolation when possible
+- Use `set -euo pipefail` and error trapping
+- Never pipe untrusted data directly to `eval`, `bash`, or similar
+
+**Example - BEFORE (unsafe)**:
+```bash
+agent_name=$1
+eval "run_agent_$agent_name"  # VULNERABLE if $agent_name is user input
+```
+
+**Example - AFTER (safe)**:
+```bash
+agent_name=$1
+if [[ "$agent_name" =~ ^[a-z-]+$ ]]; then
+  "run_agent_$agent_name"  # Still safer than eval, but validate first
+else
+  echo "Invalid agent name"
+  exit 1
+fi
+```
+
+### 4. Hardcoded Credentials & Secrets
+
+**Issue**: API keys, tokens, or credentials should never be committed to version control.
+
+**Risk**: Exposed credentials can be abused by attackers; difficult to revoke if in git history.
+
+**Mitigation**:
+- Use `.env` files locally (add to `.gitignore`)
+- Store secrets in GitHub Secrets or external secret managers
+- Scan commits with `git-secrets` or similar tools
+- Never commit `.env`, `.credential`, or similar files
+- Rotate credentials if accidentally exposed
+
+**Safe pattern**:
+```bash
+# Load from environment, not from file
+if [[ -z "${AGENT_API_KEY:-}" ]]; then
+  echo "Error: AGENT_API_KEY not set. Set via environment variable."
+  exit 1
+fi
+```
+
+### 5. Input Validation
+
+**Issue**: Agents accept agent names, configuration parameters, and file paths from user input.
+
+**Risk**: Path traversal, invalid configurations, or denial of service.
+
+**Mitigation**:
+- Validate agent names against a whitelist of known agents
+- Validate file paths are within expected directories
+- Reject suspicious patterns (e.g., `../`, absolute paths outside sandbox)
+- Use type checking and schema validation for configuration
+
+**Example**:
+```javascript
+function validateAgentName(name) {
+  // Only allow lowercase letters, numbers, hyphens
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new Error(`Invalid agent name: "${name}"`);
+  }
+  return name;
+}
+```
+
+## Recommended Tools & Practices
+
+### For Node/JavaScript Projects
+- **npm audit**: Built-in vulnerability scanner
+- **snyk**: Continuous vulnerability monitoring
+- **eslint-plugin-security**: Linting for common security issues
+
+### For Bash Scripts
+- **shellcheck**: Lint shell scripts for common mistakes
+- **git-secrets**: Prevent credential leaks
+- **set -euo pipefail**: Standard error handling pattern
+
+### For GitHub Actions
+- **GitHub Security Lab**: Detect vulnerable workflows
+- **Dependabot**: Automated dependency updates
+- **CODEOWNERS**: Enforce review on security-sensitive files
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in agency-agents:
+
+1. **Do NOT open a public GitHub issue** (avoids disclosure before fix)
+2. Email security details to the maintainers
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if available)
+4. Allow 90 days for the maintainers to address before public disclosure
+
+## Compliance & Standards
+
+This project follows security best practices from:
+- OWASP Top 10
+- GitHub Security Lab recommendations
+- Node Security Project (NSP) guidelines
+- Cloud Native Security best practices
+
+## Future Improvements
+
+- [ ] Add security linting to CI/CD pipeline
+- [ ] Implement secret scanning in git history
+- [ ] Create security audit checklist for new agent additions
+- [ ] Add rate limiting to agent invocations
+- [ ] Document secure deployment patterns for production use
+
+---
+
+**Last Updated**: 2026-03-17
+**Maintainers**: Security Team