Update Ansible doc (#65)

* Updates landing pages

* straggler ansible

* Ansible updates

* add format to flag

* add format to flag in CLI doc

* cleanup

* readability

* more readability plus screenshot

* remove flag per tim feedback

* Update docs/cnspec/cli/cnspec_scan.md

---------

Co-authored-by: Tim Smith <[email protected]>

docs/cnspec/cli/cnspec_scan.md

@@ -180,7 +180,7 @@ cnspec scan --inventory-file FILENAME
 #### Scan an Ansible inventory file
 
 ```bash
-cnspec scan --inventory-ansible --inventory-file FILENAME
+ansible-inventory -i hosts.ini --list | cnspec scan --inventory-format-ansible --inventory-file -
 ```
 
 ### Options

docs/platform/infra/opsys/automation/ansible.md

@@ -8,21 +8,17 @@ image: /img/featured_img/mondoo-feature.jpg
 
 Mondoo works seamlessly with configuration management tools in the DevOps ecosystem. For businesses already using Ansible to automate their environments, there are two primary ways to use Mondoo and Ansible together:
 
-[**Continuously assess host configuration**](#continuous-configuration-assessments-with-mondoo-and-ansible)
+- [**Continuously assess host configuration**](#run-continuous-configuration-assessments-with-mondoo-and-ansible): Use Ansible to:
 
-Use Ansible to:
+  - Install and configure [cnspec](/platform/infra/opsys/mondoo-cnspec/) on supported Linux and Windows hosts
 
-- Install and configure [cnspec](/platform/infra/opsys/mondoo-cnspec/) on supported Linux and Windows hosts
+  - Register hosts with Mondoo Platform
 
-- Register hosts with Mondoo Platform
+  - Configure hosts to continuously scan with Mondoo policies and report results to Mondoo Platform
 
-- Configure hosts to continuously scan with Mondoo policies and report scan results to Mondoo Platform
+- [**Scan Ansible inventories on demand**](#scan-ansible-inventories-on-demand): Perform on-demand scans of Ansible inventories without installing cnspec as a service on the host.
 
-[**Scan Ansible inventories on demand**](#on-demand-scanning-of-ansible-inventories)
-
-Perform on-demand scans of Ansible inventories without installing cnspec as a service on the host.
-
-Hosts from your Ansible inventory authenticate with your Mondoo Platform account so that cnspec can retrieve policies you've enabled. cnspec sends scan results from the host to Mondoo Platform, where you can see asset scores and reports.
+  Hosts from your Ansible inventory authenticate with your Mondoo Platform account so that cnspec can retrieve policies you've enabled. cnspec sends scan results from the host to Mondoo Platform, where you can see asset scores and reports.
 
 <!-- prettier-ignore -->
 import Partial from "./_automation-providers-note.mdx";
@@ -31,21 +27,21 @@ import Partial from "./_automation-providers-note.mdx";
 
 ## Requirements
 
-- In your Mondoo Platform account, enable all the policies you want to run against your Ansible inventory. To learn how to enable policies, read [Monitor Your Infrastructure Security](/platform/security/posture/monitor).
+- In your Mondoo Platform account, enable all the policies you want to run against your Ansible inventory. To learn how to enable policies, read [Manage Policies](/platform/security/posture/policies/).
 
 - You must have root or administrator access for each host in the Ansible inventory you want to scan.
 
 - You must have Ansible installed on your workstation. For installation instructions, read <a href="https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html" target="_blank">the Ansible documentation</a>.
 
 - All hosts in your inventory must allow outbound traffic on port 443 (HTTPS) to Mondoo Platform at `https://us.api.mondoo.com:443` (IP address `34.98.71.94`) to send results to your account.
 
-## Continuous configuration assessments with Mondoo and Ansible
+## Run continuous configuration assessments with Mondoo and Ansible
 
 Use Ansible to install and configure cnspec on supported Linux and Windows hosts so that Mondoo runs continuously as a service.
 
-Mondoo maintains and publishes an official <a href="https://galaxy.ansible.com/mondoo/client" target="_blank">Mondoo/cnspec Role</a>, which is available on Ansible Galaxy. The code for the role is open source and available in our <a href="https://github.com/mondoohq/ansible-mondoo" target="_blank">GitHub repo</a>.
+Mondoo maintains and publishes an official <a href="https://galaxy.ansible.com/mondoo/client" target="_blank">Mondoo/cnspec role</a>, which is available on Ansible Galaxy. The code for the role is open source and available in our <a href="https://github.com/mondoohq/ansible-mondoo" target="_blank">GitHub repo</a>.
 
-Our Ansible Role lets you:
+Mondoo's Ansible role lets you:
 
 - Install cnspec on supported Linux and Windows hosts
 
@@ -57,41 +53,37 @@ Our Ansible Role lets you:
 
 Once configured, cnspec authenticates with Mondoo Platform every 60 minutes, running every policy enabled in the registry. It sends results from the scan to Mondoo Platform so you can see the generated scores and reports in the Mondoo Console.
 
-### Hands-on: Continuous configuration assessments with Mondoo & Ansible
-
-> This section provides a hands-on guide for using the Mondoo Ansible role.
+### Set up continuous configuration assessments with Mondoo and Ansible
 
-This guide covers how to set up continuous configuration assessments on Linux and Windows hosts with Ansible. After completing this guide, you will have an Ansible inventory running cnspec as a service, registered with your Mondoo Platform account, running policy scans, and reporting the findings to Mondoo Platform.
+This section covers how to set up continuous configuration assessments on Linux and Windows hosts with Ansible. After completing this section, you will have an Ansible inventory running cnspec as a service, registered with your Mondoo Platform account, running policy scans, and reporting the findings to Mondoo Platform.
 
 #### Step 1: Generate a registration token
 
 The Mondoo Ansible role provides a `registration_token` variable to specify a Mondoo registration token to use to register the client with Mondoo Platform.
 
-1. In the [Mondoo Console](https://console.mondoo.com) navigate to the **INTEGRATIONS** page.
+1. In the [Mondoo Console](https://console.mondoo.com) side navigation bar, under **INTEGRATIONS**, select **Add New Integration**.
 
-2. Select "Add Another Integration".
-
-3. Select **Workstation**.
+2. Select **Workstation**.
 
 :::info
 
-By default, tokens expire every 600 seconds, but expiration time can be extended by selecting **Token Options** and setting the expiration time (max: 86400 seconds).
+By default, tokens expire every 600 seconds. You can extend expiration time by selecting **Token Options** and setting the expiration time (max: 86400 seconds).
 
 :::
 
 3. Copy the registration token to the clipboard.
 
-#### Step 2: Install Mondoo role and create playbook
+#### Step 2: Install the Mondoo role and create a playbook
 
-Next you must install the Mondoo Ansible role from Ansible Galaxy on your local workstation, and create an Ansible playbook to call that role on your inventory.
+Install the Mondoo Ansible role from Ansible Galaxy on your local workstation and create an Ansible playbook to call that role on your inventory:
 
-1. Download the Ansible Mondoo role on your workstation:
+1. Download the Ansible Mondoo role to your workstation:
 
    ```bash title="Download Mondoo role on your workstation"
    ansible-galaxy install mondoo.client
    ```
 
-2. Create a `playbook.yaml` file to run the Ansible Mondoo role on your inventory of hosts. You must update the `registration_token` value with your registration token from _Step 1: Generate a registration token_ above. This example has both Linux and Windows hosts, and should be updated accordingly if only using one platform or another:
+2. Create a `playbook.yaml` file to run the Ansible Mondoo role on your inventory of hosts. You must update the `registration_token` value with your registration token from _Step 1: Generate a registration token_ above. This example has both Linux and Windows hosts. If you're only using one of these platforms, remove the unneeded section:
 
    ```yaml title="Example playbook.yml"
     ---
@@ -146,58 +138,48 @@ ansible-playbook -i hosts.ini playbook.yml
 
 Once Ansible runs the `playbook.yaml` against your inventory, you can view the scan results in Mondoo Platform.
 
-1. In the [Mondoo Console](https://console.mondoo.com) navigate to the **INVENTORY** page.
+1. In the [Mondoo Console](https://console.mondoo.com) side navigation bar, under **Inventory**, select **Operating Systems**. All your assets should now be reported and have asset scores for the policies executed.
 
-2. All servers should now be reporting in and have received an asset score for the policies executed.
+2. To view detailed results and the policies that ran on an asset, select the asset in the list. If you don't see the asset you want, use the search bar to filter assets.
 
-3. To view the policies that ran on a given asset, and detailed information, select an asset in the list.
-   ![Ansible asset details in Mondoo Platform](/img/platform/infra/opsys/automation/ansible_asset_details.png)
+   ![Mondoo scan results of an asset from an Ansible inventory](/img/platform/infra/opsys/automation/ansible_asset_details.png)
 
-This view shows each policy that ran against an asset, and the individual score for each policy. Select any policy in the list to view the results from each query.
+   Tabs for policies, checks, and data queries let you dive into greater detail.
 
 :::info
 
 To learn more about how Mondoo generates asset scores, read [Manage Policies](/platform/security/posture/overview).
 
 :::
 
-#### You're done!
-
-cnspec is now running as a service on your Ansible inventory. It will continue to scan your assets every 60 minutes and report findings back to your account.
+cnspec is now running as a service on your Ansible inventory. It continues to scan your assets every 60 minutes and report findings back to your account.
 
-## On-demand scanning of Ansible inventories
-
-> This section covers how to use cnspec for on-demand scans of Ansible inventories without needing to install and configure cnspec as a service on the host.
+## Scan Ansible inventories on demand
 
 While you can easily configure Mondoo's cnspec to run as a service to continuously scan your infrastructure, there may be times when you just want to scan an Ansible inventory without having to install and configure cnspec on your infrastructure.
 
 Mondoo supports on-demand scanning of an Ansible inventory in two ways:
 
-- Use the `cnspec scan --inventory-ansible --inventory-file FILENAME` command to parse the output of `ansible-inventory -i <host_file.ini> --list` command, and scan with Mondoo.
-- Create an Ansible task that runs `cnspec scan` to scan your infrastructure.
+- Parse the output of the `ansible-inventory` command and scan with Mondoo.
+
+- Create an Ansible task that uses cnspec to scan your infrastructure.
 
-With both of the scenarios above, your assets:
+With both of these approaches, your assets:
 
 1. Authenticate with your Mondoo Platform account using the cnspec configuration on your local workstation
 
 2. Run any policies enabled in that space
 
-3. Return the results to Mondoo Platform so you can view reports and asset scores for all assets in the Mondoo Console
-
-With these approaches, Mondoo doesn't install anything on your infrastructure. Every time you want to see fresh results, you must scan the assets.
-
-The next section provides hands-on tutorials for running both on-demand scenarios.
-
-### On-demand scan of Ansible inventory
-
-This section is a hands-on guide on how to trigger an on-demand scan of an Ansible inventory. When you finish, you will have fresh asset scores and reports for all of your Ansible inventory in your Mondoo Platform account.
+3. Return the results to Mondoo Platform so you can view reports and asset scores for all assets in the Mondoo Console.
 
 :::caution
 
 Because on-demand scans of Ansible inventories run serially, we don't recommend them for large inventories. If you want to run on-demand scans that execute in parallel, please reach out to us in the [Mondoo Community Slack](https://mondoo.link/slack) channel.
 
 :::
 
+### Scan the output of the `ansible-inventory` command
+
 #### Step 1: Set up or validate your Ansible inventory
 
 An Ansible inventory is a list of hosts that is mostly stored in the two common formats `ini` and `yaml`. These examples illustrate their structure. The ini format allows grouping and easy configuration of additional properties.
@@ -250,14 +232,15 @@ instance1 | SUCCESS => {
 
 #### Step 2: Scan the Ansible inventory
 
-cnspec provides the `cnspec scan --inventory-ansible` command to scan existing Ansible inventories. There are two main ways to use this command.
+The method for scanning an Ansible inventory depends on whether your shell supports `|`.
+
+##### Option A: Pipe the Ansible inventory to cnspec scan
 
-##### Option 1: Pipe the Ansible inventory to cnspec scan
 
-The first option if you are using a shell such as `bash` or `zsh` that supports `|` redirects is to pipe the outputs of the `ansible-inventory -i hosts.ini --list` command to `cnspec scan --inventory-ansible`. For `FILENAME`, substitute the name of the inventory file.
+The first option if you are using a shell such as `bash` or `zsh` that supports `|` redirects is to pipe the output of the `ansible-inventory -i hosts.ini --list` command to `cnspec scan --inventory-format-ansible`. For `FILENAME`, substitute the name of the inventory file.
 
-```bash title="Pipe the contents of an Ansible inventory to the cnspec scan --inventory-ansible command"
-ansible-inventory -i hosts.ini --list | cnspec scan --inventory-ansible --inventory-file FILENAME --insecure
+```bash title="Pipe the contents of an Ansible inventory to the cnspec scan command"
+ansible-inventory -i hosts.ini --list | cnspec scan --inventory-format-ansible --insecure
 ```
 
 :::info
@@ -270,18 +253,21 @@ Use the `--insecure` flag for:
 
 :::
 
-##### Option 2: Scan Ansible inventory hosts.json
+##### Option B: Scan Ansible inventory hosts.json
 
-If your shell does not support pipes, you can generate a `hosts.json` from the `ansible-inventory` command and then pass that file to `cnspec scan` using the `--inventory` flag.
+If your shell does not support pipes, you can generate a `hosts.json` from the `ansible-inventory` command and then pass that file to `cnspec scan` using the `--inventory-file` flag.
 
 ```bash title="Generate hosts.json and scan with cnspec scan command"
 ansible-inventory -i hosts.ini --list > hosts.json
-cnspec scan --inventory-file hosts.json --inventory-ansible
+
+cnspec scan --inventory-file hosts.json --inventory-format-ansible
+
 ```
 
 Both cnspec and the Mondoo Console show results from each policy that runs against your assets.
 
-**Example shell output**
+<details>
+<summary>Show or hide example CLI scan output.</summary>
 
 ```
 Checks:
@@ -389,32 +375,35 @@ For detailed output, run this scan with "-o full".
 See more scan results and asset relationships on the Mondoo Console: https://console.mondoo.com/space/inventory/12ejfpX1SbxfrNf6bq8f8gCCgMb?spaceId=ansible-hosts
 ```
 
+</details>
+
 #### Step 3: View scan reports in the Mondoo Console
 
-Once Ansible completes, scan results are sent to Mondoo Platform so you can see the generated scores and reports in the Mondoo Console..
+Once Ansible completes, cnspec sends scan results to Mondoo Platform so you can see the generated scores and reports in the Mondoo Console..
 
 To view the reports in the Mondoo Console:
 
-1. In the [Mondoo Console](https://console.mondoo.com) navigate to the **INVENTORY** page.
-2. All servers should now be reporting in and have received a asset score for the policies executed.
-3. To view the policies that ran on a given asset, and detailed information, select an asset in the list.
-   ![Ansible asset details in Mondoo Platform](/img/platform/infra/opsys/automation/ansible_asset_details.png)
+1. In the [Mondoo Console](https://console.mondoo.com) side navigation bar, under **Inventory**, select **Operating Systems**. All your assets should now be reported and have asset scores for the policies executed.
+
+2. To view detailed results and the policies that ran on an asset, select the asset in the list. If you don't see the asset you want, use the search bar to filter assets.
 
-This view shows each policy that ran against an asset, and the individual score for each policy. Select any policy in the list to view the results from each query.
+   ![Mondoo scan results of an asset from an Ansible inventory](/img/platform/infra/opsys/automation/ansible_asset_details.png)
 
-We rely on [ansible-inventory](https://docs.ansible.com/ansible/latest/cli/ansible-inventory.html) command to be able to support various inventory formats and to be able to re-use [dynamic inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html) too. This command outputs a standardized format independently if a `ini` or `yaml` inventory is used.
+   Tabs for policies, checks, and data queries let you dive into greater detail.
+
+We rely on the [ansible-inventory](https://docs.ansible.com/ansible/latest/cli/ansible-inventory.html) command to support various inventory formats and re-use [dynamic inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html). This command outputs a standardized format independently if a `ini` or `yaml` inventory is used.
 
 :::info
 
-Note: At this point, we do not support group [patterns](https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html). If you need additional support, please do not hesitate to contact us.
+Currently Mondoo does not support group [patterns](https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html). If you need additional support, please contact us.
 
 :::
 
-### Hands-On: On-demand scan of Ansible inventory using an Ansible task
+### Scan on demand using an Ansible task
 
-As an alternative, you can use the `cnspec scan` command in an Ansible task. Mondoo uses the ssh-agent so you do not need to set up additional credentials configuration.
+You can use the `cnspec scan` command in an Ansible task. Mondoo uses the ssh-agent so you do not need to set up additional credentials configuration.
 
-#### Step 1: Set up or validate your Ansible Inventory
+#### Step 1: Set up or validate your Ansible inventory
 
 An Ansible inventory is a list of hosts that is mostly stored in the two common formats `ini` and `yaml`. These examples illustrate their structure. The ini format allows grouping and easy configuration of additional properties.
 
@@ -466,7 +455,7 @@ instance1 | SUCCESS => {
 
 #### Step 2: Set up playbook.yaml to run cnspec scan
 
-Next, you must create a playbook to run the `cnspec scan` against your inventory. This is an example `playbook.yaml` used to execute `cnspec scan` locally with a playbook against Linux hosts:
+Create a playbook to run a cnspec scan against your inventory. This is an example `playbook.yaml` used to execute the scan locally with a playbook against Linux hosts:
 
 ```yaml title="Example playbook.yml for executing cnspec scan against Linux hosts"
 ---
@@ -511,14 +500,13 @@ Once Ansible completes, scan results are sent to Mondoo Platform so you can view
 
 To view the reports in the Mondoo Console:
 
-1. In the [Mondoo Console](https://console.mondoo.com) navigate to the **INVENTORY** page.
+1. In the [Mondoo Console](https://console.mondoo.com) side navigation bar, under **Inventory**, select **Operating Systems**. All your assets should now be reported and have asset scores for the policies executed.
 
-2. All servers should now be reporting in and have received an asset score for the policies executed.
+2. To view detailed results and the policies that ran on an asset, select the asset in the list. If you don't see the asset you want, use the search bar to filter assets.
 
-3. To view the policies that ran on a given asset, and detailed information, select an asset in the list.
-   ![Ansible asset details in Mondoo Platform](/img/platform/infra/opsys/automation/ansible_asset_details.png)
+   ![Mondoo scan results of an asset from an Ansible inventory](/img/platform/infra/opsys/automation/ansible_asset_details.png)
 
-This view shows each policy that ran against an asset, as well as the individual score for each policy. Select any policy in the list to view the results from each query.
+   Tabs for policies, checks, and data queries let you dive into greater detail.
 
 :::info