bentopdf/SECURITY.md

# Security Configuration

## Non-Root User Support

BentoPDF now uses nginx-unprivileged for enhanced security. This follows the Principle of Least Privilege and is essential for production environments.

### Security Benefits

- **Reduced Attack Surface**: If compromised, attackers won't have root privileges
- **Compliance**: Meets security standards like SOC 2, PCI DSS
- **Kubernetes/OpenShift Compatibility**: Works with security policies that require non-root execution
- **System Protection**: Prevents system-wide damage if the application is compromised

### Usage

#### Default Configuration (nginx-unprivileged)

```bash
docker build -t bentopdf .
docker run -p 8080:8080 bentopdf
```

#### Simple Mode

```bash
# Build with simple mode enabled
docker build --build-arg SIMPLE_MODE=true -t bentopdf-simple .

# Run the container
docker run -p 8080:8080 bentopdf-simple
```

#### Kubernetes Example

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bentopdf
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 2000
        runAsGroup: 2000
      containers:
        - name: bentopdf
          image: bentopdf:latest
          ports:
            - containerPort: 8080
```

#### Docker Compose Example

```yaml
version: '3.8'
services:
  bentopdf:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        SIMPLE_MODE: false
    ports:
      - '8080:8080'
    security_opt:
      - no-new-privileges:true
```

### Verification

To verify the container is running as non-root:

```bash
# Check the user inside the container
docker exec <container_id> whoami
# Should output: nginx

# Check the user ID
docker exec <container_id> id
# Should show UID/GID for nginx user (typically 101)
```

### Security Best Practices

1. **Use nginx-unprivileged**: Built-in non-root user with minimal privileges
2. **Regular Updates**: Keep the base image updated (currently using 1.29-alpine)
3. **Port 8080**: Use high port numbers to avoid requiring root privileges
4. **Security Scanning**: Regularly scan images for vulnerabilities
5. **Network Policies**: Implement network segmentation

### Troubleshooting

If you encounter permission issues:

1. **Check file ownership**: Ensure all application files are owned by the nginx user
2. **Verify PID directory**: Ensure `/etc/nginx/tmp/` directory exists and is writable
3. **Port binding**: Ensure port 8080 is available and not blocked by firewall

### Migration from Root

If migrating from a root-based setup:

1. Update your Dockerfile to use nginx-unprivileged base image
2. Change port mappings from 80 to 8080 in all configurations
3. Update nginx.conf to use `/etc/nginx/tmp/nginx.pid` for PID file
4. Rebuild your images with the new security settings
5. Update your deployment configurations (Kubernetes, Docker Compose, etc.)
6. Test thoroughly in a staging environment