subprocess и безопасность от shell-инъекций

subprocess.run: современный API и список, обезоруживающий shell

subprocess.run(...) — это та единственная точка входа, которая нужна для запуска внешней программы; он заменяет более старые os.system и os.popen, которые всегда брали только shell-строку и почти не давали контроля над результатом. Самое важное решение при работе с run — это как ты передаёшь команду, потому что именно оно определяет, участвует ли shell вообще.

import subprocess

# БЕЗОПАСНО: список аргументов. Python вызывает execve("git", ["git","clone",url]) напрямую.
# Никакого shell. `url` — одна литеральная запись argv, метасимволы в нём не имеют смысла.
subprocess.run(["git", "clone", url])

# ОПАСНО: одна строка + shell=True. Python передаёт всю строку в /bin/sh,
# который ПАРСИТ её — всё в `url` вроде ; | && $() запускается как своя команда.
subprocess.run(f"git clone {url}", shell=True)

В форме со списком subprocess запускает программу напрямую через семейство execve ОС: программа — это argv[0], а каждый остальной элемент списка передаётся как литеральный аргумент, байт в байт. В цепочке нет никакого /bin/sh, так что нечему интерпретировать ;, |, &&, $(…) или обратные кавычки. Враждебный url вида https://h/r; rm -rf ~ — это просто (бессмысленная, безвредная) строка-аргумент, переданная git, который отвергает её как плохой URL. В этом вся защита: нет shell — нет shell-инъекции.

shell=True — вектор инъекции, а shlex.quote — утешительный приз

Опасность не в самом shell=True, а в shell=True с интерполированным недоверенным вводом. В момент, когда любая часть этой строки приходит от пользователя, из загрузки, из тела HTTP, из имени файла или другого сервиса, атакующий может протащить через неё shell-метасимволы и вырваться из задуманной команды. Это хрестоматийная OS command injection (OWASP), и для неё не нужно ничего экзотического — ; или $(…) — это весь payload.

# Уязвимость в одной строке. `filename` приходит из формы загрузки.
subprocess.run(f"convert {filename} out.png", shell=True)   # filename = "x.png; <команда>"

# Фикс — не «экранировать сильнее», а «вообще не строить shell-строку»:
subprocess.run(["convert", filename, "out.png"])            # filename is one inert argv entry

Если тебе по-настоящему нужна фича shell — пайплайн, glob, раскрытие ~, которое делает только shell, — тогда и только тогда тянись к shlex.quote(), чтобы экранировать каждый недоверенный кусок перед тем, как он войдёт в строку. Но относись к этому как к утешительному призу: shlex.quote — в одном забытом вызове от дыры, тогда как форма со списком структурно безопасна и забывать там нечего. Тянись к списку первым, каждый раз; тянись к shell (с shlex.quote на каждом недоверенном фрагменте) только когда фича shell действительно требуется.

Захват вывода и реальная проверка результата

Когда инъекция исключена, следующий вопрос: сработало ли? Запустить команду — половина работы; прочитать, что произошло, — вторая половина. subprocess.run([...], capture_output=True, text=True) захватывает stdout и stderr ребёнка как декодированные строки (без text=True ты получишь сырые bytes). Возвращённый CompletedProcess несёт .returncode — код возврата, где 0 — успех, а любое ненулевое значение — сбой, о котором программа тебе сообщает.

r = subprocess.run(["git", "clone", url], capture_output=True, text=True)
if r.returncode != 0:
    raise RuntimeError(f"clone failed: {r.stderr}")   # don't sail past a non-zero exit

# Или пусть subprocess бросит за тебя — check=True превращает ненулевой код в исключение:
subprocess.run(["git", "clone", url], check=True)     # бросает CalledProcessError при сбое

Подвох тут — это скриптовый аналог непроверенного кода возврата ошибки: по умолчанию run не бросает исключение на ненулевом выходе, так что упавший шаг выглядит успешным, и твой скрипт марширует дальше. Это тот баг крон-задачи, где ночной бэкап «отрабатывал нормально» месяцами, потому что шаг pg_dump выходил с ненулевым кодом, и никто не проверял. Дисциплина безусловна: либо сам инспектируй .returncode, либо передавай check=True, чтобы упавшая команда бросала CalledProcessError, а не проходила молча.

timeout=: граница, которая не даёт зависшему ребёнку повесить тебя

Внешние команды общаются с сетями, дисками и другими процессами — а всё это может застрять. subprocess.run([...], timeout=30) бросает TimeoutExpired, если ребёнок не завершился за заданное число секунд. Без него застрявший git fetch к мёртвому зеркалу, curl к чёрной дыре хоста или convert, жующий битый файл, повесят твой скрипт — а в CI повесят весь пайплайн — на неопределённый срок.

try:
    subprocess.run(["git", "fetch"], check=True, timeout=30)
except subprocess.TimeoutExpired:
    # дочерний процесс убит; обработай зависание вместо бесконечного ожидания
    log.error("git fetch exceeded 30s — aborting")

Это ровно продолжение инцидента с превью: битая загрузка заставила convert крутиться вечно и заняла воркера, и фиксом стало добавление одного слова — timeout=. Относись к каждому внешнему вызову как к тому, что может зависнуть, и ограничивай его. Завершают картину два смежных подвоха: чтение большого вывода через сырой subprocess.PIPE и затем .wait() может встать в deadlock, когда буфер pipe ОС заполняется и ни одна сторона его не дренирует, — run() (и Popen.communicate()) читают pipe за тебя и обходят это; и передавай env= явно, когда нужна воспроизводимость или хочешь не утечь секреты родителя в ребёнка, а cwd= — чтобы задать рабочую директорию вместо мутации процесса через chdir.