Reorganize docs content

.github/CODEOWNERS

@@ -1,4 +1,4 @@
 # Order is important. The last matching pattern has the most precedence.
 
-*             @inspec/inspec-cloud-devs
-docs/**       @inspec/inspec-cloud-devs @inspec/docs-team
+*                     @inspec/inspec-cloud-devs
+docs-chef-io/**       @inspec/inspec-cloud-devs @inspec/docs-team

docs-chef-io/content/_index.md

@@ -0,0 +1,110 @@
++++
+title = "About the Chef InSpec Azure resource pack"
+
+draft = false
+linkTitle = "Azure resource pack"
+summary = "Chef InSpec resources for auditing Azure."
+
+[cascade]
+  [cascade.params]
+    platform = "azure"
+
+[menu.azure]
+  title = "About Azure resources"
+  identifier = "inspec/resources/azure/about"
+  parent = "inspec/resources/azure"
+  weight = 10
++++
+
+Chef InSpec provides resources for auditing Azure infrastructure, including virtual machines, storage accounts, databases, and networking components. These resources help you verify that your Azure environment meets security and compliance requirements.
+
+## Initialize an InSpec profile for auditing Azure
+
+You can create a profile for testing Azure resources with `inspec init profile`:
+
+```bash
+inspec init profile --platform azure <PROFILE_NAME>
+```
+
+If your `inputs.yml` file contains your Azure project ID, you can execute this sample profile using the following command:
+
+```bash
+inspec exec <PROFILE_NAME> --input-file=<PROFILE_NAME>/inputs.yml -t azure://
+```
+
+## Set Azure credentials
+
+To use Chef InSpec Azure resources, you need to create a service principal Name (SPN) to audit an Azure subscription.
+
+You can create an SPN using the command line or from the Azure Portal:
+
+- [Azure CLI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authenticate-service-principal-cli)
+- [PowerShell](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authenticate-service-principal)
+- [Azure Portal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal)
+
+You can specify the SPN information in one of three ways:
+
+- In the `~/.azure/credentials` file
+- As environment variables
+- Using Chef InSpec target URIs
+
+### Set the Azure credentials file
+
+By default, Chef InSpec looks at `~/.azure/credentials`, and it should contain:
+
+```powershell
+[<SUBSCRIPTION_ID>]
+client_id = "<CLIENT_ID>"
+client_secret = "<CLIENT_SECRET>"
+tenant_id = "<TENANT_ID>"
+```
+
+{{< note >}}
+
+In the Azure web portal, these values have different labels:
+
+- The Azure web portal calls the `client_id` the **Application ID**
+- The Azure web portal calls the `client_secret` the **Key (Password Type)**
+- The Azure web portal calls the `tenant_id` the **Directory ID**
+
+{{< /note >}}
+
+After you set up the credentials, you can execute Chef InSpec:
+
+```bash
+inspec exec <PROFILE_NAME> -t azure://
+```
+
+### Provide credentials using environment variables
+
+As an alternative to the credentials file, you can set the Azure credentials using environment variables:
+
+- `AZURE_SUBSCRIPTION_ID`
+- `AZURE_CLIENT_ID`
+- `AZURE_CLIENT_SECRET`
+- `AZURE_TENANT_ID`
+
+For example:
+
+```bash
+AZURE_SUBSCRIPTION_ID="2fbdbb02-df2e-11e6-bf01-fe55135034f3" \
+AZURE_CLIENT_ID="58dc4f6c-df2e-11e6-bf01-fe55135034f3" \
+AZURE_CLIENT_SECRET="Jibr4iwwaaZwBb6W" \
+AZURE_TENANT_ID="6ad89b58-df2e-11e6-bf01-fe55135034f3" inspec exec my-profile -t azure://
+```
+
+### Provide credentials using Chef InSpec target option
+
+If you have several Azure subscriptions configured in your `~/.azure/credentials` file, you can use the Chef InSpec command line `--target` / `-t` option to select a specific subscription ID. For example:
+
+```bash
+inspec exec my-profile -t azure://2fbdbb02-df2e-11e6-bf01-fe55135034f3
+```
+
+## Azure resources
+
+{{< inspec_resources_filter >}}
+
+The following Chef InSpec Azure resources are available in this resource pack.
+
+{{< inspec_resources section="azure" platform="azure" >}}

docs-chef-io/content/inspec/resources/azure_active_directory_domain_service.md → docs-chef-io/content/azure_active_directory_domain_service.md

@@ -1,24 +1,20 @@
 +++
-title = "azure_active_directory_domain_service Resource"
-platform = "azure"
+title = "azure_active_directory_domain_service resource"
+
 draft = false
-gh_repo = "inspec-azure"
 
-[menu.inspec]
+
+[menu.azure]
 title = "azure_active_directory_domain_service"
-identifier = "inspec/resources/azure/azure_active_directory_domain_service Resource"
+identifier = "inspec/resources/azure/azure_active_directory_domain_service resource"
 parent = "inspec/resources/azure"
 +++
 
 Use the `azure_active_directory_domain_service` InSpec audit resource to test the properties of an Azure Active Directory service within a tenant.
 
-## Azure REST API Version, Endpoint, and HTTP Client Parameters
-
-{{< readfile file="content/inspec/resources/reusable/md/inspec_azure_common_parameters.md" >}}
-
-## Install
+## Azure REST API version, endpoint, and HTTP client parameters
 
-{{< readfile file="content/inspec/resources/reusable/md/inspec_azure_install.md" >}}
+{{< readfile file="content/reusable/md/inspec_azure_common_parameters.md" >}}
 
 ## Syntax
 
@@ -35,7 +31,7 @@ Either one of the following parameters is mandatory.
 `id`
 : Domain ID.
 
-: **Example**: `example.com`
+  For example, `example.com`
 
 ## Properties
 
@@ -77,15 +73,15 @@ Either one of the following parameters is mandatory.
 
 ## Examples
 
-### Test if an active directory domain is referenced with a valid ID
+Test if an active directory domain is referenced with a valid ID:
 
 ```ruby
 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
+Test if an active directory domain is referenced with an invalid ID:
 
 ```ruby
 describe azure_active_directory_domain_service(id: 'example.com') do
@@ -95,7 +91,7 @@ end
 
 ## Matchers
 
-{{< readfile file="content/inspec/reusable/md/inspec_matchers_link.md" >}}
+{{< readfile file="content/reusable/md/inspec_matchers_link.md" >}}
 
 This resource has the following special matchers.
 
@@ -107,6 +103,6 @@ describe azure_active_directory_domain_service(id: 'example.onmicrosoft.com') do
 end
 ```
 
-## Azure Permissions
+## 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-chef-io/content/inspec/resources/azure_active_directory_domain_services.md → docs-chef-io/content/azure_active_directory_domain_services.md

@@ -1,24 +1,20 @@
 +++
-title = "azure_active_directory_domain_services Resource"
-platform = "azure"
+title = "azure_active_directory_domain_services resource"
+
 draft = false
-gh_repo = "inspec-azure"
 
-[menu.inspec]
+
+[menu.azure]
 title = "azure_active_directory_domain_services"
-identifier = "inspec/resources/azure/azure_active_directory_domain_services Resource"
+identifier = "inspec/resources/azure/azure_active_directory_domain_services resource"
 parent = "inspec/resources/azure"
 +++
 
 Use the `azure_active_directory_domain_services` InSpec audit resource to test the properties of some or all Azure Active Directory domains within a tenant.
 
-## Azure REST API Version, Endpoint, and HTTP Client Parameters
-
-{{< readfile file="content/inspec/resources/reusable/md/inspec_azure_common_parameters.md" >}}
-
-## Install
+## Azure REST API version, endpoint, and HTTP client parameters
 
-{{< readfile file="content/inspec/resources/reusable/md/inspec_azure_install.md" >}}
+{{< readfile file="content/reusable/md/inspec_azure_common_parameters.md" >}}
 
 ## Syntax
 
@@ -37,14 +33,14 @@ The following parameters can be passed for targeting specific domains.
 `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.
 
-: **Example**: `{ starts_with_given_name: 'J', starts_with_department: 'Core', country: 'United Kingdom', given_name: John}`
+  For example, `{ 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. For more information, refer to [Microsoft's query parameters documentation](https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter).
+  Property names are in camel case. For more information, refer to [Microsoft's query parameters documentation](https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter).
 
-: **Example**: `"startswith(displayName,'J') and surname eq 'Doe'"` or `"userType eq 'Guest'"`
+  For example, `"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.
 
@@ -53,90 +49,90 @@ It is advised to use these parameters to narrow down the targeted resources at t
 `ids`
 : A list of fully qualified names of the domain.
 
-: **Field**: `id`
+  Field: `id`
 
 `authentication_types`
 : A list of the configured authentication types for the domain.
 
-: **Field**: `authenticationType`
+  Field: `authenticationType`
 
 `availability_statuses`
 : A list of domain entities when verify action is set.
 
-: **Field**: `availabilityStatus`
+  Field: `availabilityStatus`
 
 `is_admin_manageds`
 : A list of admin-managed configurations.
 
-: **Field**: `isAdminManaged`
+  Field: `isAdminManaged`
 
 `is_defaults`
 : A list of flags to indicate if they are default domains.
 
-: **Field**: `isDefault`
+  Field: `isDefault`
 
 `is_initials`
 : A list of flags to indicate if they are initial domains created by Microsoft Online Services.
 
-: **Field**: `isInitial`
+  Field: `isInitial`
 
 `is_roots`
 : A list of flags to indicate if they are verified root domains.
 
-: **Field**: `isRoot`
+  Field: `isRoot`
 
 `is_verifieds`
 : A list of flags to indicate if the domains have completed domain ownership verification.
 
-: **Field**: `isVerified`
+  Field: `isVerified`
 
 `password_notification_window_in_days`
 : A list of password notification window days.
 
-: **Field**: `passwordNotificationWindowInDays`
+  Field: `passwordNotificationWindowInDays`
 
 `password_validity_period_in_days`
 : A list of password validity periods in days.
 
-: **Field**: `passwordValidityPeriodInDays`
+  Field: `passwordValidityPeriodInDays`
 
 `supported_services`
 : A list of capabilities assigned to the domain.
 
-: **Field**: `supportedServices`
+  Field: `supportedServices`
 
 `states`
 : A list of asynchronous operations scheduled.
 
-: **Field**: `state`
+  Field: `state`
 
 {{< note >}}
 
-{{< readfile file="content/inspec/reusable/md/inspec_filter_table.md" >}}
+{{< readfile file="content/reusable/md/inspec_filter_table.md" >}}
 
 {{< /note>}}
 
 ## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-### Check domains with some filtering parameters applied at the server side using 'filter'
+Check domains with some filtering parameters applied at the 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 the server side using 'filter_free_text'
+Check domains with some filtering parameters applied at the 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
 ```
 
-### Test to ensure there are supported services using client-side filtering
+Test to ensure there are supported services using client-side filtering:
 
 ```ruby
 describe azure_active_directory_domain_services.supportedServices do
@@ -146,7 +142,7 @@ end
 
 ## Matchers
 
-{{< readfile file="content/inspec/reusable/md/inspec_matchers_link.md" >}}
+{{< readfile file="content/reusable/md/inspec_matchers_link.md" >}}
 
 This resource has the following special matchers.
 
@@ -160,6 +156,6 @@ describe azure_active_directory_domain_services do
 end
 ```
 
-## Azure Permissions
+## 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.