Разрешения

Deno запускает код в защищённой песочнице: программа не имеет доступа к конфиденциальным системным операциям ввода-вывода, если вы не предоставите ей такое разрешение. На этой странице приведён справочник по всем разрешениям и флагам --allow-* / --deny-*, которые ими управляют. Описание лежащей в их основе модели безопасности и рекомендации по запуску недоверенного кода см. в разделе Безопасность.

По умолчанию доступ к большинству системных операций ввода-вывода запрещён. Однако некоторые операции ввода-вывода разрешены в ограниченном объёме даже по умолчанию. Они описаны ниже.

Чтобы включить эти операции, пользователь должен явно предоставить разрешение среде выполнения Deno. Для этого команде deno передаются флаги --allow-read, --allow-write, --allow-net, --allow-env, --allow-run, --allow-sys, --allow-ffi и --allow-import.

Во время выполнения скрипта пользователь также может явно предоставить разрешение на доступ к определённым файлам, каталогам, сетевым адресам, переменным среды и дочерним процессам, когда среда выполнения запрашивает такое разрешение. Запросы не отображаются, если stdout/stderr не подключены к TTY или если команде deno передан флаг --no-prompt.

Пользователи также могут явно запретить доступ к определённым ресурсам с помощью флагов --deny-read, --deny-write, --deny-net, --deny-env, --deny-run, --deny-sys, --deny-ffi и --deny-import. Эти флаги имеют приоритет над флагами, разрешающими доступ. Например, если вы разрешили сетевой доступ, но запретили доступ к определённому домену, приоритет будет у флага запрета.

В Deno также предусмотрен флаг --allow-all, который предоставляет скрипту все разрешения. Он полностью отключает песочницу безопасности, поэтому использовать его следует с осторожностью. С точки зрения безопасности --allow-all ничем не отличается от запуска скрипта в Node.js (то есть защита отсутствует).

Определение: -A, --allow-all

deno run -A script.ts
deno run --allow-all script.ts

По умолчанию Deno не формирует трассировку стека для запросов разрешений, поскольку это снижает производительность. Пользователи могут включить трассировки стека, установив переменную среды DENO_TRACE_PERMISSIONS в значение 1.

Deno также может создавать журнал аудита всех обращений к разрешениям вне зависимости от того, был ли доступ разрешён или запрещён.

Задайте для DENO_AUDIT_PERMISSIONS путь к файлу, чтобы записывать данные в формате JSONL — каждая строка представляет собой объект со следующими ключами:

• v: версия формата
• datetime: время обращения к разрешению в формате RFC 3339
• permission: имя разрешения
• value: значение, с которым было запрошено разрешение, или null, если обращение было выполнено без значения

Схему можно найти в файле permission-audit.v1.json.

Кроме того, эту переменную среды можно использовать вместе с упомянутой выше DENO_TRACE_PERMISSIONS. В этом случае в записи появится новое поле stack — массив, содержащий все кадры трассировки стека.

Также можно задать DENO_AUDIT_PERMISSIONS=otel, чтобы передавать сведения о каждом обращении в виде записи журнала OpenTelemetry, а не записывать их в файл. Записи отправляются в настроенный вами экспортёр через OTEL_DENO и содержат следующие атрибуты:

• deno.permission.type
• deno.permission.value
• deno.permission.stack (если также задано DENO_TRACE_PERMISSIONS)

Это рекомендуемый вариант, если вы уже собираете данные OpenTelemetry: аудит разрешений будет храниться вместе с трассировками и метриками, что позволит сопоставить его с обработкой запросов.

OTEL_DENO=true DENO_AUDIT_PERMISSIONS=otel deno run -A main.ts

Файл конфигурации

Deno позволяет хранить разрешения в файле deno.json/deno.jsonc. Подробнее см. в разделе конфигурация.

Доступ к файловой системе

По умолчанию выполняемый код не может произвольно читать файлы в файловой системе или записывать в них. Это включает просмотр содержимого каталогов, проверку существования определённого файла, а также открытие или подключение к сокетам Unix.

Разрешение на чтение файлов предоставляется с помощью флага --allow-read (или -R), а на запись файлов — с помощью флага --allow-write (или -W). В этих флагах можно указать список путей, чтобы разрешить доступ к определённым файлам или каталогам и всем их подкаталогам.

Определение: --allow-read[=<PATH>...] или -R[=<PATH>...]

Пути могут разделяться запятыми (символами ,). Чтобы включить запятую в путь, её нужно продублировать. (Пример: this file,, contains a comma.txt)

# Allow all reads from file system
deno run -R script.ts
# or 
deno run --allow-read script.ts

# Allow reads from file foo.txt and bar.txt only
deno run --allow-read=foo.txt,bar.txt script.ts

# Allow reads from any file in any subdirectory of ./node_modules
deno run --allow-read=node_modules script.ts

Определение: --deny-read[=<PATH>...]

# Allow reading files in /etc but disallow reading /etc/hosts
deno run --allow-read=/etc --deny-read=/etc/hosts script.ts

# Deny all read access to disk, disabling permission prompts for reads.
deno run --deny-read script.ts

Определение: --allow-write[=<PATH>...] или -W[=<PATH>...]

# Allow all writes to file system
deno run -W script.ts
# or 
deno run --allow-write script.ts

# Allow writes to file foo.txt and bar.txt only
deno run --allow-write=foo.txt,bar.txt script.ts

Определение: --deny-write[=<PATH>...]

# Allow reading files in current working directory 
# but disallow writing to ./secrets directory.
deno run --allow-write=./ --deny-write=./secrets script.ts

# Deny all write access to disk, disabling permission prompts.
deno run --deny-write script.ts

Некоторые API Deno реализованы с использованием операций файловой системы, хотя они и не предоставляют прямого доступа на чтение или запись к определённым файлам. Эти API читают данные с диска и записывают их на него, но не требуют явных разрешений на чтение или запись. Например:

• localStorage
• Deno KV
• caches
• Blob

Поскольку эти API реализованы с использованием операций файловой системы, их можно использовать для потребления ресурсов файловой системы, например места на диске, даже без прямого доступа к файловой системе.

При загрузке модулей Deno может загружать файлы с диска. Иногда для этого требуются явные разрешения, а иногда доступ разрешён по умолчанию:

• По умолчанию разрешено читать все файлы, импортируемые из модуля точки входа способом, допускающим статический анализ. Сюда входят статические инструкции import и динамические вызовы import(), аргументом которых служит строковый литерал, указывающий на определённый файл или каталог с файлами. Полный список таких файлов можно вывести с помощью deno info <entrypoint>.
• Для файлов, импортируемых динамически способом, не допускающим статический анализ, требуются разрешения на чтение во время выполнения.
• Скрипт Web Worker загружается так же, как динамический импорт, поэтому для воркера, скрипт которого находится в локальном файле, например new Worker(new URL("./worker.ts", import.meta.url).href, { type: "module" }), требуется --allow-read. Это относится к точке входа воркера и всему графу его статических импортов; разрешение на чтение проверяется с учётом разрешений потока, создавшего воркер. Для воркера, загруженного с URL https:, вместо этого требуется --allow-import; для URL data: и blob: разрешения не требуются.
• По умолчанию разрешено читать файлы в каталоге node_modules/.

При загрузке модулей из сети или преобразовании кода TypeScript в JavaScript Deno использует файловую систему в качестве кеша. Это означает, что Deno может потреблять ресурсы файловой системы, например место на диске, даже если пользователь явно не предоставил разрешения на чтение или запись.

Символические ссылки

При чтении или записи через символическую ссылку Deno проверяет разрешения на основе расположения самой ссылки, а не объекта, на который она указывает. Это означает, что при наличии --allow-read=/app вы можете читать через символическую ссылку в /app/link, даже если она указывает на файл за пределами /app.

Однако Deno предотвращает повышение привилегий через символические ссылки. Если ссылка ведёт к конфиденциальному системному пути, требуются дополнительные разрешения:

• /proc, /dev, /sys (Linux): для чтения или записи через символические ссылки, ведущие к этим путям, требуется --allow-all, так как эти пути могут раскрыть конфиденциальную системную информацию.
• /proc/**/environ: требуется --allow-env, поскольку этот путь открывает доступ к переменным среды.
• /dev/null, /dev/zero, /dev/random, /dev/urandom: доступ к этим безопасным файлам устройств всегда разрешён без дополнительных разрешений.

Для создания символических ссылок с помощью Deno.symlink() требуются полные разрешения --allow-read и --allow-write (не ограниченные отдельными путями), поскольку ссылки могут указывать в произвольные места.

Примечание: Читать по уже существующим в файловой системе символическим ссылкам можно, используя разрешения для расположения самой ссылки. Полное разрешение на чтение и запись требуется только для создания новых символических ссылок с помощью Deno.symlink().

Доступ к сети

По умолчанию выполняемый код не может отправлять сетевые запросы, открывать сетевые слушатели или выполнять разрешение DNS. Это включает отправку HTTP-запросов, открытие сокетов TCP/UDP и прослушивание входящих подключений TCP или UDP.

Доступ к сети предоставляется с помощью флага --allow-net. В этом флаге можно указать список хостов, чтобы разрешить доступ к определённым сетевым адресам. В качестве хоста можно указать имя хоста или IP-адрес, при необходимости — с портом.

Имена хостов не распространяются на поддомены, если те не указаны явно. Чтобы разрешить любые поддомены хоста, можно использовать * в качестве подстановочного знака для любого поддомена.

Определение: --allow-net[=<HOST>...] или -N[=<HOST>...]

# Allow network access
deno run -N script.ts
# or
deno run --allow-net script.ts

# Allow network access to github.com and jsr.io
deno run --allow-net=github.com,jsr.io script.ts

# Allow all subdomains for example.com
deno run --allow-net="*.example.com" script.ts

# A hostname at port 80:
deno run --allow-net=example.com:80 script.ts

# An IPv4 address on port 443
deno run --allow-net=1.1.1.1:443 script.ts

# An IPv6 address, all ports allowed
deno run --allow-net=[2606:4700:4700::1111] script.ts

Определение: --deny-net[=<HOST>...]

# Allow access to network, but deny access 
# to github.com and jsr.io
deno run --allow-net --deny-net=github.com,jsr.io script.ts

# Deny all network access, disabling permission prompts.
deno run --deny-net script.ts

При загрузке модулей Deno может загружать их из сети. По умолчанию Deno разрешает загружать модули из следующих источников с помощью статического и динамического импорта без явного разрешения на сетевой доступ:

• https://deno.land/
• https://jsr.io/
• https://esm.sh/
• https://raw.esm.sh/
• https://cdn.jsdelivr.net/
• https://raw.githubusercontent.com/
• https://gist.githubusercontent.com/

Это доверенные реестры общественного блага, через пути URL которых не предполагается возможность утечки данных. Добавить другие доверенные реестры можно с помощью флага --allow-import.

Кроме того, Deno позволяет импортировать любые пакеты NPM с помощью спецификаторов npm:.

Deno также не чаще одного раза в день отправляет запросы на https://dl.deno.land/, чтобы проверять наличие обновлений Deno CLI. Это можно отключить с помощью переменной среды DENO_NO_UPDATE_CHECK=1.

Переменные среды

По умолчанию выполняемый код не может читать переменные среды или записывать в них. Это включает чтение переменных среды и установку новых значений.

Доступ к переменным среды предоставляется с помощью флага --allow-env. В этом флаге можно указать список переменных среды, чтобы разрешить доступ к определённым переменным. Начиная с Deno v2.1, можно указывать подстановочные знаки в конце, чтобы разрешить ограниченный доступ к переменным среды в заданной области.

Определение: --allow-env[=<VARIABLE_NAME>...] или -E[=<VARIABLE_NAME>...]

# Allow access to all environment variables
deno run -E script.ts
# or
deno run --allow-env script.ts

# Allow HOME and FOO environment variables
deno run --allow-env=HOME,FOO script.ts

# Allow access to all environment variables starting with AWS_
deno run --allow-env="AWS_*" script.ts

Определение: --deny-env[=<VARIABLE_NAME>...]

# Allow all environment variables except 
# AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
deno run \
  --allow-env \
  --deny-env=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY \
  script.ts

# Deny all access to env variables, disabling permission prompts.
deno run --deny-env script.ts

Флаг --ignore-env похож на --deny-env, но не запрещает доступ полностью, а незаметно возвращает undefined при чтении любой переменной среды. Это полезно, если нужно запускать код без ошибок из-за отсутствующих разрешений и считать переменные с ограниченным доступом просто неустановленными.

Определение: --ignore-env[=<VARIABLE_NAME>...]

# Ignore all environment variable reads (returns undefined).
deno run --ignore-env script.ts

# Ignore specific environment variables.
deno run --ignore-env=PORT,HOME script.ts

Примечание для пользователей Windows: в Windows имена переменных среды нечувствительны к регистру, поэтому Deno также сопоставляет их без учёта регистра (только в Windows).

При запуске Deno считывает некоторые переменные среды, например DENO_DIR и NO_COLOR (полный список).

Значение переменной среды NO_COLOR доступно всему коду, выполняющемуся в среде выполнения Deno, независимо от того, предоставлено ли этому коду разрешение на чтение переменных среды.

Сведения о системе

По умолчанию выполняемый код не может получать сведения о системе, такие как версия операционной системы, время работы системы, средняя загрузка, сетевые интерфейсы и сведения о системной памяти.

Доступ к сведениям о системе предоставляется с помощью флага --allow-sys. В этом флаге можно указать список разрешённых интерфейсов из списка, определённого в Deno.SysPermissionDescriptor. Эти строки соответствуют функциям пространства имён Deno, предоставляющим сведения об ОС, например Deno.systemMemoryInfo.

Определение: --allow-sys[=<API_NAME>...] или -S[=<API_NAME>...]

# Allow all system information APIs
deno run -S script.ts
# or
deno run --allow-sys script.ts

# Allow systemMemoryInfo and osRelease APIs
deno run --allow-sys="systemMemoryInfo,osRelease" script.ts

Определение: --deny-sys[=<API_NAME>...]

# Allow accessing all system information but "networkInterfaces"
deno run --allow-sys --deny-sys="networkInterfaces" script.ts

# Deny all access to system information, disabling permission prompts.
deno run --deny-sys script.ts

Имена интерфейсов, принимаемые --allow-sys, соответствуют функциям пространства имён Deno, предоставляющим сведения о хосте, таким как hostname, osRelease, osUptime, loadavg, networkInterfaces, systemMemoryInfo, uid, gid, username, cpus и homedir. Полный список распознаваемых имён см. в Deno.SysPermissionDescriptor.

Этот же флаг управляет доступом к соответствующим API совместимости с Node.js. Для функций в node:os и node:process, которые считывают сведения о системе, таких как os.hostname(), os.cpus(), os.networkInterfaces(), os.freemem(), os.totalmem(), os.uptime(), process.getuid() и process.getgid(), требуется --allow-sys; они сопоставляются с теми же именами интерфейсов. Например, для вызова os.cpus() требуется --allow-sys=cpus, а для os.networkInterfaces() — --allow-sys=networkInterfaces.

Дочерние процессы

По умолчанию код, выполняющийся в среде Deno, не может запускать дочерние процессы, поскольку это нарушило бы принцип, согласно которому код не может повышать свои привилегии без согласия пользователя.

Deno предоставляет механизм запуска дочерних процессов, но для этого требуется явное разрешение пользователя. Оно предоставляется с помощью флага --allow-run.

Любые дочерние процессы, запускаемые программой, работают независимо от разрешений, предоставленных родительскому процессу. Это означает, что дочерние процессы могут получать доступ к системным ресурсам независимо от разрешений, предоставленных процессу Deno, который их запустил. Это часто называют повышением привилегий.

Поэтому тщательно обдумайте, прежде чем предоставлять программе доступ --allow-run: по сути, это отменяет действие песочницы безопасности Deno. Если вам действительно нужно запустить определённый исполняемый файл, можно снизить риск, ограничив список программ, запускаемых процессом Deno, и передав конкретные имена исполняемых файлов флагу --allow-run.

Определение: --allow-run[=<PROGRAM_NAME>...]

# Allow running all subprocesses
deno run --allow-run script.ts

# Allow running "curl" and "whoami" subprocesses
deno run --allow-run="curl,whoami" script.ts

Отправка сигнала собственному процессу не требует --allow-run, поскольку это равносильно самостоятельному завершению (например, с помощью Deno.exit). Deno.kill(Deno.pid, ...) и process.kill(process.pid, ...) работают без этого флага, поэтому инструменты, повторно отправляющие сигнал собственному PID (например, signal-exit, используемый Vite), больше не требуют предоставлять полный доступ на запуск процессов.

Дочерние процессы с переменными среды LD_* и DYLD_*

Для запуска дочернего процесса с переменной среды, имя которой начинается с LD_ (например, LD_LIBRARY_PATH или LD_PRELOAD) либо с DYLD_ (например, DYLD_LIBRARY_PATH или DYLD_INSERT_LIBRARIES), требуется неограниченный флаг --allow-run. Ограниченного списка разрешённых значений, например --allow-run=curl, недостаточно, даже если значение совпадает с тем, с которым был запущен Deno:

// Fails under `--allow-run=echo`, succeeds under `--allow-run` or `--allow-all`.
new Deno.Command("echo", {
  args: ["hello"],
  env: { LD_PRELOAD: "/path/to/lib.so" },
}).outputSync();

NotCapable: Requires --allow-run permissions to spawn subprocess with LD_PRELOAD
environment variable. Alternatively, spawn with the environment variable unset.

Эти переменные указывают динамическому компоновщику загрузить произвольные общие библиотеки в дочерний процесс, поэтому они могут запускать код в этом процессе независимо от того, какой исполняемый файл вы разрешили. Требование неограниченного --allow-run не позволяет обходить ограниченный список разрешений незаметно. Если эти переменные вам не нужны, проще всего запустить дочерний процесс, не задавая их.

Определение: --deny-run[=<PROGRAM_NAME>...]

# Allow running running all programs, but "whoami" and "ps".
deno run --allow-run --deny-run="whoami,ps" script.ts

# Deny all access for spawning subprocessing, disabling
# permission prompts.
deno run --deny-run script.ts

По умолчанию для пакетов npm при установке не выполняются сценарии после установки (как и при использовании deno install), поскольку это позволило бы произвольно выполнять код. При запуске с флагом --allow-scripts сценарии после установки пакетов npm будут выполняться как дочерний процесс.

FFI (интерфейс взаимодействия с внешними функциями)

Deno предоставляет механизм FFI для выполнения кода, написанного на других языках, например Rust, C или C++, в среде выполнения Deno. Для этого используется API Deno.dlopen, который загружает общие библиотеки и вызывает содержащиеся в них функции.

По умолчанию выполняемый код не может использовать API Deno.dlopen, поскольку это нарушило бы принцип, согласно которому код не может повышать свои привилегии без согласия пользователя.

Помимо Deno.dlopen, FFI можно использовать через нативные дополнения Node-API (NAPI). По умолчанию они также запрещены.

Для использования Deno.dlopen и нативных дополнений NAPI требуется явное разрешение с помощью флага --allow-ffi. В этом флаге можно указать список файлов или каталогов, чтобы разрешить доступ к определённым динамическим библиотекам.

Как и дочерние процессы, динамические библиотеки выполняются вне песочницы и поэтому не подчиняются тем же ограничениям безопасности, что и процесс Deno, в который они загружаются. Используйте их с особой осторожностью.

Определение: --allow-ffi[=<PATH>...]

# Allow loading dynamic all libraries
deno run --allow-ffi script.ts

# Allow loading dynamic libraries from a specific path
deno run --allow-ffi=./libfoo.so script.ts

Определение: --deny-ffi[=<PATH>...]

# Allow loading all dynamic libraries, but ./libfoo.so
deno run --allow-ffi --deny-ffi=./libfoo.so script.ts

# Deny loading all dynamic libraries, disabling permission prompts.
deno run --deny-ffi script.ts

Импорт из интернета

Разрешает импортировать код из интернета. По умолчанию Deno ограничивает список хостов, с которых можно импортировать код. Это относится как к статическому, так и к динамическому импорту.

Для динамического импорта кода с помощью API import() или new Worker() требуется предоставить дополнительные разрешения. Для загрузки такого кода из локальной файловой системы требуется --allow-read. Deno также позволяет импортировать код с URL http: и https:, но в этом случае необходимо указать явный флаг --allow-import:

# allow importing code from `https://example.com`
$ deno run --allow-import=example.com main.ts

По умолчанию Deno разрешает импортировать исходный код со следующих хостов:

• deno.land
• jsr.io
• esm.sh
• raw.esm.sh
• cdn.jsdelivr.net
• raw.githubusercontent.com
• gist.githubusercontent.com

Импорт разрешён только по HTTPS.

Этот список разрешённых хостов применяется по умолчанию к статическим импортам, а также к динамическим импортам, если указан флаг --allow-import.

# allow dynamically importing code from `https://deno.land`
$ deno run --allow-import main.ts

Обратите внимание: указание списка разрешённых хостов для --allow-import заменит список хостов по умолчанию.

Используйте --deny-import, чтобы запретить импорт с определённых хостов, даже если в остальных случаях он был бы разрешён. Флаги запрета имеют приоритет над флагами разрешения:

# allow the default import hosts, except esm.sh
$ deno run --deny-import=esm.sh main.ts