From 068529da429412b1769a57f59882ee833ea72b83 Mon Sep 17 00:00:00 2001 From: Sathish Date: Fri, 2 Jul 2021 11:12:07 +0530 Subject: [PATCH 01/14] support ad domain service Signed-off-by: Sathish --- .../azure_active_directory_domain_service.rb | 27 +++++++++++++++++++ .../azure_active_directory_domain_services.rb | 20 ++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 libraries/azure_active_directory_domain_service.rb create mode 100644 libraries/azure_active_directory_domain_services.rb diff --git a/libraries/azure_active_directory_domain_service.rb b/libraries/azure_active_directory_domain_service.rb new file mode 100644 index 000000000..fe3aa7307 --- /dev/null +++ b/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 diff --git a/libraries/azure_active_directory_domain_services.rb b/libraries/azure_active_directory_domain_services.rb new file mode 100644 index 000000000..0d1f5a3b8 --- /dev/null +++ b/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) + + AzureGraphUsers.populate_filter_table(:table, @table_schema) + end +end From 987fa5057ed97bb62264131cec7f8adb3024e2bf Mon Sep 17 00:00:00 2001 From: Sathish Date: Fri, 2 Jul 2021 11:12:22 +0530 Subject: [PATCH 02/14] unit test ad domain service Signed-off-by: Sathish --- ...re_active_directory_domain_service_test.rb | 24 +++++++++++++++++++ ...e_active_directory_domain_services_test.rb | 24 +++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 test/unit/resources/azure_active_directory_domain_service_test.rb create mode 100644 test/unit/resources/azure_active_directory_domain_services_test.rb diff --git a/test/unit/resources/azure_active_directory_domain_service_test.rb b/test/unit/resources/azure_active_directory_domain_service_test.rb new file mode 100644 index 000000000..aa15f3f1f --- /dev/null +++ b/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 diff --git a/test/unit/resources/azure_active_directory_domain_services_test.rb b/test/unit/resources/azure_active_directory_domain_services_test.rb new file mode 100644 index 000000000..51a567ffd --- /dev/null +++ b/test/unit/resources/azure_active_directory_domain_services_test.rb @@ -0,0 +1,24 @@ +require_relative 'helper' +require 'azure_active_directory_domain_services' + +class AzureActiveDirectoryDomainServicesConstructorTest < Minitest::Test + # Generic resource requires `resource` parameter at least. + def test_empty_params_not_ok + assert_raises(ArgumentError) { AzureActiveDirectoryDomainServices.new } + end + + 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 From ce4617c7b21a19e84c15b1ffc1e662df8118dbb4 Mon Sep 17 00:00:00 2001 From: Sathish Date: Fri, 2 Jul 2021 11:12:29 +0530 Subject: [PATCH 03/14] integ test ad domain service Signed-off-by: Sathish --- .../controls/azure_active_directory_domain_service.rb | 9 +++++++++ .../controls/azure_active_directory_domain_services.rb | 7 +++++++ 2 files changed, 16 insertions(+) create mode 100644 test/integration/verify/controls/azure_active_directory_domain_service.rb create mode 100644 test/integration/verify/controls/azure_active_directory_domain_services.rb diff --git a/test/integration/verify/controls/azure_active_directory_domain_service.rb b/test/integration/verify/controls/azure_active_directory_domain_service.rb new file mode 100644 index 000000000..ba790751d --- /dev/null +++ b/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 diff --git a/test/integration/verify/controls/azure_active_directory_domain_services.rb b/test/integration/verify/controls/azure_active_directory_domain_services.rb new file mode 100644 index 000000000..0613e99e6 --- /dev/null +++ b/test/integration/verify/controls/azure_active_directory_domain_services.rb @@ -0,0 +1,7 @@ +control 'azure_active_directory_domain_services' do + + describe azure_active_directory_domain_services do + it { should exist } + end +end + From a43a851d2f91252981cd14556b5e3d6b41051057 Mon Sep 17 00:00:00 2001 From: Sathish Date: Fri, 2 Jul 2021 11:12:45 +0530 Subject: [PATCH 04/14] doc for domain service(s) Signed-off-by: Sathish --- .../azure_active_directory_domain_service.md | 85 +++++++++++++++ .../azure_active_directory_domain_services.md | 101 ++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 docs/resources/azure_active_directory_domain_service.md create mode 100644 docs/resources/azure_active_directory_domain_services.md diff --git a/docs/resources/azure_active_directory_domain_service.md b/docs/resources/azure_active_directory_domain_service.md new file mode 100644 index 000000000..42577d7fe --- /dev/null +++ b/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: 'contoso.com') do + it { should exist } +end +``` +## Parameters + +Either one of the following parameters is mandatory. + +| Name | Description | Example | +|--------------------|-------------|---------| +| id | Domain ID | `abcd-1234-efabc-5678` | + +## Properties + +| Property | Description | +|-------------------------------|-------------| +| id | The user's globally unique ID. | +| authenticationType | Whether the account is enabled. | +| availabilityStatus | The user's city. | +| isAdminManaged | The user's country. | +| isDefault | The user's department. | +| isInitial | The display name of the user. | +| isRoot | The user's facsimile (fax) number. | +| isVerified | The given name for the user. | +| passwordNotificationWindowInDays | The user's job title. | +| passwordValidityPeriodInDays | The primary email address of the user. | +| supportedServices | The mail alias for the user. | +| state | The user's mobile (cell) phone number. | + +## Examples + +### Test If an Active Directory Domain is Referenced with a Valid ID +```ruby +describe azure_active_directory_domain_service(id: 'someValidId') + it { should exist } +end +``` +### Test If an Active Directory Domain is Referenced with an Invalid ID +```ruby +describe azure_active_directory_domain_service(id: 'someInvalidId') + 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: 'domain_id') 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. \ No newline at end of file diff --git a/docs/resources/azure_active_directory_domain_services.md b/docs/resources/azure_active_directory_domain_services.md new file mode 100644 index 000000000..48f2a8776 --- /dev/null +++ b/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* | +|-----------------------|-------------|-----------------| +| ids | The fully qualified name of the domain. Key, immutable, not nullable, unique. | `id` | +| authentication_types | Indicates the configured authentication type for the domain. | `id` | +| availability_status | This property is always null except when the verify action is used. When the verify action is used, a domain entity is returned in the response. | `displayName` | +| is_admin_managed | The given names of domains. | `givenName` | +| is_default | The job titles of domains. | `jobTitle` | +| is_initial | The email addresses of domains. | `mail` | +| is_root | The domain types of domains, e.g.; `Member`, `Guest`. | `domainType` | +| is_verified | The domain principal names of domains, e.g.; `jdoe@contoso.com`. | `domainPrincipalName` | +| passwordNotificationWindowInDays | +| passwordValidityPeriodInDays | +| supportedServices | +| state | + +* 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. From 6f3da28a9c5930871d2cef805f04965a5f64a2f6 Mon Sep 17 00:00:00 2001 From: Sathish Date: Sat, 17 Jul 2021 18:59:44 +0530 Subject: [PATCH 05/14] fix class Signed-off-by: Sathish --- libraries/azure_active_directory_domain_services.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/azure_active_directory_domain_services.rb b/libraries/azure_active_directory_domain_services.rb index 0d1f5a3b8..fc2d92e41 100644 --- a/libraries/azure_active_directory_domain_services.rb +++ b/libraries/azure_active_directory_domain_services.rb @@ -15,6 +15,6 @@ def initialize(opts = {}) opts[:resource] = 'domains' super(opts, true) - AzureGraphUsers.populate_filter_table(:table, @table_schema) + self.class.populate_filter_table(:table, @table_schema) end end From 361644df1762490d9cd1df53b04ce8a0e04c39b9 Mon Sep 17 00:00:00 2001 From: Sathish Date: Sat, 17 Jul 2021 18:59:58 +0530 Subject: [PATCH 06/14] fix tests Signed-off-by: Sathish --- .../verify/controls/azure_active_directory_domain_services.rb | 1 - .../resources/azure_active_directory_domain_services_test.rb | 4 ---- 2 files changed, 5 deletions(-) diff --git a/test/integration/verify/controls/azure_active_directory_domain_services.rb b/test/integration/verify/controls/azure_active_directory_domain_services.rb index 0613e99e6..e5c1fb6b0 100644 --- a/test/integration/verify/controls/azure_active_directory_domain_services.rb +++ b/test/integration/verify/controls/azure_active_directory_domain_services.rb @@ -4,4 +4,3 @@ it { should exist } end end - diff --git a/test/unit/resources/azure_active_directory_domain_services_test.rb b/test/unit/resources/azure_active_directory_domain_services_test.rb index 51a567ffd..3dd00eda6 100644 --- a/test/unit/resources/azure_active_directory_domain_services_test.rb +++ b/test/unit/resources/azure_active_directory_domain_services_test.rb @@ -2,10 +2,6 @@ require 'azure_active_directory_domain_services' class AzureActiveDirectoryDomainServicesConstructorTest < Minitest::Test - # Generic resource requires `resource` parameter at least. - def test_empty_params_not_ok - assert_raises(ArgumentError) { AzureActiveDirectoryDomainServices.new } - end def test_not_allowed_parameter assert_raises(ArgumentError) { AzureActiveDirectoryDomainServices.new(resource: 'domains', fake: 'rubbish') } From 80b33e877f1b09f285bf1891ecf9c178f437ed9f Mon Sep 17 00:00:00 2001 From: Sathish Date: Sat, 17 Jul 2021 20:21:09 +0530 Subject: [PATCH 07/14] update doc Signed-off-by: Sathish --- .../azure_active_directory_domain_service.md | 38 +++++++++---------- .../azure_active_directory_domain_services.md | 28 +++++++------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/resources/azure_active_directory_domain_service.md b/docs/resources/azure_active_directory_domain_service.md index 42577d7fe..c3c1ab78e 100644 --- a/docs/resources/azure_active_directory_domain_service.md +++ b/docs/resources/azure_active_directory_domain_service.md @@ -26,7 +26,7 @@ For an example `inspec.yml` file and how to set up your Azure credentials, refer ## Syntax ```ruby -describe azure_active_directory_domain_service(id: 'contoso.com') do +describe azure_active_directory_domain_service(id: 'ipswitch.com') do it { should exist } end ``` @@ -36,36 +36,36 @@ Either one of the following parameters is mandatory. | Name | Description | Example | |--------------------|-------------|---------| -| id | Domain ID | `abcd-1234-efabc-5678` | +| id | Domain ID | `ipswitch.com` | ## Properties -| Property | Description | -|-------------------------------|-------------| -| id | The user's globally unique ID. | -| authenticationType | Whether the account is enabled. | -| availabilityStatus | The user's city. | -| isAdminManaged | The user's country. | -| isDefault | The user's department. | -| isInitial | The display name of the user. | -| isRoot | The user's facsimile (fax) number. | -| isVerified | The given name for the user. | -| passwordNotificationWindowInDays | The user's job title. | -| passwordValidityPeriodInDays | The primary email address of the user. | -| supportedServices | The mail alias for the user. | -| state | The user's mobile (cell) phone number. | +| 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: 'someValidId') +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: 'someInvalidId') +describe azure_active_directory_domain_service(id: 'ipswitch-1.com') do it { should_not exist } end ``` @@ -75,7 +75,7 @@ This InSpec audit resource has the following special matchers. For a full list o ### exists ```ruby -describe azure_active_directory_domain_service(id: 'domain_id') do +describe azure_active_directory_domain_service(id: 'M365x214355.onmicrosoft.com') do it { should exist } end ``` diff --git a/docs/resources/azure_active_directory_domain_services.md b/docs/resources/azure_active_directory_domain_services.md index 48f2a8776..2034287e9 100644 --- a/docs/resources/azure_active_directory_domain_services.md +++ b/docs/resources/azure_active_directory_domain_services.md @@ -44,20 +44,20 @@ It is advised to use these parameters to narrow down the targeted resources at t ## Properties -| Property | Description | Filter Criteria* | -|-----------------------|-------------|-----------------| -| ids | The fully qualified name of the domain. Key, immutable, not nullable, unique. | `id` | -| authentication_types | Indicates the configured authentication type for the domain. | `id` | -| availability_status | This property is always null except when the verify action is used. When the verify action is used, a domain entity is returned in the response. | `displayName` | -| is_admin_managed | The given names of domains. | `givenName` | -| is_default | The job titles of domains. | `jobTitle` | -| is_initial | The email addresses of domains. | `mail` | -| is_root | The domain types of domains, e.g.; `Member`, `Guest`. | `domainType` | -| is_verified | The domain principal names of domains, e.g.; `jdoe@contoso.com`. | `domainPrincipalName` | -| passwordNotificationWindowInDays | -| passwordValidityPeriodInDays | -| supportedServices | -| state | +| Property | Description | Filter Criteria* | +|-----------------------|-------------------------------------------------------|----------------------------------------------| +| 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` | * 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). From 2dbad7c54c07e9631825fffa2fea16ca7dc9451c Mon Sep 17 00:00:00 2001 From: Sathish Date: Sat, 17 Jul 2021 20:22:33 +0530 Subject: [PATCH 08/14] update readme Signed-off-by: Sathish --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 70de0bbf1..0b9c40dbd 100644 --- a/README.md +++ b/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) From 771b506196641502067abddfab4b65630972b253 Mon Sep 17 00:00:00 2001 From: Sathish Date: Mon, 19 Jul 2021 11:08:31 +0530 Subject: [PATCH 09/14] fix style Signed-off-by: Sathish --- .../resources/azure_active_directory_domain_services_test.rb | 1 - 1 file changed, 1 deletion(-) diff --git a/test/unit/resources/azure_active_directory_domain_services_test.rb b/test/unit/resources/azure_active_directory_domain_services_test.rb index 3dd00eda6..463495b2a 100644 --- a/test/unit/resources/azure_active_directory_domain_services_test.rb +++ b/test/unit/resources/azure_active_directory_domain_services_test.rb @@ -2,7 +2,6 @@ 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 From 70c14e9425bf835015c3d8105208d4b71f5f90a8 Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Tue, 27 Jul 2021 15:39:12 -0700 Subject: [PATCH 10/14] Docs edits Signed-off-by: Ian Maddaus --- .../azure_active_directory_domain_service.md | 34 ++++++++------- .../azure_active_directory_domain_services.md | 42 ++++++++++++------- 2 files changed, 46 insertions(+), 30 deletions(-) diff --git a/docs/resources/azure_active_directory_domain_service.md b/docs/resources/azure_active_directory_domain_service.md index c3c1ab78e..f6c1fe8ba 100644 --- a/docs/resources/azure_active_directory_domain_service.md +++ b/docs/resources/azure_active_directory_domain_service.md @@ -5,7 +5,7 @@ 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. +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 @@ -25,8 +25,9 @@ This resource is available in the [InSpec Azure resource pack](https://github.co 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 +describe azure_active_directory_domain_service(id: 'example.com') do it { should exist } end ``` @@ -36,21 +37,21 @@ Either one of the following parameters is mandatory. | Name | Description | Example | |--------------------|-------------|---------| -| id | Domain ID | `ipswitch.com` | +| id | Domain ID | `example.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. | +| 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. | @@ -58,24 +59,29 @@ Either one of the following parameters is mandatory. ## Examples ### Test If an Active Directory Domain is Referenced with a Valid ID + ```ruby -describe azure_active_directory_domain_service(id: 'ipswitch.com') do +describe azure_active_directory_domain_service(id: 'example.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 +describe azure_active_directory_domain_service(id: 'example.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 +describe azure_active_directory_domain_service(id: 'example.onmicrosoft.com') do it { should exist } end ``` diff --git a/docs/resources/azure_active_directory_domain_services.md b/docs/resources/azure_active_directory_domain_services.md index 2034287e9..9faf9f369 100644 --- a/docs/resources/azure_active_directory_domain_services.md +++ b/docs/resources/azure_active_directory_domain_services.md @@ -4,7 +4,7 @@ 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. +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 @@ -25,20 +25,22 @@ For an example `inspec.yml` file and how to set up your Azure credentials, refer ## 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. +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. +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'"` | +| 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 camel case, refer to [Microsoft's query parameters documentation](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. @@ -46,16 +48,16 @@ It is advised to use these parameters to narrow down the targeted resources at t | Property | Description | Filter Criteria* | |-----------------------|-------------------------------------------------------|----------------------------------------------| -| ids | A list of fully qualified name of the domain. | `id` | +| ids | A list of fully qualified names 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`| +| is_default | A list of flags to indicate if they are default domains. | `is_default` | +| is_initial | A list of flags to indicate if they are initial domains created by Microsoft Online Services.| `is_initial` | +| is_root | A list of flags to indicate if they are verified root domains. | `is_root` | +| is_verified | A list of flags to indicate if the domains have 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` | +| passwordValidityPeriodInDays | A list of password validity periods in days. | `passwordValidityPeriodInDays` | | supportedServices | A list of capabilities assigned to the domain. | `supportedServices` | | state | A list of asynchronous operations scheduled. | `state` | @@ -65,24 +67,30 @@ It is advised to use these parameters to narrow down the targeted resources at t The following examples show how to use this InSpec audit resource. -### Check Domains with Some Filtering Parameters Applied at Server Side (Using `filter`) +### 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`) +``` + +### 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) + +### Ensure there are supported services using 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/). @@ -90,11 +98,13 @@ This InSpec audit resource has the following special matchers. For a full list o ### 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. From 965d8d5416458c2e226cda510bec6374d28b5e32 Mon Sep 17 00:00:00 2001 From: Sathish Date: Thu, 29 Jul 2021 19:30:02 +0530 Subject: [PATCH 11/14] select all columns for AD Domain Service Signed-off-by: Sathish --- libraries/azure_active_directory_domain_services.rb | 1 + 1 file changed, 1 insertion(+) diff --git a/libraries/azure_active_directory_domain_services.rb b/libraries/azure_active_directory_domain_services.rb index fc2d92e41..0cb7a6d23 100644 --- a/libraries/azure_active_directory_domain_services.rb +++ b/libraries/azure_active_directory_domain_services.rb @@ -13,6 +13,7 @@ def initialize(opts = {}) raise ArgumentError, 'Parameters must be provided in an Hash object.' unless opts.is_a?(Hash) opts[:resource] = 'domains' + opts[:select] = %w[id authenticationType availabilityStatus isAdminManaged isDefault isInitial isRoot isVerified supportedServices passwordNotificationWindowInDays passwordValidityPeriodInDays state] super(opts, true) self.class.populate_filter_table(:table, @table_schema) From e2af41113fe7a90d750816c2feb33b15bfad6c05 Mon Sep 17 00:00:00 2001 From: Sathish Date: Thu, 29 Jul 2021 19:33:35 +0530 Subject: [PATCH 12/14] update property keys for AD Domain Service Signed-off-by: Sathish --- .../azure_active_directory_domain_services.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/resources/azure_active_directory_domain_services.md b/docs/resources/azure_active_directory_domain_services.md index 9faf9f369..c5145470a 100644 --- a/docs/resources/azure_active_directory_domain_services.md +++ b/docs/resources/azure_active_directory_domain_services.md @@ -46,20 +46,20 @@ It is advised to use these parameters to narrow down the targeted resources at t ## Properties -| Property | Description | Filter Criteria* | -|-----------------------|-------------------------------------------------------|----------------------------------------------| -| ids | A list of fully qualified names 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 they are default domains. | `is_default` | -| is_initial | A list of flags to indicate if they are initial domains created by Microsoft Online Services.| `is_initial` | -| is_root | A list of flags to indicate if they are verified root domains. | `is_root` | -| is_verified | A list of flags to indicate if the domains have completed domain ownership verification.| `is_verified`| -| passwordNotificationWindowInDays | A list of password notification window days.| `passwordNotificationWindowInDays` | -| passwordValidityPeriodInDays | A list of password validity periods in days. | `passwordValidityPeriodInDays` | -| supportedServices | A list of capabilities assigned to the domain. | `supportedServices` | -| state | A list of asynchronous operations scheduled. | `state` | +| Property | Description | Filter Criteria* | +|-----------------------|------------------------------------------------------------------|---------------------------------------------| +| ids | A list of fully qualified names of the domain. | `id` | +| authentication_types | A list of the configured authentication types for the domain. | `authenticationType` | +| availability_statuses | A list of domain entities when verify action is set. | `availabilityStatus` | +| is_admin_manageds | A list of admin managed configuration. | `isAdminManaged` | +| is_defaults | A list of flags to indicate if they are default domains. | `isDefault` | +| is_initials | A list of flags to indicate if they are initial domains created by Microsoft Online Services.| `isInitial` | +| is_roots | A list of flags to indicate if they are verified root domains. | `isRoot` | +| is_verifieds | A list of flags to indicate if the domains have completed domain ownership verification.| `isVerified` | +| password_notification_window_in_days | A list of password notification window days. | `passwordNotificationWindowInDays` | +| password_validity_period_in_days | A list of password validity periods in days. | `passwordValidityPeriodInDays` | +| supported_services | A list of capabilities assigned to the domain. | `supportedServices` | +| states | A list of asynchronous operations scheduled. | `state` | * 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). From 49842bad7a4a1db5dcb246fabf32700569a9fdea Mon Sep 17 00:00:00 2001 From: Sathish Date: Thu, 29 Jul 2021 19:41:08 +0530 Subject: [PATCH 13/14] update doc Signed-off-by: Sathish --- docs/resources/azure_active_directory_domain_services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/azure_active_directory_domain_services.md b/docs/resources/azure_active_directory_domain_services.md index c5145470a..ce813faf0 100644 --- a/docs/resources/azure_active_directory_domain_services.md +++ b/docs/resources/azure_active_directory_domain_services.md @@ -101,7 +101,7 @@ The control will pass if the filter returns at least one result. Use `should_not ```ruby describe azure_active_directory_domain_services do - it { should exist } + it { should_not exist } end ``` From da91797d4cb071c6fde546713b045a37d3cd7622 Mon Sep 17 00:00:00 2001 From: Sathish Date: Fri, 30 Jul 2021 08:16:31 +0530 Subject: [PATCH 14/14] fix styling issue Signed-off-by: Sathish --- libraries/azure_active_directory_domain_services.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/azure_active_directory_domain_services.rb b/libraries/azure_active_directory_domain_services.rb index 0cb7a6d23..ef1053cd3 100644 --- a/libraries/azure_active_directory_domain_services.rb +++ b/libraries/azure_active_directory_domain_services.rb @@ -13,7 +13,7 @@ def initialize(opts = {}) raise ArgumentError, 'Parameters must be provided in an Hash object.' unless opts.is_a?(Hash) opts[:resource] = 'domains' - opts[:select] = %w[id authenticationType availabilityStatus isAdminManaged isDefault isInitial isRoot isVerified supportedServices passwordNotificationWindowInDays passwordValidityPeriodInDays state] + opts[:select] = %w{id authenticationType availabilityStatus isAdminManaged isDefault isInitial isRoot isVerified supportedServices passwordNotificationWindowInDays passwordValidityPeriodInDays state} super(opts, true) self.class.populate_filter_table(:table, @table_schema)