secureassist enterprise portal user guidedownload.asteriskresearch.com/2.4/secureassist... ·...

SecureAssist Enterprise Portal

User Guide August 2015

Copyright © 2015 by Codiscope, LLC. All rights reserved. No part or parts of this

documentation may be reproduced, translated, stored in any electronic retrieval system,

transmitted in any form or by any means, electronic, mechanical, photocopying, recording or

otherwise, without prior written permission of the copyright owner. Codiscope retains the

exclusive title to all intellectual property rights relating to this documentation.

The information in this documentation is subject to change without notice and should not be

construed as a commitment by Codiscope. Codiscope makes no representations or

warranties, express or implied, with respect to the documentation and shall not be liable for

any damages, including any indirect, incidental, consequential damages (such as loss of

profit, loss of use of assets, loss of business opportunity, loss of data, or claims for or on

behalf of user’s customers) that may be suffered by the user.

Codiscope and the Codiscope logo are trademarks of Codiscope, LLC. Other brands and

products are trademarks of their respective owner(s).

Codiscope, LLC

20 Park Plaza, Suite 1400

Boston, MA 02116

Phone: + 1 (617) 804-5428

[email protected]

www.codiscope.com

mailto:[email protected]

http://www.codiscope.com/

Table of Contents

SecureAssist Enterprise Portal Setup .................................................................................... 1

Installation .................................................................................................................................... 1

Initial Configuration ..................................................................................................................... 6

Upgrade Instructions ................................................................................................................... 8

1 Log in to SecureAssist .................................................................................................... 11

Getting Started ........................................................................................................................... 11

Portal Navigation ........................................................................................................................ 11

2 Statistics .......................................................................................................................... 12

Project Statistics ......................................................................................................................... 12

User Statistics ............................................................................................................................. 14

3 Reports ............................................................................................................................ 17

Project Reports ........................................................................................................................... 17

User Reports ............................................................................................................................... 22

4 Rulepacks ........................................................................................................................ 27

5 Manage ............................................................................................................................ 29

Portal Users ................................................................................................................................ 29

Plugin User Groups .................................................................................................................... 31

Roles ............................................................................................................................................ 33

Account ........................................................................................................................................ 34

6 Settings ............................................................................................................................ 35

LDAP Configuration ................................................................................................................... 35

Feature Configuration ............................................................................................................... 36

Server License ............................................................................................................................. 38

Client Licenses ............................................................................................................................ 38

7 More Support .................................................................................................................. 40

8 Appendix ......................................................................................................................... 41

Roles and Associated Permissions .......................................................................................... 41

Permission Descriptions ........................................................................................................... 42

SecureAssist Enterprise Portal User Guide August 2015 — Page 1 of 42

SecureAssist Enterprise

Portal Setup The SecureAssist Enterprise Portal allows you to manage how your

Codiscope plugins operate to maximize your organization’s efficiency.

The Portal also gathers data from your plugin users, allowing you to

run statistics and reports for your projects and developers.

Installation

This section describes the installation of the Codiscope SecureAssist

Enterprise Portal and Codiscope SecureAssist Eclipse update site. The

Portal and update site can be deployed on the same application

server, or they can be deployed on separate servers. This document

assumes that they are installed on the same server.

Configure Database

Database Instructions

Derby Configure Database and User

1. To modify database name, user, and password, you need to

modify Apache Derby specific SQL script located in

<CSA_Portal_Package>/Database/portal_csa_derby.sql. Password

change is required.

2. In order to modify credentials of user that will be used to connect

to CSA Portal database, modify following line in the SQL Script:

CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY

(‘derby.user.portal_csa’,‘Passw0rd’);

3. To change password, replace Passw0rd with a new password.

4. To change user name, replace derby.user.portal_csa with

derby.user.selected_username.

5. In order to change database name, modify following line in the

SQL Script: CONNECT ‘jdbc:derby:portal_csa;create=true’;

6. To change database name, replace portal_csa with database

name of your choice.

Running SQL Script

1. Ensure that Apache Derby is running.

2. To Start Apache Derby database as the network server, execute

the <derby>/bin /startNetworkServer.bat (Windows) or <derby>/bin

/startNetworkServer.ksh (Unix) script. This will start the Network

Server up on port 1527.

3. Start Apache Derby scripting tool by executing <derby>/bin/ij.bat

(Windows) or <derby>/bin/ij.ksh (Unix) script in terminal. In ij, run

following command: run ‘<path>/<to>/portal_csa_derby.sql’;



Oracle Configure Database and User

1. To modify database name, user, and password, you need to

modify Oracle specific SQL script located in

<CSA_Portal_Package>/Database/portal_csa_oracle.sql. Password

change is required.

2. In order to modify credentials of user that will be used to connect

to CSA Portal database, modify following line in the SQL Script:

CREATE USER portal_csa IDENTIFIED BY Passw0rd DEFAULT

TABLESPACE USERS TEMPORARY TABLESPACE TEMP;

3. Replace ‘portal_csa’ and ‘Passw0rd’ with username and password

of your choice. Make sure to update all following lines with

updated information: connect portal_csa/Passw0rd;

Running SQL Script

1. Log in to SQL*Plus as sysdba using following command: sqlplus

/as sysdba

2. To log output of SQL script execution, turn on spool: spool

/<path>/<to>/log.txt ;

3. Execute SQL script: @/<path>/<to>/portal_csa_oracle.sql

4. Turn off spool: spool off;

5. Exit from SQL*Plus: exit;

6. Review log file with SQL script execution output to validate that

there are no errors.

MySQL Configure MySQL Database and User

1. Run the “mysql” command as a MySQL super user: mysql -u root -

p

2. Create an empty CSA Portal database schema. Replace ‘portal_csa’

with a database name of your choice: CREATE DATABASE portal_csa;

3. Create CSA Portal database user: GRANT ALL PRIVILEGES ON

portal_csa.* TO ‘csauser’@’localhost’ IDENTIFIED BY

‘csauserpassword’;

4. Replace ‘portal_csa’ with the name of the database that you have

created in the step above. Additionally replace ‘csauser’ and

‘csauserpassword’ with username and password of your choice. If

SecureAssist Enterprise Portal is not running on the same server

as your MySQL database server, replace ‘localhost’ with the

hostname or IP address of the Codiscope SecureAssist server.

Configuring Portal Database Schema

1. Create CSA Portal database schema by running command as a

MySQL super user: mysql -u root -p portal_csa <

path_to/portal_csa_mysql.sql

2. Replace ‘csa_portal’ with database schema created in step 2

above.

3. Replace ‘path_to’ with path to portal_csa_mysql.sql file.


Configure Secure HTTP

SecureAssist Enterprise Portal supports both HTTP and Secure HTTP

(https). Codiscope strongly recommends using secure HTTP.

However, installation of a server-side SSL certificate and

configuration of web servers is beyond the scope of this manual. For

more information about configuring the Apache Tomcat web server

to use secure HTTP, refer to your web server’s documentation.

Deploy SecureAssist Portal

Deploy Using Tomcat Manager

If your instance of Tomcat is running the Tomcat Web Application

Manager, you can use its browser interface to deploy the Portal.

1. In tomcat_home/conf/tomcat_users.xml, create a role named

manager-gui and assign a user to this role. Afterwards, restart

your Tomcat instance.

<tomcat-users><role rolename=“manager-gui”/><user

username=“USERNAME” password=“PASSWORD” roles=“manager-

gui”/></tomcat-users>

2. In your internet browser, navigate to the default Tomcat

home page.

3. Click on the Manager App link. You will be asked to enter your

username and password.


4. Enter your username and password. The Web Application

Manager page will load.

5. Navigate to the WAR file to deploy section and click the

Browse button.

6. Select the CSA Portal web application WAR file and click

Open, then click Deploy.

After the Tomcat Web Application Manager has finished

deploying the Portal, it should be listed in the Applications

section and be ready to use.


Deploy on a Running Tomcat Server

To deploy SecureAssist on a running Tomcat server,

autoDeployattribute needs to be set to true. The host will deploy the

web application when the WAR file is copied to the deployment

directory. The default deployment directory is

CATALINA_HOME/webapps.

To deploy the Portal, copy CSA_Server.warfile to

CATALINA_HOME/webapps.

After Tomcat has finished deploying the Portal, CSA_Serverdirectory

should be created in CATALINA_HOME/webapps.

Install MySQL Database Connector

The MySQL Connector/J (official JDBC driver for MySQL database) is

required when installing Codiscope SecureAssist Enterprise Portal

and using the MySQL database. This step is not necessary when

using Derby or Oracle database.

To install MySQL connector, follow these steps.

1. Navigate to http://dev.mysql.com/downloads/connector/j/ and

download MySQL Connector/J.

2. Extract mysql-connector-java-5.x.x-bin.jar file from the archive

downloaded in previous step and copy it into the

CATALINA_HOME/webapps/CSA_Server/WEB-INF/lib directory.


Deploy Codiscope SecureAssist Eclipse

Update Site

To deploy the SecureAssist Eclipse update site, simply copy the

/update folder that came with the Portal to the

CATALINA_HOME/webapps folder.

Initial Configuration

Configure Logging

Log4j configuration file is stored at

CATALINA_HOME/webapps/CSA_Server/WEBINF/classes/log4j.xmlfile.

You can edit this file to make it suitable for the deployment

environment. For more information about configuring log4j, refer to

the log4j documentation.

Note: Any changes made to the logging configuration file will take

effect only after restarting the Tomcat application server.

First Start Configuration

After successful deployment of SecureAssist Enterprise Portal, open

your browser and navigate to http://<Host>:<Port>/CSA_Server in order

to finish configuration of the portal. The following table describes the

items you will need to configure.

Item Description

License

Terms

Read terms and conditions and click I Agree to continue.

Product

License

SecureAssist Enterprise Portal license is tied to a specific

server and can be used only on that single server. In order to

acquire your license, copy your server information and send

it to SecureAssist support ([email protected]).

After receiving the server license file, click Browse and select

server license file, then click Upload.

http://logging.apache.org/log4j/1.2/index.html)


Item Description

Database

Setup

Before setting up the database connection, you must set up

the database schema and create user as described in

“Configure Database.” Complete all fields and click Save.

Examples:

Database Type: MySQL

Server: jdbc:mysql://<db_server>:3306

Database/Schema Name: portal_csa

Database User: csauser

Database Type: Derby

Server: jdbc:derby://<db_server>:1527/portal_csa

Database/Schema Name: APP

Database User: portal_csa

Database Type: Oracle

Server: jdbc:oracle:thin:@<db_server>:1521:orcl

Database/Schema Name: portal_csa

Database User: portal_csa

Administrator

Account

Setup

In the last step of initial configuration, the administrator

account must be created. Provide a username and password

for the administrator account and click Create.

Upon successful initial configuration, you will be redirected to the

Index page and will be able to log in using the administrator

credentials you created.

Configure Link on Index Page

The Index page contains a section with the link to the location from

where the Codiscope SecureAssist IDE plug-in can be installed or

updated.

In order to configure the link, navigate to

CATALINA_HOME/webapps/CSA_Server/WEB-INF/jsp/includes/. Open file

index.jsp and edit the following line so that the value equals the

correct URL from which the plug-in can be installed.

If you do not want the link to be displayed, leave the value as empty.


Upgrade Instructions

This section contains the instructions for upgrading the SecureAssist

Enterprise Portal from version 2.3 to version 2.4. In order to upgrade

the server to version 2.4, you must run the database update script

and deploy the new version of the web application.

Note: In order to upgrade to SecureAssist 2.4, you must be re-issued

a new Enterprise Portal license. Please reach out to

[email protected] for a new license for SecureAssist 2.4.

Application Upgrade

Follow these instructions to upgrade the Portal.

Note: If you have modified any configuration (for example, the

hibernate.cfg files) in order to resolve bugs, you must make these

same modifcations in the upgrade deployment.

1. Stop Apache Tomcat.

2. Create backup directory.

3. Backup following directories/files:

a. Copy following directories to backup folder:

- <tomcat>/webapps/CSA_Server/key-file

- <tomcat>/webapps/CSA_Server/stats

- <tomcat>/webapps/CSA_Server/rulepacks

b. Copy following files from

<tomcat>/webapps/CSA_Server/WEB-INF/ folder to backup

folder:

- cron.properties

- db.properties

- <company_name>-SecureAssist-PriKey.der

- SecureAssist.license

- classes/log4j.xml (optional, see step 9c )

4. Delete CSA_Server.war file from <tomcat>/webapps folder.

5. Delete <tomcat>/webapps/CSA_Server folder.

6. Copy new CSA_Server.war file to <tomcat>/webapps folder.

7. Upgrade database by following instructions in “Database

Upgrade,” above.

8. Start Apache Tomcat.

9. Copy backed-up directories/files.

a. Copy following directories to

<tomcat>/webapps/CSA_Server:

- <backup>/key-file

- <backup>/stats

- <backup>/rulepacks


b. Copy following files to <tomcat>/webapps/CSA_Server/WEB-INF:

- <backup>/cron.properties

- <backup>/db.properties

- <backup>/<company>-SecureAssist-PriKey.der

- <backup>/SecureAssist.license

c. Copy file <backup>/log4j.xml to

<tomcat>/webapps/CSA_Server/WEBINF/ classes.

Note if you are upgrading from a version prior to 2.3:

Log4j configuration file in release 2.3 contains additional

loggers to improve logging configuration. It is

recommended that you configure new log4j.xml instead

of replacing it with the previous version of the file.

10. Ensure that all directories and files copied from the backup

folder are readable and writable by a user running Tomcat

(e.g., chown tomcat:tomcat path/to/file).

11. Copy MySQL Connector (mysql-connector-java-5.x.x.jar) to

<tomcat>/webapps/CSA_Server/WEB-INF/lib/.

Note: If you are not using MySQL, you do not need to obtain a

copy and install it.

12. Remove Apache Tomcat work cache (e.g.,

/var/cache/tomcat6/work/Catalina/localhost/CSA_Server/*,

<tomcat>/work/Catalina/localhost/CSA_Server/*).

13. Restart Apache Tomcat.

Database Upgrade

Follow these instructions to upgrade the database.


Derby 4. Start the Apache Derby scripting tool by executing

<derby>/bin/ij.bat (Windows) or <derby>/bin/ij.ksh (Unix) script in

terminal.

5. In ij, run the following command: run

‘path_to/upgrade/{from_to_versions}/portal_csa_derby.sql’;

Oracle 1. Login to SQL*Plus as sysdba using following command: sqlplus /as

sysdba

2. Execute SQL script.

@/path_to/upgrade/{from_to_versions}//portal_csa_oracle.sql

3. Exit from SQL*Plus: exit;



MySQL 1. Update the Portal database schema by running command as a

MySQL super-user or user created during initial database setup:

mysql -u root -p csa_portal <

path_to/upgrade/{from_to_versions}//portal_csa_mysql.sql

2. Replace csa_portal with database schema created during initial

installation.

3. Replace path_to with path to portal_csa_mysql.sql file with upgrade

script.

Depending on your current version of SecureAssist Portal, a few

upgrade scripts may need to be run. SecureAssist Enterprise Portal

supports the following upgrade paths:

Versions Upgrade Paths

2.3.7+ to 2.4.0 Run the script inside the 2.3.7 to 2.4.0 directory.

2.3.6 to 2.4.0 Run these scripts in the following order:

‘2.3.6 to 2.3.7’

‘2.3.7_to_2.4.0’

2.3.1 to < 2.3.6 Run these scripts in the following order:

‘2,3,1_to 2.3.6’

‘2.3.6 to 2.3.7’

‘2.3.7_to_2.4.0’

2.3 Run these scripts in the following order:

‘2.3_to_2.3.1’

‘2.3.1_to 2.3.6’

‘2.3.6 to 2.3.7’

‘2.3.7_to_2.4.0’

2.2 to <2.3 Run these scripts in the following order:

‘2.2_to_2.3.1’,

‘2.3.1_to 2.3.6’

‘2.3.6 to 2.3.7’

‘2.3.7_to_2.4.0’


1 Log in to SecureAssist Enter your username and password on SecureAssist’s login screen at

http://<Host>:<Port>/CSA_Server.

Getting Started

When you first log onto the portal, SecureAssist opens on the Get

Started screen by default. The screen displays these features.

Feature Description

Learn how it works Provides a link to the SecureAssist Support screen

and its related documentation.

Install the

SecureAssist Plugin

Provides links for the download of Eclipse and Visual

Studio plugins.

Activate Provides direction for activating your SecureAssist

license.

Portal Navigation

The navigation menu on the left side of the application allows you to

access any of the SecureAssist functional areas at any time. Those

functional areas are:

Statistics —An instant-reporting function that displays the

number and types of issues identified and reviewed,

guidance searched, and history of vulnerabilities

remediated—by project or by individual user.

Reports — Allows administrators to produce various

predefined reports for projects or for groups of users.

Rulepacks — Lists the various rulepacks loaded in the Portal

for distribution to the licensed SecureAssist clients.

Manage —Contains screens for administering users, groups,

roles, and your personal account.

Settings — Contains various settings for configuring the

application and viewing license agreements.

Get Started — The “homepage.”

The following chapters will describe the functionality of SecureAssist

in detail.

http://support.codiscope.com/



2 Statistics Statistics covering plugin functionality and user activity are

periodically sent to the Portal. This information is stored on the

Portal server in a database, and there are numerous pre-defined

charts and graphs that can be viewed and exported. You can run

statistics for a project or for a user.

Project Statistics

The Project Statistics screen allows you to instantly view statistical

information by project.

Run Statistics for a Selected Project

1. Navigate to the Project Statistics window. The Select a Project

flyout will automatically open. To manually open the flyout,

click the Select a Project button.

2. Locate a project by either scrolling though the list of projects

AND/OR

Typing text into the search box to filter the selection

AND/OR

Clicking the filter icon to filter choices by Java, .Net, or PHP.


3. Click Select next to the desired project. The dialog closes, and

the Project Statistics Options window populates with default

information. The following table describes the selection

criteria on the Project Statistics Options window.

Field/Feature Description

Project Displays the currently selected project for which

statistics will be provided. To select a different

project, click Change.

File Displays the currently selected files in the project (by

default, All Files). To change the file selection, click

Change.

Date Range Displays the selected range of dates for which

statistics will be provided (defaults to the current

date). To update, click in the date boxes to select a

new start and/or end date.

Type Choose one of the following three types of statistics:

Top Findings — The ten most frequent findings for

the selected project.

File Scan — Allows you to choose individual files

for which you wish to see statistics. (When

selected, Sort by no longer is an option.)

Suppression — Displays issues suppressed by end

users, per project.

Sort by Choose to sort results by one of the following:

Category —Category of rules that were

triggered/fired.

Title — Name of specific rule.

Show Chart Click this button to display a pie chart based on the

selected criteria.

Download CSV Once a chart is displayed, click this button to save the

data to a CSV file.

4. From the Project Statistics Options window, make your

criteria selections.

5. Click Show Chart. SecureAssist displays a pie chart based on

your selections.


6. If desired, filter the report results by user:

a. In the Filters pane, click on one or more users to highlight

them.

b. Click Update. The report updates to display data for the

selected users only.

7. If desired, click Download CSV to save the data to a CSV file.

User Statistics

The User Statistics screen allows you to view statistics information for

a single user. When you access the User Statistics screen, you will see

a list of all your plugin users (this list is populated by your client

licenses).

Find a User

1. To quickly find a user in the user list, enter text into the Find

a User box. The list will automatically filter to show only

those user names that contain the text.

Run Statistics for a Single User

1. From the User Statistics window, locate the name of the

desired user in the list, then click the Get Statistics button

next to it. The User Statistics Options window displays

default information. The following table describes the

selection criteria on the User Statistics Options window.


Field/Feature Description

User Displays the currently selected user for which

statistics will be provided. To select a different user,

click Change.

Date Range Displays the selected range of dates for which

statistics will be provided (defaults to the current

date). To update, click in the date boxes to select a

new start and/or end date.

Type Choose one of the following types of statistics:

User Session — Displays the user’s distinct

sessions on a timeline. Hovering over a start or

end point will display a timestamp.

Scanned File Types — Pie chart that displays

scanned files by type.

Searched Guidance — Chart displays the guidance

categories and the number of times each was

searched by the user in a given timespan. Also

indicates the rulepack in which the guidance was

found.

Top Findings — The ten most frequent findings for

the selected user.

Issues Reviewed —Chart shows the number of

issues found and reviewed by the user. Requires

the selection of a project.

Issues Suppressed — Displays issues suppressed

by the user for a given timespan, project, and file.

Requires the selection of a project.

Sort by

(available only when

Top Findings or

Issues Suppressed is

selected)

Choose to sort results by one of the following:

Category —Category of rules that were

triggered/fired.

Title — Name of specific rule.

Select a Project

(available only when

Issues Reviewed or

Issues Suppressed is

selected)

Click this button to select a project.

Show Chart Click this button to display the statistics based on the

selected criteria.

Download CSV Click this button to save the data to a CSV file.


2. From the User Statistics Options window, make your criteria

selections.

3. Click Show Chart. SecureAssist displays a chart based on

your selections.

4. If desired, click Download CSV to save the data to a CSV file.


3 Reports There are two types of reports: Project and User. Each report

subcategory has several reports that can be generated.

Project Reports

Project reports are reports you create for one or more selected

projects. When you add a report, the application generates a ZIP

archive containing the various report types you’ve selected in the

New Report flyout. When you navigate to the Project Reports screen,

you will see a list of report packages that have already run. This will

be blank the first time you access the screen.

From this screen you will be able to run a new report from scratch,

view the details of previously run report packages, and rerun and

download previously run report packages.

Find a Report

1. To quickly find a report in the report list, enter text into the

Find a Report box. The list will automatically filter to show

only those reports whose names contain the text.

View Details of Previously Run Report

1. To view the project associated with a report, click under the

Projects column in that report’s row. The Filters flyover opens

on the right, displaying the project names selected or the

metadata used to select the project.


2. To view all other details about a report, click anywhere in the

report’s row except the Projects column. A flyout opens that

displays the Report Name, Date Range, Report Types, Start

Time and End Time when the report was run, Duration of the

report run, and Status.

Add a New Report

To run a report, you must select a report type, then select the

projects you wish to report on.

1. On the Project Report screen, click Add Report. The New

Report flyout opens.

2. In Name, enter a title for the report. This is how the report

results will be listed on the Project Report screen.

3. In Date Range, select one of the following options: 7 Days, 30

Days, or All.

4. Under Report Types, select one or more report types. (For

samples, see the appendices.)

Types of Project Reports Description

Portfolio Summary Report Lists unique defects per project, number of files

scanned, and lines of code based on the most recent

project/solution scan date.

Project Report Lists all files scanned as a part of project/solution

review including most recent scan date, defect

counts, lines of code, and developer who performed

the last scan.

Project Defect Report Lists all rules that triggered during last

project/solution review per project.

Global Defect Report Lists all rules that triggered across all files.

5. Click Next. (Next will only be available when you’ve entered a

name AND selected at least one report type.) The Filters

flyout appears, with the title of your report name at the top.

You will use this flyout to filter the projects you wish to report

on by either Project Name or Metadata. Click on each

section title to display the associated fields.


6. On the Filters flyout, select the projects you wish to report on

by either:

In the Project Name section, select one or more projects by

clicking the Add button next to each OR click Add All to select

them all.

OR

In the Metadata section, specify metadata values to select

projects.

a. In Key, enter the desired field you wish to use to filter.

b. In Value, enter the desired filter value.

c. Click Add. The filter criteria will be added to a list below

the Add feature.

d. Add more criteria as desired.

7. Click Save. The Filter flyout closes and you are returned to

the Project Reports screen. Your new report should be listed

at the top of the screen, with its status as Scheduled. The

status will toggle to Complete when the report is generated

(generation time varies with the size of the report).


Download a Report

1. From the Project Reports screen, click anywhere in the row of

the desired report EXCEPT the Projects column. A flyout

opens with a list of report details and several action buttons.

2. Scroll to the bottom of the flyout and click Download Report.

A ZIP file of the report results is automatically saved to your

Downloads folder.

3. Open the ZIP file. A separate CSV file is displayed for each

report type you selected.

Note: The downloaded ZIP files will be named “ProjectReports”

with an appended run date, and CSV files will be named by report

type. The name you entered under Report Name appears ONLY

on the Project Reports screen.

Re-Run a Report

There are times you may want to run a report identical to one

you’ve previously run. Re-Run Report allows you to do this.




2. Scroll to the bottom of the flyout and click Re-Run Report.

The Filter flyout closes and you are returned to the Project

Reports screen. The re-run report should be listed at the top

of the screen, with its status as Scheduled. The status will

toggle to Complete when the report is generated.

Note: The rerun report will have the identical name as the

original run of the report; in other words, you will have two

items with the same name in the Project Reports list.

Copy to New Report

The Copy to New Report function is essentially a “save as”

feature: when you copy to new report, you create a new report

using the selections of a previously created report as the default

selections. You can then edit those selections before saving the

new report, or just create a new report name.





2. Scroll to the bottom of the flyout and click Copy to New

Report. A flyout opens that displays the previously selected

date range and report types, but with a blank for report

name.

3. Enter a new report name in Name.

4. If desired, change selections in Date Range and Report

Types.

5. Click Next to proceed to the Filters flyout.

6. If desired, change the filter criteria.


the Project Reports screen. Your new report should be listed

at the top of the screen, with its status as Scheduled. The

status will toggle to Complete when the report is generated.

Delete a Report




2. At the top of the flyout, click Delete Report. A popup asks

you to confirm the deletion.

3. Click Yes, delete it. You are returned to the Project Reports

screen, and the report instance is deleted from the list.


User Reports

User reports are reports you create for one or more selected user

groups. When you add a report, the application generates a zip

archive containing the various report types you’ve selected in the

New Report flyout.

When you navigate to the User Reports screen, you will see a list of

report packages that have already run. This will be blank the first

time you access the screen.

From this screen you will be able to run a new report from scratch,

view the details of previously run report packages, and rerun

previously run report packages.

Find a Report

1. To quickly find a report in the report list, enter text into the

Find a Report box. The list will automatically filter to show

only those reports whose names contain the text.

View Details of Previously Run Report

1. To view the user groups associated with a report, click under

the Users column in that report’s row. The Filters flyover

opens on the right, displaying the selected user groups.

2. To view all other details about a report, click anywhere in the

report’s row except the Users column. A flyout opens that

displays the Report Name, Date Range, Report Types, Start

Time and End Time when the report was run, Duration of the

report run, and Status.


Add New Report

To run a report, you must select a report type, then select the

user groups you wish to report on.

1. On the User Reports screen, click Add Report. The New

Report flyout opens.

2. In Name, enter a title for the report.

3. In Date Range, select one of the following options: 7 Days, 30

Days, or All.

4. Under Report Types, select one or more report types. (For

samples, see the appendices.)

Types of User Reports Description

Developer File Coverage

Report

Lists count of files reviewed by type by each developer.

Developer Defect Report Lists total number of issues by category for each developer.

Developer Project

Report

Lists all files scanned by each developer. Report includes the

most recent date file was scanned by a developer, defect

counts, suppression counts, and lines of code for each file.

Developer Usage Report Lists total defect counts, suppression counts as well as first

and last time tool was used by developer.

5. Click Next. (Next will only be available when you’ve entered a

name AND selected at least one report type.) The flyout is

now titled with your report name, and the Included Groups

section appears. (These are groups that you create in the

Manage section of SecureAssist Portal.)


6. In the Included Groups section, select one or more groups

by clicking the Add button next to each OR click Add All to

select them all.


the User Reports screen. Your new report should be listed at

the top of the screen, with its status as Scheduled. The status

will toggle to Complete when the report is generated.

Download a Report

1. From the User Reports screen, click anywhere in the row of

the desired report EXCEPT the Users column. A flyout opens

with a list of report details and several action buttons.

2. Scroll to the bottom of the flyout and click Download Report.

A ZIP file of the report results is automatically saved to your

Downloads folder.

3. Open the ZIP file. A separate CSV file is displayed for each

report type you selected.

Note: The downloaded ZIP files will be named “UserReports” with

an appended run date, and CSV files will be named by report

type. The name you entered under Report Name appears ONLY

on the User Reports screen.


Re-Run an Existing Report

There are times you may want to run a report identical to one

you’ve previously run. Re-Run Report allows you to do this.




2. Scroll to the bottom of the flyout and click Re-Run Report.

The Filter flyout closes and you are returned to the Project

Reports screen. The re-run report should be listed at the top

of the screen, with its status as Scheduled. The status will

toggle to Complete when the report is generated.

Note: The rerun report will have the identical name as the

original run of the report; in other words, you will have two

items with the same name in the User Reports list.

Copy to New Report

The Copy to New Report function is essentially a “save as”

feature: when you copy to new report, you create a new report

using the selections of a previously created report as the default

selections. You can then edit those selections before saving the

new report, or just create a new report name.




2. Scroll to the bottom of the flyout and click Copy to New

Report. A flyout opens that displays the previously selected

date range and report types, but with a blank for report

name.

3. Enter a new report name in Name.

4. If desired, change selections in Date Range and Report

Types.

5. Click Next. A list of the users to be included in the report is

displayed.


the User Reports screen. Your new report should be listed at

the top of the screen, with its status as Scheduled. The status

will toggle to Complete when the report is generated.


Delete a Report




2. At the top of the flyout, click Delete Report. A popup asks

you to confirm the deletion.

3. Click Yes, delete it. You are returned to the User Reports

screen, and the report instance is deleted from the list.


4 Rulepacks A rulepack is a JAR file containing rules and guidance used by

SecureAssist to scan your projects. You can load and distribute

multiple rulepacks to your plugin users by enabling and disabling

them on the Portal.

SecureAssist provides a default rulepack, but you can also create and

edit your own custom rulepacks using the Rulepack Configurator that

comes bundled with the SecureAssist plugins. (Go to

https://codiscope.com/secureassist/docs and click Rules &

Rulepacks.)

You can have more than one default and/or custom rulepacks active.

Find a Rulepack

1. To quickly find a rulepack in the rulepack list, enter text into

the Find a Rulepack box. The list will automatically filter to

show only those rulepacks whose names contain the text.

View Details of Rulepack

1. To view all details about a rulepack, click anywhere in the

rulepack’s row. A flyout displays the following details. All

fields have their values set in Rulepack Configurator and are

read-only in SecureAssist Portal EXCEPT Status.

Field Description

Name Name of uploaded rulepack.

Status

(updateable)

Enabled or Disabled; indicated by a color bar in the left

margin. More than one rulepack can be enabled at one

time. Click on this toggle to change the rulepack’s status.

Version Version number of uploaded rulepack.

Plugin Support List of plugin versions supported by this rulepack.

Type Type of rulepack (Default or Custom).

Access Level of access (Restricted or Unbounded). A restricted

rulepack is accessible only by specified admin users.

Uploaded Date the rulepack was uploaded.

https://codiscope.com/secureassist/docs


Upload a Rulepack

1. On the Rulepacks screen, click Upload Rulepack.

2. Browse to locate the desired rulepack, then click Open to

upload it. You are returned to Rulepacks, and the new

rulepack will appear in the list with a Status of Disabled.

Enable/Disable a Rulepack

1. On the Rulepacks screen, single-click the row of the desired

rulepack. The editing flyout appears on the right.

2. Under Status, click Enabled or Disabled to select the desired

status. The flyout immediately closes, and the status of the

rulepack is updated. Changes to a rulepack become available

to users the next time they begin a session.

Download a Rulepack to edit on your machine



2. Click Download. A popup asks you to confirm the download.

3. Click Keep. The rulepack file is downloaded to your

computer. You can now edit it using Rulepack Configurator.

Delete a Rulepack



2. Click Delete Rulepack. A popup asks you to confirm the

deletion.

3. Click OK. The flyout closes, and the rulepack is removed from

the list.


5 Manage The Manage function allows you to administer users, groups, and

roles used in the SecureAssist Portal, as well as your personal

account.

Portal Users

The Portal Users screen allows you to manage the various users of

the SecureAssist Portal. These are not your plugin users, but

essentially the administrators of your SecureAssist system, such as

your portal administrators, rulepack administrators, and users who

view and generate reports based on plugin user activity.

The one default Portal user is the Server Administrator—sa-admin—

which cannot be deleted. You create and maintain the other Portal

users.

Each user is either a local user whose credentials are stored in the

Portal database and authenticated against them or authenticated

using LDAP.

Find a Portal User

1. To quickly find a user in the portal user list, enter text into the

Find a Portal User box. The list will automatically filter to

show only those portal users whose names contain the text.

Add a Portal User

1. On the Portal Users screen, click Add Portal User. The New

User flyout opens.

2. Enter a user name in Name. The user name can contain

letters and numbers only, NO spaces or special characters.

3. Enter a temporary password in Password for the new user

and then confirm it. The password must contain at least six

characters, including at least one capital letter, one lowercase

letter, and one number. The user will be able to change the

password when they log into the system.

4. Click Next to continue. The Roles flyout opens.


5. Select the role or roles you wish to assign to the user by

clicking the associated slide buttons, then click Next. The

Managed Users flyout opens.

6. If desired, select one or more users to manage, then click

Next. The Managed Projects flyout opens.

7. If desired, select one or more projects to manage, then click

Save. The flyout closes, and the new user is added to the

Portal Users list in alphabetical order with a Status of Active.

Activate/Inactivate a Portal User

1. On the Portal Users screen, single-click the name of the

desired rulepack. The editing flyout appears on the right.

2. To change the user’s status, click the slide button next to the

Status, then click Save. The flyout is closed, and the user’s

new status should be displayed on the Portal Users list.

Change/Reset a Portal User’s Password



2. Click Change Password. The New Password and Confirm

New Password fields appear.

3. Enter and confirm a new password for the user. The

password must contain at least six characters, including at

least one capital letter, one lowercase letter, and one

number.

4. Click Save. The flyout is closed, and you are returned to the

Portal Users list.

Edit a Portal User’s Assigned Roles

1. On the Portal Users screen, single-click in the Roles column of

the desired rulepack’s row. The Roles flyout appears on the

right.

2. Select the role or roles you wish to assign to the user by

clicking the associated slide buttons, then click Save. The

flyout closes, and the number of roles for the user is updated

in the Portal Users list.


Edit a Portal User’s Managed Users

1. On the Portal Users screen, single-click in the Users column of

the desired rulepack’s row. The Managed Users flyout

appears on the right.

2. Select the users you wish to assign to the portal user by

clicking the Add and Remove buttons, then click Save. The

flyout closes, and the number of users for the portal user is

updated in the Portal Users list.

Delete a Portal User



2. Click Delete User. A popup asks you to confirm the deletion.

3. Click Yes, delete it. The flyout closes, and the user is

removed from the list.

Plugin User Groups

The Plugin User Groups screen is where you can create and manage

groups of client-side plugin users of SecureAssist. The groups you

create here can then be used to filter data in the User Reports

section of SecureAssist Portal. There are no default user groups, so

the Plugin User Group screen will be blank the first time you visit it.

As you add groups, they will be listed on the screen.

Note: You can assign individuals to a plugin user group here OR on

the Client License screen.


Find a Plugin User Group

1. To quickly find a plugin user group in the group list, enter text

into the Find a Group box. The list will automatically filter to

show only those plugin user groups whose names contain the

text.

Add a Plugin User Group

1. On the Plugin User Group screen, click Add Group. The New

User Group flyout opens.

2. In Group Name, enter a name for the new group.

3. In Description, enter a brief description of the group.

4. Click the Add button next to each user you wish to add to the

group OR click Add All to add all users.

5. Click Save. The flyout closes, and your new group is added to

the Plugin User Groups list.

Edit a Plugin User Group

1. On the Plugin User Group screen, click the Edit button

next to the desired group. The User Group flyout opens.

2. Make any desired edits to the user group, then click Save.

The flyout closes, and you are returned to the Plugin User

Groups list.

Delete a Plugin User Group

1. On the Plugin User Group screen, click the Edit button

next to the desired group. The User Group flyout opens.

2. Click Delete Group. A popup asks you to confirm the

deletion.

3. Click Yes, delete it. The popup closes, and the user group is

removed from the Plugin User Groups list.


Roles

The Roles screen allows the Server Administrator to create new,

custom roles to assign to portal users on the Portal Users screen. You

can assign and maintain the specific permissions you want to allow

users in each group.

There are four default roles in the SecureAssist Portal:

GROUP_ADMIN, GROUP_STATS_VIEWER, SERVER_ADMIN, AND

STATS_VIEWER. You can see the default permissions assigned to

each of these roles in the appendix. There is also a complete list of all

permissions and their descriptions.

Find a Role

1. To quickly find a role in the role list, enter text into the Find a

Role box. The list will automatically filter to show only those

roles whose names contain the text.

Add a Role

1. On the Roles screen, click Add Role. The New Role flyout

opens.

2. Enter a unique role name in Name.

3. If desired, enter a brief description of the new role in

Description.

4. Click Next. The Permissions flyout opens.

5. Select the desired permissions, then click Save. (You must

select at least one permission in order to save the new role.)

The flyout closes and the new role is added to the Roles

screen.

Edit a Role’s Name or Description

1. On the Roles screen, click on the name of the role you wish to

edit. The editing flyout opens.

2. Make the desired edits to Name or Description, then click

Save. The flyout closes and your changes are saved.


Edit a Role’s Permissions

1. On the Roles screen, click on the permissions column in the

row of the role you wish to edit. The Permissions flyout

opens.

2. Make the desired changes to permissions, then click Save.

The flyout closes and your changes are saved.

Delete a Role

1. On the Roles screen, click on the name of the role you wish to

delete. The editing flyout opens.

2. Click the Delete Role button. A popup asks you to confirm

the deletion.

3. Click Yes, delete it. The flyout closes and the role is deleted

from the Role screen.

Account

The Account screen is where you can update your password for the

Portal.

Update Your Password

1. On the Account screen, enter your current password in

Current Password.

2. Enter your new password in New Password.

3. Re-enter your new password in Confirm New Password.

4. Click Save.


6 Settings

LDAP Configuration

The LDAP Configuration screen is where you configure LDAP settings

if you choose to use LDAP authentication for the Portal.

Section Feature Description

Authentication

& Security LDAP Authentication Enables LDAP authentication on the server for portal

users and plugin clients. (Note: plugin clients will only be

able to authenticate with LDAP usernames if Client LDAP

is also selected in Features Configuration.)

Secure LDAP If the checkbox is selected, the LDAP connection occurs

over an SSL connection.

Server Server Name The scheme and hostname of the LDAP url.

Port The port on which the LDAP server resides.

Timeout The amount of time in seconds within which LDAP

queries will time out.

Login Scope This setting is most similar to a baseDN field in LDAP.

The Enterprise Portal uses the SUBTREE_SCOPE when

running an LDAP query, and it cannot be changed from

this.

Filter Expression The LDAP search filter expression restricts the entries

that are queried.

DN Similar to the SECURITY_PRINCIPAL setting.

Password This is required if the "Login DN" setting is specified.


Feature Configuration

The following table describes the various feature settings.


Portal CSA Portal Allows user to activate IDE plugin/add-in and retrieve

license file and rulepack from Portal.

If this feature is disabled, the IDE plug-in will not activate

as Enterprise Edition.

Client

Authentication LDAP Authenticates SecureAssist users against LDAP.

To activate a SecureAssist plug-in Enterprise Edition

user, the user must be present in Active Directory.

Note: This feature can be enabled only if the LDAP

connection is configured.

Email Authenticates SecureAssist users against email. Enter

one or more domains in the Domains field; separate

multiple domains with a semicolon.

To activate a SecureAssist plug-in Enterprise Edition

user, the user’s email address must match the

organization’s domain name.

Client License Renewal Period Client license renewal period in days.

Support Email To Email address used to send support emails.

Subject Default subject for support emails.

Statistics CSA Enables automatic collection and uploads to the portal

of SecureAssist plug-in statistics.

Anonymous Gathers statistics in anonymous mode—that is, statistics

are linked to a project but are not associated with a

particular user.

Local

Configuration Filters Allows users to locally modify filter settings (for

example, turn off filters and rules, change importance,

etc.).

Review When selected, allows users to decide when file should

be scanned (for example, when they are opened, when

they are saved, or on demand).

This setting must be “unchecked” to force settings from

the Server Administrator, below.



Review

Configuration Review on File Open File review is performed on file open.

Note: To prevent users from changing this setting

ensure that Review Configuration is disabled.

Review on File Save File review is performed on file save.

Note: To prevent users from changing this setting

ensure that Review Configuration is disabled.

Project Review Review of entire project, package, or folder is performed

on demand.

Suppress Issue Allows plug-in users to suppress issues for the duration

of an IDE session.

Allowed File

Types for

Eclipse-based

IDEs

java Enables SecureAssist plug-in users to scan Java files.

jsp Enables SecureAssist plug-in users to scan JSP files.

xml Enables SecureAssist plug-in users to scan XML files.

properties Enables SecureAssist plug-in users to scan Properties

files.

ftl Enables SecureAssist plug-in users to scan FTL files.

php Enables SecureAssist plug-in users to scan PHP files.

Additionally PHP fragment must be installed.

Allowed File

Types for Visual

Studio

cs Enables SecureAssist plug-in users to scan C# files.

vb Enables SecureAssist plug-in users to scan VB .NET files.

aspx Enables SecureAssist plug-in users to scan ASP.NET files.

config Enables SecureAssist plug-in users to scan .NET

Configuration files.


Server License

The Server License screen displays the details of your server license.

This screen is read-only.

Field Description

License

Expiration Date

When the license for the Portal expires. Administrators will

still be able to login after that date and client statistics will

continue to be processed for up to 30 days, but no new

client licenses will be issued.

Client Nodes

Allowed

This is the maximum number of clients that can be

licensed by the Portal.

Client Licenses

The Client Licenses screen displays a list of the users who have

activated a plugin or add-in license.

To view details of individual user licenses, click the user’s row. A

flyout opens displaying the information about the user license.

Find a User

1. To quickly find a user in the Client License list, enter text into

the Find a User box. The list will automatically filter to show

only those users whose names contain the text.

The significant fields are:

Field Description

Node This field lists the MAC Address which is used as the client

discriminant. Up to 2 of these are stored per user, allowing

both the Eclipse plugin and Visual Studio add-in to be used

by each licensed user.

Refreshed This field shows the last time the license was downloaded

by the client.


Add a User to a Plugin User Group

Note: You can assign individuals to a plugin user group here OR

on the Plugin User Groups screen.

1. On the Client Licenses screen, select a user by clicking on its

row. A flyout opens with the details for that user.

2. Under Group Assignments, click Add next to one or more

user groups you wish to add the user to, then click Save. The

flyout closes and the user is now assigned to the selected

groups.

Delete a User

1. On the Client Licenses screen, select a user by clicking on its

row. A flyout opens with the details for that user.

2. Click the Delete User button. A popup asks you to confirm

the deletion.

3. Click Yes, delete it. The user is deleted, and the flyout closes.


7 More Support We hope this document has helped you get started with

SecureAssist. You can submit a support request at

support.codiscope.com. You will also find other manuals, release

notes, system requirements, and more.

Thanks for using Codiscope SecureAssist!

www.codiscope.com

20 Park Plaza, Suite 1400

Boston, MA 02116

Phone: + 1 (617) 804-5428

[email protected]


http://www.codiscope.com/

mailto:[email protected]


8 Appendix

Roles and Associated Permissions

Each user must be assigned at least one role. Each possible role is

described below.

Role Name Permissions

GROUP_ADMIN PER_ADD_USER

PER_DELETE_RULEPACK

PER_DISABLE_RULEPACK

PER_ENABLE_RULEPACK

PER_UPLOAD_RULEPACK

PER_VIEW_RULEPACK

GROUP_STATS_VIEWER PER_VIEW_USER_STATS

PER_VIEW_PROJECT_STATS

SERVER_ADMIN PER_ADD_USER

PER_EDIT_USER

PER_DELETE_USER

PER_RESET_LOCAL_USER_PASSWORD

PER_ADD_ROLE

PER_EDIT_ROLE

PER_DELETE_ROLE

PER_UPLOAD_RULEPACK

PER_VIEW_ALL_RULEPACK

PER_VIEW_RULEPACK

PER_ENABLE_ALL_RULEPACK

PER_DISABLE_ALL_RULEPACK

STATS_VIEWER PER_VIEW_ALL_STATS


Permission Descriptions

Each new Role is defined by the permissions selected. The Role

Name must be unique.

Permission Name Description

PER_ADD_USER Allows adding user to the system.

PER_EDIT_USER Allows editing user in the system.

PER_DELETE_USER Allows deleting user from the system.

PER_RESET_LOCAL_USER_PASSWORD Allows resetting local user password.

PER_ADD_ROLE Allows adding new role.

PER_EDIT_ROLE Allows editing existing role.

PER_DELETE_ROLE Allows deleting role.

PER_UPLOAD_RULEPACK Allows uploading rulepack.

PER_VIEW_ALL_RULEPACK Allows viewing all rulepacks uploaded to the server.

PER_VIEW_RULEPACK Allows viewing rulepacks uploaded by user.

PER_ENABLE_ALL_RULEPACK Allows enabling all rulepacks uploaded to the server.

PER_ENABLE_RULEPACK Allows enabling rulepacks uploaded to the server by user.

PER_DISABLE_ALL_RULEPACK Allows disabling all rulepacks uploaded to the server.

PER_DISABLE_RULEPACK Allows disabling rulepacks uploaded to the server by user.

PER_RESTRICT_ALL_RULEPACK Allows restricting access to all rulepacks uploaded to the

server for all users.

PER_RESTRICT_RULEPACK Allows restricting access to rulepacks uploaded to the server

by user for managed group of users.

PER_DELETE_ALL_RULEPACK Allows deleting any rulepack uploaded to the server.

PER_DELETE_RULEPACK Allows deleting rulepack uploaded to the server by user.

PER_VIEW_ALL_STATS Allows viewing all statistics.

PER_VIEW_USER_STATS Allows viewing statistics for managed users.

PER_VIEW_PROJECT_STATS Allows viewing statistics for managed projects.

PER_SYSTEM_ADMIN Allows editing server configuration.

secureassist enterprise portal user guidedownload.asteriskresearch.com/2.4/secureassist... ·...

Documents