Documentation for existing resources

* Update docs in source to use matcher-style calls, not properties-as-predicates

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

* Main doc file for aws_iam_user

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

* Add documentation for existing resources

This adds documentation for the following resources, including custom matchers:

  - aws_ec2_instance
  - aws_iam_access_key
  - aws_iam_password_policy
  - aws_iam_root_user
  - aws_iam_users

Signed-off-by: Jerry Aldrich <jerryaldrichiii@gmail.com>

* Fix `aws_iam_users` example (Console + No MFA) (#104)

Signed-off-by: Jerry Aldrich <jerryaldrichiii@gmail.com>

* Correct copypasta

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

* Remove misleading singular matcher information from the plural docs for aws_iam_users

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

* Correct `aws-iam-userss` typo (#105)

Signed-off-by: Jerry Aldrich <jerryaldrichiii@gmail.com>

* Add EC2 instance state info

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

* test commit

Signed-off-by: kgarmoe <kgarmoe@chef.io>

* copy edits

Signed-off-by: kgarmoe <kgarmoe@chef.io>

* Yikes, forgot to save after correcting a merge conflict

Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>

docs/resources/aws_ec2_instance.md

@@ -0,0 +1,99 @@
+---
+title: About the aws_ec2_instance Resource
+---
+
+# aws_ec2_instance
+
+Use the `aws_ec2_instance` InSpec audit resource to test properties of a single AWS EC2 instance.
+
+<br>
+
+## Syntax
+
+An `aws_ec2_instance` resource block declares the tests for a single AWS EC2 instance by either name or id.
+
+    describe aws_ec2_instance('i-01a2349e94458a507') do
+      it { should exist }
+    end
+
+    describe aws_ec2_instance(name: 'my-instance') do
+      it { should be_running }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that an EC2 instance does not exist
+
+    describe aws_ec2_instance(name: 'dev-server') do
+      it { should_not exist }
+    end
+
+### Test that an EC2 instance is running
+
+    describe aws_ec2_instance(name: 'prod-database') do
+      it { should be_running }
+    end
+
+### Test that an EC2 instance is using the correct image ID
+
+    describe aws_iam_instance(name: 'my-instance') do
+      its('image_id') { should eq 'ami-27a58d5c' }
+    end
+
+### Test that an EC2 instance has the correct tag
+
+    describe aws_ec2_instance('i-090c29e4f4c165b74') do
+      its('tags') { should include(key: 'Contact', value: 'Gilfoyle') }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### be_pending
+
+The `be_pending` matcher tests if the described EC2 instance state is `pending`. This indicates that an instance is provisioning. This state should be temporary.
+
+    it { should be_pending }
+
+### be_running
+
+The `be_running` matcher tests if the described EC2 instance state is `running`. This indicates the instance is fully operational from AWS's perspective.
+
+    it { should be_running }
+
+### be_shutting_down
+
+The `be_shutting_down` matcher tests if the described EC2 instance state is `shutting-down`. This indicates the instance has received a termination command and is in the process of being permanently halted and de-provisioned. This state should be temporary.
+
+    it { should be_shutting_down }
+
+### be_stopped
+
+The `be_stopped` matcher tests if the described EC2 instance state is `stopped`. This indicates that the instance is suspended and may be started again.
+
+    it { should be_stopped }
+
+### be_stopping
+
+The `be_stopping` matcher tests if the described EC2 instance state is `stopping`. This indicates that an AWS stop command has been issued, which will suspend the instance in an OS-unaware manner.  This state should be temporary.
+
+    it { should be_stopping }
+
+### be_terminated
+
+The `be_terminated` matcher tests if the described EC2 instance state is `terminated`.  This indicates the instance is permanently halted and will be removed from the instance listing in a short period. This state should be temporary.
+
+    it { should be_terminated }
+
+### be_unknown
+
+The `be_unknown` matcher tests if the described EC2 instance state is `unknown`. This indicates an error condition in the AWS management system. This state should be temporary.
+
+    it { should be_unknown }

docs/resources/aws_iam_access_key.md

@@ -0,0 +1,56 @@
+---
+title: About the aws_iam_access_key Resource
+---
+
+# aws_iam_access_key
+
+Use the `aws_iam_access_key` InSpec audit resource to test properties of a single AWS IAM access key.
+
+<br>
+
+## Syntax
+
+An `aws_iam_access_key` resource block declares the tests for a single AWS IAM access key by username and id.
+
+    describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
+      it { should exist }
+      it { should_not be_active }
+      its('create_date') { should be > Time.now - 365 * 86400 }
+      its('last_used_date') { should be > Time.now - 90 * 86400 }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that an IAM access key is not active
+
+    describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
+      it { should_not be_active }
+    end
+
+### Test that an IAM access key is older than one year
+
+    describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
+      its('create_date') { should be > Time.now - 365 * 86400 }
+    end
+
+### Test that an IAM access key has been used in the past 90 days
+
+    describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
+      its('last_used_date') { should be > Time.now - 90 * 86400 }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### be_active
+
+The `be_active` matcher tests if the described IAM access key is active.
+
+  it { should be_active }

docs/resources/aws_iam_password_policy.md

@@ -0,0 +1,69 @@
+---
+title: About the aws_iam_password_policy Resource
+---
+
+# aws_iam_password_policy
+
+Use the `aws_iam_password_policy` InSpec audit resource to test properties of the AWS IAM Password Policy.
+
+<br>
+
+## Syntax
+
+An `aws_iam_password_policy` resource block takes no parameters, but uses several matchers.
+
+    describe aws_iam_password_policy do
+      its('requires_lowercase_characters?') { should be true }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that the IAM Password Policy requires lowercase characters, uppercase characters, numbers, symbols, and a minimum length greater than eight
+
+    describe aws_iam_password_policy do
+      its('requires_lowercase_characters?') { should be true }
+      its('requires_uppercase_characters?') { should be true }
+      its('requires_numbers?') { should be true }
+      its('requires_symbols?') { should be true }
+      its('minimum_password_length') { should be > 8 }
+    end
+
+### Test that the IAM Password Policy allows users to change their password
+
+    describe aws_iam_password_policy do
+      its('allows_user_to_change_password?') { should be true }
+    end
+
+### Test that the IAM Password Policy expires passwords
+
+    describe aws_iam_password_policy do
+      its('expires_passwords?') { should be true }
+    end
+
+### Test that the IAM Password Policy has a max password age
+
+    describe aws_iam_password_policy do
+      its('max_password_age') { should be > 90 * 86400 }
+    end
+
+### Test that the IAM Password Policy prevents password reuse
+
+    describe aws_iam_password_policy do
+      its('prevents_password_reuse?') { should be true }
+    end
+
+### Test that the IAM Password Policy requires users to remember 3 previous passwords
+
+    describe aws_iam_password_policy do
+      its('number_of_passwords_to_remember') { should eq 3 }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).

docs/resources/aws_iam_root_user.md

@@ -0,0 +1,51 @@
+---
+title: About the aws_iam_root_user Resource
+---
+
+# aws_iam_root_user
+
+Use the `aws_iam_root_user` InSpec audit resource to test properties of the root user (owner of the account).
+
+To test properties of all or multiple users, use the `aws_iam_users` resource.
+
+To test properties of a specific AWS user use the `aws_iam_user` resource.
+
+<br>
+
+## Syntax
+
+An `aws_iam_root_user` resource block requires no parameters but has several matchers
+
+    describe aws_iam_root_user do
+      its { should have_mfa_enabled }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that the AWS root account has only one access key
+
+    describe aws_iam_root_user do
+      its('access_key_count') { should eq 1 }
+    end
+
+### Test that the AWS root account has Multi-Factor Authentication enabled
+
+    describe aws_iam_root_user do
+      it { should have_mfa_enabled }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### have_mfa_enabled
+
+The `have_mfa_enabled` matcher tests if the AWS root user has Multi-Factor Authentication enabled, requiring them to enter a secondary code when they login to the web console.
+
+    it { should have_mfa_enabled }

docs/resources/aws_iam_user.md

@@ -0,0 +1,63 @@
+---
+title: About the aws_iam_user Resource
+---
+
+# aws_iam_user
+
+Use the `aws_iam_user` InSpec audit resource to test properties of a single AWS IAM user.
+
+To test properties of all or multiple users, use the `aws_iam_users` resource.
+
+To test properties of the special AWS root user (which owns the account), use the `aws_iam_root_user` resource.
+
+<br>
+
+## Syntax
+
+An `aws_iam_user` resource block declares a user by name, and then lists tests to be performed.
+
+    describe aws_iam_user(name: 'test_user') do
+      it { should exist }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that a user does not exist
+
+    describe aws_iam_user(name: 'gone') do
+      it { should_not exist }
+    end
+
+### Test that a user has multi-factor authentication enabled
+
+    describe aws_iam_user(name: 'test_user') do
+      it { should have_mfa_enabled }
+    end
+
+### Test that a service user does not have a password
+
+    describe aws_iam_user(name: 'test_user') do
+      it { should have_console_password }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### have_console_password
+
+The `have_console_password` matcher tests if the user has a password that could be used to log into the AWS web console.
+
+    it { should have_console_password }
+
+### have_mfa_enabled
+
+The `have_mfa_enabled` matcher tests if the user has Multi-Factor Authentication enabled, requiring them to enter a secondary code when they login to the web console.
+
+    it { should have_mfa_enabled }

docs/resources/aws_iam_users.md

@@ -0,0 +1,55 @@
+---
+title: About the aws_iam_users Resource
+---
+
+# aws_iam_users
+
+Use the `aws_iam_users` InSpec audit resource to test properties of a all or multiple users.
+
+To test properties of a single user, use the `aws_iam_user` resource.
+
+To test properties of the special AWS root user (which owns the account), use the `aws_iam_root_user` resource.
+
+<br>
+
+## Syntax
+
+An `aws_iam_users` resource block users a filter to select a group of users and then tests that group
+
+    describe aws_iam_users.where(has_mfa_enabled?: false) do
+      it { should_not exist }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test that all users have Multi-Factor Authentication enabled
+
+    describe aws_iam_users.where(has_mfa_enabled?: false) do
+      it { should_not exist }
+    end
+
+### Test that at least one user has a console password to log into the AWS web console
+
+    describe aws_iam_users.where(has_console_password?: true) do
+      it { should exist }
+    end
+
+### Test that all users that have a console password have Multi-Factor Authentication enabled
+
+    console_users_without_mfa = aws_iam_users
+                                .where(has_console_password?: true)
+                                .where(has_mfa_enabled?: false)
+
+    describe console_users_without_mfa do
+      it { should_not exist }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has no specific matchers.  

libraries/aws_iam_user.rb

@@ -7,9 +7,9 @@ class AwsIamUser < Inspec.resource(1)
   name 'aws_iam_user'
   desc 'Verifies settings for AWS IAM user'
   example "
-    describe aws_iam_user(name: 'test_user_name') do
+    describe aws_iam_user(name: 'test_user') do
       it { should have_mfa_enabled }
-      it { should have_console_password }
+      it { should_not have_console_password }
     end
   "
   def initialize(