# Security Guide

**Version:** 1.0
**Last Updated:** 2026-01-31

Comprehensive security guidelines for using Babysitter in development and production environments. This guide covers best practices for handling code, credentials, and network security.

---

## Table of Contents

- [Overview](#overview)
- [General Security](#general-security)
  - [Production Setup](#production-setup)
  - [Authentication Configuration](#authentication-configuration)
- [Credential Management](#credential-management)
  - [Environment Variables](#environment-variables)
  - [Breakpoints for Sensitive Operations](#breakpoints-for-sensitive-operations)
  - [Journal File Review](#journal-file-review)
- [Code Review Security](#code-review-security)
  - [Reviewing Generated Code](#reviewing-generated-code)
  - [Security Test Coverage](#security-test-coverage)
  - [Security Scanning](#security-scanning)
- [Network Security](#network-security)
- [Compliance Considerations](#compliance-considerations)
- [Related Documentation](#related-documentation)

---

## Overview

Babysitter handles code generation, execution, and may interact with credentials during workflows. Following proper security practices ensures that:

- Sensitive data is not exposed in logs or version control
- Production systems are protected through approval gates
- Network services are properly secured
- Audit trails are maintained for compliance

---

## General Security

### Best Practices

**DO:**
- Review all code changes before final approval
- Use breakpoints before deploying to production
- Keep `.a5c/` directories out of version control (add to `.gitignore`)
- Regularly update to latest versions
- Run with least privilege necessary

**DON'T:**
- Commit `.a5c/` directories with sensitive data
- Run untrusted process definitions without review
- Store credentials in journal files

### .gitignore Configuration

Ensure your `.gitignore` includes:

```gitignore
# Babysitter run data
.a5c/

# Environment files with secrets
.env
.env.local
.env.*.local

# Credentials
*.pem
*.key
credentials.json
```

---

## Credential Management

### Environment Variables

Use environment variables for secrets (recommended):

```javascript
// In process definition
const apiKey = process.env.API_KEY;
await ctx.task(deployTask, { apiKey });
```

**Never hardcode credentials:**

```javascript
// BAD - Don't do this!
const apiKey = "sk-1234567890abcdef";

// GOOD - Use environment variables
const apiKey = process.env.API_KEY;
```

### Breakpoints for Sensitive Operations

Use breakpoints to require human approval for sensitive operations:

```javascript
await ctx.breakpoint({
  question: 'Deploy with production credentials?',
  title: 'Production Deployment',
  context: { environment: 'production', critical: true }
});
```

### Journal File Review

Review journal files before sharing to ensure no secrets were leaked:

```bash
# Check for leaked secrets
grep -i "password\|secret\|key\|token" .a5c/runs/*/journal/journal.jsonl
```

**Security tip:** Always set `BABYSITTER_ALLOW_SECRET_LOGS=false` in production to prevent sensitive data from appearing in logs.

---

## Code Review Security

### Reviewing Generated Code

Before approving breakpoints, review generated code for security issues:

- **SQL injection vulnerabilities** - Ensure parameterized queries are used
- **XSS vulnerabilities** - Check for proper output encoding
- **Insecure dependencies** - Review any new package additions
- **Hardcoded secrets** - Scan for API keys, passwords, tokens

### Security Test Coverage

Check test coverage for security-related tests:

- Authentication tests
- Authorization tests
- Input validation tests
- Error handling tests

### Security Scanning

Run security scans before approval:

```javascript
const security = await ctx.task(securityScanTask, {
  tools: ['npm audit', 'eslint-plugin-security']
});
```

**Recommended security tools:**

| Tool | Purpose |
|------|---------|
| `npm audit` | Dependency vulnerability scanning |
| `eslint-plugin-security` | Static analysis for security issues |
| `snyk` | Comprehensive vulnerability detection |
| `semgrep` | Code pattern matching for security |

---

## Network Security

### For Distributed Teams

1. **Use VPN** for secure access
2. **Implement authentication** on all services
3. **Use HTTPS** for all external connections
4. **Audit access logs** regularly

### Network Configuration Checklist

| Requirement | Implementation |
|-------------|----------------|
| Local-only binding | `--host 127.0.0.1` |
| Access logging | Review service logs |
| Firewall rules | Restrict to known IPs/VPN |

---

## Compliance Considerations

### For Regulated Environments

Babysitter provides several features that support compliance requirements:

| Requirement | Babysitter Feature |
|-------------|-------------------|
| **Audit trail** | Journal provides complete event history |
| **Approval gates** | Breakpoints create approval records |
| **Access control** | Limit who can approve production deployments |
| **Data retention** | Define policy for old run cleanup |
| **Encryption** | Encrypt `.a5c/` directories if needed |

### Audit Trail

Every action in Babysitter is logged in the journal:

```bash
# View complete event history for a run
cat .a5c/runs/<runId>/journal/journal.jsonl | jq .

# Filter for approval events
jq 'select(.type=="BREAKPOINT_RELEASED")' .a5c/runs/*/journal/journal.jsonl
```

### Data Retention Policy

Implement a cleanup policy for old runs:

```bash
# Example: Remove runs older than 30 days
find .a5c/runs -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;
```

### Encryption at Rest

For sensitive environments, encrypt the `.a5c/` directory:

```bash
# Using encrypted filesystem
# Mount encrypted volume at .a5c/

# Or use encryption tools
gpg --symmetric --cipher-algo AES256 .a5c/runs/sensitive-run/journal/journal.jsonl
```

---

## Related Documentation

- [Configuration Reference](./configuration.md) - Environment variables and settings
- [CLI Reference](./cli-reference.md) - Command-line options
- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
- [Glossary](./glossary.md) - Term definitions
