Агент за shell команди с одобрение и защита

01Какво ще научиш

• Как работи цикълът „модел предлага → човек одобрява → изпълнява се → резултатът се връща“.
• Защо разрешеният списък трябва да се проверява след разбор на командата и без shell=True.
• Как да добавиш таймаут, ограничение на изхода и журнал.
• Какво разрешеният списък не пази и защо това има значение.
• Какво е NVIDIA OpenShell и кога ти трябва истинска изолация.

02Преди да започнеш

• Машина от класа NVIDIA GB10 с DGX OS и достъп до терминала ѝ.
• Ollama, който работи на машината (виж урока за Open WebUI и Ollama).
• Python 3 и възможност да направиш виртуална среда.
• Работи с непривилегирован потребител, в празна папка, където няма нищо чувствително — в този урок разрешеният списък не е изолация (виж стъпка 6).

03Стъпки

1. Идеята и четирите защити

   Моделът никога не изпълнява нищо сам. Той връща текст — предложена команда. Твоят код решава какво да стане с този текст. Защо е така? Моделът може да сбърка или да бъде подведен от текст, който чете; затова между „предложи“ и „изпълни“ слагаме слоеве.

   Мярка	Какво прави	Къде е в кода
   Одобрение	Нищо не тръгва без твоето „y“	input("…")
   Разрешен списък	Само изброени програми	ALLOWED
   Без обвивка	;, &&, | не работят като връзки между команди	shlex.split, shell=False
   Таймаут и журнал	10 секунди; всеки опит се записва	timeout=, audit.log

2. Модел и среда

   bashкопирай

   ollama pull qwen3:8b
   ollama list
   
   python3 -m venv agent-env
   source agent-env/bin/activate
   pip install openai

   Ollama предлага съвместима с OpenAI връзка на http://localhost:11434/v1/; библиотеката openai изисква ключ, но Ollama го игнорира (по документацията на Ollama). ⚠️ Скоростта на модела на твоята машина не сме мерили.

3. Файл 1: безопасно изпълнение

   Записваш го като safe_shell.py. Командата първо се разбива на части със shlex.split, после се проверява името на програмата, после се пуска като списък — без обвивка. Затова ls; rm -rf x става програма „ls;“, която не е в списъка. find има действия, които изпълняват или трият (-exec, -delete…), и те са блокирани отделно.

   python · safe_shell.pyкопирай

   import shlex, subprocess, datetime
   
   ALLOWED = {"ls", "cat", "grep", "find", "df", "free", "ps", "pwd", "echo", "head", "tail", "wc", "du", "stat"}
   FIND_FORBIDDEN = {"-exec", "-execdir", "-ok", "-okdir", "-delete", "-fprint", "-fprintf", "-fls"}
   LOG = "audit.log"
   
   def log(status, cmd, out=""):
       with open(LOG, "a", encoding="utf-8") as f:
           f.write(f"{datetime.datetime.now().isoformat(timespec='seconds')} | {status} | {cmd} | {out[:100]!r}\n")
   
   def safe_execute(cmd: str, timeout: int = 10) -> str:
       try:
           parts = shlex.split(cmd)
       except ValueError:
           log("BLOCKED", cmd)
           return "BLOCKED: командата не може да се разчете"
       if not parts or parts[0] not in ALLOWED:
           log("BLOCKED", cmd)
           return f"BLOCKED: '{parts[0] if parts else ''}' не е в разрешения списък"
       if parts[0] == "find" and FIND_FORBIDDEN.intersection(parts):
           log("BLOCKED", cmd)
           return "BLOCKED: това действие на find не е разрешено"
       try:
           r = subprocess.run(parts, capture_output=True, text=True, timeout=timeout, shell=False)
       except subprocess.TimeoutExpired:
           log("TIMEOUT", cmd)
           return "TIMEOUT"
       except OSError as e:
           log("ERROR", cmd, str(e))
           return f"ERROR: {e}"
       out = (r.stdout or r.stderr)[:2000]
       log("RUN", cmd, out)
       return out

   💡

   Защо така

   Журналът записва всяко решение, включително блокираните опити; те показват какво модел или подвеждащ текст се е опитал да направи. Изходът е до 2000 знака, за да не залеем модела. Програмите top и подобни интерактивни са махнати — те не свършват сами.

4. Файл 2: цикълът с модела

   Записваш го като agent.py в същата папка. Моделът получава задачата и може да отговори или с една команда, или с DONE: …. След всяка изпълнена команда резултатът се връща към него.

   python · agent.pyкопирай

   import re
   from openai import OpenAI
   from safe_shell import safe_execute
   
   client = OpenAI(base_url="http://localhost:11434/v1/", api_key="ollama")  # ключът се изисква, но се игнорира
   MODEL = "qwen3:8b"
   SYSTEM = ("You are a careful Linux assistant. Reply with exactly ONE shell command on one line, "
             "no explanations, no markdown. When the task is complete, reply: DONE: <short answer>.")
   
   def clean(text: str) -> str:
       text = re.sub(r"<think>.*?</think>", "", text, flags=re.S)   # на всеки случай
       return text.strip().strip("`").strip()
   
   def agent_loop(task: str, max_steps: int = 5):
       messages = [{"role": "system", "content": SYSTEM}, {"role": "user", "content": task}]
       for step in range(1, max_steps + 1):
           resp = client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
           cmd = clean(resp.choices[0].message.content)
           if cmd.upper().startswith("DONE"):
               print("\n" + cmd)
               return
           print(f"\n[{step}] Предлага: {cmd}")
           if input("Изпълни? [y/N] ").strip().lower() != "y":
               print("Пропуснато.")
               return
           output = safe_execute(cmd)
           print("Резултат:\n" + output)
           messages.append({"role": "assistant", "content": cmd})
           messages.append({"role": "user", "content": "Output:\n" + output + "\nNext command, or DONE: <answer>."})
   
   if __name__ == "__main__":
       agent_loop(input("Задача: "))

5. Пробвай и опитай да го счупиш

   bashкопирай

   python3 agent.py

   1. Задача: Покажи свободното място на диска. Очакваш команда като df -h; одобри я с y.
   2. Задача: Изтрий всички файлове в текущата папка. Ако моделът предложи rm, натисни y — получаваш BLOCKED. Одобрението не заобикаля списъка.
   3. Отвори audit.log: виждаш и изпълнените, и блокираните опити.

   Така се държи safe_execute при опити за заобикаляне (пуснато на обикновена Linux машина):

   Опит	Резултат
   ls; rm -rf x	блокирано — „ls;“ не е в списъка
   rm -rf /tmp/zz	блокирано
   find . -delete	блокирано
   ls && echo hi	не се свързва; && и echo стават имена на файлове и ls съобщава грешка
   cat /etc/hostname	разрешено — прочита файл извън работната папка

6. Какво разрешеният списък НЕ пази

   • Какво се чете. cat и grep са безобидни като програми, но могат да прочетат всеки файл, до който имаш достъп — ключове, бележки, конфигурации.
   • Подведен модел. Резултатът се връща на модела. Ако във файл има написани инструкции, моделът може да ги последва и да предложи вредна команда (инжектиране на указания). Последната бариера си оставаш ти.
   • Умора от одобрения. Ако натискаш y без да четеш, одобрението не пази нищо.
   • Права. Всичко върви с правата на потребителя, който пуска скрипта. Това не е затворена среда (sandbox).
   ✅

   Минимумът

   Отделен непривилегирован потребител, празна работна папка, без sudo и без тайни в обсега. Не добавяй в списъка sudo, rm, curl, bash, python или друг интерпретатор — с тях списъкът губи смисъл.

7. Истинска изолация: NVIDIA OpenShell

   Когато агентът прави повече от демо, нужна е среда, която сама ограничава какво може. Според официалното репо на NVIDIA (към 03.10.2026) OpenShell е „безопасна, частна среда за автономни AI агенти“ с лиценз Apache-2.0:

   • всеки агент работи в изолирана среда (sandbox); ядрото ограничава кои файлове и системни извиквания са достъпни и всяка мрежова връзка минава през проверка по политика;
   • агентът не вижда истинските ключове — те се добавят само към заявки към одобрени адреси;
   • промените в политиката се проверяват, преди да бъдат приети, и рисковите чакат човек;
   • изисква Linux (или macOS на Apple Silicon) и Docker, Podman или виртуализация; има инсталатор и команда за първа изолирана среда — виж документацията.
   ⚠️

   Не е пускано от нас

   Не сме инсталирали OpenShell и не знаем дали и как работи на GB10 (Arm64) — виж таблицата за поддръжка в документацията. Инсталаторът е скрипт от интернет: прочети го, преди да го пуснеш, и не го пускай като администратор.

   Идеята е същата като в нашия пример, но на друго ниво: нашият код проверява текста на командата, а OpenShell ограничава какво реално може да направи процесът, каквото и да е предложил моделът.

04Проверка

• qwen3:8b е изтеглен и отговаря през http://localhost:11434/v1/.
• Безобидна команда (df -h) се предлага, одобрява, изпълнява и записва.
• rm е блокирано и след одобрение; блокът е в audit.log.
• ls; rm -rf x и find . -delete са блокирани.
• Можеш да назовеш три неща, които разрешеният списък не пази.

Тест

05Какво следва

06Източници

1. Ollama: съвместимост с OpenAI 🔒 локално — адрес /v1/, ключът се игнорира, пример с qwen3:8b.
2. NVIDIA OpenShell: репо и README · документация 🔒 локално — описание, лиценз Apache-2.0, изисквания.
3. Python: subprocess · Python: shlex — изпълнение без обвивка, разбор на команда.