lumina-nextjs-template/SECURITY.md

# Security

This template includes integrated security scanning powered by Semgrep.

## Security Dashboard

Access the Security Dashboard from the **Security** tab in your project:

- **Security Score**: Overall security health (0-100%)
- **Issue Breakdown**: Critical, High, Medium, and Low severity issues
- **Scan History**: View past security scans
- **Detailed Reports**: Line-by-line issue analysis with fix suggestions

## Running Security Scans

### Via Dashboard

1. Navigate to the **Security** tab
2. Click **Run Scan** button
3. Wait for analysis to complete
4. Review issues and recommendations

### Via Lumina Skill

Use the built-in Semgrep security skill:

```
User: "Scan the code for security issues"
User: "Check for OWASP Top 10 vulnerabilities"
User: "What's our security score?"
```

The skill will:
- Auto-install Semgrep if not present
- Run comprehensive security analysis
- Generate actionable reports
- Update the Security Dashboard

### Via Command Line

```bash
# Install Semgrep (if not installed) - OS-specific

# macOS (OSX)
brew install semgrep

# Linux
sudo apt-get update && sudo apt-get install -y semgrep

# Windows
choco install semgrep -y

# Universal (works on all platforms)
pip3 install semgrep

# Run security scan
semgrep --config=auto --json .

# OWASP Top 10 scan
semgrep --config=p/owasp-top-ten --json .

# Language-specific
semgrep --config=p/typescript --json .
semgrep --config=p/react --json .
```

## Security Score Calculation

Your security score is calculated based on:

```
Base Score: 100 points

Deductions:
- Critical Issue: -10 points each
- High Issue: -5 points each
- Medium Issue: -2 points each
- Low Issue: -0.5 points each

Final Score: max(0, Base Score - Total Deductions)
```

**Score Ratings:**
- 90-100: Excellent ✅
- 70-89: Good 👍
- 50-69: Fair ⚠️
- 0-49: Poor ❌

## Common Security Issues

### Critical Issues

- SQL Injection vulnerabilities
- Command Injection
- Path Traversal
- Hardcoded secrets/credentials
- Insecure cryptography

### High Issues

- XSS (Cross-Site Scripting)
- CSRF (Cross-Site Request Forgery)
- Insecure authentication
- Sensitive data exposure
- Insecure deserialization

### Medium Issues

- Missing input validation
- Weak password policies
- Insecure session management
- Missing security headers
- Information disclosure

### Low Issues

- Code smells
- Best practice violations
- Performance issues
- Deprecated functions

## Fixing Security Issues

### General Workflow

1. **Prioritize**: Fix critical and high severity issues first
2. **Review**: Understand the vulnerability and its impact
3. **Fix**: Apply recommended fixes or security patches
4. **Test**: Verify the fix doesn't break functionality
5. **Rescan**: Run a new scan to confirm the issue is resolved

### Using Lumina to Fix Issues

```
User: "Fix the SQL injection vulnerability in user-service.ts"
User: "Apply security patches for all critical issues"
User: "Review and fix the XSS issue on line 45"
```

Lumina will:
- Analyze the vulnerability
- Apply secure coding practices
- Update the code with fixes
- Run tests to verify

## Continuous Security

### Best Practices

1. **Regular Scans**: Run security scans before every deployment
2. **Pre-commit Hooks**: Add Semgrep to your git pre-commit hooks
3. **CI/CD Integration**: Include security scans in your pipeline
4. **Dependency Updates**: Keep dependencies up-to-date
5. **Security Reviews**: Conduct code reviews with security focus

### Pre-commit Hook Example

Add to `.git/hooks/pre-commit`:

```bash
#!/bin/bash
echo "Running security scan..."
semgrep --config=auto --error .

if [ $? -ne 0 ]; then
    echo "Security issues found! Commit blocked."
    echo "Run 'semgrep --config=auto .' to see details"
    exit 1
fi
```

### CI/CD Integration

#### GitHub Actions

```yaml
name: Security Scan
on: [push, pull_request]
jobs:
  semgrep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: pip3 install semgrep
      - run: semgrep --config=auto --error .
```

#### GitLab CI

```yaml
security_scan:
  image: returntocorp/semgrep
  script:
    - semgrep --config=auto --error .
```

## Security Rules

Semgrep scans use the following rule sets:

- **auto**: Automatically curated rules for your codebase
- **p/security-audit**: General security audit rules
- **p/owasp-top-ten**: OWASP Top 10 vulnerabilities
- **p/typescript**: TypeScript-specific security rules
- **p/react**: React security best practices
- **p/javascript**: JavaScript security patterns

## False Positives

If you encounter false positives:

1. Review the finding carefully
2. Add inline comments to suppress if legitimate:
   ```typescript
   // nosemgrep: rule-id
   const result = potentiallyUnsafeOperation();
   ```
3. Configure `.semgrepignore` to exclude files/patterns
4. Report false positives to improve Semgrep rules

## Resources

- [Semgrep Documentation](https://semgrep.dev/docs/)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Semgrep Rule Registry](https://semgrep.dev/explore)
- [Security Best Practices](https://cheatsheetseries.owasp.org/)

## Support

For security concerns or questions:
- Use the Semgrep security skill in Lumina
- Check the Security Dashboard for guidance
- Review Semgrep documentation
- Consult OWASP guidelines

---

**Remember**: Security is an ongoing process, not a one-time task. Regular scans and proactive security practices keep your application safe.