0.4.11
Поиск по документации… ⌘K
13 · Руководство пользователя

13. Безопасность

AstraCode даёт AI доступ к вашему коду и системе. Без защиты — это рискованно: модель может ошибиться, запустить плохую команду, переписать важный файл. Поэтому встроена многоуровневая модель безопасности.

Этот документ — что это значит для вас как пользователя: что вы видите, что делать, когда что-то спрашивает.

Четыре уровня защиты

  1. Sandbox — изоляция выполнения. Команды AstraCode не могут писать туда, куда не должны.
  2. Approvals — запросы вашего разрешения на рискованное.
  3. Secrets — шифрование ваших API-ключей.
  4. Лицензия — без активного ключа AstraCode не запускается. Активация описана отдельно: Лицензия.

Sandbox: что AstraCode может и не может делать

Три режима:

read-only

Самый строгий. AstraCode может читать любые файлы, но писать — никуда. Сеть отключена. - Полезно: проанализировать код, дать рекомендации, без побочных эффектов. - Команды типа cargo build или git commit не сработают — нет записи.

workspace-write (по умолчанию для доверенной директории)

Средний. Для доверенной рабочей директории это режим по умолчанию (рекомендуется). Для недоверенной директории AstraCode применяет более строгие настройки (вплоть до запроса подтверждений на каждое действие). Читать — везде. Писать — только в: - Рабочую директорию проекта. - /tmp и $TMPDIR.

Но даже в проекте защищены: - .git/ — никогда. - .astracode/ — никогда. - .agents/ — никогда.

Сеть — отдельный флаг: network_access = false по умолчанию (рекомендуется).

danger-full-access

Отключает sandbox. AstraCode может делать что угодно: писать в /etc, удалять /usr, ходить в любые сети.

Не используйте, кроме экстраординарных случаев. И не подтверждайте Allow always на опасное.

Где увидеть текущий режим

В status line — workspace-write / read-only / danger-full-access. Для недоверенной директории фактические права могут быть строже отображаемого режима.

Или:

text
/status

Сменить режим

toml
# ~/.astracode/config.toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/home/me/work"]
network_access = false

После — перезапуск AstraCode.

Approvals: когда вас спросят

Три политики:

untrusted

Каждое действие требует подтверждения. Очень безопасно, очень медленно. Подходит, если не доверяете модели вообще.

on-request (по умолчанию, рекомендуется)

Модель сама решает, когда запросить ваше подтверждение для рискованного действия. Это политика по умолчанию.

on-failure (устаревшая)

DEPRECATED. Команды выполняются в sandbox без вопросов; approval-диалог открывается, только если sandbox блокирует действие (например, попытку записать в .git). Не рекомендуется — используйте on-request (для интерактивной работы) или never (для скриптов).

never

Никогда не спрашивает — модели полностью развязаны руки в рамках текущего sandbox. Подходит для разовых задач или скриптовых запусков.

Как сменить

text
/approvals

Появится picker пресетов:

  • Read Only — только чтение workspace, на любое изменение спрашивается подтверждение.
  • Default (обычно текущий) — чтение, запись внутри workspace и запуск команд; вне workspace — с подтверждением.
  • Full Access — изменение файлов вне workspace без подтверждения. Перед включением показывается отдельный confirmation-диалог. Используйте осторожно.

Базовые пресеты — Read Only, Default и Full Access. Отдельно существует экспериментальный режим «Авто-проверка» (approvals_reviewer = auto_review): те же права, что у Default, но on-request-подтверждения проходят через auto-reviewer subagent. Это не входит в базовые пресеты и появляется только если в конфиге настроена соответствующая (Guardian) модель.

Текущий пресет помечается (current). Read Only может быть скрыт в зависимости от конфига.

Или вручную:

toml
approval_policy = "on-request"
approvals_reviewer = "user"     # user — спрашивают вас; auto — другой LLM

Approval-диалог: что вы видите

Когда требуется ваше разрешение, открывается нумерованный список вариантов. Для запуска команды:

text
Would you like to run the following command?

  cargo test --workspace

1. Yes, proceed (y)
2. Yes, and don't ask again for this command in this session (p)
3. No, and tell AstraCode what to do differently (esc)

Для применения правок к файлам заголовок другой, а второй вариант относится к файлам:

text
Would you like to make the following edits?

  ...

1. Yes, proceed (y)
2. Yes, and don't ask again for these files (a)
3. No, and tell AstraCode what to do differently (esc)

Что выбрать

Вариант Клавиша Когда
Yes, proceed 1 / y Безопасно, но именно в этот раз
Yes, and don't ask again… 2 / p (для команд) или a (для файлов) Безопасно, и я доверяю это в текущей сессии
No, and tell AstraCode… 3 / n / Esc Не надо делать; объяснить модели, как иначе

Отдельного варианта «Edit» (поправить команду перед запуском) в диалоге нет.

Что значит «don't ask again»

В текущей сессии аналогичные команды (или правки этих файлов) не будут спрашивать. Не персистентно — следующий запуск AstraCode снова спросит.

Когда отказывать

✗ Команда удаляет файлы, которые не нужно (rm /etc/...).
✗ Запись в .git/ или другие защищённые места.
✗ Сетевой запрос к подозрительному URL.
✗ Что-то, что не относится к вашей задаче.

В этих случаях — вариант «No…» (3 / n / Esc), и в чате:

text
Не надо делать X. Сделай Y вместо.

Что AstraCode делает в workspace-write

Типичные действия БЕЗ approval: - Чтение любых файлов. - Запуск тестов, сборки в проекте. - Чтение git status, log, blame. - Создание/изменение файлов внутри проекта.

С approval: - Запись в нерабочую директорию. - Команды с высоким риском (rm -rf, deletion patterns). - Сетевые запросы (если network_access = false). - Запуск install-команд (apt, npm install -g).

С блокировкой: - Запись в .git/, .astracode/, .agents/ — даже после approval. - Это намеренно — даже разрешение не открывает эти пути.

Secrets: ваши API-ключи

API-ключи провайдеров (OpenAI, Anthropic) хранятся в:

text
~/.astracode/secrets/local.age

Шифрование: - Файл шифруется библиотекой age (passphrase-режим). - Passphrase (master-секрет) хранится в OS keyring (Gnome Keyring / macOS Keychain / Windows Credential Manager).

Это значит: - Без вашего OS-логина расшифровать нельзя. - Если кто-то скопирует local.age — без master-ключа из вашего keyring он бесполезен. - При обновлении AstraCode секреты остаются рабочими (формат не меняется).

Где НЕ хранятся

  • В config.toml — никогда. Там только имена провайдеров.
  • В переменных окружения — ключ читается из env только если у провайдера задано provider.env_key (имя переменной указывается в конфиге провайдера). Иначе ключ берётся из зашифрованного secrets-store; задать его можно командой echo KEY | astracode provider-secret set <id>.
  • В rollout'ах — нет (модели передаются Authorization-заголовком HTTP-клиента, в rollout не пишутся).

Если потерял доступ

Если получили Failed to decrypt secrets file: - Скорее всего OS keyring потерял master-ключ (переустановка GNOME Keyring, смена пароля). - Файл local.age остался зашифрованным, но без ключа. - Решение: удалить ~/.astracode/secrets/local.age и заново ввести API-ключи через /model.

bash
rm ~/.astracode/secrets/local.age
astracode
# /model → ввести ключ заново

Дополнительные защиты

shell_environment_policy

Фильтрация переменных среды для команд:

toml
[shell_environment_policy]
inherit = "minimal"
allow = ["PATH", "HOME", "USER", "LANG", "TERM"]
deny = ["SECRET_*", "AWS_*", "*_API_KEY", "GITHUB_TOKEN"]

Защищает от случайной утечки секретов из вашей shell в команды, которые модель запускает.

/sandbox-add-read-dir

Если в текущей сессии модели нужен доступ к директории вне обычной зоны (например, для чтения чего-то из /opt):

text
/sandbox-add-read-dir /opt/proprietary-data

Только на эту сессию. Не сохраняется.

Защищённые пути

Даже в workspace-write или danger-full-access есть системные защиты:

  • .git/ — не пишется (защита git-истории).
  • .astracode/ — не пишется (защита настроек AstraCode).
  • .agents/ — не пишется (защита legacy-конфигов).

Это «hard» защиты — sandbox их применит даже если approval разрешит.

Шифрование передаваемых данных

Когда AstraCode отправляет ваш код в LLM (для генерации/анализа): - HTTPS к провайдеру (TLS). - Authorization через Bearer-токен. - Кастомные CA — ASTRACODE_CA_CERTIFICATE.

Внимание: содержимое запросов попадает на серверы провайдера (OpenAI / Anthropic). Их политики хранения данных — на их сайтах.

Если работаете с конфиденциальным кодом — рассмотрите: - Локальный LLM (vLLM, llama.cpp, Ollama). - On-prem provider вашей компании.

См. 06-model-and-providers.md.

Audit log

Все approval-решения и эскалации логируются:

text
~/.astracode/log/astracode-tui.log

С префиксом audit:::

text
audit::approval granted tool=local_shell cmd="rm tmp.txt" reason="user_approved"
audit::escalation requested cmd="sudo systemctl restart x" → denied

Полезно если хотите аудитировать, что AstraCode делал на вашей системе.

Что НЕ защищено

Sandbox и approvals — defense in depth, не абсолютная защита. Они НЕ спасают от:

  • Социальной инженерии — если вы жмёте Allow always подряд, ничего не поможет.
  • Логически правильных, но нежелательных действий — модель может сделать «правильную» правку, которая ломает вам что-то непредвиденно.
  • Уязвимости в bwrap/seatbelt — они активно патчатся, но zero-day возможны.
  • Чужого LLM — если провайдер компрометирован, он может вернуть инъекции.

Для критичных систем — запускайте AstraCode на изолированной машине или в контейнере.

Threat model

От чего AstraCode защищает:

✓ Случайное rm -rf / от модели.
✓ Утечка API-ключей через child-процессы.
✓ Запись в .git без подтверждения.
✓ Сетевые запросы из sandbox в network_access = false.
✓ Перезапись настроек AstraCode.

От чего НЕ защищает:

✗ Сознательно вредоносная модель.
✗ Эксплойты sandbox-провайдеров.
✗ Атаки по сторонним каналам (timing, кэширование).
✗ Социальная инженерия в approval-диалогах.

Хорошие привычки

✓ workspace-write + on-request — для повседневной работы.
✓ /approvals перед опасным проектом.
✓ network_access = false если задача без сети.
✓ Не жмите Allow always на всё подряд — читайте диалог.
✓ /sandbox-add-read-dir для разовых исключений вместо смены глобального режима.
✓ Backup секретов перед переустановкой OS.
✗ Не отключайте sandbox в чужих проектах.
✗ Не запускайте astracode от root — большие потери при ошибке.
✗ Не делитесь rollout'ами без просмотра — там ваши промпты и код.

Если что-то пошло не так

AstraCode сделал что-то нежелательное

  • Если изменился файл — git diff покажет. git checkout -- <file> откатит.
  • Если запустилась долгая команда — Esc остановит.
  • Если уже committed — git reset HEAD~1 (если не запушено).

Подозреваете компрометацию

bash
# Стереть секреты
rm -rf ~/.astracode/secrets

# Стереть rollouts (могут содержать промпты)
rm -rf ~/.astracode/sessions

# Стереть память
rm -rf ~/.astracode/memories

И отзовите API-ключи у провайдеров (через их dashboards).

Дополнительно

  • Безопасность (dev-вики) — техническая документация.
  • /help approvals — справка про режимы подтверждений.
  • /help sandbox-add-read-dir — справка по дополнительным правам.
ESC