Справочник по Chef InSpec

[править на GitHub]

Этот документ поможет вам ознакомиться с некоторыми терминами, используемыми в проекте Chef InSpec.

Его можно использовать двумя способами:

• Справочник в текстовом формате. Узнайте значение слова, с которым вы столкнулись.
• Справочник в виде визуальных примеров. Рассмотрите примеры и посмотрите, как маркируются части. Затем вы можете использовать текстовый справочник для получения подробностей о каждом понятии.

Визуальный справочник

Пример

Предположим, нас интересует аудит автомобилей. Допустим, у нас есть два ресурса Chef InSpec для аудита: cars, который ищет и фильтрует группы автомобилей, и car, который выполняет подробный аудит одного автомобиля.

Основный синтаксис

Давайте рассмотрим несколько простых примеров.

Пример ресурса единственного числа

describe car(owner: 'Tony Clifton') do
    it { should exist }
    its('license_plate') { should cmp 'MOONMAN' }
    it { should be_classy }
    it { should_not have_check_engine_light_on }
end

describe car(owner: ‘Tony Clifton’) do

car — это ресурс. Поскольку мы говорим только об одном автомобиле, это ресурс единственного числа.

describe car(owner: ‘Tony Clifton’)

owner — это параметр ресурса, а ‘Tony Clifton’ — значение параметра ресурса.

it { should exist }

Каждая строка внутри блока ресурса, начинающаяся с it или its, представляет собой тест. Используйте it для доступа к специфичным для ресурса матчерам, а its — для доступа к свойствам ресурса, которые в свою очередь используются с универсальными матчерами.

its('license_plate') { should cmp ‘MOONMAN’ }

license_plate — это свойство, принадлежащее ресурсу. Свойства раскрывают проверяемую информацию о ресурсе. Некоторые свойства — числа, некоторые (как это) — текст, некоторые — списки, а некоторые — более сложные объекты. Свойства всегда используются с универсальными матчерами.

its(‘license_plate’) { should cmp ‘MOONMAN’ }

cmp — это универсальный матчер. cmp — это очень гибкий, слабо типизированный оператор равенства; здесь он проверяет, совпадает ли текст номера кузова с текстом ‘MOONMAN’. Обратите внимание, что тест работает с текстом номера кузова (значением свойства), а не с ресурсом. Полный список поддерживаемых универсальных матчеров можно найти на странице Универсального матчера.

its(‘license_plate’) { should cmp ‘MOONMAN’ }

‘MOONMAN’ — это ожидаемый результат. Некоторые матчеры принимают ожидаемый результат; другие — нет.

it { should be_classy }

be_classy — это специфичный для ресурса матчер. Он возвращает значение «да» или «нет», в зависимости от того, является ли автомобиль Тони стильным или нет. (Это так. Тони — стильный человек.)

it { should_not have_check_engine_light_on }

should_not указывает, что это отрицательный тест. Таким образом, этот тест проходит, если матчер возвращает «нет».

Пример ресурса множественного числа

  describe cars.where(color: /^b/) do
    it { should exist }
    its('manufacturers') { should include 'Cadillac' }
    its('count') { should be >= 10 }
  end

describe cars.where(color: /^b/) do

cars — это ресурс. Поскольку мы потенциально говорим о многих автомобилях, это ресурс множественного числа.

describe cars.where(color: /^b/) do

where(color: /^b/) — это утверждение фильтра. Без утверждения фильтра cars просто выбирает все автомобили в мире.

describe cars.where(color: /^b/) do

color — это критерий фильтра вместе со значением фильтра /^b/. Здесь критерий выражает, что мы хотим выбрать все автомобили, цвет которых начинается с буквы ‘b’ — синий, коричневый, бордовый и т. д.

it { should exist }

Каждая строка внутри блока ресурса, начинающаяся с it или its, представляет собой тест. Используйте it для доступа к специфичным для ресурса матчерам, а its — для доступа к свойствам ресурса, которые в свою очередь используются с универсальными матчерами.

При использовании ресурсов множественного числа exist имеет особое значение: соответствует ли фильтру что-либо?

its('manufacturers') { should include ‘Cadillac’ }

manufacturers — это свойство ресурса. Свойства раскрывают проверяемую информацию о ресурсе. При ресурсах множественного числа свойства почти всегда находятся в множественном числе и почти всегда возвращают список значений. Здесь тест возвращает список имен производителей автомобилей. Некоторые свойства списков дедублируются; например, у вас может быть 10 автомобилей, но если все они — «Субару» и «Кадиллаки», в свойстве manufacturers будут только две записи. Обязательно проверьте документацию для вашего ресурса.

its(‘manufacturers’) { should include ‘Cadillac’ }

include — это универсальный матчер. include работает со списками и проверяет, присутствует ли ожидаемый результат. Здесь проверяется, содержит ли список производителей запись с текстом ‘Cadillac’. Обратите внимание, что он работает со списком производителей (значением свойства), а не с ресурсом. Полный список поддерживаемых универсальных матчеров можно найти на странице Универсального матчера.

its(‘manufacturers’) { should include ‘Cadillac’ }

‘Cadillac’ — это ожидаемый результат. Некоторые матчеры принимают ожидаемый результат; другие — нет.

its(‘count’) { should be >= 10 }

be >= — это [операторный матчер](#операторный матчер). Он позволяет выполнять числовые сравнения. Все ресурсы множественного числа имеют свойство count.

Текстовый справочник

атрибут

Устаревшее название для ввода.

управление

блок управления

Ключевое слово control используется для объявления control block. Здесь слово «управление» означает «регулирующее управление, рекомендацию или требование» — а не конструкцию разработки программного обеспечения. У control block есть имя (которое обычно относится к присвоенному идентификатору регулирующей рекомендации, которую оно реализует), метаданные, такие как описания, ссылки и теги, и, наконец, объединяет связанные блоки describe для реализации проверок.

базовый ресурс

Ресурс, который включен в InSpec; вам не нужно устанавливать дополнительные плагины или зависеть от [пакета ресурсов](#пакет ресурсов), чтобы использовать ресурс.

настраиваемый ресурс

Ресурс, который не включён в InSpec. Это может быть ресурс вашей собственной разработки или ресурс, полученный за счёт зависимости от [пакета ресурсов](#пакет ресурсов).

описать

блок describe

Ключевое слово describe используется с describe block для ссылки на ресурс Chef InSpec. Вы используете ключевое слово describe вместе с именем ресурса для объединения связанных тестов, которые применяются к ресурсу. Несколько блоков describe обычно группируются в управление, но вы также можете использовать их вне управления.

control 'Rule 1.1 - Color restrictions' do
  # Count only blue cars
  describe cars.where(color: 'blue') do
    its('count') { should eq 20 }
  end
end

DSL

DSL — аббревиатура от Domain Specific Language. Она относится к языковым расширениям, которые Chef InSpec предоставляет для упрощения создания ресурсов и контролей. Хотя файлы управления Chef InSpec используют Ruby, Control DSL упрощает написание контролей без знания Ruby, предоставляя ключевые слова DSL, такие как describe, control, it и its. Подробности о доступных ключевых словах для авторов контролей см. на странице Chef InSpec DSL.

Для авторов настраиваемых ресурсов доступен дополнительный DSL — см. страницу Resource DSL.

ожидаемый результат

При использовании матчера, expected result — это значение, с которым матчер будет сравнивать свойство, к которому осуществляется доступ.

В этом примере используется матчер cmp для сравнения свойства color с ожидаемым результатом «чёрный».

describe car(owner: 'Bruce Wayne') do
  its('color') { should cmp 'black' }
end

утверждение фильтра

При использовании ресурса множественного числа, filter statement используется для выбора отдельных объектов тестирования с использованием критериев фильтра. Утверждение фильтра почти всегда указывается ключевым словом where, и может повторяться с помощью цепочки методов.

Утверждение фильтра может использовать синтаксис вызова метода (который позволяет выполнять базовые операции с критериями, такие как равенство, сопоставление с регулярными выражениями и сравнение ruby ===) или синтаксис блока (который позволяет использовать произвольный код).

В этом примере where(...) — это утверждение фильтра.

# Count only blue cars
describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
end

критерий фильтра

критерии фильтра

При использовании ресурса множественного числа, filter criterion используется для выбора отдельных объектов тестирования в рамках утверждения фильтра. Вы можете использовать несколько filter criteria в одном утверждении фильтра.

При использовании синтаксиса вызова метода с утверждением фильтра вы предоставляете критерии фильтра в виде Hash, с именами критериев фильтра в качестве ключей и условиями в качестве значений Hash. Вы можете предоставить тест, true/false или числа, в этом случае сравнение является сравнением на равенство; или вы можете предоставить регулярное выражение, в этом случае выполняется сопоставление.

Здесь (color: blue) — единственный критерий фильтра, используемый с утверждением фильтра в синтаксисе вызова метода.

# Count only blue cars
describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
end

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

Здесь { engine_cylinders >= 6 } — утверждение фильтра синтаксиса блока, относящееся к одному критерию фильтра.

# Vroom!
describe cars.where { engine_cylinders >= 6 } do
  its('city_mpg_ratings') { should_not include '4-star' }
end

input

input — это значение, которое Chef InSpec может получить из различных источников, включая командную строку, метаданные профиля или сам DSL-файл конфигурации. Вы можете использовать эту функцию, чтобы изменить поведение профиля, передавая различные файлы атрибутов, или для хранения секретов, которые не должны напрямую присутствовать в профиле.

В прошлом входные данные назывались attributes. Входные данные Chef InSpec не связаны с атрибутами Chef Infra.

Синтаксис командной строки для входных данных описан в команде inspec exec.

Подробная информация об входных данных приведена в документации по входным данным.

it

Внутри блока describe, it объявляет отдельный тест непосредственно по отношению к ресурсу (в отличие от тестирования свойств ресурса, как это делает its). Хотя с it можно использовать универсальные соответствия, гораздо чаще используются специфичные для ресурса соответствия.

it может использоваться с should, или отрицаться с помощью should_not.

Здесь it { should ... } объявляет тест, вызывая соответствие classy? для автомобиля Тони Клифтона.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

its

Внутри блока describe, its объявляет отдельный тест по отношению к свойству ресурса (в отличие от прямого тестирования самого ресурса, как это делает it). С its необходимо использовать универсальные соответствия; использование специфичных для ресурса соответствий недоступно.

its может использоваться с should, или отрицаться с помощью should_not.

Доступное свойство передается как единственный строковый аргумент в its. В качестве расширенного использования, если у свойства есть интересующие вас методы, вы можете вызвать их, используя ‘.’ в строке; возможны и ещё более продвинутые схемы вызовов — см. документацию rspec-its.

Здесь its('fuzzy_dice') { should ... } объявляет тест, проверяя свойство fuzzy_dice автомобиля Тони Клифтона. Предположим, — учитывая натуру Тони, — что fuzzy_dice вернёт массив.

describe car(owner: 'Tony Clifton') do
  its('fuzzy_dice') { should_not be_empty }
  its('fuzzy_dice.count') { should be >= 2 }
  its('fuzzy_dice.first.fuzziness') { should cmp 'outlandishly so' }
end

matcher

matcher выполняет фактические утверждения по отношению к ресурсам или свойствам ресурсов. Соответствия всегда возвращают значение true/false. Соответствия делятся на две группы:

• специфичные для ресурса соответствия, которые работают непосредственно с ресурсом, используются с it и, как правило, сильно настроены под потребности аудита ресурса
• универсальные соответствия, которые работают со свойствами ресурса, используются с its и, как правило, очень универсальны, работая с текстом, числами и списками

Некоторые соответствия принимают параметры, называемые ожидаемыми результатами.

Для получения информации о том, как соответствия RSpec связаны с соответствиями Chef InSpec, см. Chef InSpec и RSpec.

Здесь be_classy — соответствие, специфичное для ресурса, работающее непосредственно с car, а cmp — универсальное соответствие, работающее со свойством manufacturer.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
  its('manufacturer') { should cmp 'Cadillac' }
end

множественный ресурс

plural resource — это ресурс, специализирующийся на выполнении поисков и представляющий собой множество экземпляров ресурса на платформе цели. Множественные ресурсы используются для аудита подсчётов, проверки свойств групп и обладают уникальной способностью обеспечивать отрицательные тесты («ничего подобного не должно существовать»), часто требуемые стандартами соответствия. Множественные ресурсы не предназначены для глубокого аудита отдельного элемента; для этого используйте единичные ресурсы.

Множественные ресурсы почти всегда имеют имя, оканчивающееся на ’s': processes, aws_security_groups, cars. Для множественных ресурсов обычно не существуют специфичные для ресурса соответствия. Если у них есть свойства, они почти всегда являются списками свойств, что означает, что они возвращают список значений, который может быть или не быть дедублированным.

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

Здесь cars — множественный ресурс.

describe cars.where(color: 'blue') do
  its('count') { should eq 20 }
  its('license_plates') { should include 'AUTOAZUL' }

  # License plates are unique, should have 20
  its('license_plates.count') { should cmp 20 }

  # Manufacturers are de-duplicated
  its('manufacturers') { should include 'Subaru' }
  its('manufacturers.count') { should be < 10 }
end

профиль

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

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

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

свойство

Факт о ресурсе. Обычно для доступа к свойству используется ключевое слово its, для написания теста внутри блока describe, а затем для утверждений о значении свойства используется универсальное соответствие.

У каждого ресурса разные свойства. Подробности см. в документации по ресурсам.

Здесь manufacturer — свойство ресурса car.

describe car(owner: 'Tony Clifton') do
  its('manufacturer') { should cmp 'Cadillac' }
end

репортер

Формат вывода для команды inspec exec командной строки. Доступно несколько репортеров, включая JSON и JUnit; см. документацию по команде inspec exec.

ресурс

resource представляет собой категорию элементов на целевой платформе, которые вы хотите проверить. Например, для проверки существования и разрешений файла используется ресурс file. Chef InSpec предлагает десятки различных ресурсов, от высокоспециализированных (например, aws_security_group, который проверяет правила брандмауэра в AWS) до очень общих (например, command, который выполняет команду и позволяет просмотреть её вывод).

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

Ресурсы используются в блоке describe для выполнения тестов.

Здесь car — это ресурс.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

пакет ресурсов

Пакет ресурсов — это тип профиля, используемого для распространения настраиваемых ресурсов. Этот специализированный тип профиля не содержит контролей, но содержит каталог libraries, в котором Ruby-файлы определяют настраиваемые ресурсы.

параметр ресурса

resource parameters — это информация, передаваемая ресурсу при его объявлении. Обычно параметры ресурса предоставляют идентификационную информацию или информацию о подключении. Параметры ресурса не являются тем же, что и утверждение фильтра.

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

Здесь owner: 'Tony Clifton' — это параметр ресурса.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

соответствие, специфичное для ресурса

Соответствие, которое работает непосредственно с ресурсом, а не с свойством, как это делает [универсальное соответствие](#universal matcher).

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

Например, гипотетический ресурс car определяет метод classy?, который доступен как соответствие be_classy в тестах Chef InSpec.

describe car(owner: 'Tony Clifton') do
  it { should be_classy }
end

единичный ресурс

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

цель

target — это операционная система или API, на котором Chef InSpec выполняет аудит. В Chef InSpec 1.x это всегда была операционная система (голая машина, виртуальная машина или контейнер). В Chef InSpec 2.x и более поздних версиях это может быть операционная система или API-цель, включая облачные провайдеры, такие как AWS. Chef InSpec является безагентным, то есть код и профили Chef InSpec остаются на вашем рабочем столе, а целевой ресурс удалённо запрашивается без необходимости установки чего-либо.

тест

test — это отдельное утверждение о состоянии ресурса или одного из его свойств. Все тесты начинаются с ключевого слова it или its. Тесты сгруппированы в блоке describe.

универсальный согласующий элемент

Универсальный согласующий элемент — это согласующий элемент, который может использоваться для свойств любого типа ресурса. Например, вы можете использовать cmp согласующий элемент для проверки значения свойств, не беспокоясь о преобразовании типов в Ruby. Универсальные согласующие элементы почти всегда используются с ключевым словом its.

Универсальные согласующие элементы документированы на странице Универсальные согласующие элементы.

Здесь мы получаем доступ к свойству «color», затем используем cmp универсальный согласующий элемент для сравнения свойства со значением «черный» ожидаемого результата.

describe car(owner: 'Bruce Wayne') do
  its('color') { should cmp 'black' }
end