diff --git a/docs/intro.md b/docs/intro.md index df2a063e6..9cc1c975b 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -18,6 +18,8 @@ The Mondoo unified security platform finds and prioritizes vulnerabilities and m - [What Is Mondoo?](/platform/start/plat-what-is/) +- [Plan your Mondoo Organization](/platform/start/organize/overview/) + #### [Integrate Your Infrastructure with Mondoo](/platform/infra/overview/) - [Cloud](/platform/infra/cloud/overview/) diff --git a/docs/platform/start/organize/overview.md b/docs/platform/start/organize/overview.md index e7c4c0ab2..5195320d9 100644 --- a/docs/platform/start/organize/overview.md +++ b/docs/platform/start/organize/overview.md @@ -6,26 +6,52 @@ descriptions: Create a manageable structure for monitoring and securing your inf image: /img/featured_img/mondoo-feature.jpg --- -You can rely on Mondoo to secure an enormous quantity of assets in your infrastructure -- cloud platforms, workstations, servers, containers, SaaS platforms, and much more. For larger businesses, Mondoo provides asset intelligence, security, and compliance for thousands of assets. To make securing and monitoring your infrastructure manageable, you can arrange your Mondoo assets in regions, organizations, and spaces. It's best to plan your infrastructure structure before you begin integrating your infrastructure with Mondoo. +You can rely on Mondoo to secure an enormous quantity of assets in your infrastructure—cloud platforms, workstations, servers, containers, SaaS platforms, and much more. For larger businesses, Mondoo provides asset intelligence, security, and compliance for thousands of assets. To make securing and monitoring your infrastructure manageable, you can arrange your Mondoo assets in regions, organizations, spaces, and workspaces. It's best to plan your infrastructure organization before you begin adding assets to Mondoo. -:::note +![Region, organization, space, and workspace in Mondoo](/img/platform/start/organize-basics.png) -Privately hosted Enterprise accounts run in a single region. +- [Regions](/platform/start/organize/regions) let you follow localized data protection requirements such as GDPR. Mondoo currently supports two regions: US and EU. Privately hosted Mondoo Enterprise accounts run in a single region. -::: +- [Organizations](/platform/start/organize/organizations) provide a way to separate different major parts of your business and manage team members' access. Most Mondoo customers have only one organization. However, if you have business divisions that operate quite differently and have separate dedicated teams, you might consider creating multiple organizations. -This is an example of an infrastructure organization: +- [Spaces](/platform/start/organize/spaces) are structured collections of assets, policies, compliance frameworks, security models, ticket system integrations, and reports that you manage together. You can also manage team member access by space. Most Mondoo customers have multiple spaces. -![Organize even the largest infrastructure with Mondoo](/img/platform/start/org-simple.png) +- [Workspaces](/platform/start/organize/workspaces) are ad hoc groups of assets you want to view together. You might have a workspace for a project, for monitoring a certain problem across your infrastructure, or for a type of asset. -- [Regions](/platform/start/organize/regions) allow you to follow localized policy requirements (such as GDPR). +Regions, organizations, and spaces form the structure of your assets in Mondoo. An organization can be in only one region. A space can be in only one organization. An asset can be in only one space. -- [Organizations](/platform/start/organize/organizations) provide a way to separate and organize different parts of your business and manage team members' access. +Workspaces are not structural; an asset can be in multiple workspaces. -- [Spaces](/platform/start/organize/spaces) are collections of assets, policies, and reports that you manage together. +## Examples of organizations -You can organize your infrastructure in as complex or simple a structure as you need. All security, compliance, and asset intelligence reports, data exports, and Ticket system exports are organized in the structure you create. +Imagine a US-based company called Lunalectric that makes rovers and rockets for space exploration. Lunalectric's business structure is divided by product type. There's a division focused on rovers and another focused on rockets. There's also a Commerce division containing finance, marketing, human resources, and so on. The company has a single operations team and a single security team. -![Organize a small infrastructure with Mondoo](/img/platform/start/org-complex.png) +Here's one way Lunalectric might organize their assets in Mondoo: + +![Sample organizational structure in Mondoo](/img/platform/start/luna-org-1.png) + +In this example, Lunalectric creates a single organization that contains a different space for each type of asset they monitor with Mondoo. Their AWS assets go in the Cloud space, all employee laptops are in the Workstations space, and so on. Each space contains many different workspaces for the different views and perspective they need to assess. + +Here's an alternative way Lunalectric might organize their assets: + +![Sample organizational structure in Mondoo](/img/platform/start/luna-org-2.png) + +In this second example, Lunalectric creates a single organization that contains three spaces: one space for each business division. Each space contains a very large number of assets. + +The Lunalectric team relies on many different workspaces, some examples of which are shown in the diagram above, to view subsets of assets in the different spaces. For example: + +- Each space has an "urgent" workspace that shows all the assets in the space that have serious security issues requiring immediate attention. + +- The Rocket space has a workspace that shows only assets used on federal projects. + +- The Rover space has a workspaces dedicated to cloud assets. + +- One Rocket team member, Stella, made a workspace that lets her focus on her current projects. + +- The Commerce space includes a workspace specifically for assessing the security of lunalectric web properties. + +## The best structure for you + +There's no _right_ way to organize your assets in Mondoo. Take some time to understand what you need to learn from Mondoo and outline a couple of different organizational ideas. --- diff --git a/docs/platform/start/organize/workspaces.md b/docs/platform/start/organize/workspaces.md new file mode 100644 index 000000000..6295d7402 --- /dev/null +++ b/docs/platform/start/organize/workspaces.md @@ -0,0 +1,158 @@ +--- +title: Workspaces +sidebar_label: Workspaces +sidebar_position: 5 +description: This page provides detailed information about workspaces in Mondoo Platform, and how you can use them. +image: /img/featured_img/mondoo-feature.jpg +--- + +FOO BAR BAZ start with a screenshot + +Workspaces are ad hoc groups of assets you want to view together. You might have a workspace for a project, another for monitoring urgent problems across your infrastructure, and another for a type of asset. + +Think of workspaces more as views rather than as structural divisions of your Mondoo organization. A single asset can be included in multiple workspaces. + +For example, suppose your infrastructure includes an employee's macOS workstation, which has a *critical* risk rating. The workstation is in a single [space](/platform/start/organize/spaces), which is in a single [organization](/platform/start/organize/organizations). But it can appear in both a macOS devices workspace and a workspace that shows all critical assets. + +A space can contain an unlimited number of workspaces, and their purpose is entirely up to you. Their flexibility lets them meet your unique business needs. + +## Example workspaces + +Suppose our imaginary sample business, Lunalectric, has a space is dedicated to the Rover business group, a division within the company. + +![Sample workspaces in Rover space](/img/platform/start/mars-rover-space.png) + +This space contains many different types of assets, including the Rover team's Azure and SaaS infrastructure, deployment pipelines, and employee workstations. They use workspaces to accomplish these goals: + +- View smaller, more manageable portions of their infrastructure + +- Easily assess the security of their different types of infrastructure + +- Highlight the assets that require urgent fixes + +- Show Linux assets that require patching + +As another example, suppose Lunalectric has a space that contains all of the company's AWS cloud infrastructure. With hundreds of AWS assets, they need easy ways to break down that space and understand where their security strengths and weaknesses lie. + +![Sample workspaces in AWS space](/img/platform/start/lunalectric-aws-space.png) + +To accomplish this, they create a workspace for each type of AWS asset as well as an "All AWS urgent" workspace where they can quickly view the AWS assets that pose the greatest risk to Lunalectric. + +## Set up workspaces + +You set up a workspace by defining qualifying conditions, attributes that assets must (or must not) have to be included. Mondoo dynamically creates the workspace each time you view it by including assets in the space that currently meet your criteria. + +Mondoo currently supports these conditions for including assets in, or excluding assets from, a workspace: + +| Condition | Example values | +|------------------|----------------------------------------------------------------------------------------------------------------------| +| Platform | Alpine Linux, Atlassian Jira, AWS S3 bucket, GitHub repository, Kubernetes pod, macOS, Slack team, Terraform plan ... | +| Platform version | 3, 4.5, 12.75 ... | +| Risk rating | Critical, High, Medium, Low, None | +| Asset name | test, 2024, win, us-east-1, docker- ... | + +:::note + +We continue to add new conditions for workspaces. Check back soon for more! + +::: + +### Example conditions + +You can define very simple workspaces like these with one condition: + +- Is a GCP compute image + +- Risk rating is not Low or None + +- Name contains `eu-central` + +- Is a GitHub repository or a GitLab project + +You can also combine conditions. These are examples of simple queries with multiple conditions: + +- Is a Debian device and version is not 12 + +- Name contains `dod` and risk rating is Critical or High + +- Is a macOS device and version is 15.1.0 and name contains `home` + +Mondoo workspaces support complex queries as well. For example, this query defines a workspace for viewing all older versions of three popular Linux distributions: + + (Is a Debian device and version is not 12) + and + (Is a Fedora device and version is not 40 or 41) + and + (Is a Red Hat (RHEL) device and is not version 9.5) + +### Workspaces are dynamic + +When you create a workspace, what you save is the name, description, and the criteria you define. You don't save the actual assets included in the workspace. Mondoo rebuilds a workspace every time you view it. + +For example, suppose you set up a workspace named Urgent AlmaLinux. The criteria you define for the workspace is AlmaLinux devices with Critical or High risk ratings. + +When you first view the Urgent AlmaLinux workspace, it contains 25 assets—all older versions of AlmaLinux that have other risk factors. If you patch 12 of those assets and remove additional risk factors from two others, the next time you view the workspace, it will contain only 11 assets. + +If AlmaLinux releases an advisory about a vulnerability in the newest version, this could mean that even your AlmaLinux devices running the newest version now have Critical or High risk ratings. So the next time you view the workspace, it might contain 40 assets. + +### Workspace query builder + +Use the workspace query builder to choose criteria that define what assets Mondoo includes. + +For each condition in an asset selection, you select a criterion, an operator (IS, NOT, or CONTAINS), and one or more values. If you choose multiple values for a single criterion, the query builder combines them with an OR operator. For example, this query specifies that the asset platform must be either Confluence or Jira: + +![Mondoo workspace query builder multiple values for one criterion](/img/platform/start/qb-two-values.png) + +If you define more than one condition in an asset selection (using the + ADD CONDITION button), you choose whether to combine them with an AND or AND NOT operator. For example, this query specifies that the asset platform must be Debian AND the platform version must not be 12: + +![Mondoo workspace query builder multiple values for one criterion](/img/platform/start/qb-two-conditions.png) + +This query specifies that the asset platform must be Azure storage container and the asset name must not contain `eu`: + +![Mondoo workspace query builder multiple values for one criterion](/img/platform/start/qb-two-conditions-not.png) + +If you define more than one asset selection in a query (using the + ADD ASSET SELECTION button), the query builder combines them with an OR operator. For example, in this query, asset selection 1 specifies that the platform is Debian and the version is not 12. Asset selection 2 specifies that the platform is Fedora and the version is not 40 or 41. For Mondoo to include an asset in this workspace, the asset must meet either the asset selection 1 requirement OR the asset selection 2 requirement: + +![Mondoo workspace query builder](/img/platform/start/qb-two-selections.png) + +### Add a new workspace + +1. [Navigate to the space](/platform/start/navigate/) where you want to add a new workspace. + +2. In the side navigation bar, select **Workspaces**. + +3. Select the plus sign (+) near the top-right corner of the page. + +4. Create a query to define the assets you want Mondoo to dynamically include in the workspace: + + a. Under **Asset selection 1**, select the plus sign (+) and select the the criteria to define. + + b. Choose the operator: **IS**, **NOT**, or **CONTAINS**. + + c. Choose the value(s). + + d. To add another condition for the query, select **+ ADD CONDITION**. + + e. Choose how to combine the conditions: + + - To include assets only if they meet both conditions, select **AND**. + + - To include assets that meet at least one condition, select **OR**. + + f. Choose the criteria, operator, and value for the condition. + + g. Repeat steps d-f to define as many conditions as you want. + +5. To create a complex query with another set of criteria, select + +NOT FINISHED FOO BAR BAZ + +## View workspaces + +## Manage workspaces + +### Edit a workspace + +### Remove a workspace + +--- diff --git a/static/img/platform/start/luna-org-1.png b/static/img/platform/start/luna-org-1.png new file mode 100644 index 000000000..81904c6b6 Binary files /dev/null and b/static/img/platform/start/luna-org-1.png differ diff --git a/static/img/platform/start/luna-org-2.png b/static/img/platform/start/luna-org-2.png new file mode 100644 index 000000000..c2e006a55 Binary files /dev/null and b/static/img/platform/start/luna-org-2.png differ diff --git a/static/img/platform/start/lunalectric-aws-space.png b/static/img/platform/start/lunalectric-aws-space.png new file mode 100644 index 000000000..a6867abaf Binary files /dev/null and b/static/img/platform/start/lunalectric-aws-space.png differ diff --git a/static/img/platform/start/mars-rover-space.png b/static/img/platform/start/mars-rover-space.png new file mode 100644 index 000000000..c0064f6d6 Binary files /dev/null and b/static/img/platform/start/mars-rover-space.png differ diff --git a/static/img/platform/start/org-complex.png b/static/img/platform/start/org-complex.png deleted file mode 100644 index cccd6d0de..000000000 Binary files a/static/img/platform/start/org-complex.png and /dev/null differ diff --git a/static/img/platform/start/org-simple.png b/static/img/platform/start/org-simple.png deleted file mode 100644 index dddc4a7aa..000000000 Binary files a/static/img/platform/start/org-simple.png and /dev/null differ diff --git a/static/img/platform/start/organize-basics.png b/static/img/platform/start/organize-basics.png new file mode 100644 index 000000000..301bcac40 Binary files /dev/null and b/static/img/platform/start/organize-basics.png differ diff --git a/static/img/platform/start/qb-two-conditions-not.png b/static/img/platform/start/qb-two-conditions-not.png new file mode 100644 index 000000000..921a9588b Binary files /dev/null and b/static/img/platform/start/qb-two-conditions-not.png differ diff --git a/static/img/platform/start/qb-two-conditions.png b/static/img/platform/start/qb-two-conditions.png new file mode 100644 index 000000000..23e6e88c7 Binary files /dev/null and b/static/img/platform/start/qb-two-conditions.png differ diff --git a/static/img/platform/start/qb-two-selections.png b/static/img/platform/start/qb-two-selections.png new file mode 100644 index 000000000..f3ccd62eb Binary files /dev/null and b/static/img/platform/start/qb-two-selections.png differ diff --git a/static/img/platform/start/qb-two-values.png b/static/img/platform/start/qb-two-values.png new file mode 100644 index 000000000..078af5258 Binary files /dev/null and b/static/img/platform/start/qb-two-values.png differ