Interim solution for Ansible scan not working as documented

docs/cnquery/saas/gh-app.mdx

@@ -0,0 +1,95 @@
+---
+title: Give cnquery Access to GitHub using Custom App Credentials
+sidebar_label: GitHub with Custom App Credentials
+sidebar_position: 5
+displayed_sidebar: cnquery
+description: Give cnquery access to GitHub using a custom application.
+image: /img/featured_img/mondoo-feature.jpg
+---
+
+To [query GitHub organizations and repos](/cnquery/saas/github/), cnquery needs to authenticate with GitHub. There are two ways to do this:
+
+- Option 1: Give cnquery access using a personal access token and an environment variable. This approach is easier to set up but results isn't recommended for very large GitHub organizations. To learn how to give cnquery access using a personal access token, read [Give cnquery access using a personal access token and an environment variable](/cnquery/saas/github/).
+
+- Option 2: Give cnquery access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations (with API rate limits as much as 3x higher than personal access tokens). To learn how to give cnquery access using custom app credentials, continue reading below.
+
+For cnquery to authenticate with GitHub using [custom GitHub application credentials](https://docs.github.com/en/apps/creating-github-apps), create a GitHub application and give cnquery the app ID, private key, and installation ID.
+
+## Create a GitHub application and get the authentication information cnquery needs
+
+1. In the top-right corner of any page on GitHub, select your profile icon.
+
+2. Open your account settings:
+
+   - To create an app owned by a personal account, select **Settings**.
+
+   - To create an app owned by an organization, select **Your organizations** and, to the right of the organization you want, select **Settings**.
+
+3. In the left sidebar, select **Developer settings**.
+
+4. In the left sidebar, select GitHub Apps.
+
+5. Select the **New GitHub App** button.
+
+    ![Add a new GitHub app](/img/cnspec/github/name-new-app.png)
+
+6. In the **GitHub App name** box, type a name for your app that helps you easily recognize that it's for Mondoo. The name must be unique across GitHub.
+
+7. In the **Description** box, write that this app provides authentication for Mondoo queries.
+
+8. In the **Homepage URL** box, type `https://cnquery.io' or your own company URL.
+
+9. Skip past the settings under **Identifying and authorizing users** and **Post installation**.
+
+10. Under **Webhooks**, uncheck the **Active** box.
+
+    ![Webhooks](/img/cnspec/github/webhook.png)
+
+11. Under **Permissions**, assign **read-only** permission to all repository and organization data.
+
+    ![Permissions](/img/cnspec/github/perms.png)
+
+12. Under **Where can this GitHub App be installed?**, select **Only on this account**.
+
+    ![Add a new GitHub app](/img/cnspec/github/create-gh-app.png)
+
+12. Select the **Create GitHub App** button.
+
+    GitHub creates the app and displays its properties.
+
+    ![Created GitHub app](/img/cnspec/github/created-app.png)
+
+13. In the **About** section, copy the **App ID** value and save it somewhere that you can access later. You need it when you query.
+
+14. Scroll down to the **Private keys** section and select the **Generate a private key** button.
+
+    GitHub creates a new private key and downloads it to your workstation in a PEM certificate file. Note the path to the PEM file; you need it when you query.
+
+15. In the left sidebar, select **Install App**.
+
+16. Install your custom app to any repo so that you can see its installation ID.
+
+    GitHub installs the app and displays a confirmation.
+
+    ![Install a new GitHub app](/img/cnspec/github/install-success.png)
+
+    In your browser's address bar, find the installation ID in the URL, after `/installations/`. For example, the pictured app's installation ID is `56758584`. Copy this value and save it somewhere that you can access later. You need it when you query.
+
+## Query using your custom app credentials
+
+Enter the `cnquery shell` command, passing the information you stored in the steps above:
+
+| For...                       | Substitute...                                         |
+|------------------------------|-------------------------------------------------------|
+| `YOUR-GITHUB-ORG`            | The name of the GitHub organization you want to query |
+| `YOUR-GITHUB-APP-ID`         | The app ID from step 13                               |
+| `YOUR-GITHUB-APP-INSTALL-ID` | The installation ID from step 16                      |
+| `PATH-TO-PEM-FILE`           | The path you noted in step 14                         |
+
+```bash
+cnquery shell github org <YOUR-GITHUB-ORG> --app-id <YOUR-GITHUB-APP-ID> --app-installation-id <YOUR-GITHUB-APP-INSTALL-ID> --app-private-key <PATH-TO-PEM-FILE>
+```
+
+To learn more options for querying GitHub organizations and repositories, read [Assess the Configuration of GitHub Organizations and Repositories with cnspec](/cnspec/saas/github/).
+
+---

docs/cnquery/saas/github.md

@@ -9,11 +9,15 @@ image: /img/featured_img/mondoo-feature.jpg
 
 Rely on cnquery to query and inventory your GitHub organizations and private repositories (repos) as well as public repos and open source projects your team depends on.
 
-## Give cnquery access using the GitHub API
+## Give cnquery access to your GitHub organization
 
-To query GitHub organizations and repos, cnquery needs access. You give cnquery the access it needs through the GitHub API. First, you create GitHub personal access token. Then you share that token with cnquery using an environment variable.
+To scan GitHub organizations and repos, cnquery needs access. There are two ways to do this:
 
-### Option 1: Create a GitHub personal access token
+- Option 1: Give cnquery access using a personal access token and an environment variable. This approach is easier to set up but isn't recommended for very large GitHub organizations. To learn how to give cnquery access using a personal access token, continue reading below.
+
+- Option 2: Give cnquery access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations (with API rate limits as much as 3x higher than personal access tokens). To learn how to give cnquery access using custom app credentials, read [Give cnquery Access to GitHub Using Custom GitHub App Credentials](/cnquery/saas/gh-app/).
+
+### Create a GitHub personal access token
 
 cnquery needs a personal access token to query a GitHub organization, public repo, or private repo. The token's level of access determines how much information cnquery can retrieve.
 
@@ -25,7 +29,7 @@ To learn how to create a personal access token, read [Creating a personal access
 - admin:org_hook
 - read:project
 
-#### Configure a GITHUB_TOKEN environment variable
+### Configure a GITHUB_TOKEN environment variable
 
 You supply your personal access token to cnquery using the `GITHUB_TOKEN` environment variable.
 
@@ -41,14 +45,6 @@ export GITHUB_TOKEN=<your personal access token>
 $Env:GITHUB_TOKEN = "<personal-access-token>"
 ```
 
-### Option 2: Use custom GitHub application credentials
-
-Mondoo also supports the using [custom GitHub application credentials](https://docs.github.com/en/apps/creating-github-apps). Create an application and then use the app ID and the private key to authenticate scans:
-
-```bash
-cnquery scan github org <ORG> --app-id <YOUR-APP-ID> --app-installation-id <YOUR-INSTALL-ID> --app-private-key <PATH-TO-PEM-FILE>
-```
-
 ## Query GitHub
 
 To answer any question about your environment, use cnquery's interactive shell. It has auto-complete to guide you, which is especially helpful when you're new to cnquery and learning MQL.

docs/cnquery/saas/google_workspace.mdx

@@ -1,7 +1,7 @@
 ---
 title: Query Google Workspace
 sidebar_label: Google Workspace
-sidebar_position: 3
+sidebar_position: 10
 displayed_sidebar: cnquery
 description: Query Google Workspace configuration with cnquery
 ---

docs/cnquery/saas/ms365.md

@@ -2,7 +2,7 @@
 title: Query Microsoft 365
 sidebar_label: Microsoft 365
 displayed_sidebar: cnquery
-sidebar_position: 4
+sidebar_position: 20
 description: Use cnquery to inventory and Microsoft 365
 image: /img/featured_img/mondoo-365.jpg
 ---

docs/cnquery/saas/okta.md

@@ -1,7 +1,7 @@
 ---
 title: Query Okta
 sidebar_label: Okta
-sidebar_position: 5
+sidebar_position: 30
 displayed_sidebar: cnquery
 description: Query Okta configuration with cnquery
 image: /img/featured_img/mondoo-feature.jpg

docs/cnquery/saas/slack.md

@@ -1,7 +1,7 @@
 ---
 title: Query Slack
 sidebar_label: Slack
-sidebar_position: 6
+sidebar_position: 40
 displayed_sidebar: cnquery
 description: Query your Slack workspaces with cnquery
 image: /img/featured_img/mondoo-feature.jpg

docs/cnquery/saas/snowflake.mdx

@@ -1,7 +1,7 @@
 ---
 title: Query Snowflake Configuration and Identities
 sidebar_label: Snowflake
-sidebar_position: 7
+sidebar_position: 50
 displayed_sidebar: cnquery
 description: Query Snowflake account and database configuration and identities with cnquery
 image: /img/featured_img/mondoo-feature.jpg

docs/cnspec/cli/cnspec_scan.md

@@ -177,12 +177,6 @@ cnspec scan vagrant HOST
 cnspec scan --inventory-file FILENAME
 ```
 
-#### Scan an Ansible inventory file
-
-```bash
-ansible-inventory -i hosts.ini --list | cnspec scan --inventory-format-ansible --inventory-file -
-```
-
 ### Options
 
 ```

docs/platform/infra/opsys/automation/_ansible-hide.md

@@ -0,0 +1,29 @@
+THIS IS A TEMPORARY, HIDDEN FILE
+
+Docusaurus doesn't compile this. No user will ever see it.
+
+I've taken the pipe method out of the Ansible doc until we can figure out how to make it work. I removed the --insecure flag. But Patrick still doesn't scan successfully.
+
+
+#### Step 2: Scan the Ansible inventory
+
+The method for scanning an Ansible inventory depends on whether your shell supports `|`.
+
+##### Option A: 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 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 command"
+ansible-inventory -i hosts.ini --list | cnspec scan --inventory-format-ansible
+```
+
+##### 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-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-format-ansible
+
+```

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

@@ -232,29 +232,7 @@ instance1 | SUCCESS => {
 
 #### Step 2: Scan the Ansible inventory
 
-The method for scanning an Ansible inventory depends on whether your shell supports `|`.
-
-##### Option A: 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 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 command"
-ansible-inventory -i hosts.ini --list | cnspec scan --inventory-format-ansible --insecure
-```
-
-:::info
-
-Use the `--insecure` flag for:
-
-- Hosts that have not been added to `~/.ssh/known_hosts`
-
-- Windows WinRM using self-signed certificates
-
-:::
-
-##### 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-file` flag.
+Generate a `hosts.json` file 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
@@ -483,16 +461,6 @@ Run the playbook with this command:
 ansible-playbook -i hosts.ini playbook.yml
 ```
 
-:::info
-
-Use the `--insecure` flag for:
-
-- Hosts that have not been added to `~/.ssh/known_hosts`
-
-- Windows WinRM using self-signed certificates
-
-:::
-
 #### Step 4: View scan reports in the Mondoo Console
 
 Once Ansible completes, scan results are sent to Mondoo Platform so you can view asset scores and reports for all assets scanned in the Mondoo Console.