{
  "id": "page:docs-user-guide-reference-security",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/reference/security.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/reference/security.md",
    "sourceKind": "repo-docs",
    "title": "Security Guide",
    "displayName": "Security Guide",
    "slug": "docs/user-guide/reference/security",
    "articlePath": "wiki/docs/user-guide/reference/security.md",
    "article": "\n[Docs](../index.md) › [Reference](./index.md) › Security\n\n# Security Guide\n\n**Version:** 1.1\n**Last Updated:** 2026-06-22\n\nComprehensive security guidelines for using Babysitter in development and production environments. This guide covers best practices for handling code, credentials, and network security.\n\n---\n\n## On this page\n\n- [Overview](#overview)\n- [General Security](#general-security)\n  - [Best Practices](#best-practices)\n  - [.gitignore Configuration](#gitignore-configuration)\n- [Credential Management](#credential-management)\n  - [Environment Variables](#environment-variables)\n  - [Breakpoints for Sensitive Operations](#breakpoints-for-sensitive-operations)\n  - [Journal File Review](#journal-file-review)\n  - [Secrets in the Adapters CLI and CI Triggers](#secrets-in-the-adapters-cli-and-ci-triggers)\n- [Tamper-Evident Approvals](#tamper-evident-approvals)\n- [Code Review Security](#code-review-security)\n  - [Reviewing Generated Code](#reviewing-generated-code)\n  - [Security Test Coverage](#security-test-coverage)\n  - [Security Scanning](#security-scanning)\n- [Network Security](#network-security)\n- [Compliance Considerations](#compliance-considerations)\n- [Related Documentation](#related-documentation)\n\n---\n\n## Overview\n\nBabysitter handles code generation, execution, and may interact with credentials during workflows. Following proper security practices ensures that:\n\n- Sensitive data is not exposed in logs or version control\n- Production systems are protected through approval gates\n- Network services are properly secured\n- Audit trails are maintained for compliance\n\n---\n\n## General Security\n\n### Best Practices\n\n**DO:**\n- Review all code changes before final approval\n- Use [breakpoints](./glossary.md) before deploying to production\n- Keep `.a5c/` directories out of version control (add to `.gitignore`)\n- Regularly update to latest versions\n- Run with least privilege necessary\n\n**DON'T:**\n- Commit `.a5c/` directories with sensitive data\n- Run untrusted process definitions without review\n- Store credentials in journal files\n\n### .gitignore Configuration\n\nEnsure your `.gitignore` includes:\n\n```gitignore\n# Babysitter run data\n.a5c/\n\n# Environment files with secrets\n.env\n.env.local\n.env.*.local\n\n# Credentials\n*.pem\n*.key\ncredentials.json\n```\n\n---\n\n## Credential Management\n\n### Environment Variables\n\nUse environment variables for secrets (recommended):\n\n```javascript\n// In process definition\nconst apiKey = process.env.API_KEY;\nawait ctx.task(deployTask, { apiKey });\n```\n\n**Never hardcode credentials:**\n\n```javascript\n// BAD - Don't do this!\nconst apiKey = \"sk-1234567890abcdef\";\n\n// GOOD - Use environment variables\nconst apiKey = process.env.API_KEY;\n```\n\n### Breakpoints for Sensitive Operations\n\nUse breakpoints to require human approval for sensitive operations:\n\n```javascript\nawait ctx.breakpoint({\n  question: 'Deploy with production credentials?',\n  title: 'Production Deployment',\n  context: { environment: 'production', critical: true }\n});\n```\n\n### Journal File Review\n\nReview journal files before sharing to ensure no secrets were leaked:\n\n```bash\n# Check for leaked secrets\ngrep -i \"password\\|secret\\|key\\|token\" .a5c/runs/*/journal/*.json\n```\n\n**Security tip:** Always set `BABYSITTER_ALLOW_SECRET_LOGS=false` in production to prevent sensitive data from appearing in logs.\n\n### Secrets in the Adapters CLI and CI Triggers\n\nThe host-side `adapters` CLI (package `@a5c-ai/adapters-cli`) launches and authenticates harnesses on your machine, so it can touch provider credentials. Keep secrets out of arguments and shell history:\n\n- **Prefer ambient credentials.** Use `adapters auth check` and `adapters auth setup <agent>` to verify and configure provider auth rather than passing keys inline. See the [Adapters CLI Reference](./adapters-cli.md).\n- **Avoid keys on the command line.** When launching a provider, prefer the provider's own credential chain over `--api-key`; for token-based providers use `--auth-command` to emit a short-lived bearer token instead of a static key. Anything passed as an argument may be captured in shell history and process listings.\n- **Scope environment injection.** When passing variables into a run with `adapters run --env KEY=VALUE`, pass secret *names* sourced from your environment, never literal secret values.\n\nFor CI, Babysitter v6 **Triggers** normalize inbound webhooks from GitHub, GitLab, and Bitbucket (via the `adapters-triggers` action). Treat trigger pipelines like any other secret-bearing CI job:\n\n- Store provider keys and tokens as CI secrets and reference them by name (e.g. repository/organization secrets), never inline in workflow files.\n- Grant the workflow only the token scopes it needs.\n- Be cautious with triggers that run on untrusted input (such as PRs from forks), which can expose secrets to attacker-controlled code.\n\nSee [GitHub Actions Setup](../../github-actions-setup-babysitter.md) for end-to-end CI configuration.\n\n---\n\n## Tamper-Evident Approvals\n\nThe **Breakpoints Adapter** (v6) records human-in-the-loop approvals to a durable backend and **cryptographically signs** each approval - the \"proven\" approval model. This makes the approval trail *verifiable* rather than merely *trusted*: you can confirm who approved what, and detect after-the-fact tampering, instead of relying on an unsigned log that could be edited.\n\nThis complements the [journal audit trail](#audit-trail): the journal records that an approval happened, while signed approvals let you cryptographically verify the record is authentic and unaltered.\n\nThe Breakpoints Adapter replaces the legacy `breakpoints-pro` package (now deprecated). For the approval workflow and how to route breakpoints to a durable backend, see [Breakpoints](../features/breakpoints.md).\n\n---\n\n## Code Review Security\n\n### Reviewing Generated Code\n\nBefore approving breakpoints, review generated code for security issues:\n\n- **SQL injection vulnerabilities** - Ensure parameterized queries are used\n- **XSS vulnerabilities** - Check for proper output encoding\n- **Insecure dependencies** - Review any new package additions\n- **Hardcoded secrets** - Scan for API keys, passwords, tokens\n\n### Security Test Coverage\n\nCheck test coverage for security-related tests:\n\n- Authentication tests\n- Authorization tests\n- Input validation tests\n- Error handling tests\n\n### Security Scanning\n\nRun security scans before approval:\n\n```javascript\nconst security = await ctx.task(securityScanTask, {\n  tools: ['npm audit', 'eslint-plugin-security']\n});\n```\n\n**Recommended security tools:**\n\n| Tool | Purpose |\n|------|---------|\n| `npm audit` | Dependency vulnerability scanning |\n| `eslint-plugin-security` | Static analysis for security issues |\n| `snyk` | Comprehensive vulnerability detection |\n| `semgrep` | Code pattern matching for security |\n\n---\n\n## Network Security\n\n### For Distributed Teams\n\n1. **Use VPN** for secure access\n2. **Implement authentication** on all services\n3. **Use HTTPS** for all external connections\n4. **Audit access logs** regularly\n\n### Network Configuration Checklist\n\n| Requirement | Implementation |\n|-------------|----------------|\n| Local-only binding | `--host 127.0.0.1` |\n| Access logging | Review service logs |\n| Firewall rules | Restrict to known IPs/VPN |\n\n---\n\n## Compliance Considerations\n\n### For Regulated Environments\n\nBabysitter provides several features that support compliance requirements:\n\n| Requirement | Babysitter Feature |\n|-------------|-------------------|\n| **Audit trail** | Journal provides complete event history |\n| **Approval gates** | Breakpoints create approval records |\n| **Access control** | Limit who can approve production deployments |\n| **Data retention** | Define policy for old run cleanup |\n| **Encryption** | Encrypt `.a5c/` directories if needed |\n\n### Audit Trail\n\nEvery action in Babysitter is logged in the journal:\n\n```bash\n# View complete event history for a run\ncat .a5c/runs/<runId>/journal/*.json | jq .\n\n# Filter for approval events (breakpoints resolve via EFFECT_RESOLVED)\njq 'select(.type==\"EFFECT_RESOLVED\")' .a5c/runs/*/journal/*.json\n```\n\n### Data Retention Policy\n\nImplement a cleanup policy for old runs:\n\n```bash\n# Example: Remove runs older than 30 days\nfind .a5c/runs -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \\;\n```\n\n### Encryption at Rest\n\nFor sensitive environments, encrypt the `.a5c/` directory:\n\n```bash\n# Using encrypted filesystem\n# Mount encrypted volume at .a5c/\n\n# Or use encryption tools\ngpg --symmetric --cipher-algo AES256 .a5c/runs/sensitive-run/journal/000001.*.json\n```\n\n---\n\n## Related Documentation\n\n- [Breakpoints](../features/breakpoints.md) - Approval workflow and the Breakpoints Adapter (\"proven\" signed approvals)\n- [GitHub Actions Setup](../../github-actions-setup-babysitter.md) - CI configuration, Triggers, and secret handling\n- [Adapters CLI Reference](./adapters-cli.md) - The host-side `adapters` CLI and its auth commands\n- [Configuration Reference](./configuration.md) - Environment variables and settings\n- [CLI Reference](./cli-reference.md) - Command-line options\n- [Troubleshooting](./troubleshooting.md) - Common issues and solutions\n- [Glossary](./glossary.md) - Term definitions\n\n---\n\n## Next steps\n\n- **Next:** [Configuration](./configuration.md)\n- **Related:** [Breakpoints](../features/breakpoints.md), [Troubleshooting](./troubleshooting.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-reference",
      "to": "page:docs-user-guide-reference-security",
      "kind": "contains_page"
    }
  ]
}