Expand info on how to annotate assets (#245)

* documents annotations outside console

* just switching gears

* missing image

* templates and inventories

* add expect to spellchk

* change page desc

* replacing at symbol didn't work

* tidy table

.github/actions/spelling/expect.txt

@@ -142,6 +142,7 @@ gcfs
 Gci
 gcs
 geomatchstatement
+getenv
 GFj
 GGJXG
 Ghpcn

docs/cnspec/README.mdx

@@ -22,7 +22,7 @@ import Partial from "./_include-install.mdx";
 
 ## Scan locally
 
-Use the `cnspec scan` subcommand to check local and remote targets for misconfigurations and vulnerabilities. cnspec detects the target platform and runs policy checks specific to that system.
+Use the `cnspec scan` command to check local and remote targets for misconfigurations and vulnerabilities. cnspec detects the target platform and runs policy checks specific to that system.
 
 This command evaluates the security of your local machine:
 

docs/cnspec/cnspec-adv-install/registration.md

@@ -139,51 +139,6 @@ cnspec status
 ! possible clock skew detected: 72h0m6.277868s
 ```
 
-## Annotate (tag) an asset during registration
-
-Use Mondoo annotations to add metadata to an asset. Annotations are key-value pairs that let you identify, tag, or categorize your assets. Add whatever metadata you need. Some examples are:
-
-| Example key | Example value         |
-| ----------- | --------------------- |
-| owner       | [email protected] |
-| build       | terraform             |
-| asset-tag   | luna000262            |
-| team        | 01research            |
-
-You can reuse key-value pairs or you can reuse only the key and give each asset a unique value.
-
-For example, suppose you're matching annotations to the physical asset tags on your company's workstations. You'd give every workstation in your infrastructure an `asset tag` key, but give each workstation a unique value to match the unique physical tags.
-
-As another example, you might assign the key `build` and the value `terraform` to every asset in your infrastructure that is built using Terraform.
-
-To include an annotation when you register an asset, include the `--annotation` flag in the `cnspec login` command and provide the key and value:
-
-```bash
-cnspec login --token "PASTE_YOUR_TOKEN_HERE" --annotation KEY=VALUE --config "/etc/opt/mondoo/mondoo.yml"
-```
-
-For example:
-
-```bash
-cnspec login --token 'eyJh9vLmFwcC9zcGFjZXMvdGhpcnN0eS1tZWl0bmVyLTU5OTIyNSIsInNwYWNlIjoiLy9jYXB0YWluLmFwaS5tb25kb28uYXBwL3NwYWNlcy90aGlyc3R5LW1laXRuZXItNTk5MjI1Iiwic3ViIjoiLy9jYXB0YWluLmFwaS5tb25kb28uYXBwL3VzZXJzLzI3ZkVlc2hzMHNyT0ZzdWExWTY0ajRoblFmWiJ9.le5xx5sp5Qb7WoK0vWUS1wpeSOgpWR8cNjCBYqFfImDxRh_m2KpMFx3MN4K4Gv2DeEKfj4S4wWWEsoDLkenBGhgF2cZlPG7kidguLqcNOFxoRRQoMUgX-78DH8sUaTpi' --annotation [email protected] --config "/etc/opt/mondoo/mondoo.yml"
-```
-
-:::tip
-
-You can also add an annotation when you scan an asset. Include the `--annotation` flag in the `cnspec scan` command and provide the key and value:
-
-```bash
-cnspec scan local --annotation KEY=VALUE
-```
-
-For example:
-
-```bash
-cnspec scan local --annotation asset-tag=luna0003644
-```
-
-:::
-
 ## Specify a proxy server for communication with Mondoo
 
 You can specify a proxy server for communication between cnspec and Mondoo Platform. This is useful if your default system proxy restricts communication, or if you need to monitor different types of traffic.

docs/cnspec/cnspec-adv-install/service.mdx

@@ -444,4 +444,25 @@ To execute cnspec with the inventory file, run this command:
 cnquery scan --inventory-file ./inventory.yml
 ```
 
+## cnspec inventory template
+
+cnspec inventory files are useful for a CI/CD pipeline. Inventory templates are useful for scanning different assets for different environments. They allow you to reuse the same template with a custom variable. This example uses the `getenv` function to include an environment variable (the asset name):
+
+```yaml
+spec:
+  assets:
+    - name: {{ getenv "ASSET_NAME" }}
+      connections:
+        - type: local
+          discover:
+            targets:
+              - auto
+```
+
+You can use this example inventory template by providing the `ASSET_NAME` and variable with the `cnspec scan` command and specifying the template:
+
+```bash
+ASSET_NAME="my_asset" cnspec scan --inventory-template template.yaml
+```
+
 ---

docs/cnspec/debug.mdx

@@ -2,7 +2,6 @@
 title: Scan in Debug Mode to Troubleshoot
 sidebar_label: Debug scans
 displayed_sidebar: cnspec
-sidebar_position: 8
 description: Run cnspec in debug mode for troubleshooting assistance
 image: /img/featured_img/mondoo-feature.jpg
 ---

docs/platform/intel/annotations.mdx

@@ -2,7 +2,7 @@
 title: Annotate (Tag) Assets
 sidebar_label: Annotate (Tag) Assets
 sidebar_position: 4
-description: Add annotations
+description: Add Mondoo annotations (similar to tags) to the assets in your infrastructure
 image: /img/featured_img/mondoo-feature.jpg
 ---
 
@@ -23,15 +23,22 @@ As another example, you might assign the key `build` and the value `terraform` t
 
 Annotations display in the Mondoo Console when you view an asset. When you export data from Mondoo, annotations are included. You can search for assets based on their annotations. To learn how, read [Search Your Inventory](/platform/intel/search/)
 
-## Annotate an asset
+## Add annotations
 
-You can annotate an asset in the Mondoo Console.
+There are multiple ways to annotate an asset:
 
-:::tip
+- The Mondoo Console
 
-You can also add an annotation from the command line or using automation. To learn how, read [Annotate (tag) an asset during registration](/cnspec/cnspec-adv-install/registration/#annotate-tag-an-asset-during-registration).
+- The `cnspec scan` command
+
+- The asset's local Mondoo configuration file
+
+- A cnspec inventory file
+
+- A cnspec inventory template
+
+### Annotate an asset in the Mondoo Console
 
-:::
 
 1. In the [Mondoo Console](https://console.mondoo.com), [navigate](/platform/start/navigate/) to the asset you want to annotate.
 
@@ -47,6 +54,99 @@ You can also add an annotation from the command line or using automation. To lea
 
    ![Annotation on a Mondoo asset](/img/platform/intel/existing-annotation.png)
 
+### Annotate an asset using the `cnspec scan` command
+
+You can add an annotation to an asset when you scan it using cnspec, the Mondoo CLI. To do so, include the `--annotation` flag in the `cnspec scan` command and provide the key and value:
+
+```bash
+cnspec scan TARGET --annotation KEY=VALUE
+```
+
+For example:
+
+```bash
+cnspec scan local --annotation asset-tag=luna0003644
+```
+
+To learn more about cnspec, read the [cnspec documentation](/cnspec/home/). To learn about the `cnspec scan` command, read [`cnspec scan`](/cnspec/cli/cnspec_scan/).
+
+### Annotate an asset using the local Mondoo configuration file
+
+You can add an annotation to an asset's local configuration file.
+
+On a Linux or macOS host, the configuration is stored in one of these locations:
+
+- `/etc/opt/mondoo/mondoo.yml` configures Mondoo for all user accounts.
+
+- `~/.config/mondoo/mondoo.yml` configures Mondoo for a single user.
+
+On a Windows host, configuration is stored in one of these locations:
+
+- `C:\ProgramData\mondoo\mondoo.yml` configures Mondoo for all users.
+
+- `C:\Users\{username}\.config\mondoo\mondoo.yml` configures Mondoo for a single user.
+
+Include these lines to annotate an asset:
+
+```yaml
+annotations:
+   KEY1:VALUE1
+   KEY2:VALUE2
+   ...
+```
+
+For example, this annotation identifies an asset that belongs to the research team:
+
+```yaml
+annotations:
+   team:research
+```
+
+### Annotate an asset using a cnspec inventory file
+
+You can use a [cnspec inventory](/cnspec/cnspec-adv-install/service/#cnspec-inventory) file to define a list of target assets to scan. When you do so, you can add annotations to the target assets.
+
+Include these lines in the cnspec inventory file to annotate an asset:
+
+```yaml
+annotations:
+   KEY1:VALUE1
+   KEY2:VALUE2
+   ...
+```
+
+For example, this annotation identifies an asset in the Mars Rover project:
+
+```yaml
+annotations:
+   project:mars-rover
+```
+
+### Programmatically annotate assets using a cnspec inventory template
+
+[cnspec inventory templates](/cnspec/cnspec-adv-install/service/#cnspec-inventory-template) let you re-use cnspec inventory files with custom variables. This is especially helpful in CI/CD pipelines.
+
+This example inventory template uses variables to define both the asset name and a value for the `project` annotation:
+
+```yaml
+spec:
+  assets:
+    - name: {{ getenv "ASSET_NAME" }}
+      connections:
+        - type: local
+          discover:
+            targets:
+              - auto
+      annotations:
+        project: {{ getenv "PROJECT" }}
+```
+
+To execute `cnspec scan` using the inventory template and define the Mondoo asset name and `project` annotation key value, run:
+
+```bash
+ASSET_NAME="my_asset" PROJECT="mars-rover" cnquery scan --inventory-template template.yaml
+```
+
 ## Change or remove an annotation
 
 1. In the [Mondoo Console](https://console.mondoo.com), [navigate](/platform/start/navigate/) to the asset containing the annotation you want to change or remove.

sidebars.js

@@ -369,6 +369,11 @@ module.exports = {
         },
       ],
     },
+    {
+      type: "doc",
+      id: "cnspec/debug",
+      label: "Troubleshoot in Debug Mode",
+    },
     {
       type: "doc",
       id: "cnspec/uninstall",