inspec 1.51.25 → 2.0.16

data/docs/resources/azure_virtual_machine.md.erb

@@ -0,0 +1,314 @@
+---
+title: About the azure_virtual_machine Resource
+---
+
+# azure\_virtual\_machine
+
+Use the `azure_virtual_machine` InSpec audit resource to ensure that a Virtual Machine has been provisionned correctly.
+
+## Syntax
+
+The name of the machine and the resourece group are required as properties to the resource.
+
+    describe azure_virtual_machine(group_name: 'MyResourceGroup', name: 'MyVM') do
+      its('property') { should eq 'value' }
+    end
+
+where
+
+* `MyVm` is the name of the virtual machine as seen in Azure. (It is **not** the hostname of the machine)
+* `MyResourceGroup` is the name of the resource group that the machine is in.
+* `property` is one of
+* `value` is the expected output from the matcher
+
+The options that can be passed to the resource are as follows.
+
+| Name        | Description                                                                                                         | Required | Example                           |
+|-------------|---------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------|
+| group_name: | Azure Resource Group to be tested                                                                                   | yes      | MyResourceGroup                   |
+| name:       | Name of the Azure resource to test                                                                                  | no       | MyVM                              |
+| apiversion: | API Version to use when interrogating the resource. If not set then the latest version for the resoure type is used | no       | 2017-10-9                         |
+
+These options can also be set using the environment variables:
+
+ - `AZURE_RESOURCE_GROUP_NAME`
+ - `AZURE_RESOURCE_NAME`
+ - `AZURE_RESOURCE_API_VERSION`
+
+When the options have been set as well as the environment variables, the environment variables take priority.
+
+For example:
+
+    describe azure_virtual_machine(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM') do
+      its('os_type') { should eq 'Linux' }
+      it { should have_boot_diagnostics }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+Please refer the integration tests for more in depth examples:
+
+ - [Virtual Machine External VM](../../test/integration/verify/controls/virtual_machine_external_vm.rb)
+ - [Virtual Machine Internal VM](../../test/integration/verify/controls/virtual_machine_internal_vm.rb)
+
+### Test that the machine was built from a Windows image
+
+    describe azure_virtual_machine(name: 'Windows-Internal-VM', group_name: 'Inspec-Azure') do
+      its('publisher') { should eq 'MicrosoftWindowsServer' }
+      its('offer') { should eq 'WindowsServer' }
+      its('sku') { should eq '2012-R2-Datacenter' }
+    end
+
+### Ensure the machine is in the correct location
+
+    describe azure_virtual_machine(name: 'Linux-Internal-VM', resource_group: 'Inspec-Azure') do
+      its('location') { should eq 'westeurope' }
+    end
+<br>
+
+## Properties
+
+* [`type`](#type), [`location`](#location), [`name`](#name), [`publisher`](#publisher), [`offer`](#offer), [`sku`](#sku), [`os_type`](#"os_type"), [`os_disk_name`](#os_disk_name), [`have_managed_osdisk`](#have_managed_osdisk?), [`caching`](#caching), `create_option`, `disk_size_gb`, `have_data_disks`, `data_disk_count`  , `storage_account_type`, `vm_size`, `computer_name`, `admin_username`, `have_nics`, `nic_count`, `connected_nics`, `have_password_authentication`, `password_authentication?`, `have_custom_data`, `custom_data?`, `have_ssh_keys`, `ssh_keys?`, `ssh_key_count`, `ssh_keys`, `have_boot_diagnostics`, `boot_diagnostics_storage_uri`
+
+<br>
+
+## Property Examples
+
+This InSpec audit resource has the following properties that can be tested:
+
+### type
+
+THe Azure Resource type. For a virtual machine this will always return `Microsoft.Compute/virtualMachines`
+
+### location
+
+Where the machine is located
+
+    its('location') { should eq 'westeurope' }
+
+### name
+
+Name of the Virtual Machine in Azure. Be aware that this is not the computer name or hostname, rather the name of the machine when seen in the Azure Portal.
+
+### publisher
+
+The publisher of the image from which this machine was built.
+
+This will be `nil` if the machine was created from a custom image.
+
+### offer
+
+The offer from the publisher of the build image.
+
+This will be `nil` if the machine was created from a custom image.
+
+### sku
+
+The item from the publisher that was used to create the image.
+
+This will be `nil` if the machine was created from a custom image.
+
+### os\_type
+
+Test that returns the classification in Azure of the operating system type. Ostensibly this will be either `Linux` or `Windows`.
+
+### os\_disk\_name
+
+Return the name of the operating system disk attached to the machine.
+
+### have\_managed\_osdisk
+
+Determine if the operating system disk is a Managed Disks or not.
+
+This test can be used in the following way:
+
+    it { should have_managed_osdisk }
+
+### caching
+
+Returns the type of caching that has been set on the operating system disk.
+
+### create\_option
+
+When the operating system disk is created, how it was created is set as an property. This property returns how the disk was created.
+
+### disk\_size\_gb
+
+Returns the size of the operating system disk.
+
+### have\_data\_disks
+
+Denotes if the machine has data disks attached to it or not.
+
+    it { should have_data_disks }
+
+### data\_disk\_count
+
+Return the number of data disks that are attached to the machine
+
+### storage\_account\_type
+
+This provides the storage account type for a machine that is using managed disks for the operating system disk.
+
+### vm\_size
+
+The size of the machine in Azure
+
+    its('vm_size') { should eq 'Standard_DS2_v2' }
+
+### computer\_name
+
+The name of the machine. This is what was assigned to the machine during deployment and is what _should_ be returned by the `hostname` command.
+
+### admin\_username
+
+The admin username that was assigned to the machine
+
+NOTE: Azure does not allow the use of `Administrator` as the admin username on a Windows machine
+
+## have\_nics
+
+Returns a boolean to state if the machine has NICs connected or not.
+
+This has can be used in the following way:
+
+    it { should have_nics }
+
+### nic\_count
+
+The number of network interface cards that have been attached to the machine
+
+### connected\_nics
+
+This returns an array of the NIC ids that are connected to the machine. This means that it possible to check that the machine has the correct NIC(s) attached and thus on the correct subnet.
+
+    its('connected_nics') { should include /Inspec-NIC-1/ }
+
+Note the use of the regular expression here. This is because the NIC id is a long string that contains the subscription id, resource group, machine id as well as other things. By using the regular expression the NIC can be checked withouth breaking this string up. It also means that other tests can be performed.
+
+An example of the id string is `/subscriptions/1e0b427a-d58b-494e-ae4f-ee558463ebbf/resourceGroups/Inspec-Azure/providers/Microsoft.Network/networkInterfaces/Inspec-NIC-1`
+
+### have\_password\_authentication
+
+Returns a boolean to denote if the machine is accessible using a password.
+
+    it { should have_password_authentication }
+
+### password\_authentication?
+
+Boolean to state of password authentication is enabled or not for the admin user.
+
+    its('password_authentication?') { should be false }
+
+This only applies to Linux machines and will always return `true` on Windows.
+
+### have\_custom\_data
+
+Returns a boolean stating if the machine has custom data assigned to it.
+
+    it { should have_custom_data }
+
+### custom\_data?
+
+Boolean to state if the machine has custom data or not
+
+    its('custom_data') { should be true }
+
+### have\_ssh\_keys
+
+Boolean to state if the machine has SSH keys assigned to it
+
+    it { should have_ssh_keys }
+
+For a Windows machine this will always be false.
+
+### ssh\_keys?
+
+Boolean to state of the machine is accessible using SSH keys
+
+    its('ssh_keys?') { should be true }
+
+### ssh\_key\_count
+
+Returns how many SSH keys have been applied to the machine.
+
+This only applies to Linux machines and will always return `0` on Windows.
+
+### ssh\_keys
+
+Returns an array of the keys that are assigned to the machine. This is check if the correct keys are assigned.
+
+Most SSH public keys have a signature at the end of them that can be tested. For example:
+
+    its('ssh_keys') { should include /azure@inspec.local/ }
+
+### boot\_diagnostics?
+
+Boolean test to see if boot diagnostics have been enabled on the machine
+
+    it { should have_boot_diagnostics }
+
+### boot\_diagnostics\_storage\_uri
+
+If boot diagnostics are enabled for the machine they will be saved in a storage account. This method returns the URI for the storage account.
+
+    its('boot_diagnostics_storage_uri') { should match 'ghjgjhgjg' }
+
+<br>
+
+## Matchers
+
+There are a number of built in comparison operrtors that are available to test the result with an expected value.
+
+For information on all that are available please refer to the [Inspec Matchers Reference](https://www.inspec.io/docs/reference/matchers/) page.
+
+<br>
+
+
+## Tags
+
+It is possible to test the tags that have been assigned to the resource. There are a number of properties that can be called to check that it has tags, that it has the correct number and that the correct ones are assigned.
+
+### have\_tags
+
+This is a simple test to see if the machine has tags assigned to it or not.
+
+    it { should have_tags }
+
+### tag\_count
+
+Returns the number of tags that are assigned to the resource
+
+    its ('tag_count') { should eq 2 }
+
+### tags
+
+It is possible to check if a specific tag has been set on the resource.
+
+    its('tags') { should include 'Owner' }
+
+### xxx\_tag
+
+To get the value of the tag, a number of tests have been craeted from the tags that are set.
+
+For example, if the following tag is set on a resource:
+
+| Tag Name | Value |
+|----------|-------|
+| Owner | Russell Seymour |
+
+Then a test is available called `Owner_tag`.
+
+    its('Owner_tag') { should cmp 'Russell Seymour' }
+
+Note: The tag name is case sensitive which makes the test case sensitive. E.g. `owner_tag` does not equal `Owner_tag`.
+
+
+
+## References
+
+- [Azure Ruby SDK - Resources](https://github.com/Azure/azure-sdk-for-ruby/tree/master/management/azure_mgmt_resources)

data/docs/resources/azure_virtual_machine_data_disk.md.erb

@@ -0,0 +1,182 @@
+---
+title:  About the azure_virtual_machine_datadisk Resource
+---
+
+# azure\_virtual\_machine\_datadisk
+
+Use this resource to ensure that a specific data disk attached to a machine has been created properly.
+
+## References
+
+- [Azure Ruby SDK - Compute](https://github.com/Azure/azure-sdk-for-ruby/tree/master/management/azure_mgmt_compute)
+
+## Syntax
+
+The name of the resource group and machine are required to use this resource.
+
+    describe azure_virtual_machine_data_disk(group_name: 'MyResourceGroup', name: 'MyVM') do
+      its('property') { should eq 'value' }
+    end
+
+where
+
+* `MyVm` is the name of the virtual machine as seen in Azure. (It is **not** the hostname of the machine)
+* `MyResourceGroup` is the name of the resouce group that the machine is in.
+* `property` is a resource property
+* `value` is the expected output fdrom the matcher
+
+The `count`, `have_data_disks` and `have_managed_disks` are catchall tests that give information about the virtual machine. The specific tests need to be used in conjunction with the `where` option as shown below.
+
+| Name        | Description                                                                                                         | Required | Example                           |
+|-------------|---------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------|
+| group_name: | Azure Resource Group to be tested                                                                                   | yes      | MyResourceGroup                   |
+| name:       | Name of the Azure resource to test                                                                                  | no       | MyVM                              |
+| apiversion: | API Version to use when interrogating the resource. If not set then the latest version for the resoure type is used | no       | 2017-10-9                         |
+
+These options can also be set using the environment variables:
+
+ - `AZURE_RESOURCE_GROUP_NAME`
+ - `AZURE_RESOURCE_NAME`
+ - `AZURE_RESOURCE_API_VERSION`
+
+When the options have been set as well as the environment variables, the environment variables take priority.
+
+For example:
+
+    describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM') do
+      its('count') { should cmp > 0 }
+      it { should have_data_disks }
+    end
+
+<br>
+
+## Examples
+
+The following examples show to use this InSpec audit resource.
+
+Please refer to the following integration tests for more in depth examples:
+
+ - [Linux Internal Data Disks](../../test/integration/verify/controls/virtual_machine_linux_external_vm_datadisk.rb)
+ - [Windows Internal Data Disk](../../test/integration/verify/controls/virtual_machine_windows_internal_vm_datadisk.rb)
+ 
+### Check that the first data disk is of the correct size
+
+    describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM').where(number: 1) do
+      its('size') { should cmp >= 15 }
+    end
+
+<br>
+
+## Properties
+
+* `count`, `have_data_disks`, `have_managed_disks`, `disk`, `number`, `name`, `size`, `lun`
+, `caching`, `create_option`, `is_managed_disk?`, `vhd_uri`, `storage_account_name`, `storage_account_type`, `id`, `subscription_id`, `resource_group`
+
+<br>
+
+## Property Examples
+
+### count
+
+Returns the number of data disks attached to the machine
+
+    its('count') { should eq 1 }
+
+### have\_data\_disks
+
+Returns a boolean denoting if any data disks are attached to the machine
+
+    it { should have_data_disks }
+
+### have\_managed\_disks
+
+Returns a boolean stating if the machine has Managed Disks for data disks.
+
+    it { should have_managed_disks }
+
+**The next set of attributes require the `where` operation to be used on the describe.**
+
+The following code shows an example of how to use the where clause.
+
+    describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Windows-Internal-VM').where(number: 1)
+    end
+
+### disk
+
+The zero based index of the disk attached to the machine.
+
+Typically used in the `where` clause
+
+### number
+
+The '1' based index of the disk attached to the machine.
+
+Typically used in the `where` clause as showm above.
+
+### name
+
+Returns a string of the name of the disk.
+
+### size
+
+Returns an integer of size of this disk in GB.
+
+### lun
+
+The disk number as reported by Azure. This is a zero based index value.
+
+### caching
+
+String stating the caching that has been set on the disk.
+
+### create\_option
+
+How the disk was created. Typically for data disks this will be the string value 'Empty'.
+
+### is\_managed\_disk?
+
+Boolean stating if the disk is a managed disk or not. If it is not a managed disk then it is one that is stored in a Storage Account.
+
+### vhd\_uri
+
+If this _not_ a managed disk then the `vhd_uri` will be the full URI to the disk in the storage account.
+
+### storage\_account\_name
+
+If this is _not_ a managed disk this will be the storage account name in which the disk is stored.
+
+This derived from the `vhd_uri`.  
+
+### storage\_account\_type
+
+If this is a managed disk this is the storage account type, e.g. `Standard_LRS`
+
+### id
+
+If this is a managed disk then this is the fully qualified id to the disk in Azure.
+
+### subscription\_id
+
+If this is a managed disk, this returns the subscription id of where the disk is stored.
+
+This is derived from the `id`.
+
+### resource\_group
+
+If this is a managed disk, this returns the resource group in which the disk is stored.
+
+This is derived from the `id`.
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following matchers:
+
+### eq
+
+Use the `eq` matcher to test the equality of two values: `its('Port') { should eq '22' }`.
+
+Using `its('Port') { should eq 22 }` will fail because `22` is not a string value! Use the `cmp` matcher for less restrictive value comparisons.
+
+**The following properties are ones that are applied to the virtual machine itself and not specfic disks**