Script Security Plugin

Руководство пользователя

(адаптировано из информации о Template plugin в руководстве CloudBees Plugins)

Различные плагины Jenkins требуют, чтобы пользователи определяли пользовательские скрипты, чаще всего на языке Groovy, для настройки поведения Jenkins. Если все, кто пишет эти скрипты, являются администраторами Jenkins — а именно, если у них есть разрешение Overall/RunScripts, используемое например, ссылкой Script Console, — то они могут писать любые скрипты, какие захотят. Эти скрипты могут напрямую обращаться к внутренним объектам Jenkins, используя тот же API, который предоставляется плагинам. Таким пользователям нужно полностью доверять, поскольку они могут сделать с Jenkins что угодно (даже изменить его настройки безопасности или выполнять shell-команды на сервере).

Однако, если некоторые авторы скриптов являются «обычными пользователями» с лишь более ограниченными разрешениями, такими как Job/Configure, то позволять им выполнять произвольные скрипты неуместно. Для поддержки такого разделения ролей плагин-библиотека Script Security может быть интегрирован в различные функциональные плагины. Он поддерживает две связанные системы: утверждение скриптов и Groovy- песочницу.

Утверждение скриптов

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

Когда администратор сохраняет какую-либо конфигурацию (например, задание), те скрипты, которые были отредактированы администратором, автоматически утверждаются и готовы к запуску без дальнейшего вмешательства. Для скриптов, отправленных пользователями с более низкими привилегиями, будут соответствующие предупреждения о том, что требуется утверждение. Администраторы могут утвердить такие скрипты на странице конфигурации Script Approval или отредактировав скрипт и сохранив его. В предыдущих версиях плагина Script Security администраторы могли автоматически утверждать скрипты, отправленные непривилегированными пользователями, сохраняя их без каких-либо изменений, но эта функциональность была отключена для предотвращения атак, основанных на социальной инженерии. («Сохранение» обычно означает через веб-интерфейс, но также может означать загрузку новой XML-конфигурации через REST или CLI.)

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

Теперь администратор может перейти в Manage Jenkins » In-process Script Approval, где будет показан список скриптов, ожидающих утверждения. Если не запрашивается ничего выглядящего опасным, просто нажмите Approve, чтобы разрешить запуск скрипта в дальнейшем.

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

Песочница Groovy

Ожидание, пока администратор утвердит каждое изменение скрипта, каким бы незначительным оно ни казалось, может быть неприемлемым в команде, распределённой по часовым поясам, или при жёстких сроках. Как альтернативный вариант, система Script Security позволяет запускать Groovy-скрипты без утверждения, если они ограничиваются операциями, считающимися по своей сути безопасными. Такая ограниченная среда выполнения называется песочницей. (В настоящее время реализаций песочниц для других языков нет, поэтому все такие скрипты должны утверждаться, если они настраиваются не администраторами.)

Чтобы переключиться в этот режим, просто установите флажок Use Groovy Sandbox под полем ввода Groovy-скрипта. Скрипты в песочнице могут немедленно запускаться кем угодно. (Даже администраторами, хотя скрипт подчиняется тем же ограничениям независимо от того, кто его написал.) При запуске скрипта каждый вызов метода, создание объекта и доступ к полю проверяются на соответствие белому списку одобренных операций. Если предпринята неодобренная операция, скрипт останавливается, и соответствующая функция Jenkins пока не может использоваться.

Плагин Script Security поставляется с небольшим белым списком по умолчанию, а интегрируемые плагины могут добавлять в этот список операции (обычно методы, специфичные для этого плагина).

Но вы не ограничены белым списком по умолчанию: каждый раз, когда скрипт завершается с ошибкой перед выполнением ещё не внесённой в белый список операции, эта операция автоматически добавляется в другую очередь утверждения. Администратор может перейти на ту же страницу, описанную выше, для утверждения целых скриптов, и увидеть список ожидающих утверждения операций. Если нажать Approve рядом с сигнатурой операции, она немедленно добавляется в белый список и становится доступной для скриптов в песочнице.

Большинство сигнатур имеют вид method class.Name methodName arg1Type arg2Type…, указывающий вызов метода Java с конкретным классом-«приёмником» (this), именем метода и списком типов аргументов (или параметров). (Для утверждения будет предложена наиболее общая сигнатура предпринятого вызова метода, даже если фактический объект, для которого он вызывался, был более конкретного типа, переопределяющего этот метод.) Вы также можете увидеть staticMethod для статических методов (класса), new для конструкторов и field для доступа к полям (get или set).

Администраторам в средах с высокими требованиями к безопасности следует тщательно обдумывать, какие операции вносить в белый список. Операции, изменяющие состояние сохраняемых объектов (таких как задания Jenkins), как правило, должны быть запрещены. Большинство методов getSomething безвредны.

Методы, учитывающие ACL

Однако имейте в виду, что даже некоторые методы-«геттеры» предназначены для проверки конкретных разрешений (с помощью ACL — списка контроля доступа), в то время как скрипты часто выполняются системным псевдопользователем, которому предоставлены все разрешения. Так, например, method hudson.model.AbstractItem getParent (который получает папку или корень Jenkins, содержащие задание) сам по себе безвреден, но возможный последующий вызов method hudson.model.ItemGroup getItems (который перечисляет задания по имени внутри папки) проверяет Job/Read. Этот второй вызов было бы опасно вносить в белый список безоговорочно, поскольку это означало бы, что пользователь, имеющий Job/Create в папке, сможет прочитать по крайней мере некоторую информацию из любых заданий в этой папке, даже тех, которые должны быть скрыты согласно стратегии авторизации на основе проектов; было бы достаточно создать в папке задание, содержащее такой Groovy-скрипт (детали будут различаться в зависимости от интегрирующего плагина):

println("I sniffed ${thisjob.getParent().getItems()}!");

При запуске вывод скрипта отобразит по крайней мере имена предположительно секретных проектов. Вместо этого администратор может нажать Approve, предполагая проверку разрешений для getItems; это разрешит вызов при запуске от имени реального пользователя (если интегрирующий плагин вообще так делает), но запретит его при запуске от имени системного пользователя (что более типично). В этом случае getItems фактически реализован так, что возвращает только те задания, к которым имеет доступ текущий пользователь, поэтому при запуске в первом случае (от имени конкретного пользователя) описание покажет только те задания, которые они и так могли бы видеть. Эта более продвинутая кнопка показывается только для вызовов методов (и конструкторов) и должна использоваться только там, где вы знаете, что Jenkins выполняет проверку разрешений.

Руководство разработчика

Полный пример интеграции

Простой способ

Для типичной интеграции Groovy, в которой вы предоставляете пользователю возможность использовать либо утверждение скриптов, либо песочницу, измените строковое поле скрипта вашего describable на поле SecureGroovyScript. В вашем конструкторе перед сохранением значения вызовите configuringWithKeyItem (если такой скрипт может быть только один на элемент верхнего уровня) или configuringWithNonKeyItem (если их может быть несколько). Форма конфигурации должна использовать <f:property field="…"/> для получения скрипта и конфигурации песочницы. Когда вы хотите запустить скрипт, просто вызовите evaluate.

(Для совместимости со старыми данными выберите другое имя поля и объявите исходное устаревшим. Затем вы можете определить метод readResolve, который устанавливает новое поле в SecureGroovyScript с выключенной песочницей, вызывает для него configuring(ApprovalContext.create()), чтобы уведомить систему о том, что загружен неутверждённый скрипт, и сбрасывает старое поле.)

Сложный способ

Используется, если вам нужен больший контроль, чем предлагает SecureGroovyScript:

Введите в свою конфигурацию логическое поле sandbox.

Когда поле не установлено, вам нужно вызвать ScriptApproval.configuring в @DataBoundConstructor. Используйте ApprovalContext.withCurrentUser, а также withItemAsKey, где это применимо (когда на задание приходится только один скрипт); в противном случае как минимум withItem, где применимо, и/или withKey, когда вы можете однозначно идентифицировать это использование из контекста (StaplerRequest.findAncestorObject здесь полезен). Это позволяет системе узнать, что (возможно) новый скрипт был сконфигурирован конкретным человеком. Вам также понадобится readResolve, который вызывает configuring, чтобы уведомить систему, когда конфигурируемый объект со скриптом загружен с диска (и, следовательно, конфигуратор неизвестен). Вызывайте ScriptApproval.using при запуске скрипта и перехватывайте UnapprovedUsageException, если необходимо. Дескриптор должен использовать проверку формы для поля скрипта и вызывать ScriptApproval.checking (обычно ваш дескриптор уже должен выполнять по крайней мере проверку синтаксиса этого поля).

Когда поле песочницы установлено, вам нужно лишь настроить оболочку Groovy с помощью GroovySandbox.createSecureCompilerConfiguration, а затем вызвать GroovySandbox.run; будьте готовы перехватить RejectedAccessException и вызвать ScriptApproval.accessRejected.

Предварительно одобренные методы для песочницы

Чтобы предварительно одобрить некоторые конкретные вызовы методов, просто аннотируйте их с помощью @Whitelisted, если они в вашем плагине; в противном случае вы можете зарегистрировать (с помощью @Extension) ProxyWhitelist, делегирующий в StaticWhitelist.from и загружающий текстовый файл со списком разрешённых методов.

Classpath для выполнения скриптов

При создании GroovyShell для выполнения скрипта или вызове ecureGroovyScript.evaluate вы должны передать ClassLoader, представляющий фактический classpath для скрипта. Вы можете использовать загрузчик ядра Jenkins, вашего плагина или Jenkins.getInstance().getPluginManager().uberClassLoader.

Что бы вы ни выбрали, не позволяйте непривилегированному пользователю добавлять произвольные записи classpath создавая URLClassLoader! Это сделало бы тривиальным обход всей защиты при использовании песочницы. (Пользователю достаточно сделать так, чтобы это или другое задание архивировало JAR-файл, содержащий некий класс со статическим методом, помеченным @Whitelisted и делающим что угодно, а затем вызвать этот метод из своего скрипта.) Ни одна атака ещё не была продемонстрирована при использовании полного утверждения скриптов — URLClassLoader с обычным делегированием «сначала родитель» не позволил бы тривиально маскировать невинно выглядящие API скомпрометированными версиями, — но вполне вероятно, что некое хитроумное использование META-INF/services/org.codehaus.groovy.transform.ASTTransformation или подобного может заставить в остальном безопасный скрипт вести себя неожиданным и несанкционированным образом. JENKINS-22834 предлагает безопасную стандартную альтернативу.

Модульные тесты

При написании тестов для плагинов, использующих Script Security Plugin, вы можете столкнуться с некоторыми ошибками в ваших тестах.

Если ваши тесты вызывают прямо или косвенно метод ScriptApproval.get(), то ваши модульные тесты должны использовать JenkinsRule, чтобы Jenkins.getInstance() не возвращал null. Вероятно, что тесты, которые раньше работали, начнут падать, если вы не используете песочницу. Это происходит потому, что они ставятся в очередь на утверждение. Если вам нужно выполнять скрипты независимо от утверждений, ScriptApproval.get().preapprove(script, GroovyLanguage.get()) гарантирует, что все настроенные скрипты будут утверждены. В качестве альтернативы вы можете заставить ваши тесты запускать скрипты в песочнице. В этом случае вам может понадобиться внести в белый список методы, используемые вашими тестами, — либо в целом для реальных пользователей, либо с помощью @TestExtension, чтобы иметь белый список только для тестов.

История версий

См. журнал изменений