Skip to content
This repository has been archived by the owner on May 9, 2019. It is now read-only.

Installation and Administration

Jump to bottom
Steve Billings edited this page Aug 19, 2016 · 20 revisions

Overview

AppEdit is a web application that adds additional Application-specific functionality to Code Center. It is intended to be invoked by clicking on a the View link associated with a URL stored in an Application custom attribute (attribute type: URL).

Edit Application Details

If the user that logs into AppEdit is an end user (not an auditor), AppEdit presents the Edit Application Details screen. This screen enables end users (that don't have full write access to the Code Center application details screen) to edit only certain (configured in the AppEdit config file, appedit.properties) custom application attributes on the application details screen.

Edit NAI Audit Details

If the user that logs into AppEdit is an auditor (they are assigned the designated auditor role in Code Center), AppEdit presents the Edit NAI Audit Details screen (NAI = "Not An Issue" Remediation Status). This screen enables auditors to add/change NAI audit information (status, and comment) to Application vulnerabilities. The designated auditor role, and the NAI Audit Status choicelist values are configured in the AppEdit configuration file (appedit.properties).

If the auditor rejects the remediation status, the remediation status is automatically changed to a value specified in the configuration.

An audit trail (change history) of changes to the NAI Audit data is written to the table vuln_nai_audit_change_history in the bds_catalog database on the Code Center database server.

Installation

NAI Audit Database Table Creation

If you are setting up to use the NAI Audit functionality for the first time: To create the database tables used to store NAI Audit data: Using pgAdmin or psql:

  1. Connect to the bds_catalog database on the Code Center database server.
  2. Run VulnNaiAudit_DB_Create.sql, which you'll find at the top level of the AppEdit package (appedit-<version>.zip).

Code Center Configuration

In Code Center:

  1. If they do not already exist: Create the custom attributes that end users will edit with AppEdit.
  2. If it does not already exist: Create AppEditURL app custom attribute (type=URL).
  3. For the NAI Audit functionality: If it does not already exist: Create the Overall Role that auditors will be assigned. If this is the only role auditors will be assigned, it must have the following permissions: "Can access the system", "Can read configuration data", "Can have read access to an application". Auditor users will also need to be able to view the applications (either through permissions on the auditor role, or on a different role they hold).

Populating Code Center Application Links to AppEdit

If you need to populate the Code Center applications with links to AppEdit:

  1. In the ccimporter config file: numprefixed.app.attribute.appediturl=<the name of the AppEditURL attribute> numprefixed.app.value.appediturl=http://<host:port>/AppEdit/editappdetails numprefixed.update.appediturl.on.old.apps=true
  2. Run ccimporter to populate AddEdit URL field in Code Center applications.

AppEdit Configuration

For details on the syntax used in appedit.properties, please see Configuration Files.

Edit the appedit.properties. On application server (e.g. tomcat) startup, AppEdit reads the appedit.properties file from the tomcat process owner's home directory.

  1. If you are installing AppEdit for the first time, create this file by copying it from the top level of the AppEdit package (appedit-<version>.zip). If this is not the first installation, check the copy of appedit.properties in the AppEdit package for any new properties. If there are any, merge them into the appedit.properties file in the tomcat process owner's home directory.
  2. appedit.properties should be configured as follows: 1. Set Code Center server, user, password. Please refer to the Password Encryption section below. 1. For each custom attribute to be included in the AppEdit UI: specify the AppEdit UI label (attr.N.label), the Code Center custom attribute name (attr.N.ccname), and the regex to use to validate input (attr.N.regex). 1. Input field validation for username and password is performed using regular expressions. If you want to adjust those regular expressions to allow/disallow different characters (this can help make the application more secure), adjust the values of the following properties: field.input.validation.regex.username=\[A-Za-z0-9@_.-\]+ field.input.validation.regex.psw=.+ 1. To disable the NAI Audit functionality, remove or comment out properties db.server, auditor.role.name, and nai.audit.status.*. 1. To enable the NAI Audit functionality:
    1. Set property db.server=<Code Center database server name>
    2. Set property db.port=<Code Center database port>
    3. Set property db.user=<Code Center database user name>
    4. Set property db.password=<Code Center database password>. Please refer to the Password Encryption section below.
    5. Set property auditor.role.name=<Code Center auditor role name>
    6. Define the NAI Audit Status choicelist values by defining properties nai.audit.status.0, nai.audit.status.1, etc. The final character of each property name is an integer index (start numbering at 0). The value of each property is a value in the NAI Audit Status choicelist presented to the auditor.
    7. Set nai.audit.rejected.status.name to the name of the NAI Audit Status choicelist value that means rejected.
    8. Set nai.audit.rejected.status.changes.rem.status.to to the Remediation Status value to which Remediation Status should be changed when the auditor rejects.
    9. Set nai.audit.rem.status.to.audit to the Code Center Vulnerability Remediation (Review) Status value that means "not an issue".
    10. Optionally set nai.audit.date.format to a valid timezone format as described at https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html. For example: nai.audit.date.format=MMM-dd-yyyy hh:mm:ss z
    11. If you are running against a Code Center server older than version 7.1.1, add the following property: nai.audit.cc.is.pre.7.1.1=true
    12. For faster NAI Audit page loading, enable periodic caching of component names by configuring the following properties as explained in the comments in the sample appedit.properties file: nai.audit.preload.components, nai.audit.preload.components.minutes.until.initial.run, nai.audit.preload.components.cron, nai.audit.preload.components.cache.timeout.value, nai.audit.preload.components.cache.timeout.units, nai.audit.preload.components.cache.size.
  3. Install the AppEdit application under <tomcat installation dir>/webapps. Log in as the same user that starts tomcat (owns the tomcat process) to perform these steps:
  4. Change directory to <tomcat installation dir>/webapps.
  5. If AppEdit was previously installed: Remove the AppEdit directory (and all of its contents) and the AppEdit.war file from the CodeCenter/tomcat/webapps directory.
  6. Copy the new AppEdit .war file that you got from the zip file on the github releases page (it'll have a name that includes the version) into the tomcat/webapps directory, naming it AppEdit.war so it matches the URL you configured in the ccimporter config file above.
  7. Restart tomcat to expand the AppEdit.war file.
  8. Launch from Code Center: In Code Center, go to an app, and click on the AppEdit URL View link

Password Encryption

The appedit.properties configuration file contain a Code Center password, configured via the property:

cc.password=<value>

Passwords are entered in plain text, and then (usually) automatically encrypted in-place by the utility the next time it reads the configuration file. When creating a configuration file, set the value of cc.password to the password in plain text. The first time the utility reads the file, if the property cc.password.isencrypted is not present, it will encrypt the password and insert the property cc.password.isencrypted=true. To change the password, remove the cc.password.isencrypted property, and set cc.password to the password in plain text. To tell the utility to leave the password as plain text, insert cc.password.isencrypted=false.

Notes

  • The configration file appedit.properties is read only once on startup. Therefore you need to restart the application server (e.g. tomcat) after changing the configuration file in order for those changes to take effect.
  • NAI Audit: The list of vulnerability remediation status names are cached for 1 hour. If a remediation status choicelist value is renamed in Code Center (Administration > Attributes > Vulnerability Status), the change may not appear in AppEdit for up to 1 hour. You can restart the application server (e.g. tomcat) to force the Code Center change to appear in AppEdit sooner.

Testing

To launch by hand (for testing):

  1. Make sure in appedit.properties the app.version property is set to the version string for the Code Center app you will use for testing.
  2. To avoid having to URL-escape any characters, choose for testing a Code Center application whose name consists only of alphanumeric characters.
  3. Launch the following URL in your browser: http[s]://<host>[:<port>]/AppEdit/editappdetails?appName=<Code Center application name>
  4. Log in as a user that has not been assigned the Code Center auditor role to test the Edit Application Details screen.
  5. Log in as a user that has been assigned the Code Center auditor role to test the Edit NAI Audit Details screen.

Troubleshooting

The first step in troubleshooting generally involves examining one or both of the following logs:

  1. The server-side log, AppEdit.log, which is located in the application server (tomcat) logs directory. Older logs will be named AppEdit.log.1, AppEdit.log.2, etc.
  2. The client-side (browser) log, which is displayed using the browser console. For example, in Firefox: From the menu, select Developer > Web Console, then select editappdetails or editnaiauditdetails (depending on which page you are troubleshooting).

Additional information about server-side activity can be discovered by setting the logging level to DEBUG. To change the logging level (assuming the application server is tomcat):

  1. Stop tomcat
  2. Edit the file /webapps/AppEdit/WEB-INF/classes/log4j.properties and adjust the 3 lines under "# Categories". Recommending settings for debugging: log4j.category.com.blackducksoftware.tools.appedit=DEBUG log4j.category.com.blackducksoftware.tools.connector=DEBUG log4j.category.com.blackducksoftware.tools.connector.codecenter.common=INFO
  3. Start tomcat

To return the logging level to INFO, repeat the process, but this time comment out the three lines under "# Categories".

Additional information about client-side activity can be discovered using other browser troubleshooting capabilities, such as the debugger, network traffic trace, etc.

Code Center Database Schema Dependencies

[As of AppEdit 1.4.2]

For better performance against large Code Center databases, there are three components within AppEdit that read directly from the Code Center database (via SQL). If the Code Center database schema changes, these may stop working. The operations performed via SQL are:

  1. Upon login, check to see whether the user is an auditor (has the auditor role assigned in Code Center). This is performed by the JdbcUserRoleDao object.
  2. Prior to, or upon loading the NAI Audit Details page, lookup the name/version of each component ID.
  3. The name/version of each possibly-NAI component may (if configured) be pre-loaded into a cache. This pre-loading, by the ComponentCachePopulator object, occurs once soon after startup, and then periodically (typically nightly) there-after.
  4. If pre-loading is disabled, or has not occurred yet, on-demand loading is performed by the JdbcComponentNameVersionDao object.
  5. Upon loading the NAI Audit Details page, read vulnerabilities for each component. This is performed by the JdbcVulnerabilityDao object.

In each case, AppEdit can be built to use the SDK-based component instead of the SQL-based component. This may be necessary if the Code Center schema has changed, and one of the operations mentioned above is failing as a result.

To configure AppEdit to check whether the user is an auditor via the SDK (not SQL), in AppEditApplicationContext.xml (which is packaged within the .war file in WEB-INF/classes/spring), change:

<bean id="userAuthenticationDao" class="com.blackducksoftware.tools.appedit.core.dao.hybrid.HybridUserAuthenticationDao" />

to:

<bean id="userAuthenticationDao" class="com.blackducksoftware.tools.appedit.core.dao.cc.CcUserAuthenticationDao" />.

To configure AppEdit to read component name/versions, and vulnerabilities via the SDK (not SQL), in AppEditApplicationContext.xml (which is packaged within the .war file in WEB-INF/classes/spring), change:

<bean id="appCompVulnDetailsDao" class="com.blackducksoftware.tools.appedit.naiaudit.dao.hybrid.HybridAppCompVulnDetailsDao" />

to:

<bean id="appCompVulnDetailsDao" class="com.blackducksoftware.tools.appedit.naiaudit.dao.cc.CcAppCompVulnDetailsDao" />.

If you replace HybridAppCompVulnDetailsDao with CcAppCompVulnDetailsDao in AppEditApplicationContext.xml, you can also remove the bean declarations for componentNameVersionDao, componentCachePopulator, componentCachePopulatorJob, runSoonTrigger, cronTrigger, taskExecutor, and org.springframework.scheduling.quartz.SchedulerFactoryBean.

After changing AppEditApplicationContext.xml, you will need to rebuild AppEdit.

Clone this wiki locally