Leveraging Terraform for Enhanced Asset Security with Mondoo - Part 4: Custom Resources

In the previous posts of this blog series, we introduced the Mondoo platform, its Terraform provider resources, data sources, and imports, exploring how they enhance asset security and compliance. In this fourth and final part, we'll discover another exciting aspect of Terraform's interaction with Mondoo for user-customized content. Custom resources are pivotal for adapting and extending Mondoo’s capabilities to meet specific organizational needs in security and compliance frameworks.

For more detailed insights into how Mondoo operates, check out our full article here.

Introducing Mondoo's Custom Resources

Expanding on the foundation laid in our previous blogs, this part of our series focuses on the capabilities for creating custom resources within the Mondoo ecosystem: Custom Frameworks, Custom Policies, and Custom Query Packs. These tools empower users to customize their security and compliance standards tailored to their organizational needs.

Custom Frameworks

Custom Frameworks allow organizations to define a structured collection of policies in a customized framework that aligns with their internal compliance and security guidelines. This flexibility ensures that enterprises can manage and enforce their unique security postures more effectively.

To create a custom framework, we need to write a .mql.yaml file, where we define the parameters for the framework we wish to create:

1. Frameworks Section

This is the main container for the framework definitions. It includes the overall framework details, tags, authors, and grouped controls.

1frameworks:
2  - uid: example-framework
3    name: Example Framework
4    version: "1.0"
5    license: open-source
6    tags:
7      example.com/icon: example
8    authors:
9      - name: Example Author

• uid: A unique identifier for the framework.
• name: The name of the framework.
• version: The version of the framework.
• license: The type of license under which the framework is distributed.
• tags: Metadata tags for the framework, used for categorization or identification.
• authors: List of authors or organizations that created the framework.

2. Groups Section

The groups section organizes controls into logical categories. Each group has a unique identifier, title, and contains one or more controls.

1groups:
2  - uid: example-group-am
3    title: Asset Management (AM)

• uid: A unique identifier for the group.
• title: The title of the group, describing its focus or area, e.g., "Asset Management (AM)".

3. Controls Section

Each group contains one or more controls. Controls are specific requirements or actions that need to be implemented to ensure compliance with the framework.

 1controls:
 2  - uid: example-control-am-01
 3    title: Asset Inventory
 4    docs:
 5      desc: >-
 6        A short description        
 7    evidence:
 8      - uid: example-evidence-01
 9  - uid: example-control-am-02
10    title: Acceptable Use and Safe Handling of Assets Policy
11    docs:
12      desc: >-
13        A short description        
14    evidence:
15      - uid: example-evidence-02

• uid: A unique identifier for the control.
• title: The title of the control, describing what it addresses, e.g., "Asset Inventory".
• docs: Documentation related to the control, including a detailed description.
  • desc: A description of the requirements or expectations for the control.
• evidence: References to evidence or mappings that validate compliance with the control.
  • uid: Identifier for the evidence, such as a mapping to another standard or framework.

We can then reference this framework and add it to a Mondoo Space using Terraform or the UI:

 1provider "mondoo" {
 2  region = "us"
 3}
 4
 5variable "my_custom_framework" {
 6  description = "Path to the custom policy file. The file must be in MQL format."
 7  type        = string
 8  default     = "framework.mql.yaml"
 9}
10
11resource "mondoo_custom_framework" "custom_framework" {
12  space_id = "your-space-1234567"
13  data_url = var.my_custom_framework
14}

Custom Framework Resource

Custom Policies

With Custom Policies, Mondoo users can specify detailed rules and conditions that reflect their security requirements and business logic. These policies are important for enforcing security standards and compliance across all managed assets.

1. Policies Section

This section defines the set of policies that are applied to different aspects of GitHub repositories and organizations. Each policy has a unique identifier, owner, name, version, and other metadata. It organizes policies into groups, each containing various checks.

 1policies:
 2  - uid: example1
 3    name: Example policy
 4    version: "1.0.0"
 5    tags:
 6      mondoo.com/category: compliance
 7      mondoo.com/platform: github,saas
 8    authors:
 9      - name: Mondoo
10        email: hello@mondoo.com

• uid: A unique identifier for the policy.
• name: The name of the policy.
• version: The version of the policy.
• tags: Metadata tags that categorize the policy, such as compliance or specific platforms (GitHub, SaaS).
• authors: Information about the authors or organization responsible for the policy, including their name and contact email.

2. Groups Section

Policies are divided into logical groups based on their focus areas. Each group contains multiple checks and specifies conditions (filters) under which these checks are applied.

1groups:
2  - uid: example group uid
3    title: Common checks
4    filters: asset.family.contains("unix")
5    checks:
6      - uid: example check uid

• uid: A unique identifier for the group.
• title: The title of the group, describing its focus area, e.g., "Code Changes".
• filters: Conditions specifying the platform or context where the checks should apply (e.g., asset.platform == "github-repo").
• checks: List of checks (identified by unique IDs) that are part of this group.
  • uid: A unique identifier for the check.

3. Queries Section

Each check is a specific criterion or requirement that needs to be met. Checks are referenced by their unique IDs within the groups. They define what should be validated and can include a query (MQL) to perform the validation.

 1queries:
 2  - uid: example check uid
 3    title: Ensure all artifacts on all releases are signed
 4    impact: 80
 5    filters: null
 6    tags:
 7      cisecurity.org/recommendation: 2.4.1
 8    mql: |
 9      github.repository.branches.where(name == /^release/).all(isProtected == true)      
10    docs:
11      desc: |-
12        Manual
13        **Rationale:**
14        Sign all artifacts in all releases with user or organization keys...        
15      audit: For every artifact in every release, verify that all are properly signed.

• uid: Unique identifier for the check.
• title: Brief title of the check, describing what it verifies.
• impact: Numeric value indicating the significance of the check (e.g., 80).
• filters: Conditions that determine when this check applies (can be null if not used).
• tags: Tags for additional categorization or reference.
• mql: The query language used to implement the check (MQL) - specifies the criteria for the check.
• docs: Documentation for the check:
  • desc: Description and rationale behind the check.
  • audit: Instructions on how to audit compliance with the check.
  • remediation: Recommended actions if the check fails.

We can then reference this policy and add it to a Mondoo Space using Terraform or the UI:

 1provider "mondoo" {}
 2
 3variable "my_custom_policy" {
 4  description = "Path to the custom policy file. The file must be in MQL format."
 5  type        = string
 6  default     = "policy.mql.yaml"
 7}
 8
 9resource "mondoo_custom_policy" "my_policy" {
10  space_id  = mondoo_space.my_space.id
11  source    = var.my_custom_policy
12  overwrite = true
13}

Custom Policy Resource

Custom Query Packs

Custom Query Packs extend Mondoo’s capabilities by allowing users to create collections of queries that can be executed to gather information or audit systems based on specific criteria. These packs can be used to perform custom scans and assessments.

1. Policies Section

The first section is identical to the policies section of the custom policies.

 1policies:
 2  - uid: mondoo-example-queries
 3    name: Example Query Pack
 4    version: 1.2.0
 5    license: example-licence
 6    tags:
 7      mondoo.com/category: best-practices
 8    authors:
 9      - name: Mondoo, Inc
10        email: hello@mondoo.com

• uid: Unique identifier for the policy.
• name: The name of the policy.
• version: The version of the policy.
• license: The license under which the policy is distributed.
• tags: Metadata tags categorizing the policy, such as best practices.
• authors: Information about the authors or organization responsible for the policy.

2. Groups Section

Again we can observe a similar structure we could find in the custom policies file. the only difference, is that instead of checks, we have a queries section

1groups:
2  - type: 1
3    title: ESXi asset counts
4    filters: asset.platform == 'vmware-vsphere'
5    queries:
6      - uid: mondoo-asset-count-on-vsphere-cluster-esxi
7      - uid: mondoo-asset-count-on-vsphere-cluster-vms

• type: Type of the group, usually indicating the nature of the assets being counted.
• title: The title of the group, indicating the asset category, e.g., "ESXi asset counts".
• filters: Conditions specifying the platform or context where the queries apply (e.g., asset.platform == 'vmware-vsphere').
• queries: List of queries (identified by unique IDs) that are part of this group.

3. Queries Section

The queries section references each individual query by its uid and defines the corresponding mql query.

1queries:
2  - uid: mondoo-asset-count-aws-acm-certificates
3    title: AWS ACM Certificates
4    filters: null
5    mql: aws.acm.certificates.length
6  - uid: mondoo-asset-count-aws-active-regions
7    title: AWS Regions Active
8    filters: null
9    mql: aws.regions.length

• uid: Unique identifier for the query.
• title: A descriptive title for the query, e.g., "AWS ACM Certificates".
• filters: Conditions that might be applied to the query (can be null if not used).
• mql: The query language expression used to perform the counting, specifying what assets to count.

We can then reference this query pack and add it to a Mondoo Space using Terraform or the UI:

 1provider "mondoo" {
 2  region = "us"
 3}
 4
 5variable "my_custom_querypack" {
 6  description = "Path to custom querypack file. File must be in MQL format."
 7  type        = string
 8  default     = "querypack.mql.yaml"
 9}
10
11resource "mondoo_custom_querypack" "my_query_pack" {
12  space_id = mondoo_space.my_space.id
13  source   = var.my_custom_querypack
14}

Custom Query Pack Resource

Note that you can download any existing frameworks, policies and query packs within your space and customize them to your liking.

Conclusion

The introduction of custom resources in the Mondoo Terraform provider marks a significant step forward in our ability to offer tailored security solutions. These resources allow for greater flexibility and precision in defining and enforcing security standards, making Mondoo a more adaptable and powerful tool for infrastructure security management.

This concludes our blog series about our further development of the Mondoo Terraform provider. For more information about Mondoo and other thrilling topics, visit our detailed blog posts on the subject at the Infralovers' Blog. At Infralovers, we are committed to keeping you at the cutting edge of the tech landscape.