# Security Policy

## Supported Versions

Security fixes are applied to the latest release and the `main` branch.

## Reporting a Vulnerability

Do not open a public issue for an undisclosed vulnerability. The repository is
hosted on Gitea, which has no private vulnerability-reporting feature, so
contact the repository owner privately through the hosting platform instead of
filing a public issue.

Include affected versions, impact, reproduction steps, and any suggested
mitigation. Maintainers should acknowledge a report within seven days and
coordinate disclosure after a fix is available.

## Deployment Baseline

MAESTRO can execute tools, browser actions, and optionally SSH commands. Treat
it as a privileged service. For a step-by-step checklist, see
[docs/security-hardening.md](docs/security-hardening.md).

- Keep the service bound to localhost until OAuth authentication is configured.
- Put internet-facing deployments behind a TLS reverse proxy.
- Set `safety.bash_sandbox: always` for multi-user deployments.
- Keep `MCP_ENCRYPTION_KEY`, OAuth secrets, SSH keys, and provider credentials
  outside the repository and rotate them after suspected exposure.
- Restrict `/metrics` with a bearer token or an explicit source-IP allowlist.
- Review enabled tools and integrations before granting access to untrusted users.

## Secrets and Data

MAESTRO generates and stores several secrets. All of them live under the
runtime data directory and are created with restrictive permissions:

| Secret | Default location | Mode |
|--------|------------------|------|
| Master encryption key (envelope encryption for MCP/SSH credentials) | `data/secrets/master.key` | `0600` |
| MCP credential key | `data/secrets/mcp.key` | `0600` |
| Session secret (signs login cookies; auto-generated when `auth.session_secret` is unset) | `data/secrets/session-secret.key` | `0600` |
| Web Push (VAPID) keypair | `data/secrets/vapid.json` | `0600` |
| Self-signed TLS material | `data/tls/` | `0600` keys |

`config.yaml` may hold a provider `api_key`, so the setup tooling writes it
`0600`. These paths are excluded from version control (`.gitignore`) and from
the Docker build context (`.dockerignore`); never commit them or bake them into
an image.

Operational guidance:

- **Set a stable `auth.session_secret`** (or rely on the persisted
  `data/secrets/session-secret.key`) so restarts don't invalidate sessions; in a
  multi-node deployment, share the same secret across nodes.
- **The data directory is sensitive.** Back it up with the same care as a
  password store; restrict filesystem access to the service user.
- **Core dumps are excluded** from the repository because they can contain the
  decrypted master key, SSH private keys, and the session secret in process
  memory. Keep them out of any artifact you share.
- **Rotate after suspected exposure** and review the audit log.
- Sensitive values are masked in the Settings UI and the config API responses;
  do not paste unmasked secrets into issues or logs.
