# Security Configuration for Visualisable AI Backend

This document explains the security scanning setup for the Python backend that powers the HuggingFace Spaces API.

## Overview

The backend repository now includes automated security scanning via GitHub Actions that runs before deployment to HuggingFace Spaces. This ensures that security vulnerabilities are identified and can be addressed before code reaches production.

## Security Tools Used

1. **Snyk** - Comprehensive vulnerability scanning for Python dependencies
2. **Bandit** - Python-specific security linter for common security issues
3. **Safety** - Checks Python dependencies against known security vulnerabilities database

## Setup Instructions

### 1. GitHub Repository Setup

Since this repository currently only has HuggingFace as a remote, you'll need to:

1. Create a GitHub repository for the backend:
   ```bash
   # Add GitHub as a remote
   git remote add github https://github.com/YOUR_USERNAME/visualisable-ai-backend.git
   
   # Push to GitHub
   git push github main
   ```

2. Enable GitHub Actions in the repository settings

### 2. Required Secrets

Add the following secrets to your GitHub repository (Settings → Secrets and variables → Actions):

#### SNYK_TOKEN
1. Sign up for free at https://snyk.io
2. Go to Account Settings → Auth Token
3. Copy your personal auth token
4. Add as `SNYK_TOKEN` in GitHub secrets

#### HF_TOKEN (for automated deployment)
1. Go to https://huggingface.co/settings/tokens
2. Create a new token with write access
3. Add as `HF_TOKEN` in GitHub secrets

## Workflow Features

The `security-and-deploy.yml` workflow:

1. **Runs on every push and PR** to the main branch
2. **Security scanning includes:**
   - Dependency vulnerability scanning with Snyk
   - Code security analysis with Bandit
   - Known vulnerability checking with Safety
   - Results uploaded to GitHub Security tab
   - Project monitoring in Snyk dashboard

3. **Automated deployment** (only on main branch):
   - After security checks pass
   - Pushes directly to HuggingFace Spaces
   - Maintains deployment history in GitHub

## Current Security Status

### Known Issues

**transformers==4.35.0** has known vulnerabilities:
- Multiple security issues have been fixed in newer versions
- Recommended upgrade: `transformers>=4.36.0`

### To Fix Vulnerabilities

1. Update `requirements.txt`:
   ```txt
   transformers==4.36.2  # or latest stable version
   ```

2. Test locally:
   ```bash
   pip install -r requirements.txt
   python -m pytest  # if you have tests
   python app.py  # test the application
   ```

3. Commit and push:
   ```bash
   git add requirements.txt
   git commit -m "Security: Update transformers to fix vulnerabilities"
   git push github main  # triggers security scan and deployment
   ```

## Local Security Testing

Run security checks locally before pushing:

```bash
# Install tools
pip install snyk bandit safety

# Run Snyk (requires authentication)
snyk auth
snyk test

# Run Bandit
bandit -r backend/

# Run Safety
safety check
```

## Monitoring

- **GitHub Security Tab**: View SARIF reports and security alerts
- **Snyk Dashboard**: https://app.snyk.io - Monitor all vulnerabilities
- **GitHub Actions**: Check workflow runs for security scan results

## Security Best Practices

1. **Regular Updates**: Keep dependencies updated to latest secure versions
2. **Monitor Alerts**: Check Snyk dashboard weekly for new vulnerabilities
3. **Test Before Deploy**: Always test locally after updating dependencies
4. **Review PR Scans**: Security scans run on PRs - review before merging

## Troubleshooting

### Workflow not running
- Ensure GitHub Actions is enabled in repository settings
- Check that secrets are properly configured
- Verify the workflow file is in `.github/workflows/`

### Deployment failing
- Check HF_TOKEN has write permissions
- Ensure HuggingFace Space name matches in workflow
- Manual deployment fallback: `git push origin main`

### Security scan failures
- Non-blocking by default (continue-on-error: true)
- Review logs for specific vulnerabilities
- Update dependencies to fix issues
- Can be made blocking by removing continue-on-error

## Next Steps

1. Push this repository to GitHub
2. Configure the required secrets
3. Run the workflow to establish baseline security status
4. Address the transformers vulnerability
5. Consider making security checks blocking after initial setup