protexIP 4.3 Enterprise Tutorial

Black Duck Software, Incorporated Black Duck Software, Incorporated Black Duck Software, Incorporated Black Duck Software, Incorporated

protexIP™ Tutorial protexIP™ Tutorial protexIP™ Tutorial protexIP™ Tutorial

Enterprise Version 4.Enterprise Version 4.Enterprise Version 4.Enterprise Version 4.3333

First Edition May 2007

This document created or updated in May 2007 .

Please send your comments and suggestions to:

Black Duck Software, Incorporated 265 Winter Street Waltham, MA – 02451 USA.

Copyright © 2007 by Black Duck Software, Inc.

All rights reserved. All use of this documentation is subject to the license agreement between Black

Duck Software, Inc. and the licensee. No part of the contents of this help system may be reproduced

or transmitted in any form or by any means without the written permission of the publisher.

Black Duck and protexIP(TM) are trademarks of Black Duck Software, Inc. All other trademarks or

registered trademarks are the sole property of their respective owners.

Copyright© 2007 Black Duck Software, Incorporated. All rights reserved.

iii PROTEX IP TUTORI AL

Table of Contents

1 INTRODUCTION .................................................................................7

1.1 BLACK DUCK KNOWLEDGEBASE .................................................................. 8 1.2 PROCESS OVERVIEW ............................................................................. 9

2 GETTING STARTED ........................................................................... 11

2.1 LOG IN .........................................................................................11 2.2 START PAGE....................................................................................12 2.3 CODE LOCATION................................................................................12 2.4 USING THE TUTORIAL...........................................................................13

3 PROCESS SUMMARY .......................................................................... 15

3.1 CREATE A PROJECT & RUN ANALYSIS...........................................................15 3.2 IDENTIFY .......................................................................................16 3.3 BILL OF MATERIALS .............................................................................19 3.4 REVIEW.........................................................................................20 3.5 REPORTS .......................................................................................21

4 MORE ON MANAGING PROJECTS .......................................................... 23

4.1 MANAGE � PROJECT...........................................................................23 4.2 MANAGE � ANALYSIS ..........................................................................26 4.3 MANAGE � OBLIGATIONS ......................................................................28 4.4 MANAGE � SEARCHES..........................................................................29 4.5 MANAGE � PATTERNS .........................................................................30

5 MORE ON IDENTIFICATION ................................................................. 35

5.1 IDENTIFICATION OPTIONS .......................................................................35 5.2 IDENTIFY FILES IN A FOLDER ....................................................................36 5.3 IDENTIFY AS ORIGINAL ..........................................................................36 5.4 IDENTIFY A BINARY FILE ........................................................................37 5.5 CHANGE LINKS..................................................................................37 5.6 USAGE..........................................................................................37 5.7 DECLARE A FILE ................................................................................38 5.8 DECLARE A FOLDER.............................................................................39 5.9 ADDING COMPONENTS ..........................................................................39

6 LICENSE CONFLICTS ......................................................................... 41

6.1 VIEWING LICENSE CONFLICTS ...................................................................41

7 CODE PRINTING............................................................................... 43

7.1 WHY CODE PRINT? .............................................................................43 7.2 ADD A CODE PRINT .............................................................................44 7.3 MANAGING CODE PRINTED PROJECTS ...........................................................45

8 LICENSE MANAGEMENT ..................................................................... 47

iv PREF ACE

8.1 ADDING A CUSTOM LICENSE.....................................................................48 8.2 EDITING EXISTING LICENSES ....................................................................49

9 OBLIGATIONS AND REVIEW................................................................. 51

9.1 CREATING GLOBAL OBLIGATIONS AND OBLIGATION CATEGORIES ................................51 9.2 ADDING OBLIGATIONS TO A PROJECT ...........................................................52 9.3 ADDING OBLIGATIONS TO KNOWLEDGEBASE LICENSES AND COMPONENTS .......................53 9.4 PRESENTING OBLIGATIONS FOR REVIEW BY CATEGORY..........................................54

10 COMMAND LINE INTERFACE ................................................................ 57

10.1 BDSTOOL UTILITY...............................................................................57 10.2 RUNNING ANALYSIS .............................................................................58 10.3 CODE PRINTING ................................................................................59

Preface

INTENDED AUDIENCE This tutorial is designed to help first-time users (developers, attorneys, managers, etc.)

become familiar with the basic features of protexIP.

CONTENTS OVERVIEW Chapter 1 Introduction— Provides a brief explanation of how protexIP works.

Chapter 2 Getting Started— Explains how to login and prepare to run the tutorial.

Chapter 3 Process Summary— Conduct a full code analysis, from project creation to

producing reports.

Chapter 4 More on Managing Projects—This chapter describes what can be done on

each of the Manage tabs.

Chapter 5 More on Identification— Describes additional options for Identification.

Chapter 6 License Conflicts— A brief introduction to reviewing and resolving license

conflicts.

Chapter 7 Code Printing— Learn how to customize your KnowledgeBase by adding

proprietary, 3rd party, or open source code.

Chapter 8 License Management— Explains how to customize your KnowledgeBase by

adding proprietary, 3rd party, or open source licenses, and how to edit and approve licenses.

Chapter 9 Obligations and Review— How to create and group obligations to use as a

check list for review.

Chapter 10 Command Line Interface— Explains how to use the command line to run

analysis and code print.

v PROTEX IP TUTORI AL

Figures

FIGURE 1 DUCK UPDATE................................................................................... 8 FIGURE 2 PROCESS NAVIGATION ........................................................................... 9 FIGURE 3 THE PROJECT LIST ............................................................................ 12 FIGURE 4 THE CODE TREE............................................................................... 16 FIGURE 5 SELECT TOP LEVEL OF CODE TREE ............................................................ 19 FIGURE 6 DOUBLE ARROWS.............................................................................. 20

vi PREF ACE

This page intentionally left blank.

IIIINTRODUCTIONNTRODUCTIONNTRODUCTIONNTRODUCTION

1 INTRODUCTION

Chapter Goal Provide a brief explanation of how protexIP™ works.

Time to complete 5 minutes reading.

No exercises.

Audience All protexIP Users.

Tasks • Understand how analysis is done.

• Think about the process.

Increasingly, the software development industry is assembling software using a combination of reusable components and their own proprietary code, rather than building applications entirely from scratch. Using these open source and 3rd-party components can reduce development costs and speed up the development process, but it also increases the complexity of software licensing obligations.

In this environment of composite, mixed intellectual property (IP), or ‘mixed-IP’, companies are increasingly concerned with keeping control of their own IP and properly managing the origins and obligations associated with the components that they reuse.

You can use protexIP to analyze, identify, and manage your software IP assets, and reduce the risks associated with a mixed-IP development environment.

1

8 INTRODUCTION

1.1 Black Duck KnowledgeBase

The Black Duck KnowledgeBase is a comprehensive collection of information about open

source software components and licenses. During analysis, protexIP compares the code in

your project to the components in the KnowledgeBase, and code matches are discovered.

protexIP reports on matching files, the components they come from and the licenses that

govern them. As you identify the components that make up your project, protexIP

assembles the list of licenses and obligations required for fulfillment.

1.1.1 Updating the KnowledgeBase

Updates from Black Duck, called Duck Updates are applied regularly to your KnowledgeBase.

Duck Updates consist of new software components, updates to existing components,

application updates, and new license versions for the KnowledgeBase. The Administrator at

your site manages the Duck Updates.

.

Figure 1 Duck Update

1.1.2 Code Prints & Code Matches

Files are stored in the KnowledgeBase in the form of code prints, which are digital

representations of the files. During analysis, protexIP creates code prints of your files and

compares them to the code prints in the KnowledgeBase. A code match is reported when

your code prints match KnowledgeBase code prints.

Two types of code matches are reported:

• File matches—Your file exactly matches one or more files in the KnowledgeBase.

• Snippet matches—Your file contains some code that matches code in one or

more files in the KnowledgeBase.

When a match to a KnowledgeBase file is discovered, protexIP provides the project and

license information for the detected file.

9 PROTEX IP TUTORI AL

1.1.3 KnowledgeBase Licenses

There are more than one thousand licenses that govern the projects stored in the

KnowledgeBase. The licenses are defined by a set of attributes that cover topics such as the

right to modify, copy or reverse engineer the code, the right to charge a fee, and so on. A set

of obligations for each license is derived from the attribute settings. If your source includes

code from several components with incompatible obligations, protexIP reports a license

conflict.

1.1.4 Customizing the KnowledgeBase

You can customize the KnowledgeBase by adding and editing components, as well as the

licenses and obligations that go along with them. The Code Printing feature enables you to

add open source, 3rd party, and proprietary components to your local copy of the

KnowledgeBase in order to track and manage their re-use in your projects. Component

Manager and License Manager enable you* to note the approval status and edit the

obligations associated with any component or license. You can create new licenses and edit

existing KnowledgeBase licenses to reflect your corporate policy.

*The Attorney role is required to manage components and licenses.

1.2 Process Overview

Figure 2 Process Navigation

The protexIP user interface is set up with areas that guide you through a project analysis,

from creating a project to presenting a final report.

• Start—Create a new project or select an existing project.

• Manage—Set analysis options, run analysis, declare a project license.

• Identify—View and identify code matches and folders, review string search results,

view and edit the Bill of Materials (BOM).

• Review—Approve identified components in the Bill of Materials.

• Report—Create customized reports of your project.

In addition, there is a Tools page for administration and management.

10 INTRODUCTION

1.2.1 Discovery & Identification

During analysis, protexIP can discover the following types of data:

• File and snippet matches.

• Import statements and Include statements.

• Binary dependencies.

• String search results.

When analysis is complete, you can examine the discoveries and identify the origin of the

code. During this process, a Bill of Materials is created that lists the identified components.

These components are then ready for review and approval.

1.2.2 Review

This area is used to examine and determine the approval status of the components on the

Bill of Materials. Users must have the role of Manager or Attorney to conduct reviews.

1.2.3 Reports

You can create, save, or print reports at any point in the analysis process. Choose from a set

of customized report templates (if available), or create a report on-the-fly to meet particular

requirements. Reports can be created in HTML, Word or Excel formats.

GGGGETTING ETTING ETTING ETTING SSSSTARTEDTARTEDTARTEDTARTED

2 GETTING STARTED

Chapter Goal Login and prepare to run the tutorial.

Time to complete 20 minutes, plus 10 for client installation if required.

Audience All protexIP users.

Tasks • Login to your Black Duck Server.

• Download the client if required (ask your Black Duck Administrator).

• Continue the tutorial.

The protexIP server is accessed via a web interface. The supported browsers are Internet

Explorer and Mozilla Firefox. Your local machine can be either Linux or Windows.

2.1 Log in

To log in, follow these steps:

1. Open a browser window and navigate to the protexIP server.

http://<your blackduck server>

2. Enter your email address and the password that was provided by your Black Duck

Administrator, then click Login. The Start tab displays.

2

12 GETTING STAR TE D

2.2 Start Page

The Start page includes a table that displays status information about your projects. If you do

not have a protexIP project, the Start page displays the text message “No Projects Found.”

From this page you can:

• View and select your protexIP projects.

• Create new projects.

2.2.1 Project List

The project list shows all of the projects you are assigned to.

To sort the project list, follow these steps:

1. Click Project Name to sort the list alphabetically.

2. Click Last Analyzed to sort by analysis date.

3. Click Code Overview to sort by project status.

Figure 3 The Project List

2.2.2 Code Overview

The colors used in the Code Overview represent the status of the files in that project.

• Green—These files have no issues; either there are no matches, or the file has been

identified and approved.

• Yellow—These files have matches and need to be identified.

• Blue—These files are identified, and are pending approval.

• Red—These files are identified with a component that causes a license violation.

2.3 Code Location

Your code can reside on a server that is accessible by your protexIP server, or it can be kept

on your local machine.

If your code is local (ask your System Administrator about your configuration), you must

download the protexIP client in order to conduct analysis. If your code is accessible by the

protexIP server, you do not have to download the client.


2.3.1 Download and Login with the protexIP Client

The client is required to run analysis on local code.

Note: The protexIP client requires 150MB of disk space.

To download the protexIP client software, follow these steps:

1. Select the Tools link in the upper right hand corner of the protexIP browser, then

select the protexIP Client Software link under Download.

2. Under Client Software (Includes MB Estimation Tool), select either Download

(Linux) or Download (Windows) based on the operating system of your client

machine.

3. Follow the instructions to download and install the client.

In order to run analysis on local code, you must start protexIP via the client. Once the code

is analyzed, you can start protexIP via the client or by browsing directly to the server.

To start protexIP using the client tool, follow these steps:

1. To start the protexIP client on Windows, select

Start > Programs > Black Duck Software > protexIP.

2. Your default browser opens to the protexIP login page.

Note: Running the Linux client pops up two login windows rather than one.

2.4 Using the Tutorial

This tutorial is designed to introduce you to the basic steps for using protexIP, from running

analysis to issue resolution. This tutorial is also designed for a user with the role of

“Manager.” If your role is not Manager, your Black Duck Manager or Project Leader must

create the tutorial project for you.

To run the tutorial, you can use the sample files provided for the exercises. Download the

files onto your desktop or client computer. The sample files are in the Tutorial_Files.zip

file.

To download and extract the sample files, follow these steps:

1. Login to your Black Duck server.

2. Select the Help link. The Help Resources page displays.

3. Select Tutorial Sample Files.

4. Choose a location for Tutorial_Files.zip, such as “My Documents ” on a

Windows machine, or /home/user/ on a Linux machine. Save the file to this

14 GETTING STAR TE D

location.

5. Unzip the file. This extracts the sample files to a directory called Tutorial_Files.

Later in the tutorial, you are instructed to browse to the directory that contains the code.

PPPPROCESS ROCESS ROCESS ROCESS SSSSUMMARYUMMARYUMMARYUMMARY

3 PROCESS SUMMARY

Chapter Goal Conduct a full analysis, from project creation to producing reports. You can

explore additional details in the remaining chapters.

Time to complete 30 - 40 minutes.

Audience Managers, developers, attorneys and others who want hands-on use of the

software to obtain a high-level overview.

Tasks • Create and manage a project.

• Run analysis and review results.

• Identify components.

• Review components.

• Create a custom report.

Follow the steps outlined in this chapter to conduct your first analysis. Make sure you know

the location of the tutorial sample files.

The Manager or Project Leader role is required to create a new project. If you are not a Manager, the project must be created for you.

3.1 Create a Project & Run Analysis

The first step in conducting analysis is to create a protexIP project.

To create a new project, follow these steps:

1. Login to the server (directly or via the client, depending on code location). The

Start page displays.

2. Click New Project. The Create a New Project dialog appears.

3

16 PROCESS SUMM ARY

3. Select a file source by browsing to the location of the tutorial sample files and

highlighting the directory.

4. Edit the name for the project, such as “Amanda’s Test Project ”.

5. Select Proprietary for the default license type.

6. Select the Analyze Now check box.

7. Click OK to open the Manage �� Analysis tab. Scroll down to the bottom of the

page to view a status bar that displays the analysis progress.

8. When the analysis is complete, the Analysis Complete dialog appears. The Take

me to the next step check box is selected by default. Click OK to display the

Identify �� Bill of Materials tab.

Note: The Black Duck KnowledgeBase is constantly updated with new projects and licenses. Therefore, the results of your analysis may not match the results in the tutorial.

3.2 Identify

The Identify area is used to review and resolve analysis results. Analysis discoveries are

displayed on the Code Matches, Searches, and Dependencies tabs.

• The Bill of Materials tab displays identified components.

• The Code Matches tab displays the potential components.

• The Searches tab displays string search results.

• The Dependencies tab displays a list of

discovered dependencies.

Your code tree is displayed in the Identify idea, and

files are highlighted based on the selected filter. The

default filter is Pending Identification. As you

navigate through the code tree, the results on the

Code Matches, Searches, and Dependencies tabs

update to reflect the selected folder or file. When you

select the top-level folder, results for the entire

project are displayed.

Figure 4 The Code Tree

Note: To create a custom filter, click New Filter to display the Create New Filter pop-up. You can specify a variety of custom filter settings, including file name patterns.


Navigation

To view the results for specific folders, follow these steps:

1. Click the directory src_io. The Code Matches tab now displays detected

components for that directory.

2. Click any row in the table to open the Identify As area. This is used to further

explore the component and matched files, and to identify the component as part of

your project.

3. If your file matches multiple versions of a KnowledgeBase component, click the +

to expand the list and select a specific version.

4. Click the Searches tab to see the results for the src_io directory.

5. Click the Dependencies tab to see the results for the src_io directory.

To view the results for a specific file follow these steps:

1. Click samplefile1.h. The Code Matches tab displays the detected components

for the file.

2. Select any row in the table to open the Identify As area. This is used to further

explore the component and matched files, and to identify the component as part of

your project.

3. If your file matches multiple versions of a KnowledgeBase component, click the +

to expand the list and select a specific version.

4. As you select different components, the file comparison displays the current match.

Click Compare All Matches in New Window to see full screen file comparison.

Click print to view and print the current match.

5. View the Searches tab to see the results for the file.

6. View the Dependencies tab to see the results for the file.

To view the Bill of Materials, follow these steps

1. In your code tree, click the project name to view results for the entire project

2. Select the Bill of Materials (BOM) tab. There is currently only one component,

the project itself.

3. Files that do not require identification are assumed to be Original Code, as noted in

the Usage and # Files columns.

4. Select the Code Matches tab to begin identification.

18 PROCESS SUMM ARY

3.2.1 Identify a Folder

When you select a component that is listed on the Code Matches tab, an identification area is

displayed for the component. There is a show me link which displays the list of files that

match the component. By default, the radio option “Identify Snippet and File

Matches ” is selected.

Suppose that the PostgreSQL Database is part of your distribution.

To view the list of files that match a component, follow these steps.

1. Select the component Postgre SQL Database Server.

2. Click the show me link in the Identify As area. The filter changes to Pending

Identification as Postgre SQL Database Server. The code tree shows the

matching files in bold. Note that the matching files are all in one folder. In this

case, it is better to make the identification at the folder level.

3. Select the folder src_pgsl. The Code Matches tab refreshes. Again, select the

component Postgre SQL Database Server to view the Identify As area.

4. In the Component Comment field in area, you can write a summary of how and

why you use this component. This comment appears with the component in the

Review and Report areas, so use it to provide important information to the project

reviewers.

5. Click OK. The page refreshes. The PostgreSQL project appears bold in the

component table.

6. Navigate to the Bill of Materials (BOM) tab. This shows that 23 files are resolved

to the Postgre project.

7. In your code tree, select the project name to view the BOM for the entire project.

The BOM continues to grow as more components are identified.

3.2.2 Change the Filter

Refresh the filter to show files that need identification.

To change the filter, follow one of these two these steps:

• Click the drop-down arrow to view the list of filter options. Select Pending

Identification.

Note: The drop-down arrow may not be visible if the tree view frame is too narrow. Click and drag the right side of the frame to expose the drop-down arrow.

- or -

• Click the yellow area of the bar to select Pending Identification.


3.2.3 Identify a File

The status of the file samplefile.java is Pending Identification.

To view the matches and identify the file, follow these steps:

1. Click samplefile.java .

protexIP displays the file in the open frame on the page, and components with

matching files are listed. Notice that the Usage and % fields identify this match as

a 93% snippet match.

2. Select the various rows in the table to see a side-by-by side comparison of the

matched file. The yellow section bar at the side of the frame represents the

matched portion of the file.

3. This file contains a snippet from a file in the Apache-Jakarta Pool project. Select

the + icon to expand the versions of Pool, then select Version 1.3.

4. Add a Component Comment about your use of the Pool project, then click the

(save comment) link.

5. Select the Component Comment dropdown and select File Comment. Here you

can add a comment that will be attached to the file and displayed in various report

areas.

6. Click OK to complete the Identification. (Clicking OK automatically saves the

comment.)

protexIP only identified the matching snippet as Pool; the rest of the file is considered

original code. If you make modifications to the file, including adding a new open source

snippet, it will be found on the next analysis. If you navigate to the Bill of Materials for this

file, you will see that it has two sources: original code, and a snippet from Pool.

3.3 Bill of Materials

As you identified components in your code, they were added

to the Bill of Materials.

To view the Bill or Materials, follow these steps:

1. Select on the top level of your project in the code

tree.

2. Navigate to the Bill of Materials tab and view the

identified components.

Figure 5 Select Top Level of Code Tree

20 PROCESS SUMM ARY

3. Click the component Apache-Jakarta Pool. A frame opens where you can add

or edit information about the component.

4. Click the show me link to view the identified file.

Note: The >> arrows in front of the file samplefile.java indicate that the identification was done at the file level. An identification can be reset only at the level at which it was applied.

5. Select the component Postgre SQL Database Server

to verify the version number, license and comment.

6. Click the show me link and note that the >> arrows

indicate where the identification was done.

Figure 6 Double Arrows

3.4 Review

Your user role must be Manager or Attorney to view the Review area.

In the Review area, you go over the Bill of Materials. You can view the list of obligations

associated with each component, identify which obligations are fulfilled, and approve or

disapprove of the components.

To review the Bill of Materials, follow these steps:

1. Select Review. The Review area opens and displays a table that lists the

components on the Bill of Materials.

2. Select the table row for Apache-Jakarta Pool.

3. The project status is Pending Approval. If you are a manager or attorney, you can

change the status to Approved.

4. The listed obligations for Apache-Jakarta Pool reflect the obligations of the

Apache 2.0 license. If you are a manager or attorney, you can check off each

obligation as it is fulfilled.

5. If there is a conflict between this license and another license on the Bill of

Materials, only an Attorney can check Resolve License Conflicts.

6. The Reviewer can add text to the Component Comment.


3.5 Reports

When a project is complete, it is important to create and save a report on the project. In

addition, creating and saving reports along the way allows you to mark your progress.

Reports can be created at any time, and each report can contain different information, based

on the audience.

3.5.1 Code Label

The Code Label presents a summary of the project, in a familiar, easy-to-read format.

To view the Code Label, follow these steps:

1. Select the Report area for your project.

2. The Code Label tab displays.

3.5.2 Project

To create a project report, follow these steps:

1. Select the Report area for your project. Select the Project tab.

2. If your company created report templates, choose one from the Select a report

template drop-down list. You can continue to customize the report by enabling or

disabling sections as desired.

See Help, Types of Reports for a description of each section.

3. Use the Format drop-down list to choose an output format for the report.

4. Click Show Report. The report opens in a new window in the selected format.

5. Print or save the report as desired.

22 PROCESS SUMM ARY


MMMMORE ON ORE ON ORE ON ORE ON MMMMANAGING ANAGING ANAGING ANAGING PPPPROJECTSROJECTSROJECTSROJECTS

4 MORE ON MANAGING PROJECTS

Chapter Goal Create a project and run analysis.

Time to complete 45 minutes.

Audience Managers who create and maintain protexIP projects.

Tasks • Select a license.

• Set analysis options.

• Create project-level obligations.

• Create project-level string searches.

• Re-run analysis.

Managing a project entails selecting a license, choosing the capture options, creating project

level obligations, and running analysis. This chapter describes what can be done on each of

the Manage tabs.

4.1 Manage �� Project

You can use the Project tab to:

• Enter a project description.

• Enter information for the Code Label report.

• Declare a license.

• Define the file name patterns always to be flagged as Pending

Identification.

• Clone the project.

• Delete shared file contents.

• Delete the project.

4

24 MORE ON M AN AGI NG PROJECTS

4.1.1 Declare a License

The declared license is the license used for distribution of your project. protexIP reports

license violations and obligations based upon this license.

Note: The License Manager allows a company to add its own licenses to the KnowledgeBase. Users with the Attorney role can create licenses and define attributes and obligations.

You can choose a KnowledgeBase license, a Template license, or a custom license. If you

select the Proprietary license type when you create a project, the default license is the Basic

Proprietary Commercial License. To learn more about the Template licenses, view Help,

About Licenses.

To select a license, follow these steps:

1. In the License section, select Change.

2. Scroll through the list of licenses and select a new license. For this tutorial, we use

the default license, the Basic Proprietary Commercial License. You can change your

declared license at any time.

3. Click OK (button) to accept a new license, or Cancel to keep your current license.

4.1.2 Detect File Names

protexIP requires identification of files with matches; however, other files may also be of

interest even if no matches are discovered. Examples of this include:

• Files with the extension .jar or .exe often represent a component or library;

requiring identification of all these file types helps ensure a more complete Bill of

Materials.

• Files with the name legal may contain important license information that requires

attention, regardless of code matches.

The list of patterns can be set globally by the Black Duck Administrator; the Administrator

can enforce the default for all projects or allow changes to the defaults on a project basis.

To see an example of a Detected File Name, follow these steps:

1. Navigate to the Identification area.

2. Select the file lib/somecomponent.jar.

To identify a file without any matches, you must declare the file. Declaring files and folders

is similar to Identification and is covered in more detail in the next chapter.


4.1.3 Clone a Project

Cloning a project creates a replica of the original project. You might use this, for example, to

create a new protexIP project when you branch the development code, or to create an

experimental project. The project profile is cloned: declared licenses, analysis settings, search

strings, obligations, declared components, and so on. You can choose whether to include

analysis results and the list of project members.

To clone your current project, follow these steps:

1. On the Manage tab, click Clone Project. The Clone Project dialog appears.

2. Enter a name for the new project.

3. Select whether to clone the scan results. If you plan to scan new code, or to begin

the identification process from the start, do not select this option.

4. Select whether to clone the list of Assigned Users. If the new project has a

different user list, do not select this option.

5. Select OK to begin the clone.

6. When the process is complete, navigate to the Start area to select the new project

and run analysis.

4.1.4 Delete Multi-user File Comparison Content

During analysis, protexIP makes a copy of your non-binary files and puts them in a database on the protexIP server. During the Identification phase, these files are used to display file comparison, string search, and dependency results, allowing people without access to the code to conduct identification and review (hence the name, multi-user file comparison). This option allows you to delete the files from the protexIP server while retaining the project results.

To delete multi-user files for a project, follow these steps (if you choose to do this on the Tutorial project, re-

analyze the project to recreate the multi-user files):

1. Select the project from the Start page. The Manage � Project tab displays.

2. Select Delete Multi-user File Comparison Content.

3. Select Yes in the confirmation dialog, then click OK.


4.1.5 Delete a Project

Deleting a project removes all traces of the project from protexIP. Make sure you do not

delete a project accidentally, as it cannot be undone.

To delete a project, follow these steps (if you choose to do this on the Tutorial project, re-analyze the project to

continue):

1. Select a project to delete from the Start page. The Manage � Project tab displays.

2. Select Delete.

3. Select Yes in the confirmation dialog, then click OK.

4.2 Manage �� Analysis

From the Analysis tab you can:

• Update the code location.

• Set the capture options.

• Start analysis.

4.2.1 Database Options

The basic database for code matches and string searches is the KnowledgeBase. The

customer database contains code printed projects and custom string searches. You can

choose to do analysis against just one of the databases depending on your project

requirements. By default, both databases are selected.

4.2.2 Capture Options

protexIP discovery types are listed in the Capture Options section and included options are

checked. The default status of each item is set by the Black Duck Administrator. The

Administrator can enforce the default for all projects or allow changes to the defaults on a

project basis. The tutorial files contain examples of each discovery type.

Use the check boxes to turn the various options on and off.

• Code matches—Search for matches between your code and code in the

KnowledgeBase. File matches are exact matches between your file and one or more

files in the KnowledgeBase; snippet matches are found when a portion of code in

your file matches code in one or more KnowledgeBase files.

• Dependencies—Search for Import and Include statements, as well as DLLs, and

provide a list of files, packages, and libraries upon which your software depends.


• String Searches—String searches are designed to identify license text in your files.

In addition, you can create your own string searches.

• Expand archive files—With this option Off, each archive file (.jar , .zip, etc.)

is analyzed as a single binary file; with this option On, each archive file is treated

like a folder, and analysis is conducted on each file inside the archive. Initially, you

may want to leave this option Off.

o Exact matches to certain archive files, such as .jar files, are very useful

discoveries, and are only found if this option is Off.

o If you ran the MB estimation tool on unexpanded archive files, you may

use up your megabyte allotment if you expand the files.

To set Capture Options, follow these steps:

1. Check or uncheck any options.

2. Click OK to confirm your changes.

Note: If a project is already analyzed, it must be re-analyzed to implement the change.

4.2.3 Enable Multi-user File Comparison

Side-by-side file comparison is key to the identification of code matches. During analysis,

protexIP makes a copy of your non-binary files and puts them in a database on the protexIP

server. During the Identification phase, these files are used to display file comparison, string

search, and dependency results, allowing all project members to do file comparison without

needing access to the files themselves. These stored files are used only for identification; they

cannot be analyzed, downloaded, or used in any other way.

If Multi-user file comparison is set to No, file comparison only works for the following

scenario:

a. You download the client to run analysis, and

b. You maintain the code in the original location during Identification so

that protexIP can find it for file comparison.


4.2.4 Run Analysis

When you make changes to your code, you must re-run analysis to pick up the changes (for

example: new files, removed files, edited files). protexIP automatically analyzes only new

and modified files, allowing you to quickly run analysis on a regular basis once a project

baseline is done.

Black Duck adds new projects to the KnowledgeBase on a regular basis. In order to force

analysis of files against the new projects, select Re-analyze ALL files. You may want to re-

analyze all files at various points in the release process so your results are always up-to-date.

File, folder, and snippet resolutions are maintained, so you do not have to re-do that work

after re-analysis.

4.3 Manage �� Obligations

Obligations are tasks that must be fulfilled to meet the requirements of the project or

component. Obligations can come from various sources; by default, obligations are derived

from the declared license, but your attorneys and managers can create obligations at the

global level, as well as at the project level. Obligations can be organized into a customized

list of Categories, enabling you to determine who must fulfill the obligation.

The default obligations for a project come from the declared license. All project members

can view the obligations, but only an attorney or manager can mark them as fulfilled.

Additional obligations for a project can be added or created here.

To mark an obligation as fulfilled, follow these steps:

1. Select an obligation; the details display.

2. Check the box This obligation has been fulfilled.

3. Click OK. Repeat for all obligations.

To create a new obligation for the project, follow these steps:

1. Click Add an Obligation. The Add a New Obligation pop-up appears.

2. If your company has created global categories and obligations, select the

appropriate Global Obligation Category, and then the Global Obligation.

3. Click OK to add this to the project.

4. To create a new obligation, Click Add an Obligation. Tab to the Obligation field

and enter the task. Optionally, enter a description and select a Category.

5. Click OK to add the obligation to the project.


4.4 Manage �� Searches

String searches in the KnowledgeBase are designed to discover license text in your files.

Managers can create custom string searches at the global level, as well as at the project level.

Search strings are not case sensitive, and do not accept wildcard characters.

To add a project level string search, follow these steps:

1. On the Searches tab, click Add a String Search.

2. Enter a name for the string search, and a list of search words. To search for a

multi-word phrase, enclose the text in quotes.

Name: Search for Microsoft Files

Contains All of These Words: “Copyright by Microsoft”

3. Click Show More Options to build a more advanced string search.

4. Click OK to add the new string search.

5. You must re-run analysis to find matches to the new search.


4.5 Manage �� Patterns

protexIP analyzes every file in the folder of code; how analysis is conducted on the file

depends on its pattern and file type. A pattern is a group of letters, including the wildcard

character *, and can represent either the file extension or part of the filename. Patterns are

placed into a category, with different analysis options available for each category. The default

status for each pattern is set by the Black Duck Administrator. The Administrator can

enforce the default for all projects or allow changes to the defaults on a project basis.

Table 1 Available protexIP Processes by File Type

File Type Available Processes

Snippet Matches

File Matches

Searches

Dependencies

Decompress

Expand Archive

Multi-user File

Comparison

Text X X X X

Binary X X

Java Source File X X X X X

C/C++ Source File X X X X X

Archive X X X

Compressed X X X

Other files X X

Ignored File

4.5.1 Syntax

This section describes the syntax you can use to define patterns that can be used to include and exclude files.

'*' matches zero or more characters, '?' matches one character.

In general, patterns are considered relative paths; relative to a task-dependent base directory (the dir attribute in the case of <fileset>). Only files found below that base directory are considered. So while a pattern like ../foo.java is possible, it will not match anything when applied because the parent of the base directory is never scanned for files.

Examples:

*.java matches .java , x.java and FooBar.java , but not FooBar.xml (does not end with .java ).

?.java matches x.java , A.java , but not .java or xyz.java (both do not have one character before .java ).


Note: Combinations of *'s and ?'s are allowed.

Matching is done on a per-directory basis. This means that first the first directory in the pattern is matched against the first directory in the path to match. Then the second directory is matched, and so on. For example, when we have the pattern /?abc/*/*.java and the path /xabc/foobar/test.java , the first ?abc is matched with xabc , then * is matched with foobar , and finally *.java is matched with test.java . They all match, so the path matches the pattern.

You can use '**' to match multiple directory levels. This syntax can be used to match a complete directory tree, or a file anywhere in the directory tree. To do this, ** must be used as the name of a directory. When ** is used as the name of a directory in the pattern, it matches zero or more directories. For example: /test/** matches all files/directories under /test/, such as /test/x.java , or /test/foo/bar/xyz.html , but not /xyz.xml .

There is one "shorthand": if a pattern ends with / or \, then ** is appended. For example, mypackage/test/ is interpreted as mypackage/test/** .

Table 2 Example Patterns

Pattern Matches

**/CVS/* Matches all files in CVS directories that can be located anywhere in the directory tree.

Matches:

CVS/Repository

org/apache/CVS/Entries

org/apache/jakarta/tools/ant/CVS/Entries But not:

org/apache/CVS/foo/bar/Entries (foo/bar/ part does not match)

org/apache/jakarta/** Matches all files in the org/apache/jakarta directory tree.

Matches: org/apache/jakarta/tools/ant/docs/index.html

org/apache/jakarta/test.xml

But not:

org/apache/xyz.java (jakarta/ part is missing).

org/apache/**/CVS/* Matches all files in CVS directories that are located anywhere in the directory tree under org/apache .

Matches:

org/apache/CVS/Entries

org/apache/jakarta/tools/ant/CVS/Entries

But not:

org/apache/CVS/foo/bar/Entries

(foo/bar/ part does not match)


**/test/** Matches all files that have a test element in their path, including test as a filename.

4.5.2 Add a New Pattern

Suppose you have a custom file type, *.abc . By default, protexIP treats the files as “other”

and only file matches are discovered; use the Pattern area to define the appropriate

processes.

To add a new pattern, follow these steps:

1. Navigate to the Manage �� Patterns tab.

2. Select Add Pattern …. The Create a New Pattern pop-up appears.

3. In the Pattern field, enter

*.abc

4. Select Java Source File for type. The available Processes are displayed with check

boxes.

5. Check each of the available Process boxes, then click OK to accept your choices.

Re-run analysis on your code to see the new discoveries on the *.abc files.

4.5.3 Using Patterns to ignore files and folders

You can identify files and folders to bypass during analysis by setting the File Type to

Ignored File. For example, suppose you are not interested in analyzing the image files; you

can select each of the associate file types and set the type.

To change a pattern to Ignored File, follow these steps:

1. Search for the file pattern gif . Enter gif into the search field and click Go.

2. The pattern **/*.gif displays. Select that row in the Pattern table. The details

area opens.

3. Select Ignored File from the File Type drop-down list, then click OK.

4. Repeat for additional file types (.jpg , .jpeg , .bmp) as desired.

Re-run analysis to see the changes to your code tree.


You can also define a pattern that bypasses an entire folder during analysis. Suppose you

want to bypass the “licenses” folder during analysis.

To create a pattern to ignore a folder, follow these steps:

1. Navigate to the Manage �� Patterns tab.

2. Select Add Pattern. The Create a New Pattern pop-up appears.

3. In the Pattern field, enter

**/licenses

4. Select Ignored File from the File Type drop-down list, then click OK.

Re-run analysis to see the changes to your code tree.

4.5.4 Default Pattern

There is a catch-all pattern named [default]. This handles all file patterns that are not

specifically declared. The default setting for [default] is to analyze for file matches only.

4.5.5 Global File Patterns

The previous sections described how to create patterns for a particular project, but you can

also set global patterns by selecting the Patterns tab under Policy Manager in the Tools area.

The process is the same as for project patterns, but global patterns are applied to all projects.

For more information, see the Help topic “Adding a New Global File Pattern.”

MMMMORE ORE ORE ORE OOOON N N N IIIIDENTIFICATIONDENTIFICATIONDENTIFICATIONDENTIFICATION

5 MORE ON IDENTIFICATION

Chapter Goal Learn additional options for Identification.


Audience Managers, developers, and others who are responsible for carrying out the

Identification phase of project analysis.

Tasks • View lists of detected and identified components.

• Identify the origin of a file.

• Identify the origin of files in a folder.

• Learn about the Bill of Materials (BOM).

5.1 Identification Options

You can use the following options to identify components based on file and folder matches:

• Identify Match (single file)—Identify the matched file or snippet as originating

from the selected component.

• Identify Snippet and File matches—Identify all matching files and snippets as

originating from the selected component.

• Identify File matches—Identify only exact file matches as originating from the

selected component. Matching snippets are not identified.

• Exclude Component—The selected component is excluded from the Bill of

Materials, and any matches to the component are suppressed.

• Original To—Identify one or more files or snippets as Original Code. All matches

are suppressed. Use this option when the match is not an indicator of code re-use,

but perhaps due to boilerplate or auto-generated code.

5

36 MORE ON IDENTIFIC ATI ON

5.2 Identify Files in a Folder

Working at the folder level allows you to identify a group of files within a folder that match

the same component. Matching files that are located outside of the folder are NOT

identified.

To identify a folder, follow these steps:

1. Select the directory src_ourfaces. The files in the directory match two

components.

2. Browse through the source tree and view the file comparison for some of the files.

Notice that the file faces-config.xml states:

This file is part of the OurFaces distribution of JavaServer Faces custom ui components.

3. Suppose you want to identify the matching files and snippets as originating from

the OurFaces directory. Select the top level of the folder and choose a version of

OurFaces from the component list.

4. Add a Component Comment, then click OK to identify the files in the folder.

5. You can also add a comment at the folder level. Select File Comment from the

Component Comment drop-down list, add your comment, and then click (save

comment). The comment appears in several sections of the Report.

Browse through the folder and note that there is still and unidentified file. This is because

this file does not match OurFaces.

5.3 Identify as Original

Sometimes matches identified by protexIP are due to the use of common, boilerplate or

autogenerated code. You can suppress the matches by identifying the snippet or file as

original to your project.

To identify a snippet or file as original, follow these steps:

1. Select the file template.c. View the file comparison for several of the

matching components. Note that the matching snippet is an auto-generated table,

created by an encryption algorithm. There is no indication that snippet contains

open source code.

2. To identify this file, select any component from the table. In the Identify As: area,

select Original To.

3. There is no need to make a component comment, since the file is original. Select

File Comment from the drop-down list, and add a comment regarding the

contents of the file. Select OK to accept your choice.


4. The file count for Original Code on the Bill of Materials now includes this file.

5.4 Identify a Binary File

protexIP discovers exact matches for binary files, such as .jar , .exe , etc. There is no file

comparison available, but an exact match is a very strong indicator of the file origin.

To identify a jar file, follow these steps

1. Select the file lib/commons-fileupload-1.1.jar. The file matches many

components, which indicates common use of this file.

2. Select Apache-Jakarta Fileupload from the component list. Add a

Component Comment, then click OK.

3. The component is added to the Bill of Materials.

5.5 Change Links

In the Identify As area, the component, version, license, and usage fields have a change

link. This allows you to identify a file or folder by selecting one of the discovered

components and changing the information. In the next few examples, change links are used

to create a Local Component and set the Usage.

5.6 Usage

Usage describes how a component is integrated into the project. Choosing the appropriate

usage is important for calculating license compliance.

Usages are separated into four main categories. If you are shipping code, it is a Partial

Component or a Component. The other Usages, Prerequisite and IP or Other

Intangible, represent components that you are NOT shipping.

• Partial Component—The component is identified based on file or snippet

matches. Notice on the Bill of Materials that the Usage is File or Snippet for the

source files that we identified.

• Component—The project is used in its entirety. This is the default usage for

several file types, including .jar files; notice that the Bill of Materials shows a

Usage of “Component” for the Apache-Jakarta Fileupload project.

• Prerequisite—Required by the project, but not released as part of the project. For

example, a library may be required but is not shipped.

• IP or other intangible—This property represents meta-information about the

implementation of a standard, or use of development tools.


When you identify or declare a component, protexIP defaults to the most likely usage. You

can change the usage to reflect the way the component is combined with the project. Within

the component category, there are five levels of Usage, indicating how tightly the component

is integrated. The following is a simplified description of the usage levels:

• Component (Merely aggregated): Work “does not use” the project.

• Component (Separate work): Work is not derived from the project.

• Component (Dynamic Library): Work is compiled or linked with the project.

• Component (Module): Work is a separate module from the project (Unmodified).

• Component: Work is tightly integrated with the project.

To change the usage of a component, follow these steps:

1. Select the file jboss.jar.

2. Select JBoss from the component list. Note that the default usage is Component,

which represents a tightly integrated component.

3. Select the Change link next to Usage to activate a drop-down list of Usage

options. Select the Advanced link to display the Usages in a table.

4. Select the Usage Component (Separate Work), then click OK.

5. Add a Component Comment, then click OK.

6. The component is added to the Bill of Materials. Notice that the updated Usage is

displayed.

5.7 Declare A File

Declaring a file is a way to identify a file without code matches. Some files require

identification because the file name matches the File Name Patterns in the Detect File

Names area (see Manage � Project), but Identification from the Code Matches tab is

available only for files with matches.

To declare a file, follow these steps:

1. Select the file lib/somecomponent.jar. There are no matching components

detected, yet the file requires identification because “.jar ” is listed in File Name

Patterns.

2. To declare the file, navigate to the Bill of Materials tab. Click the Declare File

button in the lower right corner.

3. To declare this as an original file, start to type the project name in the Component

field. Projects are displayed with a Black Duck icon; select the project from the list,

then click OK.


Note: a “KB” icon indicates that a component is from the KnowledgeBase.

4. Enter a File Comment, then click OK.

5.8 Declare a Folder

Declaring a folder is another form of identification. The main difference between declaring

and identifying a folder is that declaring resolves ALL of the files in the folder, even those

with no matches, or with matches to a different component. Folder declaration is done on

the Bill of Materials tab.

To declare a folder, follow these steps:

1. Select the directory tools in the code tree. View the various components that are

matched. Suppose you want to identify all the files as GnuPG, not just the files

with matches.

2. Navigate to Identify � Bill of Materials.

3. Click the Declare Folder … button. This opens the Declare Folder dialog.

4. Begin typing GnuPG in the Suggest field, then select it from the matching list.

5. Click OK to accept the component.

6. You can add a comment in the Folder Comment field. The comment appears in

several places on the project report. Click OK to accept the comment.

7. Select the row for GnuPG on the Bill of Materials. The comment field changes to

Component Comment. Here you can add a comment that appears on the Bill of

Materials section of the report.

5.9 Adding Components

There may be some components that are part of your project that are not included in the

scanned code. For example, if your application contains an open source component such as

Apache-Jakarta Tomcat, you might choose to forego running analysis on the Tomcat

directory and instead add it to the Bill of Materials.

To declare a component, follow these steps:

1. Verify that you have selected the top level of the project. View the Bill of Materials

tab.

2. Click the Add a component button. This opens the Add a New Bill of Materials

Entry dialog.

3. Enter Tomcat into the Suggest box.

4. Select Apache Tomcat from the suggestion list.


5. Click OK to accept the component.

5.9.1 Building a project hierarchy

Just as manufactured items can be composed of various components, software can also be

assembled from multiple code components. Some components may be developed internally,

others may be purchased, and still others may be taken from open source. These

components in turn may contain still other components, all of which can create a Bill of

Materials with a complicated hierarchy.

By using the Bill of Materials � Add Component functionality, you can create a hierarchy of

protexIP projects (building from the set of standard projects in the KnowledgeBase, as well

as custom-created projects) to create a multi-level Bill of Materials. By creating projects that

represent software components and adding them as components in the Bill of Materials, this

creates a “parent / child” relationship between the software components. However, the

license calculation over this hierarchy is performed according to the “usage” of the

component that is selected in the Add new Bill of Materials Entry dialog.

Users may decide to create a project hierarchy for the following reasons:

• Software as Components Implementation—Many software companies have

employed a methodology where software is built as a series of individual reusable

components and then assembled into applications. Project hierarchies can be used

to group protexIP projects into the application assemblies and manage the licenses

over the entire bundle.

• Break apart large Monolithic Applications—In certain cases, there are

advantages to breaking apart large applications into smaller pieces. In certain

situations, this can improve performance, and it also allows you to manage the

software licenses over those specific pieces. A project hierarchy can be used to

combine the various protexIP projects into one application assembly.

LLLLICENSE ICENSE ICENSE ICENSE CCCCONFLICTSONFLICTSONFLICTSONFLICTS

6 LICENSE CONFLICTS

Chapter Goal Review and resolve license conflicts.

Time to complete 10 minutes

Audience Attorneys

Tasks • Review license conflicts.

• Resolve license conflicts.

6.1 Viewing License Conflicts

On the Bill of Materials tab, the flag next to each component indicates the presence of

license conflicts. No flag means there are no conflicts. A yellow flag indicates a conflict

between identified components. A red flag indicates a conflict with the declared project

license.

To view license conflicts, follow these steps:

1. Select the project GnuPG.

2. Click the view details link in the License Conflict Status line.

3. The dialog details the conflicts between the GPL license and the Basic Proprietary

Commercial License and the Apache and Sun licenses.

6.1.1 Resolving License Conflicts

A license conflict indicates the presence of issues with your distribution. There are several

ways to deal with license conflicts.

• Remove and/or rewrite the problem code.

6

42 L ICENSE CONFLICTS

• Update the usage: change the way the code is used so that it uses a distribution

method that does not cause conflicts.

• An Attorney user can resolve license conflicts in the Review area. However, this

should only be done when there is a clear reason to invalidate the conflict.

CCCCODEODEODEODEPPPPRINTING RINTING RINTING RINTING

7 CODE PRINTING

Chapter Goal Learn how to customize your KnowledgeBase by adding proprietary, 3rd

party, or open source code.


Audience Users must have the role of Code Print Manager

Tasks • Add components to the KnowledgeBase

• Manage code printed components

7.1 Why Code Print?

Code Printing lets you add components to your protexIP KnowledgeBase. Your Code

Printed components are stored in a custom database; analysis is conducted with this database

as well as the standard KnowledgeBase, and matches to code printed components are

reported. This helps you to manage your IP assets:

• Track the re-use of proprietary components.

• Track the use of 3rd party components for which you have proprietary licenses.

• Track the use of open source projects that are not in the Black Duck

KnowledgeBase.

When you run an analysis, matches to the custom database appear along with matches to the

standard database, and are identified and reviewed in the same way.

You can assign licenses to the code printed components. You can choose from any of the

standard licenses in the KnowledgeBase, or add a custom license using License Manager.

7

44 CODE PRI NTING

7.1.1 Code Printing – Proprietary Software

Suppose your company develops projects under several licenses, some proprietary and some

open source. When you release a product under an open source license, you want to verify

that it does not contain any of your proprietary code. Use Code Printing to manage this

process.

1. Code print the proprietary component, which adds it to the custom database.

2. When running analysis on future projects, such as open source projects, matches to

the proprietary component are identified.

3. Matches between an analyzed project and the proprietary component could alert

you to code leakage.

7.1.2 Code Printing – 3 rd Party Software

Suppose your company purchased a license to a 3rd party software product. The license

stipulates that you may ship this product only under certain circumstances. You want to

verify that this product is not shipped without authorization.

1. Code Print the 3rd party proprietary product, which adds it to your custom

database.

2. When running analysis on future projects, matches to this 3rd party proprietary

component are identified.

3. Matches between an analyzed project and the 3rd party product could alert you to

unauthorized usage of the product.

7.1.3 Code Printing – Open Source Software

Suppose your company uses an open source component that is not part of the Black Duck

KnowledgeBase. You can code print this component in order to manage its use.

1. Code print the open source component, which adds it to your custom database.

2. As you run analysis on future projects, matches to this open source component are

identified.

3. Matches between an analyzed project and the open source component could alert

you to improper usage of the component.

7.2 Add a Code Print

Projects can be code printed via the User Interface or using bdstool; instructions for code

printing via bdstool can be found in section 10.3


To add a Code Print, follow these steps:

1. Use the Tools link to access Component Manager.

2. The Component list displays. Select the Add Code Print … button. A code-

selection dialog appears.

3. Navigate through the tree and select a folder to code print.

4. Enter a name for the component, select a license, then click OK to accept your

choices. The screen refreshes, and the management tabs for your component are

displayed. A custom license for the component can be added; see Adding a New

License for instructions.

5. On the General tab, add information about the component.

6. On the Obligations tab, build the list of obligations that apply to the use of this

component; see Obligations and Review for more instructions.

7. On the Code Print tab, click Code Print Now. The status bar displays progress as

code prints are created.

Future analyses will discover code matches with the code printed components.

Note: In order to view results in previously analyzed projects, select Re-analyze ALL Files. Otherwise, matches are found in new and modified files only.

7.3 Managing Code Printed projects

If you have the Code Print Manager role, you can manage your code printed projects in the

Component Manager area.

To select a Code Printed component, follow these steps:

1. Navigate to Tools �� Component Manager. The list of all components, both

code printed and standard, is displayed.

2. Change the filter in the Show: area to CodePrinted. Click Go to accept your

choice. The list of code printed projects is displayed.

3. Select any of the components from the list. The management tabs for the

component are displayed.

7.3.1 Re-Code Printing

Re-code printing a project follows the same convention as re-analysis. Only new and

modified file are re-code printed unless you select Re-analyze ALL Files.

46 CODE PRI NTING

7.3.2 Deleting a Code Printed Component

You can delete a code printed component, which removes the code prints and files from the

custom database.

To delete a Code Printed component, follow these steps:

1. Open Component Manager and search for the component you want to delete.

2. Scroll to the bottom of the General tab. Select the Delete This Component

check box, then click OK. The Confirm Deletion dialog appears.

3. Click OK. The Component Manager refreshes and the code printed project is

gone.

LLLLICENSE ICENSE ICENSE ICENSE MMMMANAGEMENT ANAGEMENT ANAGEMENT ANAGEMENT

8 LICENSE MANAGEMENT

Chapter Goal Learn how to customize your KnowledgeBase by adding proprietary, 3rd

party, or open source licenses; edit and approve licenses.


Audience Users must have the role of Attorney.

Tasks • Add Licenses to the KnowledgeBase.

• Manage and edit standard KnowledgeBase licenses.

The KnowledgeBase contains over 1,000 licenses which govern the components that are

there. The KnowledgeBase licenses consist of several parts:

• Text—The full text of each license is entered, using HTML. The license text is

included in the License Texts report section, which can then be used to create a

“readme” file for your project.

• Attributes—protexIP includes a set of 18 attributes that can be set for each

license. Attributes cover typical license settings such as the right to distribute or

charge a fee for the software.

• Obligations—Obligations represent requirements that must be fulfilled.

Obligations have several sources:

o Some are derived from license attributes.

o You can add or edit obligations associated with a license.

o You can add or edit obligations associated with a component.

Obligations are presented during project Review, and they can be marked as

Fulfilled as appropriate.

8

48 L ICENSE M AN AGEM ENT

8.1 Adding a Custom License

Add your proprietary licenses and assign them to analyzed and code printed projects; this

enables you to manage license conflicts and obligations that are uniquely set for your license.

You can add 3rd party and open source licenses and assign them to analyzed and code

printed projects. Once a license is added, use the Component Manager to assign it to the

applicable components.

To add a new license, follow these steps:

1. Navigate to Tools �� License Manager. The list of KnowledgeBase licenses is

displayed.

2. Click Add License …. The Add a New License dialogue appears.

3. Enter a License name and click OK to accept your choice. The license

management tabs are displayed.

4. Navigate to the General tab. Enter the text of the license in the Text: field. Use

HTML if desired.

5. Navigate to the Attributes tab. Review each of the attributes and set them to the

appropriate value for your license. The obligations that are created appear in the

Review area, and are used to identify license conflicts.

6. Navigate to the Obligations tab. The obligations you see (if any) are derived from

the attribute settings. You can also add an Obligation unique to this license. See

Obligations and Review for more information on creating obligations.

8.1.1 Using a Custom License

protexIP users are likely to analyze a mix of proprietary, open source, and 3rd party

components. License calculation is conducted on the declared licenses for the various

components. If your custom license is in the KnowledgeBase, you can assign it to

proprietary projects and components.

To assign a custom license to a project, follow these steps:

1. Navigate to the Manage � Project tab.

2. Click Change in the License area. The list of licenses in the KnowledgeBase is

displayed.

3. Select your custom license from the list, then click OK.

View the Manage �� Obligations tab. The obligations for the project are derived from

your custom license. View the Identify �� Bill of Materials tab. Red flags indicate a conflict

between your custom license and the license of the identified component.


8.2 Editing Existing Licenses

The standard licenses in the KnowledgeBase can be edited, cloned, approved or

disapproved, and customized in other ways to reflect your license policies.

To edit a standard KnowledgeBase license, follow these steps:

1. Navigate to Tools �� License Manager. The License Manager page is displayed.

2. Select a license; for training purposes, select Apache 1.1 (the original license will be

restored after the exercise).

3. On the General tab, you can set an approval status for the license. License

approval or disapproval trickles down to all components under that license. If you

don’t want to automatically approve all components under Apache 1.1, change the

Status to Reviewed rather than Approved.

4. On the Attributes tab, you can change the settings for the license. Use this if you

have a different interpretation of the license. Making changes on this tab affects the

list of obligations and the license conflicts. Change #9, Runtime Notice, to True,

then click OK. This will create a new obligation.

5. On the Obligations tab, note that there is an obligation regarding the notice at

runtime. You can also add custom obligations regarding the use of this license. See

Obligations and Review for more information on creating obligations. Example

obligations might include:

• Use of a component under Apache 1.1 should be replaced with a version

under Apache 2.0 if available.

• You must receive approval from the Open Source Committee.

8.2.1 Restore Original License

To delete your edits to the license, follow these steps:

1. Navigate to the General tab. Select the Restore Original check box.

2. Click OK. The Confirm Deletion dialog appears. Click OK again to accept your

deletion.

50 L ICENSE M AN AGEM ENT


OOOOBLIGATIONS AND BLIGATIONS AND BLIGATIONS AND BLIGATIONS AND RRRREVIEW EVIEW EVIEW EVIEW

9 OBLIGATIONS AND REVIEW

Chapter Goal Learn to create and group obligations to use as a check list for review.


Audience You must be a Manager or Attorney to create obligations; Power Developers

are to mark Obligations as fulfilled.

Tasks • Categorize and create global obligations.

• Attach obligations to licenses and components.

• Present obligations for Review by category.

If you have the Attorney role, you can use the Obligations Manager to create and edit global

obligations and obligation categories. You can add obligations to projects, and you can also

add obligations to KnowledgeBase licenses and components.

9.1 Creating Global Obligations and Obligation Categories

You can use the Obligation Manager to create and edit global obligations and obligation

categories.

To add an obligation category, follow these steps:

1. Navigate to Tools �� Obligation Manager �� Obligation Categories to display

the Obligation Categories page.

9

52 OBLIG ATIONS AND REVI EW

2. Click the Add an Obligation Category… button. The Add a New Obligation

Category dialog appears.

3. Type a name for the new obligation category in the Name box.

4. Select the Reset Fulfillment Status on Clone check box to reset the fulfillment

status when you clone the project (create an exact copy with a new name).

5. Click OK to add the new obligation category.

Note: To edit an existing obligation category, select the obligation category, then edit the information displayed in the bottom frame. Click OK to save your changes.

To add a global obligation, follow these steps:

1. Navigate to Tools �� Obligation Manager �� Global Obligations to display the

Global Obligations page.

2. Click the Add an Obligation… button. The Add a New Obligation dialog

appears.

3. Type a name for the new obligation category in the Name box, type a description

in the Description box, and select a category from the Category drop-down.

4. Click OK to add the new obligation.

Note: To edit an existing obligation, select the obligation, then edit the information displayed in the bottom frame. Click OK to save your changes.

9.2 Adding Obligations to a Project

Lets you add new obligations, view obligations, and edit obligations for a project. Initially, this page contains obligations listed with the proprietary license template (this is the default license). You can add or delete obligations from this page as required. Obligations listed on this page are based on the license you select for this project.

To add an obligation to a project, follow these steps:

1. Navigate to Manage �� Obligations to display the Obligations page.


appears.

3. Use the Global Obligation Category and Global Obligation drop-downs to create

the new obligation based on an existing global obligation.

- or -


To create a new obligation from scratch, proceed directly to the next step without

selecting a global category and obligation.

4. Type a name for the obligation in the Name box, type a description in the

Description box, and select a category from the Category drop-down. Select the

applicable check box to include the obligation in review checklists, or to mark the

obligation as fulfilled.



9.3 Adding Obligations to KnowledgeBase Licenses and Components

To add an obligation to a KnowledgeBase license, follow these steps:

1. Navigate to Tools �� License Manager to display the License Manager page.

2. Select a license, then click the Obligations tab to display the list of obligations for

the selected license.


appears.

4. Use the Global Obligation Category and Global Obligation drop-downs to create

the new obligation based on an existing global obligation.

- or -










To add an obligation to a KnowledgeBase component, follow these steps:

7. Navigate to Tools �� Component Manager to display the Component Manager

page.

8. Select a component, then click the Obligations tab to display the list of obligations

for the selected component.


appears.

10. Use the Global Obligation Category and Global Obligation drop-downs to create the new obligation based on an existing global obligation.

- or -









9.4 Presenting Obligations for Review by Category

Once the obligations have been set globally—at the license level, or at the project level—they can be checked and confirmed during the Review process (as discussed in section 3.4, “Review”). During the review step, the obligations can be filtered by obligation category. Once reviewed, the obligations can be marked as fulfilled for each of the individual components.

To review the obligations and confirm them as fulfilled:

1. Select Review. The Review area opens and displays a table that lists the

components on the Bill of Materials.

2. Select a component in a table row which contains a custom obligation, either at the

project level or the license level.

3. Above the obligation description table column, click the Show drop-down to


display the obligation categories.

4. Select an obligation category and notice the effects of the filter.

5. Select All to display all of the obligations.

CCCCOMOMOMOMMAND MAND MAND MAND LLLLINE INE INE INE IIIINTERFACENTERFACENTERFACENTERFACE

10 COMMAND LINE INTERFACE

Chapter Goal Learn basic steps for using the command line to run analysis and code print.


Audience Managers and developers who will write automation to conduct analysis on a

regular basis and/or those responsible for adding custom projects to the

database.

Tasks • Login to the command line interface.

• Run analysis.

• Code print.

While the protexIP web application provides most of the functionality you need, you also

have the option of using a command line interface to run protexIP. Resolution continues to

be done in the web application. Use the command line option to:

• Automate running protexIP in your nightly builds.

• Add custom projects (Code Print) to your KnowledgeBase.

This chapter helps you to learn the commands for logging in via the command line, running

analysis, and code printing.

10.1 bdstool Utility

The bdstool utility provides the command line interface to protexIP functionality. This

utility is installed when you download and install the client software. You can run bdstool

from either a Linux or Windows system. To access bdstool , open a shell on your Linux

system or a command prompt window on your Windows system, then login.

10

58 COMM AND L INE INTERFACE

10.1.1 Login

Open the desired shell or window and login to bdstool using the same user name and

password as in the web application.

bdstool --server <http://server> --user <[email protected] om> --password <foobar> login

Once you login to bdstool , you remain logged in until you log out, or until you or

someone else logs in to bdstool with a different ID. If you need to login again, you do not

need to specify the password; it is encrypted and saved in a file .bdspass in your local user

directory.

10.1.2 List Projects

Use this command to list all projects to which you are assigned. You need to know the

project ID when you setup a directory for scanning.

bdstool list-projects

10.2 Running Analysis

Creating a project for analysis is always done in the web application.

To run an analysis from the command line, follow these steps:

1. Create a project in the web application. Assign a name to the project that properly

identifies the application, declare a license, and choose the desired caption options.

2. Open a command line window and login to bdstool.

3. In the command line window, change to the code directory.

cd <directory>

Associate the code with the project.

bdstool new-project <c_project-id>

4. Run the analysis.

bdstool analyze

5. Open the protexIP Web application to see the analysis results and conduct

identification and review.

10.2.1 Analysis Options and Commands

Use bdstool options to further define your analysis. The format for using an option is as

follows:

bdstool analyze --<option> --<option>


Table 1 Command Line Options

Option Function

force This invokes a total rescan of all files. This has the same effect as

deselecting “Re-scan modified files only” in the web application.

local Perform analysis on the top level directory only. Do not recurse into

subdirectories.

accept <file

pattern>

Perform analysis on files that match the specified pattern. This has

the same effect as adding File Patterns in Scan Options. When using

the command line, specified file patterns are added to the list of

default patterns.

verbose Prints more output to the screen while analysis is taking place

10.2.2 Advanced Commands

To see a list and description of additional options and advanced commands:

• Type the following in the command line.

bdstool help analyze

10.3 Code Printing

Note: You must have the Code Print Manager role to Code Print a project. See your Black Duck Administrator to verify your roles.

Creating a project for Code Printing is done in the protexIP Web application.

To code print a project, follow these steps:

1. Create a project in the protexIP Web application. Assign a name to the project, declare a

license, and choose the desired caption options.

2. Open a command line window and login to bdstool.

3. In the command line window, change to the code directory.

cd <directory>

4. Associate the code to the project.

bdstool new-project <c_project-id>

5. Run the analysis.

60 COMM AND L INE INTERFACE

bdstool codeprint

6. Once the Code Prints are created, they are automatically uploaded and stored in the custom

database. The source files are also uploaded to the server to be used by the File Comparison

tool.

10.3.1 Code Printing Options

Use bdstool options to further define your Code Print. The format for using an option is as

follows:

bdstool codeprint --<option>

Option Function

force Like analysis, Code Printing the same directory more than once

defaults to Code Printing modified files only. This invokes Code

Printing of all files.

local Perform analysis on the top level directory only. Do not recurse into

subdirectories.

no-source-upload Source files are not uploaded; just the Code Prints are uploaded.

These files are not accessible for viewing via the File Comparison

Tool.

reset-all Removes the previously code printed source files and code prints

before code printing.

reset-all --no-files Removes code prints and source files from the database, and then

does not upload any files. The project itself it not deleted, but it is

empty.

10.3.2 Code Printing Advanced Commands

To see a list and description of additional options and advanced commands, you can:

• Type the following in the command line

bdstool help codeprint

protexIP 4.3 Enterprise Tutorial

Documents

Transcript of protexIP 4.3 Enterprise Tutorial