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
- If you want to use the command-line examples in this guide, do the following:
- Install or update to the latest version of the Google Cloud CLI.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- Review OS Config quotas.
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 IDUSER_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
To view OS inventory data, use one of the following methods:
- Use the gcloud CLI or API
- Use Cloud Asset Inventory
View OS inventory data using the gcloud CLI or API
gcloud
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 locatedVIEW
: the type of output information that is required. The following view types are available:basic
: displays only OS informationfull
: 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
To view inventory details for a specific VM, run the
os-config inventories describe
command and specify theINSTANCE_ID
orINSTANCE_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 VMZONE
: the zone where the VM instance is locatedVIEW
: the type of output information that is required. The following view types are available:basic
: displays only OS informationfull
: 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
To view a list of inventory data for VMs in a specific zone, create a
GET
request to theprojects.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 IDZONE
: the zone where the OS policy assignments are located
To view inventory details for a specific VM, create a
GET
request to theprojects.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 IDZONE
: the zone where the VM instance is locatedINSTANCE
: 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:
- Set up VM Manager.
- On your Google Cloud project, enable the Cloud Asset Inventory API, the Google Cloud CLI, and assign permissions.
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:
- Use the gcloud CLI or API
- If you are a Security Command Center premium tier user, use the Security Command Center dashboard
- Use Cloud Asset Inventory
View vulnerability report using the gcloud CLI or API
gcloud
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
To view vulnerability report for a specific VM, run the
os-config vulnerability-reports describe
command specifying theINSTANCE_ID
returned from the previous step or theINSTANCE_NAME
.gcloud compute os-config vulnerability-reports describe INSTANCE_NAME \ --location=ZONE
Replace the following:
INSTANCE_NAME
: the name for your VMZONE
: 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
To view vulnerability reports for VMs in a specific zone, create a
GET
request to theprojects.locations.instances.vulnerabilityReports
method.GET https://osconfig.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/instances/–/vulnerabilityReports
Replace the following:
PROJECT_ID
: your project IDZONE
: the zone where the OS policy assignments are located
To view vulnerability report for a specific VM, create a
GET
request to theprojects.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 IDZONE
: the zone where the VM instance is locatedINSTANCE
: 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:
- Set up VM Manager.
- On your Google Cloud project, enable the Cloud Asset Inventory API, the Google Cloud CLI, and assign permissions.
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 VMsTo 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 RUNNINGView 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 VMZONE
: 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
- Learn more about OS inventory management.