Migrate AnyConnect HostScan 4.3.x to 4.6.x and Later
Migrate AnyConnect HostScan 4.3.x to 4.6.x and Later
This migration process is necessary when upgrading HostScan from version 4.3.x or earlier to version 4.6.x or later. It is a one-time procedure, necessary because of internal library changes that occurred with release 4.6.x and later. Migration is supported in ASDM 7.9.2 and later ASDM releases. You cannot migrate if you are running earlier versions of ASDM.
Note |
If you have a HostScan version earlier than 4.3.05050, you must upgrade to 4.3.05050, or a later 4.3.x version, prior to starting this migration process. |
Beginning with macOS Catalina release (10.15.x), the operating system will no longer support executing 32-bit binaries, which are included in HostScan package 4.3.x and earlier. End users who attempt to connect from macOS Catalina to ASA headends running HostScan package 4.3.x and earlier will not be able to successfully establish VPN connections. If a device running macOS Catalina release attempts to connect with ASA headends running HostScan package 4.3 and earlier, a posture assessment failed popup appears. Due to the above-mentioned Apple enforcement, all HostScan versions prior to 4.7.x must be migrated to HostScan 4.8.00175 or later .
This migration guides you through the transition of antivirus (AV), antispyware (AS), and firewall (FW) policies in 4.3.x and earlier, to the new antimalware (AM) and firewall (PFW) policies. The new policy format is needed for HostScan 4.6.x and later.
Before you begin
In HostScan 4.6.x and later, the procedure to check for ANY antimalware (endpoint.am) and/or ANY personal firewall (endpoint.pfw) is now accomplished with LUA scripts. Refer to the supporting LUA Procedures for HostScan 4.6 and Later section.
SUMMARY STEPS
- Initiate the HostScan Upgrade, making it part of the running configuration.
- Remove incompatible policies from the running configuration.
- Close and restart ASDM to reset the configuration.
- Complete the HostScan upgrade (at Configuration > Remote Access VPN > Secure Desktop Manager > HostScan Image).
- Close and restart ASDM to reset the configuration.
- Determine the DAP Polices that require migration.
- Migrate the DAP Policies.
- Determine which advanced endpoint assessment policies require migration.
- Migrate the Advanced Endpoint Assessment (AEA) Policies. Repeat this step until all policies are migrated.
- Save the migrated AEA policies.
- Remove and re-add any defined LUA scripts.
- Migration is complete. You must close and restart ASDM to reset the configuration.
DETAILED STEPS
Step 1 |
Initiate the HostScan Upgrade, making it part of the running configuration. |
Step 2 |
Remove incompatible policies from the running configuration. |
Step 3 |
Close and restart ASDM to reset the configuration. You must restart ASDM at this point. Do not skip this step. |
Step 4 |
Complete the HostScan upgrade (at Configuration > Remote Access VPN > Secure Desktop Manager > HostScan Image). Install the HostScan 4.6.x or later Package again. This time, complete the procedure including saving the configuration. |
Step 5 |
Close and restart ASDM to reset the configuration. Again, you must restart ASDM at this point. Do not skip this step. |
Step 6 |
Determine the DAP Polices that require migration. Go to Configuration > Remote Access VPN > Network (Client) Access > Dynamic Access Policies to complete the migration. A Migrate Policies action appears and is enabled only when the HostScan image version is greater than or equal to 4.6.x or later. If no attributes need migration, these buttons appear, but are disabled. |
Step 7 |
Migrate the DAP Policies. |
Step 8 |
Determine which advanced endpoint assessment policies require migration. |
Step 9 |
Migrate the Advanced Endpoint Assessment (AEA) Policies. Repeat this step until all policies are migrated. |
Step 10 |
Save the migrated AEA policies. Click OK to return to the HostScan screen, and then Apply All. |
Step 11 |
Remove and re-add any defined LUA scripts. Existing LUA scripts will not work with HostScan 4.6.x or later. They must be manually removed from your configuration and re-added. Keep in mind the following new guidelines:
|
Step 12 |
Migration is complete. You must close and restart ASDM to reset the configuration. |
Fallback AnyConnect HostScan 4.6.x or Later to 4.3.x
These files contain the configuration and policies that were in place when running the older HostScan release. They were created and saved in the disk0/HostScan_Migration_Backup directory when you installed the newer HostScan release.
This procedure guides you through a fallback to your previous HostScan release of 4.3.x or earlier. It restores the antivirus (AV), antispyware (AS), and firewall (FW) policies that were in place before attempting a migration to HostScan 4.6.x or later.
Before you begin
In order to be able to fallback to the earlier HostScan release, you must have the following backup files.
- dap-bkp.xml
- data-bkp.xml
- data-record-bkp.txt
SUMMARY STEPS
- Save the configuration and policies that were associated with the older HostScan release from the backup directory.
- Uninstall the newer release of HostScan, 4.6.x or later.
- Save any configuration and policies that are associated with this now uninstalled, newer version of HostScan.
- Install the old version of HostScan to which you are falling back.
- Restore the back-up configuration and policies.
- Close and restart ASDM.
DETAILED STEPS
Step 1 |
Save the configuration and policies that were associated with the older HostScan release from the backup directory. These are the configuration and policies that were in place before you upgraded. They were created when you initially installed the newer HostScan release. They are necessary to restore your appliance to its previous state.
|
Step 2 |
Uninstall the newer release of HostScan, 4.6.x or later. |
Step 3 |
Save any configuration and policies that are associated with this now uninstalled, newer version of HostScan. |
Step 4 |
Install the old version of HostScan to which you are falling back. Allow this to finish and restart ASDM before proceeding. |
Step 5 |
Restore the back-up configuration and policies.
|
Step 6 |
Close and restart ASDM. You must do this to finish the process. |
Supporting Procedures
Install and Enable HostScan on the ASA
Use this procedure to upload, or upgrade, and enable a new HostScan image on the ASA. This image can enable the HostScan functionality for AnyConnect.
You can specify a standalone HostScan package.
Note |
You do not need to restart the security appliance after you install or upgrade HostScan; however, you must exit and restart Adaptive Security Device Manager (ASDM) to access Secure Desktop Manager. |
Before you begin
Note |
If you are attempting to upgrade to HostScan version 4.6.x or later from a 4.3.x version or earlier, you will receive an error message due to the fact that all existing AV/AS/FW DAP policies and LUA script(s) that you have previously established are incompatible with HostScan 4.6.x or later. You must perform a one-time migration procedure to adapt your configuration. This procedure involves leaving this dialog box to migrate your configuration for compatibility with HostScan 4.6.x and later before saving this configuration. Abort this procedure and refer to the AnyConnect HostScan 4.3.x to 4.6.x or Later Migration Guide for detailed instructions. Briefly, migration involves navigating to the ASDM DAP policy page to review and manually delete the incompatible AV/AS/FW attributes, and then reviewing and rewriting LUA scripts. |
Procedure
Step 1 |
Download the hostscan_version-k9.pkg file to your computer. |
Step 2 |
Open ASDM and choose . ASDM opens the HostScan Image panel. |
Step 3 |
Click Upload to prepare to transfer a copy of the HostScan package from your computer to a drive on the ASA. |
Step 4 |
In the Upload Image dialog box, click Browse Local Files to search for the HostScan package on your local computer. |
Step 5 |
Select the hostscan_version-k9.pkg file you downloaded above and click Select. The path to the file you selected is in the Local File Path field and the Flash File System Path field reflects the destination path of the HostScan package. If your ASA has more than one flash drive, you can edit the Flash File System Path to indicate another flash drive. |
Step 6 |
Click Upload File. ASDM transfers a copy of the file to the flash card. An Information dialog box displays the following message:
|
Step 7 |
Click OK. |
Step 8 |
In the Use Uploaded Image dialog, click OK to use the HostScan package file you just uploaded as the current image. |
Step 9 |
Check Enable Host Scan if it is not already checked. |
Step 10 |
Click Apply. |
Step 11 |
From the File menu, choose Save Running Configuration To Flash. |
Endpoint Attribute Definitions
The following endpoint selection attributes are available for DAP use.The Attribute Name field shows you how to enter each attribute name in a LUA logical expression, used in the Advanced area in Dynamic Access Policy Selection Criteria pane. The label variable identifies the application, filename, process, or registry entry.
Attribute Type |
Attribute Name |
Source |
Value |
Max String Length |
Description |
---|---|---|---|---|---|
Antimalware (Requires Cisco Secure Desktop) |
endpoint.am["label"].exists |
Host Scan |
true |
— |
Antimalware program exists |
endpoint.am["label"].version |
string |
32 |
Version |
||
endpoint.am["label"].description |
string |
128 |
Antimalware description |
||
endpoint.am["label"].lastupdate |
integer |
— |
Seconds since update of antimalware definitions |
||
Personal firewall (Requires Secure Desktop) |
endpoint.pfw["label"].exists |
Host Scan |
true |
— |
The personal firewall exists |
endpoint.pfw["label"].version |
string |
string |
Version |
||
endpoint.pfw["label"].description |
string |
128 |
Personal firewall description |
||
AnyConnect (Does not require Cisco Secure Desktop or Host Scan) |
endpoint.anyconnect. clientversion |
Endpoint |
version |
— |
AnyConnect client version |
endpoint.anyconnect. platform |
string |
— |
Operating system on which AnyConnect client is installed |
||
endpoint.anyconnect. platformversion |
version |
64 |
Version of operating system on which AnyConnect client is installed |
||
endpoint.anyconnect. devicetype |
string |
64 |
Mobile device type on which AnyConnect client is installed |
||
endpoint.anyconnect. deviceuniqueid |
64 |
Unique ID of mobile device on which AnyConnect client is installed |
|||
endpoint.anyconnect. macaddress |
string |
— |
MAC Address of device on which AnyConnect client is installed Must be in the format xx-xx-xx-xx-xx-xx, where 'x' is a valid hexadecimal character |
||
Application |
endpoint.application. clienttype |
Application |
string |
— |
Client type: CLIENTLESS ANYCONNECT IPSEC L2TP |
Device |
endpoint.device. hostname |
Endpoint |
string |
64 |
Host Name only. Not FQDN |
endpoint.device.MAC |
string |
— |
Mac Address for a network interface card. Only one Mac address per entry Must be in the format xxxx.xxxx.xxxx where x is a hexadecimal character. |
||
endpoint.device.id |
string |
64 |
BIOS Serial Number. The number format is manufacturer-specific. There is no format requirement |
||
endpoint.device.port |
string |
— |
TCP port in listening state You can define a single port per line An integer between 1 and 65535 |
||
endpoint.device. protection_version |
string |
64 |
Version of Host Scan image they are running |
||
endpoint.device. protection_extension |
string |
64 |
Version of Endpoint Assessment (OPSWAT) |
||
File |
endpoint.file["label"].exists |
Secure Desktop |
true |
— |
The files exists |
endpoint.file[“label”]. endpointid |
|||||
endpoint.file["label"]. lastmodified |
integer |
— |
Seconds since file was last modified |
||
endpoint.file["label"]. crc.32 |
integer |
— |
CRC32 hash of the file |
||
NAC |
endpoint.nac.status |
NAC |
string |
— |
User defined status string |
Operating System |
endpoint.os.version |
Secure Desktop |
string |
32 |
Operating system |
endpoint.os.servicepack |
integer |
— |
Service pack for Windows |
||
Policy |
endpoint.policy.location |
Secure Desktop |
string |
64 |
Location value from Cisco Secure Desktop |
Process |
endpoint. process["label"].exists |
Secure Desktop |
true |
— |
The process exists |
endpoint. process["label"].path |
string |
255 |
Full path of the process |
||
Registry |
endpoint. registry["label"].type |
Secure Desktop |
dword string |
— |
dword |
endpoint. registry["label"].value |
string |
255 |
Value of the registry entry |
||
VLAN |
endoint.vlan.type |
CNA |
string |
— |
VLAN type: ACCESS AUTH ERROR GUEST QUARANTINE ERROR STATIC TIMEOUT |
Create Additional DAP Selection Criteria in DAP Using LUA
This section provides information about constructing logical expressions for AAA or endpoint attributes. Be aware that doing so requires sophisticated knowledge of LUA. You can find detailed LUA programming information at http://www.lua.org/manual/5.1/manual.html.
In the Advanced field you enter free-form LUA text that represents AAA and/or endpoint selection logical operations. ASDM does not validate text that you enter here; it just copies this text to the DAP policy file, and the ASA processes it, discarding any expressions it cannot parse.
This option is useful for adding selection criteria other than what is possible in the AAA and endpoint attribute areas above. For example, while you can configure the ASA to use AAA attributes that satisfy any, all, or none of the specified criteria, endpoint attributes are cumulative, and must all be satisfied. To let the security appliance employ one endpoint attribute or another, you need to create appropriate logical expressions in LUA and enter them here.
The following sections provide detailed explanations of creating LUA EVAL expressions, as well as examples.
Syntax for Creating LUA EVAL Expressions
Note |
If you must use Advanced mode, we recommend that you use EVAL expressions whenever possible for reasons of clarity, which makes verifying the program straightforward. |
EVAL(<attribute> , <comparison>, {<value> | <attribute>}, [<type>])
<attribute> |
AAA attribute or an attribute returned from Cisco Secure Desktop, see Endpoint Attribute Definitions for attribute definitions |
|
<comparison> |
One of the following strings (quotation marks required) |
|
“EQ” |
equal |
|
“NE” |
not equal |
|
“LT” |
less than |
|
“GT” |
greater than |
|
“LE” |
less than or equal |
|
“GE” |
greater than or equal |
|
<value> |
A string in quotation marks that contains the value to compare the attribute against |
|
<type> |
One of the following strings (quotation marks required) |
|
“string” |
case-sensitive string comparison |
|
“” |
case-insensitive string comparison |
|
“integer” |
number comparison, converts string values to numbers |
|
“hex” |
number comparison using hexadecimal values, converts hex string to hex numbers |
|
“version” |
compares versions of the form X.Y.Z. where X, Y, and Z are numbers |
LUA Procedures for HostScan 4.6 and Later
LUA Script for 'ANY' Antimalware (endpoint.am) with Last Update
Use the following LUA script to check for 'ANY' antimalware product/vendor (endpoint.am). Modifications may apply to accommodate a different Last Update interval. The following example shows how a Last Update must have been performed in <30 days (noted as 2592000 seconds).
assert(function()
for k,v in pairs(endpoint.am) do
if(EVAL(v.activescan, "EQ", "ok", "string")and EVAL (v.lastupdate, "LT", "2592000", "integer"))
then
return true
end
end
return false
end)()
LUA Script for 'ANY' Personal Firewall
Use the following LUA script to check for 'ANY' firewall product/vendor (endpoint.pfw):
assert(function()
for k,v in pairs(endpoint.pfw) do
if (EVAL(v.enabled, "EQ", "ok", "string")) then
return true
end
end
return false
end)()
Additional LUA Functions
When working with dynamic access policies, you might need additional flexibility of match criteria. For example, you might want to apply a different DAP based on the following:
-
CheckAndMsg is a LUA function that you can configure DAP to call. It generates a user message based on a condition.
-
Organizational Unit (OU) or other level of the hierarchy for the user object.
-
Group names that follow a naming convention with many possible matches might require the ability to use a wildcard.
You can accomplish this flexibility by creating a LUA logical expression in the Advanced section of the DAP pane in ASDM.
The DAP CheckAndMsg Function
The ASA displays the message to the user only when the DAP record containing the LUA CheckAndMsg function is selected and results in a connection termination.
The syntax of the CheckAndMsg function follows:
CheckAndMsg(value, “<message string if value is true>”, “<message string if value if false>”)
Be aware of the following when creating CheckAndMsg functions:
-
CheckAndMsg returns the value passed in as its first argument.
-
Use the EVAL function as the first argument if you do not want to use string comparison. For example:
(CheckAndMsg((EVAL(...)) , "true msg", "false msg"))
CheckandMsg returns the result of the EVAL function, and the security appliance uses it to determine whether to choose the DAP record. If the record is selected and results in termination, the security appliance displays the appropriate message.
OU-Based Match Example
DAP can use many attributes returned from an LDAP server in a logical expression. See the DAP trace section for example output of this, or run a debug dap trace.
The LDAP server returns the user Distinguished Name (DN). This implicitly identifies where in the directory the user object is located. For example, if the user DN is CN=Example User, OU=Admins, dc=cisco, dc=com, this user is located in OU=Admins,dc=cisco,dc=com. If all administrators are in this OU, or any container below this level, you can use a logical expression to match this criteria as follows:
assert(function()
if ( (type(aaa.ldap.distinguishedName) == "string") and
(string.find(aaa.ldap.distinguishedName, "OU=Admins,dc=cisco,dc=com$") ~= nil) ) then
return true
end
return false
end)()
In this example, the string.find function allows for a regular expression. Use the $ at the end of the string to anchor this string to the end of the distinguishedName field.
Group Membership Example
You can create a basic logical expression for pattern matching of AD group membership. Because users can be members of multiple groups, DAP parses the response from the LDAP server into separate entries in a table. You need an advanced function to accomplish the following:
-
Compare the memberOf field as a string (in the event the user belongs to only one group).
-
Iterate through each returned memberOf field if the returned data is of type "table."
The function we have written and tested for this purpose is shown below. In this example, if a user is a member of any group ending with "-stu," they match this DAP.
assert(function()
local pattern = "-stu$"
local attribute = aaa.ldap.memberOf
if ((type(attribute) == "string") and
(string.find(attribute, pattern) ~= nil)) then
return true
elseif (type(attribute) == "table") then
local k, v
for k, v in pairs(attribute) do
if (string.find(v, pattern) ~= nil) then
return true
end
end
end
return false
end)()
Deny Access Example
You can use the following function to deny access in the absence of an antimalware program. Use it with a DAP that has Action set to terminate.
assert(
function()
for k,v in pairs(endpoint.am) do
if (EVAL(v.exists, "EQ”, "true", "string")) then
return false
end
end
return CheckAndMsg(true, "Please install antimalware software before connecting.", nil)
end)()
If a user lacking an antimalware program attempts to log in, DAP displays the following message:
Please install antimalware software before connecting.
Examples of DAP EVAL Expressions
Study these examples for help in creating logical expressions in LUA:
Description | Example |
---|---|
Endpoint LUA checks for Windows 10 |
|
Endpoint LUA checks for a match on CLIENTLESS OR CVC client types. |
|
Endpoint LUA checks if a single Antimalware program Symantec Enterprise Protection is installed on the user PC, displays a message if it is not. |
|
Endpoint LUA checks for McAfee Endpoint Protection versions 10 to 10.5.3 and versions above 10.6. |
|
Endpoint LUA checks if McAfee Antimalware definitions have been updated within the last 10 days(864000 sec) and displays a message if an update is needed. |
|
Check for a specific hotfix after debug dap trace returns: endpoint.os.windows.hotfix["KB923414"] = "true"; |
|
Check for Antimalware Programs and Provide Messages
You can configure messages so that the end users are aware of and able to fix problems with their antimalware software. If access is allowed, the ASA displays all messages generated in the process of DAP evaluation on the portal page. If access is denied, the ASA collects all messages for the DAP that caused the "terminate" condition and displays them in the browser on the logon page.
The following example shows how to use this feature to check on the status of Symantec Endpoint Protection.
-
Copy and paste the following LUA expression into the Advanced field of the Add/Edit Dynamic Access Policy pane (click the double arrow on the far right to expand the field).
(CheckAndMsg(EVAL(endpoint.am["538"].description,"EQ","Symantec Endpoint Protection","string") and EVAL(endpoint.am["538"].activescan,"NE","ok","string") "Symantec Endpoint Protection is disabled. You must enable before being granted access", nil))
-
In that same Advanced field, click the OR button.
-
In the Access Attributes section below, in the leftmost tab, Action, click Terminate.
-
Connect from a PC that has Symantec Endpoint Protection installed, but has Symantec Endpoint Protection disabled. The expected result is that the connection is not allowed and that the user will be presented the message "Symantec Endpoint Protection is disabled. You must enable before being granted access."
Check for Antimalware Programs and Definitions Older than 2 Days
This example checks for the presence of the Symantec and McAfee antimalware programs, and whether the virus definitions are older than 2 days (172,800 seconds). If the definitions are older than 2 days, the ASA terminates the session with a message and links for remediation. To accomplish this task, perform the following steps.
-
Copy and paste the following LUA expression into the Advanced field of the Add/Edit Dynamic Access Policy pane:
(CheckAndMsg(EVAL(endpoint.am["538"].description,"EQ","Symantec Endpoint Protection","string") and EVAL(endpoint.am["538"].lastupdate,"GT","172800","integer"), "Symantec Endpoint Protection Virus Definitions are Out of Date. You must run LiveUpdate before being granted access", nil)) or (CheckAndMsg(EVAL(endpoint.am["1637"].description,"EQ","McAfee Endpoint Security","string") and EVAL(endpoint.am["1637"].lastupdate,"GT","172800","integer"), "McAfee Endpoint Security Virus Definitions are Out of Date. You must update your McAfee Virus Definitions before being granted access", nil))
-
In that same Advanced field, click AND.
-
In the Access Attributes section below, in leftmost tab Action, click Terminate.
-
Connect from a PC that has Symantec and McAfee antimalware programs with versions that are older than 2 days.
The expected result is that the connection is not allowed and that the user is presented a message that the virus definitions are out of date.