CloudSpec | An Open Source Tool For Validating Your Resources In Your Cloud Providers Using A Logical Language


CloudSpec is an open source tool for validating your resources in your cloud providers using a logical language that everybody can understand. With its reasonably simple syntax, you can validate the configuration of your cloud resources, avoiding mistakes that can lead to availability or confidentiality issues.


With CloudSpec you validate resources in your cloud provider. A resource can be anything, from an EC2 Instance to an SES rule. Anything that a CloudSpec provider implements.

Resources have properties and associations. Properties define the shape, or configuration, of the resource, while associations define its relationships with other resources. With CloudSpec, you not only can validate the configuration of the resource, but also the configuration of its associated resources. For example, let’s take an EC2 Instance. It has properties defining its shape, like its unique instance ID, its name, its type, and the such. But it also has associations like the subnet it belongs to, the EBS volumes attached to it, the AMI it uses, and the such. You not only can validate whether an EC2 Instance is of a particular instance type, or has the delete termination flag enabled, but also the size of its attached volumes, the CIDR block of its subnet, or any other property in its associated resources, or associated resources to its associated resources, and so on. You follow me.

Your cloud resources are entangled together, creating a graph. A graph that you can traverse and validate as you see fit according to your best practices or compliance policies. That ability, plus its logical language, is the beauty of CloudSpec.

set aws:regions = ["us-east-1", "eu-west-1"]

use "./my_module" as my_module

rule "Buckets must have access logs enabled"
    on aws:s3:bucket
    assert access_logs is enabled
end rule

rule "Instances must use 'gp2' volumes and be at least 50GiBs large."
    on aws:ec2:instance
    with tags["environment"] equal to "production"
    assert devices (
        > volume (
            type equal to "gp2" and
            size gte 50

You can find the full syntax in the CloudSpec Reference documentation.


CloudSpec itself does not support any resource. The core of CloudSpec is the syntax interpreter for the specification files and its validation engine. However, CloudSpec does use providers, which are extensions to CloudSpec supporting each different type of resource.

A provider defines the shape of each resource type, properties and associations, and the logic to load those resources.

You can find the available providers and resources they provide in the CloudSpec Reference documentation.

Running CloudSpec docker image

You can either build and run the CloudSpec jar yourself, or you can run the latest docker image straight from the Docker Hub registry.

To use the Docker image, you first need to put your spec files (e.g. specs/my_module) in a directory to mount it in the Docker container. Otherwise, the CloudSpec will not be able to open the spec files outside the container.

export AWS_ACCESS_KEY_ID=***
export AWS_REGION=eu-west-1
docker run -v "/my_module:/my_module" -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION efoncubierta/cloudspec run -d my_module

If you are running the docker container in AWS with a dedicated IAM role attached, you can omit the AWS environment variables.

For more options of the CloudSpec command, see help:

docker run efoncubierta/cloudspec -h

Build CloudSpec

If you want to build CloudSpec yourself, follow these instructions.


  • Git
  • Maven 3
  • OpenJDK 8
  • Docker

Pull the source code and build CloudSpec:

# Clone git repo
git clone
cd cloudspec
# Build CloudSpec
mvn clean install
# Run CloudSpec
java -jar runner/target/cloudspec-${VERSION}.jar -h


For the time being, this is a pet project and, therefore, only some resources in AWS are supported, but I am open to collaborations. Feel free to fork this project and send pull requests.