9 – Security
All parameters associated with security, including external use of the RefTracker API, are collected in this 9.x Security group of parameters.
RefTracker System key
9.1 System key:
This key can be used for multiple purposes because it identifies an instance of RefTracker with a unique key.
Although it is only used by R2R at the moment (see more about this below), it may be used elsewhere in the future.
Background process IP addresses
Parameter 9.5 is used to record any additional IP addresses used for RefTracker background services.
RefTracker checks that calls to its background processes, such as ReftSevice, come from the same server as the RefTracker application, in order to ensure they are not coming from external bad players. However, some customers have load balancing and other server reliability structures in place that mean that these calls may come from other IP addresses (comma separate them, if you need to enter more than one IP address here). In-house customers may need to set this parameter, if ReftService fails to run on your configuration.
RefTracker to RefTracker security setup
RefTracker to RefTracker (R2R) requests are checked for security, and for any viruses in attachments. To implement the security, parameter 9.1 sets a key that must be returned by the system sending the R2R request. In this way requests can only come from senders who have been approved to send.
It works like this for sending questions:
When a question is sent, the XML record includes the following:
Datetime that the question was created
The sender system key (parameter 9.1)
The number of expected attachments
The IP address of the sender
A one-time unique transaction key -created by the receiver
When the question is received, the receiver will check that a system key is present in the record.
The receiver’s response to the sender will include the one-time transaction key that proves it was legitimate.
For sending attachments, the sender will send the one time transaction key and the system key.
The receiver will check the one time transaction key matches.
For further security, the system key, and IP address used to send the question are also checked for a match. Further, a check is made that the question was created less than 10 minutes ago.
The parameter 9.10 checks are also made, but are not sufficient on their own.
9.10 R2R acceptable domains:
This parameter allows your organisation to control the organisations that will be able to send requests to your organisation using the RefTracker to RefTracker Redirect function – this function will automatically create a new question in your RefTracker system when the organisations you allow here send you details of a question using their Third party redirect function and the RefTracker to RefTracker transfer method. Only organisations listed in this parameter are allowed to use the exchange/R2R.asmx web service that provides the RefTracker to RefTracker functionality.
We recommend running your RefTracker web under https:// if you use R2R, as this provides additional security.
To allow an organisation to send questions to you using RefTracker to RefTracker you need to add the domain of that organisation’s RefTracker system into this box followed by a space and then the System key from that organisation’s parameter 9.1.
List one domain per line only (end with a space or, preferably, a new line). The entry for an organisation that accesses their RefTracker system at http://abc.altarama.com/staff.aspx would be: http://abc.altarama.com followed by a space then that organisation’s System key.
To do this, ask the system that wants to send requests to you, to provide the value in their parameter 9.1. You then need to add that value to that site’s domain in parameter 9.10, space separated.
Above is an example: the patchaus.altarama.com RefTracker system wants to send requests R2R to the english.altarama.com RefTracker system.
Parameter 9.1 in the patchaus system looks like this:
To add the mandatory extra security to the English.altarama.com system we add a space to the https://patchaus.altarama.com entry in parameter 9.10, and then paste in the key that our patchaus contact has given us from their parameter 9.1 shown above. Here’s an example from the system that wants to receive from patchaus.altarama.com, where the parameter 9.1 from the patchaus system is as highlighted in yellow:
Any organisation that you allow here ALSO needs to be defined in the Organisation code table as a RefTracker to RefTracker type entry.
And to complete the setup, you will also need to check that the RefTracker to RefTracker request form is set up as you want it. The form controls attributes of questions transferred in this way, such as their target response date and allocation. Until you add at least one domain to this parameter no one will be able to send questions to you by the RefTracker to RefTracker method – in other words, this feature is turned off until you turn it on here. More information about sending requests to other RefTracker systems using the RefTracker to RefTracker web service is provided in the “Redirecting questions to other RefTracker systems” part of the Staff manual page about the Redirect function. Information for System administrators about R2R set up is also in that section.
Password Management
9.30 Allow blank password: In order to protect the integrity of hosted systems, blank passwords are not allowed on hosted systems. If you have an in-house system and would like to allow blank passwords, please contact Altarama about allowing this feature for your in-house system.
9.31 Enforce password change: Set this parameter to “No” if you do not want to force users to change their passwords. If this parameter is set to “Yes”, all users will need to change their passwords according to the policy chosen in Parameters 9.32, 33, and 34. If a user’s password has expired and they can change their own password, they are presented with their My preferences page so they can immediately make the change. If the grace period has expired they will not be able to do anything else in RefTracker until they correctly change their password. If a user’s password has expired and they cannot change their own password, the user will be allowed in. The Active System administrator will be sent an Alert email asking them to provide a new password for this user’s signon (and let the user know about it). So, to enforce your password policy it is critical that you change the user’s password whenever you receive one of these emails – it may mean that someone who should no longer be using your system, is using it!
9.32 Password expiry: If parameter 9.31 has been set to “Yes” select the time period after which the password must be changed (how often it needs to be changed).
9.33 Password expiry grace period: If parameter 9.31 has been set to “Yes” select the time period after expiry of their password that staff will be allowed in. If a user tries to log in during the grace period they will be shown their My preferences screen that allows them to change their password, or, if they do not have permission to do that, an email will be sent to the System administrator advising them that the password for that user needs to be changed.
9.34 Password strength: Leave this parameter as “Not controlled” if you do not want to force users to use a password of a particular strength.
“Regular” – requires at least 8 characters including at least two character types
“Strong” – requires at least 10 characters including at least three character types
“Very strong” – requires at least 14 characters including at least four character types
The four possible character types are:
Lower case, Upper case, Numbers, punctuation/symbols.
An attempt to use a password that is not strong enough will result in a validation message to the user.
The password policy you set here will show in all places where staff are asked to create a new password.
Parameters 9.35 and 9.36 provide a system that allows you to specify controls on how many times a user can unsuccessfully try to log into your RefTracker system. This will prevent bad players from continually trying different passwords to get in.
9.35 Password attempts: sets the number of unsuccessful login attempts that a user can make in the parameter 9.36 period of time, before the user is locked out for the parameter 9.36 period of time. Default for this parameter is 5. Decrease this parameter to increase the security this function provides. Set it to zero to turn off this functionality.
9.36 Failed login lock: sets the period of time for which a user will be locked out if they make parameter 9.35 number of unsuccessful login attempts in the parameter 9.36 period of time. Default for this parameter is 4 hours. Increase this parameter to increase the security this function provides.
An unsuccessful login attempt is defined as any login attempt where the password is incorrect for the user name provided.
If a user provides an incorrect password they will be warned about the number of unsuccessful login attempts that remain before they will be locked out.
When the parameter 9.35 number of attempts have been made within the parameter 9.36 time period from the first invalid attempt, the user will be locked out for the parameter 9.36 period of time from that last invalid attempt made. So, that means that if parameter 9.35 is three and parameter 9.36 is 1 hour, the user will be locked out for an hour immediately after a third unsuccessful attempt has been made within an hour of the first unsuccessful attempt.
In the example in the screen print below, the user’s third unsuccessful attempt was at 11:58am, so, the jw user will not be allowed to log in, even if they provide the right password until after 12:58pm.
If the user had only had two unsuccessful attempts, without a following successful attempt, the unsuccessful login count would also be cleared at 12:58pm.
System administrators can also clear locked accounts by going to System>Users full and using the Unlock users function in Admin mode. In that page locked users are indicated by a red “head and shoulders” icon.
API security parameters overview
If you do not use the RefTracker Widget, or RefChatter to RefTracker interface (that both use the API), or the published API for a custom interface, all of the 9.5x parameters should be unticked. This prevents use of the API and is the default setup for new RefTracker systems.
If you do use the RefTracker Widget, or RefChatter to RefTracker interface, or the published API for a custom interface, the tick boxes in this screen enable/disable each described API method. Only tick a method if you need to use that API method.
If the key is empty then the method will work without any key being sent but it is not secure. This should only be used by customers in secure environments as it is not secure.
If the APIkey is set, then the key must be present in the parameters sent in your API calls. If an API method (including the widget, and RefChatter interface, that use the API) is being used outside a secure environment, it is very important that its APIkey is set and used, to prevent use by bad players.
These security APIkeys (9.50-56) can be copied so that a given customer can use the same key for more than one API method (allowing them to use the same key for all methods used by their custom interface/s).
Select the key that you want to use as the common key. Right mouse click and use the context menu to copy the key.
Then you can select the key you want to paste it into, right click and select paste. Be sure to use Update to save your change. Please note that ctrl c and ctrl v cannot be used for this copy and paste process – you MUST use right click and the context menu for this copy and paste.
This copy capability is restricted to existing keys as the key must fit the profile pattern of an API key. You cannot copy just any value into these keys.
If you are developing an API application, we recommend that you utilise this copy function to set all 9.50-56 parameters that you need to use to the same value, so that you can use the same APIkey value for this application, and any other future applications.
See the API Documentation help page, for full instructions about how to use these parameters and keys with your API methods.
In summary:
Parameter 9.50 is used with the quickQuestion method that is used in the RefTracker Widget and similar applications that you might develop to add simple requests.
Parameter 9.51 is used with the AddQuestion method that is used internally be the RefTracker to RefTracker functionality, and in applications you might develop using the RefTracker API that send requests to RefTracker.
Parameter 9.52 is used with the getQuestion method that is used to retrieve information about a specific request, and make that information available to another application.
Parameter 9.53 is used with the search method that is used to retrieve requests by a large number of different attributes of those requests in order to make those requests known to other applications.
Parameter 9.54 is used with the Extract method that is used in conjunction with the RefTracker Data extract function to be able to extract an XML record of data about each request in a selected range of requests in your RefTracker system, for use in other applications.
Parameter 9.55 is used with the clientAction method that can be used by any applications that you might develop to make the “View my requests” screen available in other applications.
Parameter 9.56 is used with the requestForms, requestFormXSD, requestFormXMLExample that are used to find information about the format of the data required when adding a question to a RefTracker system using the chosen request form, in any application that you might develop using the API.
It is also used with the categories API method that provides information about the frequency of use of categories in your RefTracker system, for use in other applications.
And it is also used by the codetable method that provides information about the values that are set in the selected code table in your RefTracker system, for use of that code table in other applications.
** RefTracker Widget customer implementation instructions:
Parameter 9.50 needs to be set and the key used in your RefTracker widget setup, if you use the RefTracker widget. See the Managing the RefTracker widget help page, for full instructions about how to use this parameter and key.
** RefChatter to RefTracker interface implementation instructions:
The RefChatter to RefTracker interface uses the API, and so, needs this security applied.
To implement the additional security you MUST do the following:
i. Go to System>Parameters>9 – Security
ii. Enable and set an APIkey for parameters 9.51 and 9.56
iii. Select the apikey at parameter 9.56 by right clicking and selecting Copy, and paste it over the key for 9.51 using right click and Paste.
iv. Click Update to save your changes.
v. Then copy the key used in parameters 9.51 and 9.56 to the RefTrackerAPIkey field in RefChatter and save it. To find where to paste this key, go to your RefChatter Dashboard, and from the right hand menu select the RefTracker interface icon. In that screen click on the Edit settings gear icon.
In the screen that displays, past the RefTracker apikey in the line that says “security key”, and click “save settings”.
Your RefChatter to RefTracker interface will not work while you are doing the above steps so please do them out of RefChatter and RefTracker operating hours.
** RefTracker API custom interface implementation instructions:
All the API calls (except addQuestion) use a JSON string and need the appropriate API key for the appropriate API method, from these 9.x parameters page, included in the call in order to prevent unauthorised use.
Add the “apikey” parameter like this – https://currentrelease.altarama.com/exchange/api.asmx/requestFormXSD?parameters={“apikey”:”vDxzDLvz7kO7AUBbyTsp6Q”,”formkey”:”basic”}The “apikey” does not need to be the first parameter as shown in this example.
See the API Documentation help page, for full instructions about how to use these parameters and keys with your API methods.
URL security
This group of parameters controls whether URL’s entered into your RefTracker will be checked by the Google safe browser service to ensure that they are not known to be malicious sites. As desirable as it is to have URL’s provided by both staff and client’s, checked to ensure they are not malicious sites, this service may not always be accessible or operating. Some organisations may not want the lack of this service to impact on their ability to deliver URL’s, and some will not want to deliver URL’s that have not been checked. You can choose how you want your system to operate in this situation, and you can exclude domains that you know will not be malicious links (such as you own domain) so they can always be delivered, even when the lookup service is temporarily unavailable.
9.70 Scan for unsafe URL’s: Set this parameter to “Disabled” if you do not want to use this service. Customer using securely in-house only systems, may want to select this option, but we recommend it is not used except to deal with extended service outages.
Set this to “Enabled (relaxed)” (default) to have all URL’s checked against Google safe browsing to ensure that they do not point to a known malicious site, but if the safe browsing service is temporarily unavailable, deliver the URL anyway. An error message will be sent to your System administrator, so they know that they know the service is not operating, after 10 minutes, then 20 minutes, the 30 minutes, then 1 hour, then 90 mins, and if the error is still occurring every 90 minutes after that.
Set this to “Enabled (strict)” to have all URL’s checked against Google safe browsing to ensure that they do not point to a known malicious site, and if the service is unavailable replace all URL’s except those using the domains in parameter 9.72 with “* UNSAFE URL REMOVED *” and send an error to the System administrator, so they know that they know the service is not operating, after 10 minutes, then 20 minutes, the 30 minutes, then 1 hour, then 90 mins, and if the error is still occurring every 90 minutes after that.
If this service is enabled, all URL’s entered into RefTracker by staff or clients, are checked against the Google safe browsing API as it is loaded to the database. Any URL that the service indicates as being known to present malicious information will be automatically removed and replaced with “* UNSAFE URL REMOVED *”.
You can see an example of this by entering http://altarama.malware (not an actual malware site – just used for testing).
If RefTracker detects a badly formatted URL, the invalid formatting means it cannot be checked against Google safe browser, so it is preceded by the note “*WARNING – malformed URL : ” to indicate that, if it happens to bring up a web page, the page has not been checked as safe. Note that this warning is not inserted until after the page has been processed, which means you may not see it before any email goes out. If you are concerned about the possibility of clients seeing a warning like this, set this parameter 9.70 to Disabled.
To simulate a call to the URL scanning service when it is unavailable, ensure you are in Debug mode, and insert a URL which contains the string simulateurlscanerror
e.g. http://www.simulateurlscanerror.com
Using your Browser Developer tools Console you’ll see a 403 Forbidden error if RefTracker is disallowing the URL, but an 500 Internal server error if an error is preventing the URL from being checked.
9.71 URL cache: This parameter specifies the period during which the URL being referred to Google safe browsing will not be rescanned (i.e. assumed safe for this period). When a URL being loaded to the database is detected, RefTracker first checks this cache (URL table) to see if there is a record of it being safely checked within the period you select here. If the URL is in the table it means it has been previously checked by Google safe browsing and found to be safe, so another check in not required. This improves response times and limits the number of lookups to the service.
9.72 Safe domains: URL’s containing the domains listed here, and any URLs which are part of the domain in parameter 1.5 (your Organisation URL, if you have specified one), will not be referred to google safe browsing. This improves response times, limits the number of lookups to the service, and ensures that URL’s using these domains can be provided to end users, even if the Google safe browsing service is unavailable and you have selected the very secure Strict option.
Each domain listed here must be on a new line.
Consider adding domains for information sources that you regularly use and trust e.g. www.altarama.com
Attachment upload security parameters overview
In order to prevent files containing viruses from being uploaded as attachments to RefTracker you can set parameter 9.80 to an enabled option. When 9.80 is set to an enabled option, the Antivirus executable defined in parameter 9.81 is used to check whether the attachment file is safe before loading the attachment to RefTracker.
It works like this – when a file is uploaded by an end user or staff member, or received via email importing or R2R, it is saved into a temporary folder (attachment\temp) with a disguised temporary file name e.g. nh6drv3racxderl0Jh.tmp
The file scanning function is then called (which executes the virus check – usually Windows Defender) to scan the file and will receive a result as follows
NoThreatFound = 0
ThreatFound = 1
FileNotFound = 2
Timeout = 3
[Error] = 4
If the result is timeout, then it will retry 5 more times (with a default timeout of 30 seconds each time).
If the final result is anything other than NoThreatFound then the file will be disallowed and immediately deleted. A separate process looks for any files in attachment/temp that have not been accessed for more than 15 minutes and deletes them, as a failsafe, to ensure that unsafe files cannot be retained in that folder due to failure of the immediate delete process.
The user is presented with a message like the following to explain that the file could not be used as an attachment.
If the result is NoThreatFound then the file is renamed to the original file name and uploaded to the RefTracker target folder.
With regard to email importing and R2R, the bad file is removed by a background process, so the file is already gone by the time staff see the request. However, the fact that it was removed, is recorded in the History, so staff can check the import History record, if they suspect a file has been removed.
Testing and problem solving this attachment file scanning functionality: If you try to attach a file (or send one through email importing) with the file name containing the string
simulatethreat
and RefTracker is in debug mode (parameter 80.5 set to Yes), this check will be sent a ThreatFound response, and the file will not be uploaded.
There is a similar test process for RefTracker to RefTracker (R2R) that looks for any filename containing
diabolicalthreat
and does not load that file.
Apparently there is an unsafe file here Download Anti Malware Testfile – Eicar that could also be used for testing but you will not be able to download it if you are running a virus checker locally, and we certainly don’t recommend not running your virus checker, even for testing!
Should an issue arise with accessing Windows Defender the System administrator will be emailed with information about the issue, when RefTracker starts up. “File not found” means the patch specified in parameter 9.81 does not lead to a file of that name, and “not recognized” means that the patch does not appear to be to a product that the RefTracker attachment security function can utilise.
A record of every scan undertaken is placed in the utility log for diagnostic purposes. The log looks like this, where:
Yellow – is the temporary file name before upload to RefTracker
Green – the original file name of the file being scanned for upload
9.80 Scan files before upload: As desirable as it is to have files virus checked before being uploaded by both staff and client’s, this service may not always be accessible or operating. Some organisations may not want the lack of this service to impact on their ability to accept files, and some will not want to allow files to be uploaded if they have not been checked. You can choose how you want your system to operate in this situation.
Set this to Disabled if you do not want files virus checked before upload. We do not recommend this setting but, it may need to be used on occasion to cope with extended virus checker service outages.
Set this to Enabled (relaxed) which is the default setting, to have all attachments uploaded to RefTracker immediately checked by the selected antivirus software (such as Windows defender) and only saved into RefTracker if the antivirus software reports that the file is safe, but if the virus checking service is temporarily unavailable, upload the file anyway. An error message will be sent to your System administrator, so they know that they know the service is not operating, after 10 minutes, then 20 minutes, the 30 minutes, then 1 hour, then 90 mins, and if the error is still occurring every 90 minutes after that.
Set this to Enabled (strict) to have all attachments uploaded to RefTracker immediately checked by the selected antivirus software (such as Windows defender) and only saved into RefTracker if the antivirus software reports that the file is safe, but if the virus checking service is temporarily unavailable, do not upload the file. An error message will be sent to your System administrator, so they know that they know the service is not operating, after 10 minutes, then 20 minutes, the 30 minutes, then 1 hour, then 90 mins, and if the error is still occurring every 90 minutes after that. However your staff will notice that it is not as soon as they try to upload a file as they will be prevented from doing so, though the message will be the same as if the file contained a virus e.g.
To simulate a call to the Virus scanning service when it is unavailable, ensure you are in Debug mode, and upload an attachment named simulateavscanerror
e.g. simulateavscanerror.pdf
The Antivirus software to be used is defined in parameter 9.81.
As part of the RefTracker initialisation, parameter 9.81 is checked to make sure that it is valid.
If the parameter is not valid a dedicated warning email will be sent as attachments will not be able to be uploaded.
If the 9.80 parameter is on and the 9.81 parameter is not valid then all file uploads will be treated as ThreatFound, and not uploaded, because this function has to be fail-safe.
Using your Browser Developer tools Console you’ll see a 403 Forbidden error if RefTracker is disallowing the file upload, but an 500 Internal server error if an error is preventing the file upload.
9.81 Av scan executable: The Antivirus program executable location needs to be defined here as it can be different for different servers. For parameter 9.80 and the attachments scanning security to work, this executable must be correct for the server running the IIS server for this instance of RefTracker (the server running RefTracker, not the server running the SQL server, if they are separate).
Note that the presence of another antivirus product on this RefTracker server, or the Antivirus product being turned off, will result in all responses from Windows Defender returning ThreatFound, and so, no attachments being allowed to be uploaded.
Also note that the executable name for your virus checker may change with newer versions of that product, in which case it will need to be changed here (however, if you have chosen to use Windows Defender, the system will automatically look for the latest version of Defender). Whenever you change this parameter, RefTracker will check that the file you have specified exists. It is also checked whenever RefTracker is restarted with an email going to the system admin if it is not detected, as attachments uploaded will not be allowed until it is fixed or parameter 9.80 is used to turn off the attachment security checking.
Supported Antivirus products are Windows Defender, EST, AVG and AVAST.
So far, only Windows Defender has been fully tested. Windows Defender is considered to be suitable for server protection. If you are using Defender you shouldn’t need to change this parameter. Please contact Altarama about use of any other setting.
The executable location that you enter at parameter 9.81 is checked to ensure that it is a valid executable for one of the supported products.
Behind the scenes there is a new hidden parameter avscanexe which holds the following values
mpcmdrun.exe:1|ecls.exe:2|ashcmd.exe:3|avgscanx.exe:4|avgscana.exe:4
These values are mapping the executable file name to
1 = Windows Defender
2 = ESET
3 = AVAST
4 = AVG
If one of these strings can’t be detected in the Antivirus product location entered at parameter 9.81, the parameter will not be updated.
If the executable file name for any of these products changes then the hidden parameter will need to be updated by Altarama.
ADDITIONAL INFORMATION FOR IN-HOUSE CUSTOMERS (AND HOSTED SYSTEM MANAGERS)
Where more than one RefTracker instance is running on a single server (such as where RefTracker is being hosted, or in-house customers that have more than one instance), a problem with Microsoft Defender (or your chosen virus checker product) can result in all instances not being able to upload attachments. For this reason, a way to turn parameter 9.80 “Scan files before upload” on and off for ALL instances on a server, has been provided.
To to set parameter 9.80 to Yes to turn virus checking back on, run the following SQL with the machine name of the server that needs this change made for all its instances, placed where VMK54032 is appearing in the script.
To use it to turn virus checking off for all instances on the server, replace VMK54032 with the machine name of the server that needs its RefTracker instances amended, and change the parameter update value from 1 to 0.
Example SQL to turn parameter 9.80 to “Yes” for all instances on server VMK54032
declare @command varchar(2000)
select @command =
‘use [?];
begin
if exists (select * from sys.tables where name = ”parameter”)
if exists (select * from parameter where parameter_id = ”webserver”)
If exists (select * from parameter where parameter_id = ”webserver” and [parameter_value:en] like ”%VMK54032%”)
BEGIN
PRINT ”Update ” + ”?”;
Update parameter set [parameter_value:en] = ”1” where parameter_id = ”scanUploads”
END
end
‘
exec master.sys.sp_MSforeachdb @command