azure_graph_generic_resources Resource
Use the azure_graph_generic_resources
Inspec audit resource to test any valid Azure resource available through Microsoft Azure Graph API.
Azure REST API Version, Endpoint, and HTTP Client Parameters
This resource interacts with API versions supported by the resource provider.
The api_version
can be defined as a resource parameter.
If not provided, this resource uses the latest version.
For more information, refer to the azure_generic_resource
document.
Unless defined, this resource uses the azure_cloud
global endpoint and default values for the HTTP client.
For more information, refer to the resource pack README.
Install
This resource is available in the Chef InSpec Azure resource pack.
For information on configuring your Azure environment for Chef InSpec and creating an InSpec profile that uses the InSpec Azure resource pack, see the Chef InSpec documentation for the Azure cloud platform.
Syntax
describe azure_graph_generic_resources(resource: 'RESOURCE', filter: {starts_with_property_name: 'A'}, select: %w(properties to be tested)) do
its('property') { should eq 'value' }
end
where
- Resource parameters are used to query Azure Graph API endpoint for the resource to be tested.
property
- This generic resource dynamically creates the properties on the fly based on the type of resource that has been targeted and the parameters provided with theselect
parameter.value
is the expected output from the chosen property.
Parameters
The following parameters can be passed for targeting specific Azure resources.
resource
- Azure resource type where the targeted resource belongs. This is the only MANDATORY parameter. For example,
users
. filter
- A hash containing the filtering options and their values. The
starts_with_
operator can be used for fuzzy string matching. Parameter names are in the snake case. For example,{ starts_with_given_name: 'J', starts_with_department: 'Core', country: 'United Kingdom', given_name: John}
. filter_free_text
- OData query string in double quotes,
"
. Property names are in the camel case, refer to Azure query parameters documentation for more information. For example,"startswith(displayName,'J') and surname eq 'Doe'"
. select
- A list of the query parameters defining the attributes the resource will expose and to be tested. Property names are in camel case. If not provided then the predefined attributes will be returned from the API. For example,
['givenName', 'surname', 'department']
. api_version
- API version of the Azure Graph API to use when interrogating the resource. If not set, then the predefined stable version will be used. For example,
v1.0
orbeta
.
It is advised to use filter
or filter_free_text
to narrow down the targeted resources at the server side, Azure Graph API, for a more efficient test.
Properties
Attributes will be created dynamically by pluralizing the name of the properties of the resources and converting them to snake_case
form.
For example, if the query parameters are select: %w{ country department givenName }
, then the parameters will be:
ids
(default)countries
departments
given_names
Filter Criteria
Returned resources can be filtered by their parameters provided with the select
option, or the default values returned from the API unless the select
is used.
For example, if the query parameters are select: %w{ country department givenName }
, then the filter criteria will be:
id
(default)country
department
givenName
Examples
Test a selection of user accounts
**Using filter parameter.**
describe azure_graph_generic_resources(resource: 'USERS', filter: { starts_with_given_name: 'J', starts_with_department: 'customer', country: 'United Kingdom' }, select: %w{ country userPrincipalName}) do
it { should exist }
its('countries'.uniq) { should eq ['United Kingdom'] }
end
**Using filter_free_text parameter.**
describe azure_graph_generic_resources(resource: 'USERS', filter_free_text: "startswith(givenName,'J') and startswith(department,'customer') and country eq 'United States'", select: %w{ country userPrincipalName}) do
it { should exist }
its('countries'.uniq) { should eq ['United States'] }
end
Filter* the results to only include that match the given country (Client-Side Filtering is NOT Recommended)
describe azure_graph_generic_resources(resource: 'USERS', select: %w{ country }).where(country: 'United Kingdom') do
it { should exist }
end
Note
Test given_names
Parameter.
azure_graph_generic_resources(resource: 'USERS', filter: { starts_with_given_name: 'J' }, select: %w{ givenName }).given_names.each do |name|
describe name do
it { should start_with('J') }
end
end
Matchers
For a full list of available matchers, see our Universal Matchers page.This resource has the following special matchers.
exist
# Should not exist if there is no resource with a given name.
describe azure_graph_generic_resources(resource: 'USERS', filter: { given_name: 'fake_name'}, select: %w{ givenName }) do
it { should_not exist }
end
not_exists
# Should exist if there is at least one resource with a given name.
describe azure_graph_generic_resources(resource: 'USERS', filter: { given_name: 'valid_name'}, select: %w{ givenName }) do
it { should exist }
end
Azure Permissions
Graph resources require specific privileges granted to your service principal.
Please refer to the Microsoft Documentation for information on how to grant these permissions to your application.