NIST Logo and ITL Banner Link to the NIST Homepage Link to the ITL Homepage Link to the NIST Homepage
Search CSRC:
AppVet Logo

4.  Configuration


4.1 Overview

Before running AppVet, the AppVet system must be configured. Figure 4-1 shows the AppVet system and related configurations.


appvet-configuration

Figure 4-1. AppVet configurations. (Enlarge)



AppVet involves the following configurations:

  • AppVet: AppVet must be configured using the AppVetProperties.xml configuration file. This file is used by AppVet to configure various attributes of AppVet including logging and timeout values. The schema for AppVetProperties.xml is defined in AppVet Properties Schema.
  • MySQL: AppVet requires that MySQL be configured with a database and relational tables to support AppVet functionality. The schemas for the AppVet database are defined in Database Schema.
  • Tool Adapter: AppVet requires that a tool adapter configuration file be defined for each tool service used by AppVet. A tool adapter configuration file describes information about a tool service and is used by AppVet to connect to the service and typically do not require additional modification by the AppVet administrator. With the exception of some reserved internal tools for AppVet registration and pre-processing, a tool adapter configuration file is provided by the vendor or owner of the tool service. Both registration and pre-processing adapters are included with AppVet. The schema for a tool adapter is defined in Tool Service Adapter Schema.
  • Apache Tomcat: Apache Tomcat does not need to be configured to run AppVet. However, Tomcat may need to be configured to support the hosting organization's deployment requirements (e.g., using SSL). Such configurations are beyond the scope of this document.
  • Tool Service: A tool service may have its own internal configuration file (shown as ToolServiceProperties.xml in Figure 4-1). We show this file here in order to distinguish it from a tool adapter configuration file that is defined by the vendor or owner of the tool service but used by AppVet. AppVet does not use a tool service's configuration file.

4.2 AppVet Installer

All AppVet configurations are generated using the AppVet Installer. The AppVet installer generates and configures the following items:

  • AppVet AppVetProperties.xml file
  • AppVet MySQL database and relational tables
  • Registration and pre-processing tool adapters

Before running the AppVet Installer, set the environment variable APPVET_FILES_HOME to a directory path on the host system. It is recommended to use a path that does not contain spaces or special characters. For example, use C:\appvet_files on Windows.

Next, launch the AppVet Installer from the appvet Eclipse project by right clicking on /src/gov/nist/appvet/installer/AppVetInstaller.java and selecting Run As > Java Application. This will bring up the AppVet installer application as shown in Figure 4-2.


installer_start

Figure 4-2. AppVet installer. (Enlarge)



Select Next to view the Host dialog as shown in Figure 4-3.


installer_2

Figure 4-3. Host dialog. (Enlarge)



The Host dialog provides the following options:

  • Use Hostname: This option should be selected for production systems or development systems that have a fully-qualified domain name (FQDN).
  • Use Static IP: This option should be selected for development systems if a static IP is available. This option should not be selected for production systems.
  • Use DHCP: This option should be selected for development systems using a dynamic IP address.
  • Keep Apps: This option should be selected if apps should be archived on the system. If this option is not selected, apps will be deleted after they are processed. Note that keeping apps on the system may result in significant disk space usage.
Select Next to view the Administrator dialog as shown in Figure 4-4. Enter the AppVet administrator account information. Note that additional administrators can be added later.


installer_3

Figure 4-4. Admin dialog. (Enlarge)



Select Next to view the Platform dialog as shown in Figure 4-5. Select SSL if Secure Socket Layer is enabled for your Tomcat server. In addition, enter the primary port of your Tomcat server. Note that this information MUST match your Tomcat server.xml configuration. Next, add your MySQL username and password. Note that adding an incorrect MySQL username or password will result in errors when running AppVet.


installer_4

Figure 4-5. Platform dialog. (Enlarge)



Select Install to view the AppVet installation progress as shown in Figure 4-6.


installer_5

Figure 4-6. Admin dialog. (Enlarge)



After running the AppVet installer, the $APPVET_FILES_HOME directory is generated as shown in Figure 4-7.


appvet_files_directory

Figure 4-7. AppVet files directory. (Enlarge)



The AppVet files directory contains three subdirectories: /apps , /conf , and /logs . The /apps directory is used as permanent storage for tool reports as well as temporary storage for uploaded apps. The /conf directory contains the main AppVet configuration file AppVetProperties.xml and a set of tool service adapters defined in /tool_adapters . In Figure 4-7, two internal tools, registration.xml and appinfo.xml are defined as well as two other tools, android-cert-test.xml and masterkey-extrafield-test.xml . The /logs directory contains the AppVet log appvet_log.txt .

Note that $APPVET_FILES_HOME/conf/AppVetProperties.xml is initially configured with default values for operational use and should be appropriate in most cases. However, for AppVet development, it is best to edit AppVetProperties.xml and change the XPath value in /Appvet/Logging/Level from INFO to DEBUG . In addition, change the XPath value in /Appvet/Logging/ToConsole from false to true . These changes will configure AppVet to display DEBUG log messages to the Eclipse console.

4.3 Tool Service Adapters

AppVet accesses a tool service using a tool service adapter. A tool service adapter is an XML configuration file that defines properties of a tool service including the service's required (REST) API parameters. A tool service adapter's structure is defined by the Tool Service Adapter Schema. Typically, tool service adapters will be defined and published by the tool service provider. Thus, tool service adapters require little or no configuration by the AppVet administrator.

Adding a new tool service to AppVet involves adding a new tool service adapter to the $APPVET_HOME/conf/tool_adapters directory. When adding a new tool configuration file, AppVet automatically adds a new entry for the tool into the database. Note that newly added tools are not applied to previously processed apps. Instead, a tool status of N/A is displayed for such apps.

Tool services can be removed from AppVet by removing their corresponding adapter from the $APPVET_HOME/conf/tool_adapters directory. Removing a tool from AppVet will hide results for the tool even if an app has been previously processed by the tool. However, AppVet will continue to store all previously generated results for the tool in its repository. If the tool is later re-added to the system, AppVet will display the tool's results for previously processed apps. To ensure proper operation of AppVet, ensure that Tomcat is shut down before adding or removing a tool service adapter.

The AppVet administrator must ensure that tool service adapters for all desired tools are present in $APPVET_HOME/conf/tool_adapters. Do not include adapters for tool services that are not available to AppVet or that AppVet cannot authenticate to. Doing so will lead to AppVet system errors for those tools.