proagents 1.0.0

package/proagents/runbooks/README.md

@@ -0,0 +1,219 @@
+# Runbooks
+
+Standard operating procedures for common operational scenarios.
+
+---
+
+## Overview
+
+Runbooks provide step-by-step procedures for handling incidents, debugging production issues, managing vulnerabilities, and responding to performance problems.
+
+---
+
+## Available Runbooks
+
+| Runbook | Scenario |
+|---------|----------|
+| [Incident Response](./incident-response.md) | Production incident handling |
+| [Production Debugging](./production-debugging.md) | Debugging live issues |
+| [Dependency Vulnerability](./dependency-vulnerability.md) | Security vulnerability response |
+| [Performance Degradation](./performance-degradation.md) | Performance issue response |
+
+---
+
+## Quick Reference
+
+### Severity Levels
+
+| Level | Description | Response Time | Examples |
+|-------|-------------|---------------|----------|
+| **SEV1** | Critical - System down | 15 minutes | Complete outage, data loss |
+| **SEV2** | High - Major feature broken | 1 hour | Auth broken, payments failing |
+| **SEV3** | Medium - Degraded service | 4 hours | Slow performance, partial outage |
+| **SEV4** | Low - Minor issue | 24 hours | UI glitch, non-critical bug |
+
+---
+
+## Incident Response Quick Start
+
+```bash
+# 1. Assess the situation
+/runbook incident assess
+
+# 2. Start incident response
+/runbook incident start --severity SEV2 --description "Login failures"
+
+# 3. Follow guided steps
+/runbook incident guide
+
+# 4. Close incident
+/runbook incident close --resolution "Fixed auth service timeout"
+```
+
+---
+
+## Runbook Commands
+
+```bash
+# List available runbooks
+/runbook list
+
+# Start a runbook
+/runbook start <runbook-name>
+
+# View runbook steps
+/runbook view <runbook-name>
+
+# Log runbook execution
+/runbook log --action "Restarted service"
+
+# Generate post-mortem
+/runbook postmortem --incident INC-123
+```
+
+---
+
+## Runbook Structure
+
+Each runbook follows this structure:
+
+```markdown
+# Runbook: [Name]
+
+## Overview
+[Description and when to use]
+
+## Prerequisites
+[Required access, tools, knowledge]
+
+## Steps
+[Numbered step-by-step procedure]
+
+## Verification
+[How to confirm resolution]
+
+## Escalation
+[When and how to escalate]
+
+## Post-Incident
+[Cleanup and documentation]
+```
+
+---
+
+## On-Call Responsibilities
+
+### Before On-Call
+
+- [ ] Review recent deployments
+- [ ] Check monitoring dashboards
+- [ ] Verify access to all systems
+- [ ] Confirm notification settings
+- [ ] Review open incidents/issues
+
+### During On-Call
+
+- [ ] Respond to alerts within SLA
+- [ ] Follow runbooks for known issues
+- [ ] Escalate when necessary
+- [ ] Document all actions
+- [ ] Hand off to next on-call
+
+### After Incident
+
+- [ ] Update incident timeline
+- [ ] Create post-mortem if needed
+- [ ] Update runbooks with learnings
+- [ ] Follow up on action items
+
+---
+
+## Creating Custom Runbooks
+
+```yaml
+# runbooks/custom/my-runbook.yaml
+name: "My Custom Runbook"
+description: "Handle specific scenario"
+severity: "SEV3"
+tags: ["custom", "my-service"]
+
+prerequisites:
+  - access: "production-ssh"
+  - tool: "kubectl"
+
+steps:
+  - name: "Assess situation"
+    description: "Check service status"
+    command: "kubectl get pods -n my-service"
+    expected: "All pods running"
+
+  - name: "Check logs"
+    description: "Review recent errors"
+    command: "kubectl logs -n my-service --tail=100"
+    look_for:
+      - "ERROR"
+      - "Exception"
+
+  - name: "Apply fix"
+    description: "Restart affected pods"
+    command: "kubectl rollout restart deployment/my-service -n my-service"
+    requires_confirmation: true
+
+verification:
+  - "All pods are Running"
+  - "No errors in logs"
+  - "Health checks passing"
+
+escalation:
+  after: "30 minutes"
+  to: "#platform-team"
+```
+
+---
+
+## Integration
+
+### With PagerDuty/OpsGenie
+
+```yaml
+# proagents.config.yaml
+runbooks:
+  integration:
+    pagerduty:
+      enabled: true
+      auto_attach: true
+
+    opsgenie:
+      enabled: true
+      auto_create_alert: true
+
+  auto_trigger:
+    - alert: "High CPU Usage"
+      runbook: "performance-degradation"
+    - alert: "Auth Service Down"
+      runbook: "incident-response"
+```
+
+### With Slack/Teams
+
+```yaml
+runbooks:
+  notifications:
+    slack:
+      channel: "#incidents"
+      notify_on:
+        - "incident_started"
+        - "escalation"
+        - "resolution"
+```
+
+---
+
+## Best Practices
+
+1. **Keep Updated**: Review runbooks after each incident
+2. **Test Regularly**: Run drills to verify procedures work
+3. **Be Specific**: Include exact commands, not vague instructions
+4. **Include Context**: Explain why each step is needed
+5. **Version Control**: Track runbook changes in git
+6. **Cross-Train**: Ensure multiple team members can execute

package/proagents/runbooks/dependency-vulnerability.md

@@ -0,0 +1,505 @@
+# Dependency Vulnerability Runbook
+
+Response procedures for security vulnerabilities in dependencies.
+
+---
+
+## Overview
+
+This runbook provides step-by-step procedures for responding to security vulnerabilities discovered in project dependencies.
+
+**When to use:**
+- Security advisory received for a dependency
+- Automated vulnerability scan detected issues
+- CVE announced affecting your dependencies
+- Security researcher report received
+
+---
+
+## Prerequisites
+
+- [ ] Access to dependency management tools (npm, pip, etc.)
+- [ ] Access to security scanning tools (Snyk, npm audit, etc.)
+- [ ] Permission to create/merge security PRs
+- [ ] Understanding of project dependencies
+- [ ] Contact info for security team
+
+---
+
+## Severity Classification
+
+### CVSS Score Mapping
+
+| CVSS Score | Severity | Response Time |
+|------------|----------|---------------|
+| 9.0 - 10.0 | Critical | 24 hours |
+| 7.0 - 8.9 | High | 72 hours |
+| 4.0 - 6.9 | Medium | 1 week |
+| 0.1 - 3.9 | Low | 1 month |
+
+### Impact Assessment
+
+| Factor | Questions |
+|--------|-----------|
+| Exploitability | Is there a public exploit? Is it being exploited in the wild? |
+| Attack Vector | Network accessible? Requires user interaction? |
+| Data Risk | Can it access sensitive data? Can it modify data? |
+| System Access | Can it execute arbitrary code? Can it escalate privileges? |
+| Usage Pattern | Is the vulnerable code path actually used? |
+
+---
+
+## Step 1: Assess the Vulnerability
+
+### 1.1 Gather Information
+
+```bash
+# Check vulnerability details
+npm audit
+
+# Or using Snyk
+snyk test
+
+# Get specific CVE details
+curl -s https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=CVE-2024-XXXXX | jq
+```
+
+### 1.2 Document the Vulnerability
+
+```markdown
+## Vulnerability Assessment
+
+**CVE ID**: CVE-2024-XXXXX
+**Package**: lodash
+**Affected Version**: < 4.17.21
+**Our Version**: 4.17.19
+**Severity**: High (CVSS 7.5)
+
+**Description**: Prototype pollution vulnerability allows attackers to
+inject properties into object prototypes, potentially leading to
+remote code execution.
+
+**Exploit Available**: Yes, public PoC available
+**Being Exploited**: Yes, active exploitation reported
+
+**Our Usage**:
+- Direct dependency in 3 projects
+- Transitive dependency in 12 projects
+- Used functions: _.get, _.set, _.merge (vulnerable)
+```
+
+### 1.3 Assess Impact
+
+```bash
+# Find all affected projects
+grep -r "lodash" */package.json
+
+# Check if vulnerable functions are used
+grep -r "\.merge\|\.set\|\.defaultsDeep" src/
+
+# Check dependency tree
+npm ls lodash
+
+# Generate dependency graph
+npx depcruise --output-type dot src | dot -T svg > deps.svg
+```
+
+---
+
+## Step 2: Immediate Response
+
+### 2.1 Critical/High Severity
+
+**For actively exploited vulnerabilities:**
+
+```bash
+# 1. Notify security team immediately
+/security alert --severity critical --cve CVE-2024-XXXXX
+
+# 2. Check for signs of exploitation
+grep -r "vulnerable_pattern" /var/log/app/
+
+# 3. Consider temporary mitigation
+# - Disable affected feature
+# - Add WAF rules
+# - Restrict access
+```
+
+**Temporary Mitigation Options:**
+
+```javascript
+// Option A: Patch at runtime (temporary!)
+const _ = require('lodash');
+const originalMerge = _.merge;
+_.merge = function(target, ...sources) {
+  // Validate inputs
+  for (const source of sources) {
+    if (source && typeof source === 'object') {
+      if ('__proto__' in source || 'constructor' in source) {
+        throw new Error('Prototype pollution attempt blocked');
+      }
+    }
+  }
+  return originalMerge(target, ...sources);
+};
+```
+
+```yaml
+# Option B: WAF rule (AWS WAF example)
+Rules:
+  - Name: BlockPrototypePollution
+    Priority: 1
+    Action: Block
+    Statement:
+      ByteMatchStatement:
+        SearchString: "__proto__"
+        FieldToMatch:
+          Body: {}
+```
+
+### 2.2 Medium/Low Severity
+
+```bash
+# Create tracking issue
+/security issue create \
+  --title "Vulnerability in lodash < 4.17.21" \
+  --severity medium \
+  --cve CVE-2024-XXXXX \
+  --due-date "2024-01-22"
+
+# Add to sprint planning
+/jira add-to-sprint --issue SEC-123 --sprint current
+```
+
+---
+
+## Step 3: Identify Fix Path
+
+### 3.1 Check for Patched Version
+
+```bash
+# Check available versions
+npm view lodash versions
+
+# Check if fix is available
+npm audit fix --dry-run
+
+# Check advisory for fixed version
+npm audit --json | jq '.vulnerabilities.lodash.fixAvailable'
+```
+
+### 3.2 Analyze Upgrade Path
+
+```bash
+# Check for breaking changes
+npm outdated lodash
+
+# Review changelog
+curl -s https://raw.githubusercontent.com/lodash/lodash/master/CHANGELOG.md
+
+# Check compatibility
+npm ls lodash
+# Note any packages requiring older version
+```
+
+### 3.3 Decision Matrix
+
+| Scenario | Action |
+|----------|--------|
+| Direct fix available | Upgrade directly |
+| Breaking changes | Plan migration, temporary mitigation |
+| Transitive dependency | Upgrade parent package |
+| No fix available | Alternative package or fork |
+| False positive | Document and suppress |
+
+---
+
+## Step 4: Apply Fix
+
+### 4.1 Direct Dependency Fix
+
+```bash
+# Create security branch
+git checkout -b security/fix-lodash-vulnerability
+
+# Update package
+npm install lodash@4.17.21
+
+# Verify fix
+npm audit
+
+# Run tests
+npm test
+
+# Commit with security reference
+git commit -m "fix(security): upgrade lodash to fix CVE-2024-XXXXX
+
+- Upgrades lodash from 4.17.19 to 4.17.21
+- Fixes prototype pollution vulnerability (CVSS 7.5)
+- Advisory: https://github.com/advisories/GHSA-xxxx
+
+Security: HIGH"
+```
+
+### 4.2 Transitive Dependency Fix
+
+```bash
+# Option A: Upgrade parent package
+npm install parent-package@latest
+
+# Option B: Use npm overrides (npm 8.3+)
+# In package.json:
+{
+  "overrides": {
+    "lodash": "4.17.21"
+  }
+}
+
+# Option C: Use resolutions (yarn)
+# In package.json:
+{
+  "resolutions": {
+    "lodash": "4.17.21"
+  }
+}
+
+# Verify
+npm ls lodash
+# Should show only 4.17.21
+```
+
+### 4.3 Replace Package (if no fix)
+
+```bash
+# Find alternatives
+npx npm-check-updates --doctor
+
+# Replace usage
+# e.g., Replace lodash.merge with spread operator or native methods
+
+# Before
+const merged = _.merge({}, defaults, options);
+
+# After
+const merged = { ...defaults, ...options };
+```
+
+---
+
+## Step 5: Test & Verify
+
+### 5.1 Run Security Tests
+
+```bash
+# Full vulnerability scan
+npm audit
+snyk test
+
+# Security-focused tests
+npm run test:security
+
+# Penetration testing (if applicable)
+npm run test:pentest
+```
+
+### 5.2 Run Regression Tests
+
+```bash
+# Full test suite
+npm test
+
+# Integration tests
+npm run test:integration
+
+# E2E tests
+npm run test:e2e
+```
+
+### 5.3 Verify Fix
+
+```bash
+# Confirm patched version
+npm ls lodash
+# Should show: lodash@4.17.21
+
+# Confirm no vulnerabilities
+npm audit
+# Should show: found 0 vulnerabilities
+
+# Test the specific vulnerability (in isolated environment)
+# DO NOT run in production
+node test-vulnerability.js
+# Should fail/be blocked
+```
+
+---
+
+## Step 6: Deploy & Monitor
+
+### 6.1 Deploy Fix
+
+```bash
+# Fast-track for critical vulnerabilities
+# Skip normal deployment queue
+
+# Deploy to staging
+kubectl apply -f k8s/staging/
+
+# Verify staging
+npm run verify:staging
+
+# Deploy to production
+kubectl apply -f k8s/production/
+
+# Verify production
+npm run verify:production
+```
+
+### 6.2 Monitor for Issues
+
+```bash
+# Watch error rates
+# Set up alert for any increase after deployment
+
+# Watch for exploitation attempts
+# Monitor WAF/security logs
+
+# Check application logs
+kubectl logs -f -n production -l app=my-service | grep -i security
+```
+
+---
+
+## Step 7: Documentation & Follow-up
+
+### 7.1 Document the Response
+
+```markdown
+# Security Incident Report: CVE-2024-XXXXX
+
+## Summary
+- **Vulnerability**: Prototype pollution in lodash
+- **Severity**: High (CVSS 7.5)
+- **Affected**: 3 direct, 12 transitive dependencies
+- **Detection**: Automated Snyk scan
+- **Resolution**: Upgraded to lodash@4.17.21
+
+## Timeline
+- 2024-01-15 09:00 - Vulnerability detected by Snyk
+- 2024-01-15 09:15 - Assessment completed
+- 2024-01-15 10:00 - Fix developed and tested
+- 2024-01-15 11:00 - Deployed to production
+- 2024-01-15 11:30 - Verified fix in production
+
+## Impact
+- No evidence of exploitation
+- No user data compromised
+- Downtime: 0
+
+## Lessons Learned
+- Need better monitoring for lodash-related packages
+- Consider adding prototype pollution WAF rules proactively
+
+## Action Items
+- [ ] Add automated lodash monitoring (due: Jan 22)
+- [ ] Implement WAF rules for prototype pollution (due: Jan 25)
+- [ ] Review similar dependencies (due: Jan 30)
+```
+
+### 7.2 Update Security Processes
+
+```bash
+# Add to vulnerability monitoring
+echo "lodash" >> .security/monitored-packages.txt
+
+# Update security policy
+git add SECURITY.md
+git commit -m "docs: update security policy after CVE-2024-XXXXX"
+
+# Update runbook if needed
+git add runbooks/dependency-vulnerability.md
+git commit -m "docs: add lessons learned from CVE-2024-XXXXX"
+```
+
+### 7.3 Preventive Measures
+
+```yaml
+# Add to CI/CD pipeline
+# .github/workflows/security.yml
+name: Security Scan
+on: [push, pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm audit --audit-level=moderate
+      - run: npx snyk test
+```
+
+```json
+// Add to package.json
+{
+  "scripts": {
+    "preinstall": "npm audit",
+    "postinstall": "npm audit fix"
+  }
+}
+```
+
+---
+
+## Commands Reference
+
+```bash
+# Security scanning
+npm audit                        # NPM audit
+npm audit fix                    # Auto-fix vulnerabilities
+npm audit fix --force            # Force fix (may break things)
+snyk test                        # Snyk scan
+snyk monitor                     # Add to Snyk monitoring
+
+# Dependency analysis
+npm ls <package>                 # Show dependency tree
+npm outdated                     # Show outdated packages
+npm why <package>                # Why package is installed
+
+# Quick fixes
+npm update <package>             # Update to latest allowed
+npm install <package>@latest     # Update to absolute latest
+npm install <package>@X.Y.Z      # Install specific version
+
+# Create security PR
+/security fix --cve CVE-XXXX --create-pr
+```
+
+---
+
+## Escalation
+
+### When to Escalate
+
+- Critical vulnerability with active exploitation
+- Unable to fix without breaking changes
+- Fix requires significant refactoring
+- Unsure about impact assessment
+- External disclosure required
+
+### Escalation Contacts
+
+| Role | Contact | When |
+|------|---------|------|
+| Security Lead | @security-lead | All critical/high vulnerabilities |
+| Engineering Lead | @eng-lead | Breaking changes required |
+| Legal/Compliance | @legal | Data breach potential |
+| PR/Communications | @pr-team | Public disclosure needed |
+
+---
+
+## Resources
+
+- [NVD Database](https://nvd.nist.gov/)
+- [GitHub Security Advisories](https://github.com/advisories)
+- [Snyk Vulnerability DB](https://snyk.io/vuln)
+- [npm Advisories](https://www.npmjs.com/advisories)
+- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)