Add Unique Asset Context with Custom Attributes in CSAM

There is no such thing as “too much context” when it comes to asset management.

Continuous discovery and comprehensive, normalized asset data create the foundation for streamlined risk detection and response. The more reliable asset data a security team has, the better it can operationalize an asset catalog.

Qualys Cybersecurity Asset Management (CSAM) provides comprehensive active and passive discovery methods, as well as integrations with third-party tools like ServiceNow. It can help you to build a reliable asset catalog that can be filtered and queried based on specific attributes.

Inevitably, every organization has practices or asset characteristics that cannot be captured by a Qualys agent, scan, or an API. And hence, we are now introducing custom attributes in CSAM.

In this blog post, we will cover the difference between custom attributes and Qualys tags, explain a few critical use cases, and walk you through the setup within CSAM.

Asset Tagging Vs. Custom Attributes

Qualys tags are used to categorize and organize data with low cardinality.

They represent discrete values used for grouping and categorizing similar items.

For example, Qualys tags can be used to categorize operating systems like “LINUX,” “WINDOWS,” by using a Dynamic Qualys Rule.

Tags enable efficient filtering and searching based on broad categories or characteristics. But there are certain fringe cases of valuable “high cardinality data” in every organization. It might be a procurement code for each asset that cannot be discovered through a scan, which is more specific than a Qualys tag can capture.

There may be critical assets in geolocation that are supported by a local IT group, but you need to be selective because it’s not every asset at the location.

Custom attributes in CSAM are catch-alls in such cases, security teams need actionable context for assets and have more flexibility and granularity in capturing or managing the data.

The Custom Attributes are available for searches via the Qualys Query Language (QQL).

Getting started with the Custom Attributes.

The only requirement for setting custom attributes on your assets is an active CyberSecurity Asset Management (CSAM) License.

You can add, edit, and remove custom attributes from an asset record.

There is a 20-custom field limit per asset.

Also, you can add business context through custom attributes, such as support groups, business units, or procurement tags (refer to Fig 3).

Custom Attributes via the Qualys APIs.

In some cases, you don’t need to enter custom attributes manually. This data might already exist in another source. In such cases, you can also add custom attributes to assets through the Qualys Public APIs.

Authentication

You will need valid Qualys credentials for authentication of your Qualys account.
To make API requests to the Qualys API servers, you need valid Qualys credentials for authentication.
The application must authenticate using Qualys account credentials (username and password) as part of the HTTP request. The credentials are transmitted using the “Basic Authentication Scheme” over HTTPS.

Endpoint Reference

This blog uses the API server URL for Qualys US Platform 4 (https://qualysapi.qg4.apps.qualys.com) in sample API requests.

If you’re on another platform, replace this URL with the appropriate server URL for your account.

If you’re on another platform, replace this URL with the appropriate server URL for your account.

Click here to identify your Qualys platform and get the API URL

qps/rest/2.0/update/am/asset

Body Params

Qualys CSAM has many ways to add, edit, and remove custom attributes. We’ve already covered leveraging custom attributes within an asset record. Here are a few other options at your disposal:

filters object

Filter to create a custom attribute on a single asset or multiple assets matching the filter criteria.

data object

Define the custom attributes and the operation to be performed.

Operations available for custom attributes:

• Add: To add new Custom Attributes key & value pair, or to update the value of an existing key.
• Set: To replace all existing Custom Attributes with the list of new attributes provided.
• Remove: To remove existing Custom Attributes based on key or/and value provided.

Examples

To “add” a new custom attribute on a single asset

curl 'https://qualysapi.qg4.apps.qualys.com/qps/rest/2.0/update/am/asset' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--user 'username:password!' \
--data '{
    "ServiceRequest": {
        "filters": {
            "Criteria": [
                {
                    "field": "id",
                    "operator": "EQUALS",
                    "value": "10057974"
                }
            ]
        },
        "data": {
            "Asset": {
                "customAttributes": {
                    "add": {
                        "CustomAttribute": [
                            {
                                "key": "MyFirstCustomAttribute",
                                "value": "QualysFunTeam"
                            },
                            {
                                "key": "MyAssetProcurementID",
                                "value": "QLYS 123456"
                            }
                        ]
                    }
                }
            }
        }
    }
}'

To “Set” custom attributes on multiple assets (Set will remove all existing Custom Attributes and set the new ones being sent)

curl 'https://qualysapi.qg4.apps.qualys.com/qps/rest/2.0/update/am/asset' \

--header 'Content-Type: application/json' \

--header 'Accept: application/json' \

--user username:password' \

--data '{

    "ServiceRequest": {

        "filters": {

            "Criteria": [

                {

                    "field": "name",

                    "operator": "CONTAINS",

                    "value": "EC2AMAZ-"

                }

            ]

        },

        "data": {

            "Asset": {

                "customAttributes": {

                    "set": {

                        "CustomAttribute": [

                            {

                                "key": "Decomission ETA",

                                "value": "Q4 2023"

                            },

                            {

                                "key": "Supported By",

                                "value": "IT Ops Group"

                            }

                        ]

                    }

                }

            }

        }

    }

}'

To “Remove” a single custom attribute from multiple assets

curl 'https://qualysapi.qg4.apps.qualys.com/qps/rest/2.0/update/am/asset' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--user username:password' \
--data '{
    "ServiceRequest": {
        "filters": {
            "Criteria": [
                {
                    "field": "id",
                    "operator": "EQUALS",
                    "value": "10057974"
                }
            ]
        },
        "data": {
            "Asset": {
                "customAttributes": {
                    "remove": {
                        "CustomAttribute": [
                           
                            {
                                "key": "Decomission ETA",
                                "value": "Q4 2023"
                            }
                        ]
                    }
                }
            }
        }
    }
}'

Operationalize Asset Data

While custom attributes in CSAM are not a primary source for asset context, they can be a valuable supplement to your robust asset catalog. The ability to filter, query, and create dashboard widgets for unique attributes within the organization helps to fine-tune your asset management strategy.

The key, as with all asset data in CSAM, is that it is operational. The Qualys Cloud Platform can leverage this data to prioritize and streamline remediation workflows for targeted assets. This will improve compliance, streamline risk reduction for high-value business assets, and help unify security with IT operations through a complete business context.