Assist_Design/docs/operations/security-monitoring.md

# Security Monitoring Setup

## 🎯 Quick Start

Your project now has comprehensive security monitoring! Here's what was set up:

## 📦 What's Included

### 1. **GitHub Actions Workflows** (`.github/workflows/`)

#### `security.yml` - Main Security Pipeline

- **Daily scans** at 9 AM UTC
- **Pull request** security checks
- **Manual trigger** available
- Includes:
  - Dependency vulnerability audit
  - Dependency review (for PRs)
  - CodeQL security analysis
  - Outdated dependencies check

#### `pr-checks.yml` - Pull Request Quality Gate

- Runs on every PR
- Checks: linting, type safety, security audit, tests, formatting

#### `dependency-update.yml` - Auto-merge Helper

- Auto-approves safe dependency updates
- Auto-merges patch updates
- Works with Dependabot

### 2. **Dependabot Configuration** (`.github/dependabot.yml`)

- **Weekly** dependency updates (Mondays at 9 AM)
- Groups updates to reduce PR noise
- Monitors: npm, GitHub Actions, Docker
- Auto-labels PRs for easy tracking

### 3. **Git Hooks** (`.husky/`)

- **pre-commit**: Runs linting and type checks
- **pre-push**: Optional security audit (commented out by default)

### 4. **NPM Scripts** (Enhanced)

```bash
pnpm security:audit      # Full security audit
pnpm security:check      # Check high/critical vulnerabilities
pnpm security:fix        # Auto-fix vulnerabilities when possible
pnpm security:report     # Generate JSON report
pnpm update:check        # Check for outdated packages
pnpm update:safe         # Safe update with verification
```

## 🚀 Getting Started

### 1. Fix Current Vulnerability

```bash
# Update Next.js to fix the current high-severity issue
cd /home/barsa/projects/customer_portal/customer-portal
pnpm add next@latest --filter @customer-portal/portal
pnpm security:check
```

### 2. Enable GitHub Actions

- Push these changes to GitHub
- Go to **Settings → Actions → General**
- Enable **Read and write permissions** for workflows
- Go to **Settings → Code security → Dependabot**
- Enable **Dependabot alerts** and **security updates**

### 3. Optional: Enable Stricter Pre-push Checks

Edit `.husky/pre-push` and uncomment the security check lines to run audits before every push.

## 📊 Monitoring Dashboard

### View Security Status

1. **GitHub Actions**: Check `.github/workflows/security.yml` runs
2. **Dependabot**: View PRs in **Pull requests** tab
3. **Security Advisories**: Check **Security** tab
4. **Artifacts**: Download audit reports from workflow runs

### Email Notifications

GitHub will automatically notify you about:

- Security vulnerabilities
- Failed workflow runs
- Dependabot PRs

### Configure Notifications

1. Go to **Settings → Notifications**
2. Enable **Actions** and **Dependabot** notifications
3. Choose **Email** or **Web** notifications

## 🔄 Workflow Triggers

### Automatic

- **Daily**: Full security scan at 9 AM UTC
- **On Push**: Security checks when pushing to main/master
- **On PR**: Comprehensive checks including dependency review
- **Weekly**: Dependabot checks for updates (Mondays)

### Manual

```bash
# Trigger from GitHub UI
1. Go to Actions → Security Audit
2. Click "Run workflow"
3. Select branch and run

# Or use GitHub CLI
gh workflow run security.yml
```

## 🛠️ Local Development

### Before Committing

```bash
pnpm lint              # Check code quality
pnpm type-check        # Verify types
pnpm security:check    # Check vulnerabilities
pnpm test              # Run tests
```

### Weekly Maintenance

```bash
pnpm update:check      # See what's outdated
pnpm update:safe       # Update safely
```

### Generate Security Report

```bash
pnpm security:report
# Creates security-report.json with detailed findings
```

## 📋 Best Practices

### For Daily Development

- ✅ Run `pnpm security:check` weekly
- ✅ Review Dependabot PRs within 48 hours
- ✅ Keep dependencies up to date
- ✅ Never commit secrets (use `.env` files)

### For Security Issues

- 🚨 **High/Critical**: Fix within 24 hours
- ⚠️ **Medium**: Fix within 1 week
- ℹ️ **Low**: Fix in next maintenance window

### For Dependency Updates

- ✅ **Patch versions**: Auto-merge after CI passes
- ⚠️ **Minor versions**: Review and test
- 🚨 **Major versions**: Careful review and thorough testing

## 🔍 Troubleshooting

### If Security Scan Fails

```bash
# View detailed audit
pnpm audit

# Try to auto-fix
pnpm security:fix

# If auto-fix doesn't work, update manually
pnpm update [package-name]@latest
```

### If Workflow Fails

1. Check workflow logs in GitHub Actions
2. Run the same commands locally
3. Ensure all secrets are configured
4. Verify permissions are set correctly

## 📚 Additional Resources

- **Security Policy**: See `SECURITY.md`
- **Complete Guide**: See `docs/how-it-works/COMPLETE-GUIDE.md`
- **GitHub Security**: [https://docs.github.com/en/code-security](https://docs.github.com/en/code-security)
- **npm Security**: [https://docs.npmjs.com/security](https://docs.npmjs.com/security)

## 🎉 Next Steps

1. **Fix the current vulnerability**:

   ```bash
   pnpm add next@16.0.10 --filter @customer-portal/portal
   ```

2. **Push to GitHub** to activate workflows:

   ```bash
   git add .
   git commit -m "feat: add comprehensive security monitoring"
   git push
   ```

3. **Enable Dependabot** in GitHub repository settings

4. **Review first security scan** in GitHub Actions

---

**Need Help?** Check `SECURITY.md` for detailed security policies and contact information.