View 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 Google 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.

Example command to set permissions

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

Set up your VM

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, set up VM Manager.

After setting up VM Manager on your VMs, you can then view OS inventory data and vulnerability reports.

View OS inventory data

View OS inventory data using the gcloud CLI or API

gcloud

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

    gcloud compute os-config inventories list \
       --location=ZONE \
       --view=VIEW
    

    Replace the following:

    • ZONE: the zone where the VM is located
    • VIEW: the type of output information that is required. The following view types are available:

      • basic: displays only OS information
      • full: displays information about both OS and packages

      If unspecified, the default is basic.

    Example (basic view)

    gcloud 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        CentOS Linux 7 (Core)                      20210217.00-g1.el7           2021-04-12T22:19:36.559Z
    5138980234596718741  rhel-8         Red Hat Enterprise Linux 8.3 (Ootpa)       20210316.00-g1.el8           2021-09-16T17:19:24Z
    7127836223366142250  windows        Microsoft Windows Server 2019 Datacenter   20210316.00.0+win@1          2021-09-16T17:13:18Z
    

    Example (full view)

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

    The output is similar to the following:

    INSTANCE_ID          INSTANCE_NAME  OS                                        INSTALLED_PACKAGES   AVAILABLE_PACKAGES  OSCONFIG_AGENT_VERSION       UPDATE_TIME
    29255009728795105    centos7        CentOS Linux 7 (Core)                     265                  49                  20210217.00-g1.el7           2021-04-12T22:19:36.559Z
    5932621394110773366  rhel8          Red Hat Enterprise Linux 8.3 (Ootpa)      410                  138                 20210217.00-g1.el8           2021-09-16T17:57:16Z
    7127836223366142250  windows        Microsoft Windows Server 2019 Datacenter  36                   6                   20210316.00.0+win@1          2021-09-16T17:53:19Z
    
  2. To view inventory details for a specific VM, run the os-config inventories describe command and specify the INSTANCE_ID or INSTANCE_NAME returned from the previous step.

    gcloud compute os-config inventories describe INSTANCE_NAME \
       --location=ZONE \
       --view=VIEW
    

    Replace the following:

    • INSTANCE_NAME: the name for your VM
    • ZONE: the zone where the VM instance is located
    • VIEW: the type of output information that is required. The following view types are available:

      • basic: displays only OS information
      • full: displays information about both OS and packages

      If unspecified, the default is basic.

    Example (basic view)

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

    Example output

    architecture: x86_64
    hostname: centos-7-88tz3
    kernelRelease: 3.10.0-957.1.3.el7.x86_64
    kernelVersion: '#1 SMP Thu Nov 29 14:49:43 UTC 2018'
    longName: CentOS Linux 7 (Core)
    osconfigAgentVersion: 20210429.3-g1.el8
    shortName: centos
    updateTime: '2021-05-11T22:11:53.064Z'
    version: '7'
    

    Example (full view)

    gcloud compute os-config inventories describe centos7 \
       --location=us-central1-c \
       --view=full
    

    Linux example output

    ┌─────────────────────────────────────────────────────────────────────────────────────┐
    │                               Installed Packages (Yum)                              │
    ├─────────────────────────────────────┬──────────────┬────────────────────────────────┤
    │             PACKAGE_NAME            │ ARCHITECTURE │            VERSION             │
    ├─────────────────────────────────────┼──────────────┼────────────────────────────────┤
    │ GeoIP                               │ x86_64       │ 1.5.0-13.el7                   │
    │ NetworkManager                      │ x86_64       │ 1:1.12.0-8.el7_6               │
    │ NetworkManager-libnm                │ x86_64       │ 1:1.12.0-8.el7_6               │
    │ NetworkManager-team                 │ x86_64       │ 1:1.12.0-8.el7_6               │
    │ NetworkManager-tui                  │ x86_64       │ 1:1.12.0-8.el7_6               │
    │ acl                                 │ x86_64       │ 2.2.51-14.el7                  │
    │ yum-cron                            │ all          │ 3.4.3-161.el7.centos           │
    │ yum-metadata-parser                 │ x86_64       │ 1.1.4-10.el7                   │
    │ yum-plugin-fastestmirror            │ all          │ 1.1.31-50.el7                  │
    │ zlib                                │ x86_64       │ 1.2.7-18.el7                   │
    └─────────────────────────────────────┴──────────────┴────────────────────────────────┘
    ┌───────────────────────────────────────────────────────────────────────────────┐
    │                        Package Updates Available (Yum)                        │
    ├───────────────────────────────┬──────────────┬────────────────────────────────┤
    │          PACKAGE_NAME         │ ARCHITECTURE │            VERSION             │
    ├───────────────────────────────┼──────────────┼────────────────────────────────┤
    │ GeoIP                         │ x86_64       │ 1.5.0-14.el7                   │
    │ NetworkManager                │ x86_64       │ 1:1.18.8-2.el7_9               │
    │ NetworkManager-libnm          │ x86_64       │ 1:1.18.8-2.el7_9               │
    │ NetworkManager-team           │ x86_64       │ 1:1.18.8-2.el7_9               │
    │ yum-cron                      │ all          │ 3.4.3-168.el7.centos           │
    │ yum-plugin-fastestmirror      │ all          │ 1.1.31-54.el7_8                │
    │ zlib                          │ x86_64       │ 1.2.7-19.el7_9                 │
    └───────────────────────────────┴──────────────┴────────────────────────────────┘
    architecture: x86_64
    hostname: centos-7-88tz3
    kernelRelease: 3.10.0-957.1.3.el7.x86_64
    kernelVersion: '#1 SMP Thu Nov 29 14:49:43 UTC 2018'
    longName: CentOS Linux 7 (Core)
    osconfigAgentVersion: 20210429.3-g1.el8
    shortName: centos
    updateTime: '2021-05-11T22:21:52.323Z'
    version: '7'
    

    Windows example output

    ┌───────────────────────────────────────────────────────────┐
    │                Installed Packages (GooGet)                │
    ├───────────────────────┬──────────────┬────────────────────┤
    │      PACKAGE_NAME     │ ARCHITECTURE │      VERSION       │
    ├───────────────────────┼──────────────┼────────────────────┤
    │ google-osconfig-agent │ x86_64       │ 20210415.4.0+win@1 │
    └───────────────────────┴──────────────┴────────────────────┘
    ┌───────────────────────────────────────────────────┐
    │     Installed Packages (Windows Update Agent)     │
    ├───────┬────────────┬────────────────┬─────────────┤
    │ TITLE │ CATEGORIES │ KB_ARTICLE_IDS │ SUPPORT_URL │
    ├───────┼────────────┼────────────────┼─────────────┤
    │ title │ C1, C2     │ 4589208        │ url.com     │
    └───────┴────────────┴────────────────┴─────────────┘
    ┌───────────────────────────────────────────────────────────────┐
    │           Installed Packages (Quick Fix Engineering)          │
    ├─────────┬─────────────────┬────────────┬──────────────────────┤
    │ CAPTION │   DESCRIPTION   │ HOT_FIX_ID │     INSTALL_TIME     │
    ├─────────┼─────────────────┼────────────┼──────────────────────┤
    │ caption │ Security Update │ KB4470788  │ 2019-03-12T00:00:00Z │
    └─────────┴─────────────────┴────────────┴──────────────────────┘
    ┌───────────────────────────────────────────────────────────────────────────┐
    │                  Installed Packages (Windows Application)                 │
    ├──────────────────┬─────────────────┬───────────────────────┬──────────────┤
    │   DISPLAY_NAME   │ DISPLAY_VERSION │       PUBLISHER       │ INSTALL_DATE │
    ├──────────────────┼─────────────────┼───────────────────────┼──────────────┤
    │ PowerShell 7-x64 │ 7.0.2.0         │ Microsoft Corporation │ 2021-06-08   │
    └──────────────────┴─────────────────┴───────────────────────┴──────────────┘
    ┌───────────────────────────────────────────────────────────┐
    │             Package Updates Available (GooGet)            │
    ├───────────────────────┬──────────────┬────────────────────┤
    │      PACKAGE_NAME     │ ARCHITECTURE │      VERSION       │
    ├───────────────────────┼──────────────┼────────────────────┤
    │ google-osconfig-agent │ x86_64       │ 20210415.4.0+win@1 │
    └───────────────────────┴──────────────┴────────────────────┘
    ┌───────────────────────────────────────────────────┐
    │  Package Updates Available (Windows Update Agent) │
    ├───────┬────────────┬────────────────┬─────────────┤
    │ TITLE │ CATEGORIES │ KB_ARTICLE_IDS │ SUPPORT_URL │
    ├───────┼────────────┼────────────────┼─────────────┤
    │ title │ C1, C2     │ 4589208        │ url.com     │
    └───────┴────────────┴────────────────┴─────────────┘
    ┌───────────────────────────────────────────────────────────────┐
    │       Package Updates Available (Quick Fix Engineering)       │
    ├─────────┬─────────────────┬────────────┬──────────────────────┤
    │ CAPTION │   DESCRIPTION   │ HOT_FIX_ID │     INSTALL_TIME     │
    ├─────────┼─────────────────┼────────────┼──────────────────────┤
    │ caption │ Security Update │ KB4470788  │ 2019-03-12T00:00:00Z │
    └─────────┴─────────────────┴────────────┴──────────────────────┘
    architecture: x86_64
    hostname: windows
    kernelRelease: 10.0.17763.1817
    kernelVersion: 10.0.17763.1817 (WinBuild.160101.0800)
    longName: Microsoft Windows Server 2019 Datacenter
    osconfigAgentVersion: 20210901.00.0+win@1
    shortName: windows
    updateTime: '2021-09-12T22:14:35Z'
    version: 10.0.17763
    

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/v1/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/v1/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 OS inventory data from Cloud Asset Inventory

OS inventory management stores and forwards inventory and vulnerability report 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 and vulnerability report data from Cloud Asset Inventory, you need to complete the following setup:

For more information, see Viewing VM Manager data.

View vulnerability reports

Software vulnerabilities are weaknesses that can either cause an accidental system failure or result in malicious activity. For more information, see Vulnerability reports.

To view vulnerability report data, you can use any of the following options:

View vulnerability report using the gcloud CLI or API

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 compute os-config vulnerability-reports list \
       --location=ZONE
    

    Replace ZONE with the zone where the VM is located.

    Example

    gcloud 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 INSTANCE_ID returned from the previous step or the INSTANCE_NAME.

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

    Replace the following:

    • INSTANCE_NAME: the name for your VM
    • ZONE: the zone where the VM instance is located

    Example

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

    Example output

    ┌───────────────────────────────────────────────────────────────────┐
    │                          Vulnerabilities                          │
    ├──────────────────┬──────────┬───────────────┬─────────────────────┤
    │       CVE        │ SEVERITY │ CVSS_V3_SCORE │     CREATE_TIME     │
    ├──────────────────┼──────────┼───────────────┼─────────────────────┤
    │ CVE-2012-6655    │ LOW      │ 3.3           │ 2021-04-29T22:19:53 │
    │ CVE-2016-1585    │ MEDIUM   │ 9.8           │ 2021-04-29T22:19:53 │
    │ CVE-2016-2781    │ LOW      │ 6.5           │ 2021-04-29T22:19:53 │
    │ CVE-2019-7306    │ LOW      │ 7.5           │ 2021-04-29T22:19:53 │
    │ CVE-2020-13776   │ LOW      │ 6.7           │ 2021-04-29T22:19:53 │
    │ CVE-2021-31879   │ MEDIUM   │ 6.1           │ 2021-05-05T06:11:53 │
    └──────────────────┴──────────┴───────────────┴─────────────────────┘
    name: projects/384587888288/locations/us-west2-a/instances/29255009728795105/vulnerabilityReport
    updateTime: '2021-05-11T22:29:50'
    

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/v1/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/v1/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

View vulnerability reports using the Security Command Center dashboard

Security Command Center is Google Cloud's centralized vulnerability and threat reporting service.

If you are a Security Command Center premium tier user, you can access vulnerability report data for the operating systems that are running on VMs across your organization.

From the Findings tab in the Security Command Center dashboard, you can review the Common Vulnerabilities and Exposures (CVE) IDs for all identified vulnerabilities that are affecting your operating system.

For information about using the Security Command Center dashboard to access and review operating system vulnerability data, see VM Manager.

View vulnerability reports data from Cloud Asset Inventory

OS inventory management stores and forwards inventory and vulnerability report 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 and vulnerability report data from Cloud Asset Inventory, you need to complete the following setup:

For more information, see Viewing VM Manager data.

OS inventory management (earlier version)

If you are still using the earlier version of OS inventory management, expand the following section to review the instructions for the Google Cloud CLI.

OS inventory management (earlier version)

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
  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
  
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 are returned, review Information provided by OS inventory management.

What's next