# Security Practices for Agent Deployment

## Container Isolation
- Run containers with the minimum privileges needed.
- Never use `privileged: true` unless absolutely required (e.g. hardware access).
- Prefer `read_only: true` for the root filesystem, with writable tmpfs for `/tmp`.
- Drop all capabilities and add only what's needed: `cap_drop: [ALL]`, then
  `cap_add: [NET_BIND_SERVICE]` if binding to low ports.
- Set `security_opt: [no-new-privileges:true]` to prevent privilege escalation.

## Secret Management
- NEVER hardcode secrets (API keys, tokens, passwords) in docker-compose.yml.
- Use `${VAR}` syntax and store actual values in `.env` (which is gitignored).
- For sensitive values, prefer Armorer's vault: `armorer vault set KEY VALUE`.
- Rotate secrets periodically — Armorer can detect stale secrets via monitoring.

## Network Security
- Use internal Docker networks for service-to-service communication.
- Only expose ports that need external access (e.g. the gateway port).
- Prefer binding to `127.0.0.1:PORT:PORT` if the service should only be local.
- For LAN-accessible services, bind to `0.0.0.0:PORT:PORT` explicitly.

## Image Provenance
- Prefer official Docker Hub images or verified publisher images.
- Pin image tags to specific versions (e.g. `node:18-alpine`, not `node:latest`).
- Check the image's Dockerfile for suspicious layers or excessive permissions.
- For git-cloned repos, review the Dockerfile before building.

## File Permissions
- Volume-mounted directories should be owned by the user running the container.
- Common non-root users in images: `node` (UID 1000), `postgres` (UID 999).
- Armorer pre-creates volume directories with correct ownership to avoid root-owned files.
- If a container creates files as root, consider adding `user: "1000:1000"` to the service.

## Monitoring
- Prefer OTEL-first monitoring for agent runtime activity (events, tool outcomes, message flow).
- Armorer can consume OTEL-derived JSONL feeds from `~/.armorer/otel_events/`.
- File-pattern monitoring (`monitor_targets`) is available as a fallback mode.
- The Core service performs periodic security scans on registered agents.
- Review container logs regularly: `docker compose logs --tail 50`.

## Update Policy
- Keep images updated — check for new versions periodically.
- Before updating, back up volume data (especially databases).
- Use `docker compose pull && docker compose up -d` for image updates.
- For git-based installs, `git pull` then rebuild: `docker compose up -d --build`.
