When managing systems, there are situations where you want to remove an asset, which could be a server, router, or laptop. One reason to manually remove an asset can be to show risk score changes without waiting for the configurable Asset Inactivity Limit to take effect.
All assets remain marked as active unless configured otherwise. This means that the risk score will continue to be calculated on the active assets. When assets are not active, their vulnerabilities are listed and included in your risk score. Thus the calculated risk score could be considered inaccurate, which would skew your view of risk within the business or prompt you to spend time remediating vulnerabilities on an asset that isn’t critical.
And of course you don’t want to report an inaccurate risk score to management.
You might consider deleting the asset, but deleting an asset requires a call to Kenna support. However marking an asset inactive is just an API invocation. You can mark an asset inactive in the UI as well.
This blog will present how to inactivate and reactivate an asset via the Kenna Security REST API; but first, let’s see how to list assets.
How to list active assets
The list_assets.py program lists assets’ ID, host name, and a note. Asset results can be filtered by a status parameter. Valid values are “active” or “inactive.” If no parameter is specified, then information on both “active” and “inactive” assets are returned from the API invocation.
The list assets API retrieves active assets with open vulnerabilities. Since this is the first time we’re going over some API code, let’s look at some basic bits of code. This code does not contain pagination; therefore only the first 500 assets can be listed. Pagination will be covered in a future blog.
All Kenna APIs use an API token or Key for authentication. Here the API key is obtained from an environmental shell variable.
Next the HTTP header is initialized with the Accept and X-Risk-Token keys. The Accept key advertises we will accept JSON. The customized key, X-Risk-Token, passes the API key to verify who you are.
Recall that this program can list separately or both active and inactive assets. We won’t discuss command line inputs, and proceed directly to function, list_assets(), which takes the parameters url and context. The url is used to invoke the API and context for annotating which assets are being displayed.
The list asset API is invoked and the assets are obtained.
Assets are sorted by asset ID. Then, asset ID, host name, and note are extracted for each asset and displayed if the asset’s status matches the script input parameters. Finally the number of assets are displayed.
Let’s take a look at the URLs that are used. For active assets, the URL is:
And for inactive assets, the URL is:
This sums to: “https://api.kennasecurity.com/assets?filter=inactive“.
With these URLs, list_assets() is called for each URL if applicable.
How to inactivate an asset
Now that we know how to list assets, let’s see how to manually inactivate an asset. Setting the status manually inactive means that no matter what information Kenna has on the asset, the status will be inactive.
Since we’ve gone over the basics in the list assets example, let’s look at the important bits of code in set_asset_inactive.py. The set_asset_inactive.py program can take two parameters, the asset ID, which is required, and an optional note so that you can notate why or when the asset is made ‘inactive’. If there is no note, it is cleared.
Since the code is modifying the asset, we use the update asset API, and it requires a body. The body is in JSON. As you can see the asset key in the JSON body contains the inactive flag and notes. This code only modifies the inactive flag and notes. The URL is forged with the server and asset ID to be modified.
How to reactivate an asset
If for some reason (reassigning the IP address), you want to reactivate the asset, you need to remove the manual override. Just manually setting the asset’s status to “active” means that Kenna will always see the asset active, which may not be what you want. Instead by setting the remove_override flag, the asset reverts to its natural state: able to transition automatically from active/inactive in response to activity or lack thereof.
The code in reactivate_asset.py is very similar to set_asset_inactive.py. The important difference is in the body that will be sent to update the asset.
As you can see, the only difference is the remove_override flag that is set instead of the inactive flag.
First let’s list some assets:
Now inactive asset with asset ID 3 and a note on when it was compromised.
List again to verify. You might have to wait approximately 30 seconds before the change can be seen.
The vulnerability has been fixed, and now reactivate the asset with the asset ID. A note was added to state when the asset was reactivated.
List the assets to verify. You might have to wait approximately 30 seconds before the change can be seen.
So now you know how to list, inactivate, and reactivate assets via Kenna Security’s REST APIs. Developing a program might be more user friendly than clicking through the Kenna GUI. The code could be modified to take in multiple assets to inactivate, thus saving GUI clicks. If you’re interested in playing with these samples, they’re located in a Kenna Security blog_samples repo in the assets directory.