From e2e9915aa4543accd3556f186d5713a381b6445e Mon Sep 17 00:00:00 2001 From: Clinton Wolfe Date: Thu, 1 Feb 2018 10:21:54 -0500 Subject: [PATCH] Skeletal aws_kms_keys resource Signed-off-by: Rony Xavier Signed-off-by: Clinton Wolfe --- docs/resources/aws_kms_keys.md | 70 ++++++++++++ libraries/_aws_connection.rb | 4 + libraries/aws_kms_keys.rb | 44 ++++++++ .../default/verify/controls/aws_kms_keys.rb | 5 + test/unit/resources/aws_kms_keys_test.rb | 103 ++++++++++++++++++ 5 files changed, 226 insertions(+) create mode 100644 docs/resources/aws_kms_keys.md create mode 100644 libraries/aws_kms_keys.rb create mode 100644 test/integration/default/verify/controls/aws_kms_keys.rb create mode 100644 test/unit/resources/aws_kms_keys_test.rb diff --git a/docs/resources/aws_kms_keys.md b/docs/resources/aws_kms_keys.md new file mode 100644 index 000000000..e7519bf95 --- /dev/null +++ b/docs/resources/aws_kms_keys.md @@ -0,0 +1,70 @@ +--- +title: About the aws_kms_keys Resource +--- + +# aws_kms_keys + +Use the `aws_kms_keys` InSpec audit resource to test properties of some or all AWS KMS Keys. + +AWS Key Management Service (KMS) is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data, and uses Hardware Security Modules (HSMs) to protect the security of your keys. AWS Key Management Service is integrated with several other AWS services to help you protect the data you store with these services. + +Each AWS KMS Key is uniquely identified by its key-id or key-arn. + +
+ +## Syntax + +An `aws_kms_keys` resource block uses an optional filter to select a group of KMS Keys and then tests that group. + + # Verify the number of KMS keys in the AWS account + describe aws_kms_keys do + its('entries.count') { should cmp 10 } + end + +
+ +## Examples + +The following examples show how to use this InSpec audit resource. + +As this is the initial release of `aws_kms_keys`, its limited functionality precludes examples. + +
+ +## Matchers + +### exists + +The control will pass if the filter returns at least one result. Use should_not if you expect zero matches. + + # Verify that at least one KMS Key exists. + describe aws_kms_keys + it { should exist } + end + +## Properties + +### key_arns + +Provides a list of key arns for all KMS Keys in the AWS account. + + describe aws_kms_keys do + its('key_arns') { should include('arn:aws:kms:us-east-1::key/key-id') } + end + +### key_ids + +Provides a list of key ids for all KMS Keys in the AWS account. + + describe aws_kms_keys do + its('key_ids') { should include('fd7e608b-f435-4186-b8b5-111111111111') } + end + +### entries + +Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations. + + # Allow at most 100 KMS Keys on the account + describe aws_kms_keys do + its('entries.count') { should be <= 100} + end diff --git a/libraries/_aws_connection.rb b/libraries/_aws_connection.rb index 06c3b30f2..f723fa5b1 100644 --- a/libraries/_aws_connection.rb +++ b/libraries/_aws_connection.rb @@ -60,4 +60,8 @@ class AWSConnection def s3_client @s3_client ||= Aws::S3::Client.new end + + def kms_client + @kms_client ||= Aws::KMS::Client.new + end end diff --git a/libraries/aws_kms_keys.rb b/libraries/aws_kms_keys.rb new file mode 100644 index 000000000..2b28925b6 --- /dev/null +++ b/libraries/aws_kms_keys.rb @@ -0,0 +1,44 @@ +class AwsKmsKeys < Inspec.resource(1) + name 'aws_kms_keys' + desc 'Verifies settings for AWS KMS Keys in bulk' + example ' + describe aws_kms_keys do + it { should exist } + end + ' + + # Underlying FilterTable implementation. + filter = FilterTable.create + filter.add_accessor(:entries) + .add(:exists?) { |x| !x.entries.empty? } + .add(:key_arns, field: :key_arn) + .add(:key_ids, field: :key_id) + filter.connect(self, :key_data) + + def key_data + @table + end + + def to_s + 'KMS Keys' + end + + def initialize + backend = AwsKmsKeys::BackendFactory.create + @table = backend.list_keys({ limit: 1000 }).to_h[:keys] # max value for limit is 1000 + end + + class BackendFactory + extend AwsBackendFactoryMixin + end + + class Backend + class AwsClientApi + BackendFactory.set_default_backend(self) + + def list_keys(query = {}) + AWSConnection.new.kms_client.list_keys(query) + end + end + end +end diff --git a/test/integration/default/verify/controls/aws_kms_keys.rb b/test/integration/default/verify/controls/aws_kms_keys.rb new file mode 100644 index 000000000..881d535ee --- /dev/null +++ b/test/integration/default/verify/controls/aws_kms_keys.rb @@ -0,0 +1,5 @@ +control "aws_kms_keys recall" do + describe aws_kms_keys do + it { should exist } + end +end diff --git a/test/unit/resources/aws_kms_keys_test.rb b/test/unit/resources/aws_kms_keys_test.rb new file mode 100644 index 000000000..9f7217d83 --- /dev/null +++ b/test/unit/resources/aws_kms_keys_test.rb @@ -0,0 +1,103 @@ +require 'helper' +require 'aws_kms_keys' + +# MAKKPB = MockAwsKmsKeysPluralBackend +# Abbreviation not used outside this file + +#=============================================================================# +# Constructor Tests +#=============================================================================# +class AwsKmsKeysConstructorTest < Minitest::Test + + def setup + AwsKmsKeys::BackendFactory.select(MAKKPB::Empty) + end + + def test_empty_params_ok + AwsKmsKeys.new + end + + def test_rejects_unrecognized_params + assert_raises(ArgumentError) { AwsKmsKeys.new(shoe_size: 9) } + end +end + + +#=============================================================================# +# Search / Recall +#=============================================================================# +class AwsKmsKeysRecallEmptyTest < Minitest::Test + + def setup + AwsKmsKeys::BackendFactory.select(MAKKPB::Empty) + end + + def test_search_miss_key_empty_kms_key_list + refute AwsKmsKeys.new.exists? + end +end + +class AwsKmsKeysRecallBasicTest < Minitest::Test + + def setup + AwsKmsKeys::BackendFactory.select(MAKKPB::Basic) + end + + def test_search_hit_via_empty_filter + assert AwsKmsKeys.new.exists? + end +end + +#=============================================================================# +# Properties +#=============================================================================# +class AwsKmsKeysProperties < Minitest::Test + def setup + AwsKmsKeys::BackendFactory.select(MAKKPB::Basic) + end + + def test_property_key_ids + basic = AwsKmsKeys.new + assert_kind_of(Array, basic.key_ids) + assert(basic.key_ids.include?('012026a4-b657-42bf-99ae-111111111111')) + refute(basic.key_ids.include?(nil)) + end + + def test_property_key_arns + basic = AwsKmsKeys.new + assert_kind_of(Array, basic.key_arns) + assert(basic.key_arns.include?('arn:aws:kms:us-east-1::key/012026a4-b657-42bf-99ae-111111111111')) + refute(basic.key_arns.include?(nil)) + end +end +#=============================================================================# +# Test Fixtures +#=============================================================================# +module MAKKPB + class Empty < AwsKmsKeys::Backend + def list_keys(query = {}) + OpenStruct.new({ keys: [] }) + end + end + + class Basic < AwsKmsKeys::Backend + def list_keys(query = {}) + fixtures = [ + OpenStruct.new({ + key_id: '012026a4-b657-42bf-99ae-111111111111', + key_arn: 'arn:aws:kms:us-east-1::key/012026a4-b657-42bf-99ae-111111111111', + }), + OpenStruct.new({ + key_id: '012026a4-b657-42bf-99ae-222222222222', + key_arn: 'arn:aws:kms:us-east-1::key/012026a4-b657-42bf-99ae-222222222222', + }), + OpenStruct.new({ + key_id: '012026a4-b657-42bf-99ae-333333333333', + key_arn: 'arn:aws:kms:us-east-1::key/012026a4-b657-42bf-99ae-333333333333', + }), + ] + + OpenStruct.new({ keys: fixtures }) + end + end +end