@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/templates/rollback-plan.md

@@ -1,201 +1,201 @@
-# Rollback Plan: v{version}
-
-**Released:** {date}
-**Tier:** {tier}
-**Previous version:** {previous_version}
-**Previous tag:** {previous_tag}
-**Author:** EZ Agents release-agent
-
----
-
-## Rollback Decision Criteria
-
-Roll back **immediately** if any of the following occur within {rollback_window} of release:
-
-### MVP Tier (30-minute window)
-- [ ] Application fails to start
-- [ ] Error rate exceeds 20%
-- [ ] Health endpoint returns non-200
-- [ ] Critical functionality broken (login, core user flow)
-
-### Medium Tier (15-minute window)
-- All MVP criteria plus:
-- [ ] Error rate increases >5% above pre-release baseline
-- [ ] P95 response time increases >200ms
-- [ ] Payment/auth system errors
-
-### Enterprise Tier (5-minute window)
-- All Medium criteria plus:
-- [ ] Any SLA breach
-- [ ] Any compliance-related failure
-- [ ] Security alert triggered
-- [ ] Data integrity issue detected
-
----
-
-## Rollback Procedure
-
-### Step 1: Decision (T+0)
-
-Whoever observes a rollback trigger calls rollback immediately.
-
-**Do NOT wait** to gather more data. Roll back, then investigate.
-
-Contact: {oncall_contact or "N/A"}
-
-### Step 2: Application Rollback (T+2 minutes)
-
-Choose rollback method based on deployment platform:
-
-**Vercel:**
-```bash
-vercel rollback
-# Or use Vercel dashboard → Deployments → select previous → Promote
-```
-
-**Netlify:**
-```bash
-# Netlify dashboard → Deploys → select previous deploy → Publish deploy
-```
-
-**Railway:**
-```bash
-# Railway dashboard → Deployments → select previous → Rollback
-```
-
-**Heroku:**
-```bash
-heroku releases
-heroku rollback v{previous_release_number}
-```
-
-**Generic (git-based deploy):**
-```bash
-git revert HEAD --no-edit
-git push origin main
-# Triggers your CI/CD to redeploy previous version
-```
-
-**Docker:**
-```bash
-docker pull {registry}/{image}:{previous_version}
-docker tag {registry}/{image}:{previous_version} {registry}/{image}:latest
-docker push {registry}/{image}:latest
-# Restart containers
-```
-
-### Step 3: Database Rollback (if applicable)
-
-{If database migrations were run:}
-
-**Check if rollback is needed:**
-Was a database migration applied as part of this release? Check migration history:
-```bash
-npx prisma migrate status 2>/dev/null
-# Or: cat .planning/releases/v{version}-migrations.md
-```
-
-**If migration must be rolled back:**
-
-```bash
-# Prisma
-npx prisma migrate resolve --rolled-back {migration_name}
-
-# Django
-python manage.py migrate {app_name} {previous_migration}
-
-# Rails
-rails db:rollback STEP=1
-
-# Flyway
-flyway undo
-```
-
-**WARNING:** Only roll back migrations if the data model change is backward-compatible OR no new data has been written. When in doubt: roll back application first, keep database as-is, hotfix forward.
-
-### Step 4: Verify Rollback (T+5 minutes)
-
-```bash
-# Check health
-curl -f https://{your-domain}/health || echo "HEALTH_CHECK_FAILED"
-
-# Check error rate
-# View in your monitoring dashboard — should return to pre-release baseline
-
-# Smoke test key flows
-# 1. Visit {your-domain}
-# 2. Log in with test account
-# 3. Perform core user action
-```
-
-Expected state after successful rollback:
-- Application responds to all requests
-- Error rate returns to pre-release baseline
-- Health endpoint returns 200
-- Core user flows work
-
-### Step 5: Post-Rollback Communication
-
-Notify relevant parties (team, users if customer-facing):
-
-```
-[Status Update]
-We rolled back v{version} due to [brief description].
-Service is restored. Root cause investigation in progress.
-ETA for fix: [estimate]
-```
-
-### Step 6: Post-Mortem
-
-After rollback is complete and service is stable:
-
-1. **Root cause analysis** — What caused the issue?
-2. **Timeline** — When detected, when rolled back, total impact duration
-3. **Fix plan** — How to fix before re-releasing
-4. **Process improvement** — What check could have caught this?
-
-Write post-mortem to: `.planning/releases/v{version}-POSTMORTEM.md`
-
-Update CHANGELOG.md:
-```markdown
-## [v{version}] — ROLLED BACK
-Released {date}, rolled back {rollback_date}.
-Reason: {brief reason}
-Fix scheduled for v{next_version}
-```
-
----
-
-## Forward Fix Procedure
-
-After rolling back, create a hotfix:
-
-```bash
-/ez:hotfix start {fix-description}
-# Make the fix
-/ez:hotfix complete {fix-description} {new_version}
-```
-
-Or plan a new phase if the fix is larger:
-
-```bash
-/ez:plan-phase {next_phase} --gaps
-```
-
----
-
-## Emergency Contacts
-
-{Fill in before going to production:}
-
-| Role | Contact | When to Call |
-|------|---------|--------------|
-| On-call developer | {name/handle} | Any rollback decision |
-| Database admin | {name/handle} | If DB rollback needed |
-| Customer success | {name/handle} | If customer impact >5 min |
-
----
-
-*Generated by EZ Agents release-agent*
-*Release: v{version} — {tier} tier*
-*Created: {timestamp}*
+# Rollback Plan: v{version}
+
+**Released:** {date}
+**Tier:** {tier}
+**Previous version:** {previous_version}
+**Previous tag:** {previous_tag}
+**Author:** EZ Agents release-agent
+
+---
+
+## Rollback Decision Criteria
+
+Roll back **immediately** if any of the following occur within {rollback_window} of release:
+
+### MVP Tier (30-minute window)
+- [ ] Application fails to start
+- [ ] Error rate exceeds 20%
+- [ ] Health endpoint returns non-200
+- [ ] Critical functionality broken (login, core user flow)
+
+### Medium Tier (15-minute window)
+- All MVP criteria plus:
+- [ ] Error rate increases >5% above pre-release baseline
+- [ ] P95 response time increases >200ms
+- [ ] Payment/auth system errors
+
+### Enterprise Tier (5-minute window)
+- All Medium criteria plus:
+- [ ] Any SLA breach
+- [ ] Any compliance-related failure
+- [ ] Security alert triggered
+- [ ] Data integrity issue detected
+
+---
+
+## Rollback Procedure
+
+### Step 1: Decision (T+0)
+
+Whoever observes a rollback trigger calls rollback immediately.
+
+**Do NOT wait** to gather more data. Roll back, then investigate.
+
+Contact: {oncall_contact or "N/A"}
+
+### Step 2: Application Rollback (T+2 minutes)
+
+Choose rollback method based on deployment platform:
+
+**Vercel:**
+```bash
+vercel rollback
+# Or use Vercel dashboard → Deployments → select previous → Promote
+```
+
+**Netlify:**
+```bash
+# Netlify dashboard → Deploys → select previous deploy → Publish deploy
+```
+
+**Railway:**
+```bash
+# Railway dashboard → Deployments → select previous → Rollback
+```
+
+**Heroku:**
+```bash
+heroku releases
+heroku rollback v{previous_release_number}
+```
+
+**Generic (git-based deploy):**
+```bash
+git revert HEAD --no-edit
+git push origin main
+# Triggers your CI/CD to redeploy previous version
+```
+
+**Docker:**
+```bash
+docker pull {registry}/{image}:{previous_version}
+docker tag {registry}/{image}:{previous_version} {registry}/{image}:latest
+docker push {registry}/{image}:latest
+# Restart containers
+```
+
+### Step 3: Database Rollback (if applicable)
+
+{If database migrations were run:}
+
+**Check if rollback is needed:**
+Was a database migration applied as part of this release? Check migration history:
+```bash
+npx prisma migrate status 2>/dev/null
+# Or: cat .planning/releases/v{version}-migrations.md
+```
+
+**If migration must be rolled back:**
+
+```bash
+# Prisma
+npx prisma migrate resolve --rolled-back {migration_name}
+
+# Django
+python manage.py migrate {app_name} {previous_migration}
+
+# Rails
+rails db:rollback STEP=1
+
+# Flyway
+flyway undo
+```
+
+**WARNING:** Only roll back migrations if the data model change is backward-compatible OR no new data has been written. When in doubt: roll back application first, keep database as-is, hotfix forward.
+
+### Step 4: Verify Rollback (T+5 minutes)
+
+```bash
+# Check health
+curl -f https://{your-domain}/health || echo "HEALTH_CHECK_FAILED"
+
+# Check error rate
+# View in your monitoring dashboard — should return to pre-release baseline
+
+# Smoke test key flows
+# 1. Visit {your-domain}
+# 2. Log in with test account
+# 3. Perform core user action
+```
+
+Expected state after successful rollback:
+- Application responds to all requests
+- Error rate returns to pre-release baseline
+- Health endpoint returns 200
+- Core user flows work
+
+### Step 5: Post-Rollback Communication
+
+Notify relevant parties (team, users if customer-facing):
+
+```
+[Status Update]
+We rolled back v{version} due to [brief description].
+Service is restored. Root cause investigation in progress.
+ETA for fix: [estimate]
+```
+
+### Step 6: Post-Mortem
+
+After rollback is complete and service is stable:
+
+1. **Root cause analysis** — What caused the issue?
+2. **Timeline** — When detected, when rolled back, total impact duration
+3. **Fix plan** — How to fix before re-releasing
+4. **Process improvement** — What check could have caught this?
+
+Write post-mortem to: `.planning/releases/v{version}-POSTMORTEM.md`
+
+Update CHANGELOG.md:
+```markdown
+## [v{version}] — ROLLED BACK
+Released {date}, rolled back {rollback_date}.
+Reason: {brief reason}
+Fix scheduled for v{next_version}
+```
+
+---
+
+## Forward Fix Procedure
+
+After rolling back, create a hotfix:
+
+```bash
+/ez:hotfix start {fix-description}
+# Make the fix
+/ez:hotfix complete {fix-description} {new_version}
+```
+
+Or plan a new phase if the fix is larger:
+
+```bash
+/ez:plan-phase {next_phase} --gaps
+```
+
+---
+
+## Emergency Contacts
+
+{Fill in before going to production:}
+
+| Role | Contact | When to Call |
+|------|---------|--------------|
+| On-call developer | {name/handle} | Any rollback decision |
+| Database admin | {name/handle} | If DB rollback needed |
+| Customer success | {name/handle} | If customer impact >5 min |
+
+---
+
+*Generated by EZ Agents release-agent*
+*Release: v{version} — {tier} tier*
+*Created: {timestamp}*

package/ez-agents/templates/security-user-setup.md

@@ -0,0 +1,244 @@
+# Security Operations User Setup Guide
+
+This guide covers manual setup steps and human-action checkpoints for Security Operations workflows.
+
+---
+
+## Prerequisites
+
+### Docker for Security Scanning
+
+Security scans use OWASP ZAP via Docker. Install Docker Desktop:
+
+- **Windows:** https://docs.docker.com/desktop/install/windows-install/
+- **macOS:** https://docs.docker.com/desktop/install/mac-install/
+- **Linux:** https://docs.docker.com/engine/install/
+
+Verify installation:
+```bash
+docker --version
+docker run hello-world
+```
+
+---
+
+## Cloud Credentials
+
+### AWS Credentials
+
+For AWS WAF and Secrets Manager operations:
+
+1. **Create IAM User** (if not exists):
+   ```bash
+   aws iam create-user --user-name ez-security-automation
+   ```
+
+2. **Attach Policies**:
+   - `AWSWAF_FullAccess` (for WAF management)
+   - `SecretsManagerReadWrite` (for secret rotation)
+
+3. **Create Access Key**:
+   ```bash
+   aws iam create-access-key --user-name ez-security-automation
+   ```
+
+4. **Store Credentials Securely**:
+   ```bash
+   # macOS Keychain
+   security add-generic-password -s "ez-agents" -a "aws-access-key" -w "YOUR_ACCESS_KEY"
+   security add-generic-password -s "ez-agents" -a "aws-secret-key" -w "YOUR_SECRET_KEY"
+   
+   # Or use environment variables (temporary)
+   export AWS_ACCESS_KEY_ID="..."
+   export AWS_SECRET_ACCESS_KEY="..."
+   ```
+
+### Cloudflare Credentials
+
+For Cloudflare WAF operations:
+
+1. **Generate API Token**:
+   - Go to Cloudflare Dashboard → Profile → API Tokens
+   - Create token with `Zone` → `WAF` → `Edit` permissions
+
+2. **Store Securely**:
+   ```bash
+   # macOS Keychain
+   security add-generic-password -s "ez-agents" -a "cloudflare-api-token" -w "YOUR_TOKEN"
+   ```
+
+---
+
+## Dashboard-Only WAF Steps
+
+Some WAF configurations require manual dashboard interaction:
+
+### AWS WAF
+
+1. **Navigate to AWS WAF Console**:
+   https://console.aws.amazon.com/wafv2/
+
+2. **Select Web ACL**:
+   - Choose your application's Web ACL
+   - Review current rules
+
+3. **Add Rate-Based Rule**:
+   - Click "Add rules" → "Create rule"
+   - Select "Rate-based rule"
+   - Configure:
+     - Name: `RateLimit-Auth`
+     - Limit: 2000 requests per 5 minutes
+     - Aggregate key type: IP
+
+4. **Enable Logging**:
+   - Go to "Logging" tab
+   - Click "Add logging"
+   - Select Kinesis Data Firehose or S3 bucket
+
+### Cloudflare WAF
+
+1. **Navigate to Cloudflare Dashboard**:
+   https://dash.cloudflare.com/
+
+2. **Select Domain** → **Security** → **WAF**
+
+3. **Create Custom Rule**:
+   - Click "Create rule"
+   - Name: `Rate Limit Login`
+   - Field: `URI Path` → `Equals` → `/login`
+   - Choose rate limiting threshold
+   - Action: `Block` or `Managed Challenge`
+
+4. **Enable Bot Fight Mode** (if available):
+   - Security → Bots
+   - Toggle "Bot Fight Mode" to On
+
+---
+
+## Break-Glass / Manual Rotation Steps
+
+### Emergency Secret Rotation
+
+When automated rotation fails or during security incidents:
+
+1. **Identify Compromised Secret**:
+   ```
+   Secret ID: _______________
+   Systems Affected: _______________
+   ```
+
+2. **Generate New Secret**:
+   - Use password manager or secure generator
+   - Minimum 32 characters, mixed case, numbers, symbols
+
+3. **Update All Systems**:
+   - List all systems using this secret:
+     ```
+     1. _______________
+     2. _______________
+     3. _______________
+     ```
+
+4. **Verify Functionality**:
+   - Test each system with new secret
+   - Monitor logs for authentication failures
+
+5. **Revoke Old Secret**:
+   - Delete or disable old credential
+   - Document revocation time
+
+6. **Post-Incident Review**:
+   - Schedule post-mortem within 48 hours
+   - Update runbooks with lessons learned
+
+### Break-Glass Access
+
+For emergency access when normal authentication fails:
+
+1. **Contact Security Team**:
+   - Primary: _______________
+   - Secondary: _______________
+
+2. **Document Justification**:
+   ```
+   Reason for break-glass: _______________
+   Requested by: _______________
+   Approved by: _______________
+   Time: _______________
+   ```
+
+3. **Use Emergency Credentials**:
+   - Retrieve from secure storage (e.g., physical safe, separate vault)
+   - Use for minimum time necessary
+   - Rotate immediately after use
+
+4. **Post-Use Actions**:
+   - Change all break-glass credentials
+   - File incident report
+   - Review access logs
+
+---
+
+## Audit Log Configuration
+
+### Enable Audit Logging
+
+For compliance and security monitoring:
+
+1. **Configure Log Destination**:
+   - S3 bucket for long-term storage
+   - CloudWatch Logs for real-time monitoring
+   - SIEM integration (if available)
+
+2. **Set Retention Policy**:
+   - Minimum: 90 days online
+   - Archive: 7 years for compliance
+
+3. **Configure Alerts**:
+   - Failed authentication attempts (>5 in 5 minutes)
+   - Privilege escalation events
+   - Secret rotation failures
+
+---
+
+## Compliance Evidence Collection
+
+### For Audits
+
+Maintain these artifacts:
+
+| Artifact | Location | Owner |
+|----------|----------|-------|
+| Security scan reports | `.planning/security/scans/` | Security Team |
+| Secret rotation logs | `.planning/security/rotations/` | Security Team |
+| RBAC manifests | `.planning/security/access/` | Security Team |
+| Compliance checklists | `.planning/security/evidence/` | Compliance Team |
+
+### Evidence Retention
+
+- **GDPR**: Keep for duration of processing + 3 years
+- **HIPAA**: Minimum 6 years
+- **SOC 2**: Minimum 1 year (3 recommended)
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Docker scan fails | Docker not running | Start Docker Desktop |
+| AWS permission denied | Missing IAM policy | Attach required policies |
+| Cloudflare API error | Invalid token | Regenerate API token |
+| Secret rotation fails | Secret in use | Schedule maintenance window |
+
+### Getting Help
+
+- **Documentation**: `.planning/phases/23-security-operations/`
+- **Templates**: `ez-agents/templates/security-*`
+- **Incident Runbook**: `ez-agents/templates/incident-runbook.md`
+
+---
+
+*Guide Version: 1.0 | Last Updated: 2026-03-20*