Viewing operating system details

This document describes how to set up and use OS inventory management. For an overview of OS inventory management, see OS inventory management.

Use OS inventory management to collect and view operating system details for your virtual machine (VM) instances. These operating system details include information such as hostname, operating system, and kernel version. You can also get information about installed OS packages, available OS package updates, and OS vulnerabilities. For a list of common scenarios for using OS inventory management, review When to use OS inventory management.

Before you begin

Supported operating systems

For the full list of operating systems and versions that support OS inventory management, see Operating system details.

Permissions

Owners of a Cloud project have full access to inventory data. For all other users, you need to grant permissions. You can grant one of the following granular roles:

  • roles/osconfig.inventoryViewer: contains permissions to list and describe inventory data.
  • roles/osconfig.vulnerabilityReportViewer: contains permissions to list and describe vulnerability report data.

For example, to grant a user access to view inventory data, use the following command:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member user:USER_ID@gmail.com \
    --role roles/osconfig.inventoryViewer

Replace the following:

  • PROJECT_ID: the project ID
  • USER_ID: the user's Google Workspace username

Overview

Before you can use OS inventory management, you need to configure your VMs to use the feature. To configure your VMs to use OS inventory management, you must complete the following procedures:

  1. Set up VM Manager.
  2. Optional. If you want to integrate with Cloud Asset Inventory, see OS inventory and Cloud Asset Inventory integration.

After setting up OS inventory management on your VMs, you can then view operating system details.

View operating system details

To view operating system details, use either of the following methods:

To review the two versions of OS inventory management, see OS inventory management versions.

OS inventory and Cloud Asset Inventory integration

OS inventory management stores and forwards data to Cloud Asset Inventory. Cloud Asset Inventory is a metadata inventory service that allows you to view, monitor, and analyze assets across Google Cloud. From Cloud Asset Inventory, you can poll the information and view changes in the data.

To access OS inventory data from Cloud Asset Inventory, you need to complete the following setup:

OS inventory management v2.0

Use this method to complete the following tasks:

View inventory data

gcloud

  1. To view a list of inventory data for VMs in a specific zone, run the os-config inventories list command.

    gcloud alpha compute os-config inventories list \
       --location=ZONE
    

    Replace ZONE with the zone where the VM is located.

    Example

    gcloud alpha compute os-config inventories list \
       --location=us-central1-c
    

    The output is similar to the following:

    INSTANCE_ID        INSTANCE_NAME  OS                     OSCONFIG_AGENT_VERSION       UPDATE_TIME
    29255009728795105  centos7-old    CentOS Linux 7 (Core)  20210217.00-g1.el7  2021-04-12T22:19:36.559Z
    29255333728795105  centos8-new    CentOS Linux 8 (Core)  20210217.00-g1.el7  2019-04-12T22:19:36.559Z
    
  2. To view inventory details for a specific VM, run the os-config inventories describe command and specify the INSTANCE_ID returned from the previous step.

    gcloud alpha compute os-config inventories describe INSTANCE_ID \
       --location=ZONE
    

    Replace the following:

    • INSTANCE_ID: the ID for your VM
    • ZONE: the zone where the VM instance is located

    Example

    gcloud alpha compute os-config inventories describe 29255009728795105 \
       --location=us-central1-c
    

    Example output

    "osInfo": {
    "longName": "CentOS Linux 7 (Core)",
    "shortName": "centos",
    "version": "7",
    "architecture": "x86_64",
    "kernelVersion": "#1 SMP Wed Feb 3 15:06:38 UTC 2021",
    "kernelRelease": "3.10.0-1160.15.2.el7.x86_64",
    "osconfigAgentVersion": "20210217.00-g1.el7",
    "hostname": "centos7-old"
    },
    "items": {
    "availablePackage-kernel:x86_64:3.10.0-1160.24.1.el7": {
      "id": "availablePackage-kernel:x86_64:3.10.0-1160.24.1.el7",
      "originType": "INVENTORY_REPORT",
      "availablePackage": {
        "yumPackage": {
          "architecture": "x86_64",
          "version": "3.10.0-1160.24.1.el7",
          "packageName": "kernel"
        }
      },
      "createTime": "2021-04-10T17:19:36.455Z"
    },
    "availablePackage-device-mapper:x86_64:7:1.02.170-6.el7_9.4": {
      "id": "availablePackage-device-mapper:x86_64:7:1.02.170-6.el7_9.4",
      "originType": "INVENTORY_REPORT",
      "availablePackage": {
        "yumPackage": {
          "architecture": "x86_64",
          "version": "7:1.02.170-6.el7_9.4",
          "packageName": "device-mapper"
        }
      },
      "createTime": "2021-04-10T17:19:36.455Z"
    

API

  1. To view a list of inventory data for VMs in a specific zone, create a GET request to the projects.locations.instances.inventories.list method.

    GET https://osconfig.googleapis.com/v1alpha/projects/PROJECT_ID/locations/ZONE/instances/–/inventories
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where the OS policy assignments are located
  2. To view inventory details for a specific VM, create a GET request to the projects.locations.instances.getInventory method.

    GET https://osconfig.googleapis.com/v1alpha/projects/PROJECT_ID/locations/ZONE/instances/INSTANCE/inventory
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where the VM instance is located
    • INSTANCE: specify either the instance ID or the name for your VM

View vulnerability reports

gcloud

  1. To view vulnerability reports for VMs in a specific zone, use the os-config vulnerability-reports list command.

    For example, to list all the VMs that have inventory data, run the following command:

    gcloud alpha compute os-config vulnerability-reports list \
       --location=ZONE
    

    Replace ZONE with the zone where the VM is located.

    Example

    gcloud alpha compute os-config vulnerability-reports list \
       --location=us-west2-a
    

    The output is similar to the following:

    INSTANCE_ID         VULNERABILITY_COUNT  UPDATE_TIME
    29255009728795105   2                    2021-04-13T19:10:10.303046Z
    307058717116242358  1                    2021-04-13T19:10:10.303046Z
    
  2. To view vulnerability report for a specific VM, run the os-config vulnerability-reports describe command specifying the ID returned from the previous step.

    gcloud alpha compute os-config vulnerability-reports describe INSTANCE_ID \
       --location=ZONE
    

    Replace the following:

    • INSTANCE_ID: the ID for your VM
    • ZONE: the zone where the VM instance is located

    Example

    gcloud alpha compute os-config vulnerability-reports describe 29255009728795105  \
       --location=us-west2-a
    

    Example output

    name: projects/384587888288/locations/us-west2-a/instances/29255009728795105/vulnerabilityReport
    updateTime: '2021-04-13T19:10:10.303046Z'
    vulnerabilities:
    – createTime: '2021-04-02T20:30:17.888879Z'
     details:
       cve: CVE-2015-8872 dosfstools
       cvssV3: {}
       severity: SEVERITY_UNSPECIFIED
     installedInventoryItemIds:
     – installedPackage-dosfstools:x86_64:3.0.20-10.el7
     updateTime: '2021-04-02T20:30:17.888879Z'
    – createTime: '2021-04-02T20:30:17.637911Z'
     details:
       cve: CVE-2020-24977
       cvssScore: 6.4
       cvssV3:
         attackComplexity: ATTACK_COMPLEXITY_LOW
         attackVector: ATTACK_VECTOR_NETWORK
         availabilityImpact: IMPACT_LOW
         baseScore: 6.5
         confidentialityImpact: IMPACT_LOW
         exploitabilityScore: 3.9
         impactScore: 2.5
         integrityImpact: IMPACT_NONE
         privilegesRequired: PRIVILEGES_REQUIRED_NONE
         scope: SCOPE_UNCHANGED
         userInteraction: USER_INTERACTION_NONE
       description: 'NIST vectors: AV:N/AC:L/Au:N/C:P/I:N/A:P'
       severity: MEDIUM
     installedInventoryItemIds:
     – installedPackage-libxml2:x86_64:2.9.1-6.el7.5
     updateTime: '2021-04-02T20:30:17.637911Z'
    

API

  1. To view vulnerability reports for VMs in a specific zone, create a GET request to the projects.locations.instances.vulnerabilityReports method.

    GET https://osconfig.googleapis.com/v1alpha/projects/PROJECT_ID/locations/ZONE/instances/–/vulnerabilityReports
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where the OS policy assignments are located
  2. To view vulnerability report for a specific VM, create a GET request to the projects.locations.instances.getVulnerabilityReport method.

    GET https://osconfig.googleapis.com/v1alpha/projects/PROJECT_ID/locations/ZONE/instances/INSTANCE/vulnerabilityReport
    

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where the VM instance is located
    • INSTANCE: specify either the instance ID or the name for your VM

OS inventory management v1.0

Use this method to complete the following tasks:

  • List VMs: view a list of VMs that are reporting inventory data
  • View inventory data: review the inventory data that is available for a VM

List VMs

To view the list of VMs that have OS inventory management set up, run the instances os-inventory list-instances command.

For example, to list all the VMs that have inventory data, run the following command:

gcloud compute instances os-inventory list-instances

The output is similar to the following:

NAME                  ZONE        MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP  STATUS
inventory-instance   us-east1-b    e2-standard-2               192.0.2.1                RUNNING
instance-inventory1  us-west1-b    e2-standard-2               192.0.2.2                RUNNING
instance-inventory2  asia-east2-b  e2-standard-2               192.0.2.3                RUNNING

You can also use filters to narrow down your results. For example, you can list all VMs that have OS inventory management set up and whose hostname matches the regex instance-* by running the following command:

gcloud compute instances os-inventory list-instances --inventory-filter="Hostname~instance-*"

The output is similar to the following:

NAME                  ZONE        MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP  STATUS
instance-inventory1  us-west1-b    e2-standard-2               192.0.2.2                RUNNING
instance-inventory2  asia-east2-b  e2-standard-2               192.0.2.3                RUNNING

View inventory data

To view the inventory data for your VM, use the instances os-inventory describe command.

To view the inventory data collected for a VM, run the following command:

gcloud compute instances os-inventory describe VM-NAME \
    --zone=ZONE

Replace the following:

  • VM-NAME: the name of your VM
  • ZONE: the zone where the VM is located

To view the types of output details that is returned, review Information provided by OS inventory management.

What's next