k9 Architecture

How k9 Works


This document describes how k9 assesses AWS accounts and delivers reports to you.


Logical Architecture

This figure illustrates the logical architecture of the system:

The major components within the system are:

Customer-managed components:  Customers have one to many AWS accounts that k9 will monitor and assess.  Customers also provide a KMS encryption key and S3 bucket where assessment reports will be delivered to as part of a Secure Inbox implementation.  These resources are often hosted by the customer’s ‘Security’ account.

k9-managed components: k9 operates the IAM access assessment and report delivery processes from a dedicated AWS account.

AWS-managed components: k9 uses the AWS Identity Access Management (IAM), encryption Key Management Service (KMS), and Simple Storage Service (S3) to deliver the service. 

How it Works

The k9 access inventory generation process queries customer IAM entity and policy data from the AWS IAM service using customer-provided access (AWS trust policy). The inventory process will enumerate IAM entities and assess access to resource types supported by k9.  The assessment process uses the IAM policy simulation API to ask AWS who has access to what, which is really the only way to be sure about such things.  This description glosses over a lot of detail, particularly that this assessment process requires deep knowledge of the AWS security model, careful data modeling, and usually requires a large number of queries to the IAM service, even when highly optimized (don’t worry: AWS IAM API usage is free).

The inventory generation process will run at least once per 24 hour period in which there are changes to IAM or resources. The inventory process generates a report that is encrypted with the customer’s KMS encryption key and stored in an internal k9-managed S3 bucket.  This report is then published to customer or partner-managed analysis and audit systems.  The first supported delivery endpoint is a customer-managed Secure Inbox implemented using an S3 bucket and KMS.

Making the AWS Access Model Comprehensible

AWS offers more than 150 services that have more than 3000 distinct API actions. Reporting the full set of API actions a principal can take on a resource is unlikely to be useful to Security, Compliance, and Application teams. The burden of understanding and summarizing what that access means would fall to them and the report would likely drown them in data. This is especially true for interactions between capabilities that might, e.g. allow a principal to escalate privileges and change a security policy.

Visit k9 Access Capability Model to learn about our motivations for developing our own access model.

k9 summarizes each IAM user or role’s provisioned access to AWS resources into a small number of access capabilities:

  • administer-resource – one or more AWS api actions results in the capability to administer an AWS resource with create, modify, or destroy a given resource or the security controls for that resource (e.g. modify bucket policies)
  • use-resource – a generic capability indicating that the principal has the ability to use a resource, but the resource manages its access control internally, e.g. rds-db:connect
  • read-data – capability indicating the principal has the ability to read data from the resource, e.g. read objects from an S3 bucket or DynamoDB table
  • write-data – capability indicating the principal has the ability to write data in the resource, e.g. put objects into an S3 bucket or DynamoDB table
  • delete-data – capability indicating the principal has the ability to delete data from the resource, e.g. delete objects in an S3 bucket or items from a DynamoDB table
  • unclassified-access – the principal’s level of access to the resource has not been classified by k9 yet (unhandled, unknown)

Certain actions may classify to multiple capabilities.  For example, the rds:DeleteDBCluster action classifies to both delete-data and administer-resource because deleting the DB cluster:

  1. destroys the cluster’s data volume and automated backups, rendering all cluster data unrecoverable
  2. terminates the database cluster instances and endpoints, which are otherwise replaceable

Here are an excerpt from the S3 mappings to give you a broader sense of how the mapping of AWS API actions to k9 capabilities works:

API Action(s)
read-data S3 s3:ListBucket, s3:GetObject, s3:GetObjectAcl, s3:GetObjectLegalHold, s3:GetObjectRetention, s3:GetObjectTagging, s3:GetObjectTorrent, s3:GetObjectVersion, s3:GetObjectVersionAcl, s3:GetObjectVersionTagging, s3:GetObjectVersionTorrent, s3:ListMultipartUploadParts
write-data S3 s3:AbortMultipartUpload, s3:PutObject, s3:PutObjectTagging, s3:PutObjectVersionAcl, s3:PutObjectVersionTagging, s3:RestoreObject
delete-data S3 s3:DeleteObject, s3:DeleteObjectVersion

The k9 access inventory report clearly identifies which AWS IAM principals have access to what AWS services and resources in terms of these k9 access capabilities.  For example, here is an excerpt for the continuous integration (ci) user in a sandbox account (full sample – xlsx):

Notice how the ci user has full access to the KMS, RDS, RDS Data, RDS DB, and S3 service APIs as well as full access to a number of specific S3 buckets.  This user is definitely one where engineers would want to review its access.  In particular, it may not make sense for a continuous integration user to be able to delete-data, even though it may need broad privileges to administer resources.

Contact Us

Please contact us and we’ll be happy to answer any questions you may have.