# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 3.x     | ✅ Yes             |
| < 3.0   | ❌ No              |

## Reporting a Vulnerability

If you discover a security vulnerability, please report it responsibly:

1. **Do NOT** open a public GitHub issue
2. **Report** security concerns via [GitHub Security Advisories](https://github.com/alvbln/Alvin-Bot/security/advisories/new)
3. Include a description of the vulnerability and steps to reproduce

## What to Report

- Authentication or authorization bypasses
- API key exposure in logs or responses
- Injection vulnerabilities (command injection, prompt injection)
- Insecure default configurations
- Dependencies with known vulnerabilities

## Response Timeline

- **Acknowledgment:** Within 48 hours
- **Assessment:** Within 1 week
- **Fix:** Depending on severity, typically within 2 weeks

## Security Best Practices for Users

- Never commit your `.env` file or API keys to version control
- Use strong passwords for the web dashboard (`WEB_PASSWORD`)
- Keep your Alvin Bot installation updated to the latest version
- Run behind a reverse proxy (nginx) with HTTPS in production
- Restrict network access to the dashboard port

## Threat Model & Defense Layers

Alvin Bot is an **autonomous agent with shell, filesystem, and network access by
design** — treat it like `sudo` access to the machine it runs on. Its security
posture is layered, not a single wall:

**Trust boundary.** People who may instruct the bot are trusted operators:
`ALLOWED_USERS` (Telegram) / approved groups / paired DMs. Everyone and
everything else is untrusted — including the *content* the agent ingests while
working (web pages, search results, documents, e-mails, and the output of
external MCP tool servers).

**Defense layers (defense-in-depth):**

1. **Who may talk to the bot** — `ALLOWED_USERS` / group approval / DM pairing.
   The bot refuses to start if Telegram is enabled with no allowlist.
2. **What the web UI exposes** — bound to `127.0.0.1` by default; when reachable
   off-host it requires `WEB_PASSWORD` on every channel (HTTP *and* the chat
   WebSocket), and warns when traffic is unencrypted.
3. **What shell commands may run** — `EXEC_SECURITY` (default `allowlist`:
   metacharacter block + binary allowlist) plus an always-on destructive-command
   guard (`rm -rf` of protected paths, disk destruction, fork bombs, writes to
   credential files).
4. **What files may be written** — an always-on write/edit guard refuses to
   write credential, persistence, or system paths (`.env`, `~/.ssh`,
   `authorized_keys`, `~/.alvin-bot` internals, shell rc files, `LaunchAgents`,
   `/etc`, …). This protects against both mistakes and prompt injection.
5. **What secrets external tools see** — external MCP servers receive a
   secret-free environment (no `BOT_TOKEN`, no API keys); pass any value a
   server needs explicitly via that server's `env` config.
6. **How untrusted content is treated** — fetched web content, web-search
   results, and MCP tool output are wrapped in an explicit *untrusted-content
   fence* instructing the model to treat the enclosed text as DATA, never as
   instructions; a heuristic scan flags likely injection attempts in the logs.
7. **Network egress** — an SSRF guard blocks fetches to private/loopback/cloud-
   metadata addresses.

**Prompt-injection stance.** Layers 4–6 mean a malicious instruction smuggled
into ingested content cannot, on its own, make the agent exfiltrate credentials
or establish persistence — the dangerous *actions* are blocked regardless of
what the model is talked into, and the content is labelled as untrusted before
the model sees it. This is mitigation, not a guarantee; combine it with a small,
trusted `ALLOWED_USERS` set. The `EXEC_SECURITY=full` power mode relaxes layer 3
for single-user trusted boxes; layers 4–6 remain on.