Creating Custom Auto-WriteUp Rules
Auto-WriteUp rules save analysis time by automatically associating files from OSS projects to fully audited groups after a scan. See the Using Auto-WriteUp section of the User Guide guide for more information about the types of rules the Flexera Compliance Library team maintains. This tech note will describe how to create custom (user-generated) Auto-WriteUp rules.
(1). You can create custom Auto-WriteUp rules in FlexNet Code Insight versions 6.6 and later. There is an Excel file in the <FNCI_ROOT_DIR>/config/core/rules/>directory called Auto-WriteUp.xlsx. You can write rules directly into this workbook or make a copy to create different workbooks for use in different workspaces (or to save a clean copy). In order to use the custom Auto-WriteUp rules you must configure FNCI to check an Excel workbook. Within <FNCI_ROOT_DIR>/config/core/, open Auto-WriteUp.properties in a text editor and give userRules the name of the Excel file (for example: userRules=Auto-Writeup.xlsx).
(2). The Auto-WriteUp Excel workbook contains two spreadsheet tabs: file_rules and group_rules. Every group_rule must contain at least a value for group_name. At a minimum, every file_rule must contain an MD5 and a group_name that corresponds to a group_rule with the same group_name.
(3). The easiest type of files to create rules for are binaries (like Java Jar files and RPMs) and single files (like JavaScript libraries) whose MD5 hash uniquely identifies an OSS project. Writing rules for other types of files, including source files in large libraries requires more effort. The same file might be in several different versions of an OSS component, so rules for old versions might trigger incorrect groups for newer versions of a library. For such cases, you might choose to ignore versions or manually input them as part of the normal audit process. Contact your Flexera representative for advice or if you have any additional questions.
(4). These are the file_rule fields:
- md5: The file's MD5 digest. This will be the trigger for the rule. We can get the MD5 by either scanning the file or using a command line tool (such as md5sum).
- version_id: The FNCI ID for the version of the selected component. You can find the ID by using the Research tab in the FNCI webUI. Search for the component and then click on the plus button for more details. Scroll down and click on the Manage Version and Vulnerabilities button to see the version IDs.
- version: This is the text representation of the version. It is used to build the group name according to FNCI conventions.
- text_header: This is text that you can optionally add to a group's As-found license text field. You might choose to say something like "The following text was found on the project website:". You can use
@fileto refer to the file's name, e.g., "Sample from @file" will resolve to "Sample from license.txt". - text: This is the As-found license text for the file.
- short_text: This is an alternate As-found license text in case you only want to include a small portion of a long license. You can select to use text or short_text in /config/core/Auto-WriteUp.properties
- note_header: This is text that you can optionally add to a group's external notes text field.
- note: This is the external notes text.
- parent_group_name: This field is for when you're creating a group that's for an OSS project that has a subcomponent. For example, the Apache Ant source distribution comes with a copy of the JUnit jar file. The JUnit file_rule should reference the parent_group_name of the Apache Ant group_rule to indicate that JUnit is bundled with Ant.
- parent_group_license: Use this field only in conjunction with parent_group_name.
- group_name: This field associates the file_rule with the corresponding group_rule (e.g. OpenSSL or zlib).
- group_license: This field associates the file_rule with the corresponding group_rule's group_license (e.g. Apache 2.0 or MIT).
(5). As an example, let's fill out the file information for file a sample file from DataTables.js (from https://www.datatables.net/download/download😞
| md5 | version_id | version | text_header | text | short_text | note_header | note |
| 6573e7a4b0b58350670b20d7dd911ad0 | 1980332 | 1.9.1 | The following text is found in file @file in the materials | * This source file is free software, under either the GPL v2 license or a * BSD style license, available at: * http://datatables.net/license_gpl2 * http://datatables.net/license_bsd * * This source file is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY * or FITNESS FOR A PARTICULAR PURPOSE. See the license files for details. * * For details please refer to: http://www.datatables.net | Not necessary. | Not necessary. | Not necessary. |
| parent_group_name | parent_group_license | group_name | group_license |
| Not necessary. | Not necessary. | DataTables | GPL v2.0 or BSD-3 |
(6). These are the group_rule fields:
- parent_group_name: This field is for when you're creating a group that's for an OSS project that has a subcomponent. Otherwise you can ignore this.
- parent_group_license: Use this field only in conjunction with parent_group_name.
-
group_name: The name of the group. This will be used to create a group name using FNCI conventions:
<group_name> <version from file_rules> (<group_license>). - group_license: The license of the files in the group.
- component_id: The FNCI id for the selected component. You can find the ID by using the Research tab in the FNCI webUI. Search for the component and then click on the plus button to see the component ID.
- title: The title of the group. Not commonly used.
- description: The description of the selected component.
- url: The url of the selected component.
- license_ids: The FNCI ids for the possible licenses of the selected component (comma separated). You can search for license ids by using the Research tab in the FNCI webUI. Select the License tab, search for the license, and then click on the plus button to see the Id.
- priority: The group's priority level. By FNCI convention priority is determined by the license obligations. Priority 1 licenses contain copyleft or viral clauses (clauses that potentially put proprietary source code at risk), e.g., the GPL or Affero GPL licenses. Priority 2 indicates commercial code, code under unknown licenses, or licenses with usual or vanity conditions, e.g., Dinkumware. Priority 3 indicates permissive, attribution style licenses, e.g. Apache 2.0.
- text_header: Same as file_rule text_header.
- text: Same as file_rule text.
- short_text: Same as file_rule short_text.
- note_header: Same as file_rule note_header.
- note: Same as file_rule note.
(7). Note that if both a file_rule and a group_rule specify different As-found license text or notes, both will be included in the resulting group. Also, you cannot have headers (text_header or note_header) that don't have any corresponding text or notes.
(8). Let's continue our example and input data for the group_rules tab for DataTables.js:
| parent_group_name | parent_group_license | group_name | group_license | component_id | title | description | url | license_ids |
| Not necessary. | Not necessary. | DataTables | GPL v2.0 or BSD-3 | 172144 | Not necessary. | DataTables is a table enhancing plug-in for the jQuery Javascript library, adding sorting, paging and filtering abilities to plain HTML tables with minimal effort. | www.datatables.net | 331, 4 |
| priority | text_header | text | short_text | note_header | note |
| 1 | The following text is found on the project website (www.datatables.net) | DataTables is released with dual licensing, using the GPL v2 (license-gpl2.txt) and an BSD style license (license-bsd.txt). You may select which of the two licenses you wish to use DataTables under. Please see the corresponding license file for details of these licenses. | DataTables is released with dual licensing, using the GPL v2 (license-gpl2.txt) and an BSD style license (license-bsd.txt). | Not necessary. | Not necessary. |
(8) Here's what our resulting group looks like in Detector:
Some notes:
- You can add additional files to a group by adding rows with MD5s in the file_rules tab and referencing the appropriate group. If there are files with different versions referencing the same group, multiple groups will be created (unless "versioned groups" is turned off).
- Auto-WriteUp creates a log in
<FNCI_ROOT_DIR>/logs/called Auto-WriteUp.log that contains useful information for debugging rules.
