Only the latest commit on the default branch receives security fixes.
This project allows allowlisted Telegram users (ALLOWED_USER_IDS, ALLOWED_CHAT_IDS) to submit tasks to AGY on an Ubuntu VM. Setting AGY_PERMISSION_MODE=full is equivalent to trusting the allowed Telegram accounts, Bot Token, model inputs and model decisions with the service user's VM permissions.
The following are outside the project's security guarantees:
- A compromised Telegram account, Bot Token or AGY account.
- Prompt injection contained in websites, logs, repositories or files read by AGY.
- Host privilege escalation available to the service user, including Docker group access.
- Secrets intentionally requested from AGY or sent through Telegram.
- Instructions and secrets intentionally stored in scheduled-task prompts.
- Set
ALLOWED_USER_IDS(orALLOWED_USER_ID) before startup; there is no first-user auto-binding. - Keep
.envat mode600and never commit it.chat_state.db,schedules.db, and the instance-lockbot.pidfile are all created at mode600automatically; do not loosen them. - Uploaded attachments and per-chat/schedule working directories are automatically purged once a day when older than 30 days (
cleanup_expired_workspaces_and_uploads, run from the schedule loop). This is a disk-hygiene measure, not a data-retention guarantee — do not rely on it for compliance purposes, and do not assume sensitive content is gone before 30 days have passed. - Prefer Safe mode. Use Full only on a dedicated, recoverable VM.
- Remember that scheduled tasks run unattended. In Full mode they inherit automatic tool approval, so review the generated prompt before confirming a schedule.
- Never place tokens, passwords, private keys or other credentials in a scheduled-task prompt; prompts are persisted in SQLite.
- Avoid granting
NOPASSWD:ALLto the service user. If temporarily enabled for root-level VM maintenance, revoke it immediately after use (sudo rm -f /etc/sudoers.d/$USER). - Keep snapshots or tested backups and minimize credentials stored on the VM.
- Rotate the Bot Token immediately if it may have leaked.
- Interactive flags (
-i,--prompt-interactive) are strictly prohibited to prevent unmonitored deadlocks in headless environments. - Dangerous operations (including
--dangerously-skip-permissions,update,install,plugin install/uninstall/enable/disable/import/link) require explicit two-phase confirmation (/agy_confirm) with a 15-minute TTL token. - All CLI executions bypass the shell and invoke
asyncio.create_subprocess_execdirectly. - Subprocess environments are strictly sanitized:
TELEGRAM_BOT_TOKEN,ALLOWED_USER_IDS, and other credentials are automatically scrubbed, withNO_COLOR=1andTERM=dumbenforced.
- All user-uploaded attachments and
/add_dirdirectory inclusions are strictly validated withsafe_jointo prevent path traversal outsideAGY_WORKSPACE_ROOT. - File extensions are restricted to an allowlist of safe text, source code, data, and image formats.
- When AGY outputs media URLs or file links to be forwarded to Telegram, all remote URLs undergo pre-flight SSRF inspection.
- The host domain is resolved via DNS, and all target IPs (IPv4 and IPv6) are validated to ensure they are public. Private IP ranges (e.g. RFC 1918, link-local, loopback, AWS metadata
169.254.169.254) are strictly blocked to prevent DNS rebinding and internal network scanning. - The file is fetched directly by the bot process itself (
httpx, redirects disabled) rather than handed to Telegram as a bare URL, so the validated IP is the one actually connected to.
- AGY's
--continueflag resumes "the most recently active conversation in the current working directory" — this scope is tied to the process's cwd, not to any notion of Telegram chat or user (confirmed empirically: two unrelated--continuecalls issued from the same cwd share conversation history; from different cwds they do not). - Every normal per-chat turn therefore runs in a dedicated working directory (
<state dir>/workspaces/chat-<chat_id>/), created on first use, with the realAGY_WORKDIRreachable via--add-dir. Without this, two authorized chats issuing plain messages close together could have one silently resume and see conversation history from the other. - Explicit
--conversation <UUID>binding (when supported by a future feature) is unaffected by this — it works by ID regardless of cwd. - Scheduled task execution and the
/schedule_addprompt-rewrite step already used their own isolated per-run working directories before this was generalized to normal chat turns.
- Disabled by default (
ALLOW_BOT_UPDATE=0). Enabling it means any allowlisted Telegram user can triggergit pull origin mainagainst the deployed repo and force a service restart — treat this as equivalent to granting that user deploy access to the VM. /updaterunsgit pullwith no shell interpolation (argv array) and a bounded timeout; it does not accept user-supplied arguments.- Both commands attempt
systemctl restart agy-telegram.servicefirst. Since the service normally runs as an unprivileged user, this call is commonly rejected by polkit (Interactive authentication required). The fallback path exits the process with a non-zero status code specifically so systemd'sRestart=on-failurepolicy (configured byinstall.sh) brings it back up — no additional sudo/polkit grant is required or recommended for this feature to function. - Only enable
ALLOW_BOT_UPDATEif you trust every allowlisted user with the ability to deploy new code to this VM.
security-scan.sh runs a battery of open-source scanners against this repo and writes their reports to security-reports/<timestamp>/:
- pip-audit — known-CVE
3F6C
scan of
requirements.lock. - bandit — static analysis for common Python security anti-patterns.
- semgrep — flexible static analysis using the public
p/pythonandp/owasp-top-tenrulesets. - gitleaks — scans the full git history for committed secrets and tokens.
./security-scan.shThe script is self-contained: it bootstraps its own dependencies on first run (a dedicated .security-tools-venv/, kept separate from the app's own venv/, plus gitleaks via apt if missing) and does not require anything to be installed beforehand.
It also installs a git pre-commit hook (.git/hooks/pre-commit) that runs gitleaks protect --staged before every commit, blocking it if the staged changes contain a secret. This catches leaks before they land instead of relying solely on a later manual scan of git history. The hook is local to your checkout (.git/hooks/ isn't version-controlled), so it's reinstalled automatically the next time security-scan.sh runs on a fresh clone. To bypass it for a confirmed false positive, use git commit --no-verify.
Not every finding these tools report is a real vulnerability — bandit and semgrep in particular flag patterns (e.g. any f-string used to build SQL) without understanding surrounding validation logic, so always read a flagged line in context before acting on it. A finding that's confirmed to be a false positive is still worth a one-line comment at the flagged code (why it's safe) so the next person — or the next scan — doesn't have to re-derive the same reasoning.
Do not commit security-reports/. It is already excluded via .gitignore: a gitleaks report in particular can contain the actual secret snippets it found, and even a stale bandit/semgrep report tied to a specific commit can read as a map of "here's what to check first" if the underlying code regresses later. Treat scan output as a local, disposable artifact — re-run the scanner instead of trying to keep an old report current.
Do not open a public issue containing exploit details or secrets. Contact the repository owner privately through the security reporting channel configured on the hosting platform. Include affected commit, impact and minimal reproduction steps without real credentials.