Support ad domain services

README.md

@@ -113,6 +113,8 @@ With the generic resources:
 
 The following is a list of static resources. 
 
+- [azure_active_directory_domain_service](docs/resources/azure_active_directory_domain_service.md)
+- [azure_active_directory_domain_services](docs/resources/azure_active_directory_domain_services.md)
 - [azure_aks_cluster](docs/resources/azure_aks_cluster.md)
 - [azure_aks_clusters](docs/resources/azure_aks_clusters.md)
 - [azure_api_management](docs/resources/azure_api_management.md)

docs/resources/azure_active_directory_domain_service.md

@@ -0,0 +1,85 @@
+---
+title: About the azure_active_directory_domain_service Resource
+platform: azure
+---
+
+# azure_active_directory_domain_service
+
+Use the `azure_active_directory_domain_service` InSpec audit resource to test properties of an Azure Active Directory Service within a Tenant.
+
+## 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, the latest stable version will be used.
+For more information, refer to [`azure_graph_generic_resource`](azure_graph_generic_resource.md).
+
+Unless defined, `azure_cloud` global endpoint, and default values for the http client will be used.
+For more information, refer to the resource pack [README](../../README.md).
+
+## Availability
+
+### Installation
+
+This resource is available in the [InSpec Azure resource pack](https://github.com/inspec/inspec-azure).
+For an example `inspec.yml` file and how to set up your Azure credentials, refer to resource pack [README](../../README.md#Service-Principal).
+
+## Syntax
+```ruby
+describe azure_active_directory_domain_service(id: 'ipswitch.com') do
+  it { should exist }
+end
+```
+## Parameters
+
+Either one of the following parameters is mandatory.
+
+| Name               | Description | Example |
+|--------------------|-------------|---------|
+| id                  | Domain ID | `ipswitch.com` | 
+
+## Properties
+
+| Property                      | Description                                                                   |
+|-------------------------------|-------------------------------------------------------------------------------|
+| id                            | The fully qualified name of the domain. Key, immutable, not nullable, unique. |
+| authenticationType            | Indicates the configured authentication type for the domain.The value is either Managed or Federated. |
+| availabilityStatus            | This property is always null except when the verify action is used.           |
+| isAdminManaged                | The value of the property is false if the DNS record management of the domain has been delegated to Microsoft 365. |
+| isDefault                     | true if this is the default domain that is used for user creation. There is only one default domain per company. Not nullable |
+| isInitial                     | true if this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is only one initial domain per company. |
+| isRoot                        | true if the domain is a verified root domain. Otherwise, false if the domain is a subdomain or unverified. |
+| isVerified                    | true if the domain has completed domain ownership verification.               |
+| passwordNotificationWindowInDays| Specifies the number of days before a user receives notification that their password will expire. If the property is not set, a default value of 14 days will be used. |      
+| passwordValidityPeriodInDays  | Specifies the length of time that a password is valid before it must be changed. If the property is not set, a default value of 90 days will be used. |
+| supportedServices             | The capabilities assigned to the domain.                                      |
+| state                         | Status of asynchronous operations scheduled for the domain.                   |
+
+## Examples
+
+### Test If an Active Directory Domain is Referenced with a Valid ID
+```ruby
+describe azure_active_directory_domain_service(id: 'ipswitch.com') do
+  it { should exist }
+end
+```
+### Test If an Active Directory Domain is Referenced with an Invalid ID
+```ruby
+describe azure_active_directory_domain_service(id: 'ipswitch-1.com') do
+  it { should_not exist }
+end
+```
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exists
+```ruby
+describe azure_active_directory_domain_service(id: 'M365x214355.onmicrosoft.com') do
+  it { should exist }
+end
+```
+## Azure Permissions
+
+Graph resources require specific privileges granted to your service principal.
+Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.

docs/resources/azure_active_directory_domain_services.md

@@ -0,0 +1,101 @@
+---
+title: About the azure_active_directory_domain_services Resource
+platform: azure
+---
+
+# azure_active_directory_domain_services
+Use the `azure_active_directory_domain_services` InSpec audit resource to test properties of some or all Azure Active Directory Domains within a Tenant.
+
+## 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, the latest stable version will be used.
+For more information, refer to [`azure_graph_generic_resources`](azure_graph_generic_resources.md).
+
+Unless defined, `azure_cloud` global endpoint, and default values for the http client will be used.
+For more information, refer to the resource pack [README](../../README.md).
+
+## Availability
+
+### Installation
+
+This resource is available in the [InSpec Azure resource pack](https://github.com/inspec/inspec-azure).
+For an example `inspec.yml` file and how to set up your Azure credentials, refer to resource pack [README](../../README.md#Service-Principal).
+
+## Syntax
+
+An `azure_active_directory_domain_services` resource block returns all Azure Active Directory Domains contained within the configured Tenant and then tests that group of domains.
+```ruby
+describe azure_active_directory_domain_services do
+  #...
+end
+```
+## Parameters
+
+The following parameters can be passed for targeting specific Domains.
+
+| Name              | Description                                                 | Example                             |
+|-------------------|-------------------------------------------------------------|-------------------------------------|
+| 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 snake_case. | `{ starts_with_given_name: 'J', starts_with_department: 'Core', country: 'United Kingdom', given_name: John}` |
+| filter_free_text  | [OData](https://www.odata.org/getting-started/basic-tutorial/) query string in double quotes, `"`. Property names are in camelcase, refer to [here](https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter) for more information. | `"startswith(displayName,'J') and surname eq 'Doe'"` or `"userType eq 'Guest'"` |
+
+It is advised to use these parameters to narrow down the targeted resources at the server side, Azure Graph API, for a more efficient test.
+
+## Properties
+
+| Property              | Description                                           | Filter Criteria<superscript>*</superscript>  |
+|-----------------------|-------------------------------------------------------|----------------------------------------------|
+| ids                   | A list of fully qualified name of the domain.         | `id`                                         |
+| authentication_types  | A list of the configured authentication types for the domain.| `authentication_type`                 |
+| availability_statuses | A list of domain entities when verify action is set.  | `availability_status`                        |
+| is_admin_managed      | A list of admin managed configuration.                | `is_admin_managed`                           |
+| is_default            | A list of flags to indicate if it is default domains. | `is_default`                                 |
+| is_initial            | A list of flags to indicate if initial domains created by Microsoft Online Services.| `is_initial`   |
+| is_root               | A list of flags to indicate if verified root domain.  | `is_root`                                    |
+| is_verified           | A list of flags to indicate if the domain has completed domain ownership verification.| `is_verified`|
+| passwordNotificationWindowInDays | A list of password notification window days.| `passwordNotificationWindowInDays`          |
+| passwordValidityPeriodInDays | A list of password validity period in days.    |  `passwordValidityPeriodInDays`              |
+| supportedServices     | A list of capabilities assigned to the domain.        |  `supportedServices`                         |
+| state                 | A list of asynchronous operations scheduled.          |  `state`                                     |
+
+<superscript>*</superscript> For information on how to use filter criteria on plural resources refer to [FilterTable usage](https://github.com/inspec/inspec/blob/master/dev-docs/filtertable-usage.md).
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Check Domains with Some Filtering Parameters Applied at Server Side (Using `filter`)
+```ruby
+describe azure_active_directory_domain_services(filter: {authenticationType: "authenticationType-value"}) do
+  it { should exist }
+end
+```    
+### Check Domains with Some Filtering Parameters Applied at Server Side (Using `filter_free_text`)
+```ruby
+describe azure_active_directory_domain_services(filter_free_text: "startswith(authenticationType,'authenticationType-value')") do
+  it { should exist }
+end
+```
+### Ensure There are supported services (Client Side Filtering)
+```ruby
+describe azure_active_directory_domain_services.supportedServices do
+  it { should_not exist }
+end
+```    
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exists
+
+The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+```ruby
+describe azure_active_directory_domain_services do
+  it { should exist }
+end
+```
+## Azure Permissions
+
+Graph resources require specific privileges granted to your service principal.
+Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.

libraries/azure_active_directory_domain_service.rb

@@ -0,0 +1,27 @@
+require 'azure_graph_generic_resource'
+
+class AzureActiveDirectoryDomainService < AzureGraphGenericResource
+  name 'azure_active_directory_domain_service'
+  desc 'Verifies settings for an Azure AD Domain Service'
+  example <<-EXAMPLE
+    describe azure_active_directory_domain_service(id: 'M365x214355.onmicrosoft.com') do
+      it { should exist }
+    end
+  EXAMPLE
+
+  def initialize(opts = {})
+    raise ArgumentError, 'Parameters must be provided in an Hash object.' unless opts.is_a?(Hash)
+
+    opts[:resource] = 'domains'
+    opts[:resource_identifiers] = %i(id)
+    super(opts, true)
+  end
+
+  def exists?
+    !failed_resource?
+  end
+
+  def to_s
+    super(AzureGraphUser)
+  end
+end

libraries/azure_active_directory_domain_services.rb

@@ -0,0 +1,20 @@
+require 'azure_graph_generic_resources'
+
+class AzureActiveDirectoryDomainServices < AzureGraphGenericResources
+  name 'azure_active_directory_domain_services'
+  desc 'Verifies settings for all Azure Active Directory Domain Services'
+  example <<-EXAMPLE
+    describe azure_active_directory_domain_services do
+      it { should exist }
+    end
+  EXAMPLE
+
+  def initialize(opts = {})
+    raise ArgumentError, 'Parameters must be provided in an Hash object.' unless opts.is_a?(Hash)
+
+    opts[:resource] = 'domains'
+    super(opts, true)
+
+    self.class.populate_filter_table(:table, @table_schema)
+  end
+end

test/integration/verify/controls/azure_active_directory_domain_service.rb

@@ -0,0 +1,9 @@
+control 'azure_active_directory_domain_service' do
+
+  azure_active_directory_domain_services.ids.each do |domain_service_id|
+    describe azure_active_directory_domain_service(id: domain_service_id) do
+      it { should exist }
+      its('isVerified') { should eq true }
+    end
+  end
+end

test/integration/verify/controls/azure_active_directory_domain_services.rb

@@ -0,0 +1,6 @@
+control 'azure_active_directory_domain_services' do
+
+  describe azure_active_directory_domain_services do
+    it { should exist }
+  end
+end

test/unit/resources/azure_active_directory_domain_service_test.rb

@@ -0,0 +1,24 @@
+require_relative 'helper'
+require 'azure_active_directory_domain_service'
+
+class AzureActiveDirectoryDomainServiceConstructorTest < Minitest::Test
+  # Generic resource requires a parameter.
+  def test_empty_params_not_ok
+    assert_raises(ArgumentError) { AzureActiveDirectoryDomainService.new }
+  end
+
+  def test_not_allowed_parameter
+    assert_raises(ArgumentError) { AzureActiveDirectoryDomainService.new(resource: 'domains', id: 'some_id', fake: 'random') }
+  end
+
+  def test_filter_not_allowed
+    assert_raises(ArgumentError) { AzureActiveDirectoryDomainService.new(resource: 'domains', id: 'some_id', filter: 'random') }
+  end
+
+  def test_resource_identifier_is_a_list
+    assert_raises(ArgumentError) do
+      AzureActiveDirectoryDomainService.new(resource: 'domains', id: 'some_id',
+                                            resource_identifier: 'random')
+    end
+  end
+end

test/unit/resources/azure_active_directory_domain_services_test.rb

@@ -0,0 +1,19 @@
+require_relative 'helper'
+require 'azure_active_directory_domain_services'
+
+class AzureActiveDirectoryDomainServicesConstructorTest < Minitest::Test
+  def test_not_allowed_parameter
+    assert_raises(ArgumentError) { AzureActiveDirectoryDomainServices.new(resource: 'domains', fake: 'rubbish') }
+  end
+
+  def test_id_not_allowed
+    assert_raises(ArgumentError) { AzureActiveDirectoryDomainServices.new(resource: 'domains', id: 'some_id') }
+  end
+
+  def test_filter_filter_free_text_together_not_allowed
+    assert_raises(ArgumentError) do
+      AzureActiveDirectoryDomainServices.new(resource: 'domains',
+                                             filter: { name: 'some_id' }, filter_free_text: %w{some_filter})
+    end
+  end
+end