Download the latest release for your OS from Github.
To check if your installation is up to date, open the Help menu and select Check for updates.
Run the executable OpossumUI-for-linux.AppImage
Run OpossumUI in OpossumUI-for-mac.zip.
Run OpossumUI-for-win.exe to install the OpossumUI. Then open OpossumUI from the start menu.
Files with a .opossum extension are zip-archives which contain an input.json (must be provided) together with an output.json (optional). An output file will be automatically created and added to the archive after opening the archive if there is no such file yet.
Two .json files are used by the app to store data:
- an input file, that must be provided,
- an output file, which is created by the app when saving for the first time if not already present.
The output file must be in the same folder as the input file and called [NAME_OF_THE_FIRST_FILE]_attributions.json
to be recognized by the app.
To open the input file in the app, click the Open File button on the left of the top bar (or on the entry in the File menu with the same name).
If you try to open a .json file, a popup will be shown which asks whether you would like to create a .opossum file and proceed (recommended) or continue working with the old format (two separate .json files).
To search for a path, press CTRL + F or open the Edit menu and select Search for Files and Folders.
To locate signals, press CTRL + L or open the Edit menu and select Locate Signals. This will open the Locate Signals popup.
From here, you can choose which signals you want to locate in the resource tree. You can search for signals by string, criticality
or choose one or multiple existing license name(s). Once selected, the locations of matching signals will be highlighted in the resource tree.
Note: When searching for matching resources, the input of the search field, the selected criticality and the selected license names are linked with and, while different license names in the license search field are linked with or. That is, when searching for a license name using the search field (and the checkbox) and additionally selecting another license name, only the resources matching the license name and the term in the search field will be highlighted while when searching for multiple license names, all resources matching one of these licenses will be highlighted.
You can also locate signals by license from the Project Statistics popup, by clicking on the locator icon next to each license.
To view project metadata, open the File menu and select Project Metadata.
To view project statistics, open the File menu and select Project Statistics. This opens a popup that shows various
tables and pie charts summarizing the state of the project.
It is possible to directly export data to files. The following formats are available:
- Follow-Up: Just the items marked as follow-up are present in this file as csv file.
- Compact component list: All attributions not marked as follow-up or 1st Party are exported to a csv file. Attributions marked as "exclude from notice" are not exported.
- Detailed component list: All attributions not marked as follow-up or 1st Party are exported to a csv file.
- SPDX JSON: All attributions are listed as JSON file.
- SPDX YAML: All attributions are listed as YAML file.
To generate a document, open the File menu and select Export.
The basic building block of license/attribution information in the opossumUI is the Attribution. An Attribution isn't only a software package with name & version (or purl) and copyright, distributed under one or more licenses. It can in principle be any file which has a copyright or is distributed under a license. The purpose of the opossumUI is to link resources to the corresponding attributions, with an emphasis on correct licensing and copyright information. In the opossumUI, a distinction between signals and attributions is made:
- attributions are attribution information that are created in the current run of the opossumUI. They are stored in the output file, together with the resources they have been linked to,
- signals are attribution information that have been linked to a resource before the current opossumUI run. They can come from automatic tools or previous run of the opossumUI. They have a source and can be used as starting point for assigning attributions.
In the Top Bar, the following elements are present. From left to right:
- the Open File button (read Open File section to learn more about opening a file),
- the
Progress Bar(shown only if a file is currently opened), - the
Progress Bar Toggle, - the
View Switch, - the app version.
The Progress Bar indicates how many files have manually received an attribution (dark green), how many have an
automatically pre-selected attribution (lighter green with gradient), and how many files have a signal, but have not
yet received an attribution (orange), with respect to the total number of files. Hovering on the bar shows a tooltip
containing all 4 numbers. Clicking on the bar navigates to a file that has a signal, but no attribution.
Clicking the Progress Bar Toggle replaces the Progress Bar by the Critical Signals Progress Bar. The
Critical Signals Progress Bar indicates how many files have a highly critical signal but no attribution (red),
a medium critical signal but no attribution (orange) with respect to the total number of files not having an attribution.
Hovering on the bar shows a tooltip containing all 4 numbers. Clicking on the bar navigates to a file that has a critical signal,
but no attribution.
The View Switch allows to change between the Audit View, the Attribution View, and the Report View (the views
are described in more detail in the respective sections).
The app version is crucial to allow the development team to reproduce bugs: please always include it in screenshots/videos/emails documenting a bug.
Resource is the generic name used throughout the app to indicate a file or a folder (as in many cases they are
treated the same). The Audit View focuses on the navigation through the resources to add/edit/remove attributions
while seeing which signals have been found by the remote tools. The page has two main components:
- a
Resource Treeon the left, - a
Selected Resource Panelon the center right (shown only if a resource has been selected in theResource Tree).
In the case that a folder receives an attribution this attribution is also inferred to all its children that do not have their own attribution. Therefore, adding an attribution to a folder affects its children if these are not attributed themselves. The inference stops once a folder or a file is hit that has a differing attribution.
In the Resource Tree resources can be selected. Icons help to find information in the folder
structure:
- a file icon
indicates that the resource is a file, - a folder icon
indicates that the resource is a folder, - a icon consisting of four squares
indicates that the resource is a breakpoint (breakpoints are special folders
that are included to visually collect a set of dependencies. These folders cannot have any signal or attribution.
Furthermore, no attribution is inferred beyond such a breakpoint), - a exclamation mark
indicates the presence of signals attached to the resource.
The coloring scheme reads as follows:
- red indicates the presence of signals but no attribution for the resource itself,
- green indicates the presence of attribution for the resource itself,
- light red indicates the presence of signals but no attribution in children,
- light green indicates the presence of attribution in children,
- grey indicates the absence of both, signals and attribution, in children,
- blue indicates the presence of signals in children but no attribution of the resource itself.
The Selected Resource Panel shows the path of the selected resource at the top. If the input file contains information
about the location of the file (baseUrlsForSources) an icon to externally open the file is shown.
Below the path, the element is divided into two columns. In the Attribution Selection Column, in the center of the
screen, attributions and signals related to the selected resource are listed. In the Attribution Details Column on
the right, additional information is shown for the selected attribution/signal.
In the Attribution Selection Column the following sub-panels may be present:
Attribution Sub-Panel(always shown),Signals Sub-Panel(accessible via theLOCALtab),Attributions in Folder Content Sub-Panel(accessible via theLOCALtab),Signals in Folder Content Sub-Panel(accessible via theLOCALtab),Add to Attribution Sub-Panel(accessible via theGLOBALtab).
The Attributions Sub-Panel shows a list of all attributions that are assigned to the selected resource.
Pre-selected attributions are signaled by an P icon. They can be confirmed, therefore being considered
attributions in all views and in the progress bar. However, that is not a requirement. Pre-selected and
attributions are both written in the output file. Clicking on one of the
attributions, shows the details of that attribution in the Attribution Details Column. Clicking on Add new
attribution shows a blank Attribution Details Column that allows for adding a new attribution to the list of
attributions, upon saving. If the shown attributions are inferred from a containing folder, they cannot be modified.
Instead, the
OVERRIDE PARENT button can be clicked for creating new attributions for the selected resource. (Note that attributions
are not saved separately, if they are identical to the attributions of a containing folder and can thus be inferred.)
The Signals Sub-Panel, Attributions in Folder Content Sub-Panel and Signals in Folder Content Sub-Panel show lists
of the signals of the selected resource and the attributions and signals of the resources contained within the selected
folder. Clicking on the one of the listed items, shows the details of the respective attribution/signal in the
Attribution Details Column. By clicking the + icon of an item, the respective attribution/signal can be added to
the attributions of the selected resource. In the Signals Sub-Panel signals that were used to create the pre-selected
attributions are shown with a P icon, even if the relative attributions have been deleted. The cards in the
... in folder content sub-panels also show the number of resources in the folder that are linked to the shown
attribution.
Similar signals that deviate only by comment, attributionConfidence, originIds, or the preSelected flag are merged into a single signal with multiple comments according to the comments of the individual merged signals. When adding a merged signal to the attributions of the current resource, the comment of the resulting attribution is empty. Relevant parts can be copied from the merged signal.
The Add to Attribution Sub-Panel allows to add an existing attribution to the attributions of the selected resource.
As in the other panels, the details of the attributions can be shown by clicking on the respective list item, while the
attribution can be added by clicking on the corresponding + icon.
The Attribution Details Column is used in the Audit View and in the Attribution View (see next section) to show
details of the selected attribution and to edit and save the information of the selected attribution. Note that inferred
attribution information and signals cannot be edited.
IMPORTANT: Some fields in the column have special meanings/behaviors:
- PURL: If provided, package name and version are extracted from it, and the corresponding fields are not editable. A basic validity check is done on the purl: if the purl text is red it means it is invalid and saving is prevented.
- License Text: It will appear in the attributions document. It will be automatically filled in for licenses suggested in the license name dropdown.
- Exclude From Notice Checkbox: If checked, the relative attribution will not be shown in the notice document.
In the case of first party code, the respective flag should be preferred.
Exclude From Notice Checkbox should be used only if:
- the content of the attribution does not need attribution or
- the attribution isn't an actual attribution or
- it was globally decided that this attribution does not need attribution (e.g. it is proprietary but bought for the whole company).
- Comment / Comments: In the case of an ordinary signal or an attribution, the comment textbox is displaying a single comment. In the case of a merged signal, the comment textbox is displaying multiple comments according to the comments of the individual merged signals.
- Needs Review Checkbox: This checkbox can be used to signal to another OpossumUI user that an attribution needs further review. The state of the checkbox is persisted when saving the attribution, so it can e.g. be used for a typical QA workflow.
The Attribution Details Column, if editable, shows the following buttons:
- SAVE, saves the edited information for the selected resource only, removing the pre-selected attribute if present.
- SAVE GLOBALLY, (shown only if the attribution of the selected resource is also linked to other resources) saves the changes for all the linked resources. The same can also be done by pressing Ctrl + S.
- CONFIRM, removes the pre-selected attribute from the attribution for the selected resource only.
- CONFIRM GLOBALLY, (shown only if the attribution of the selected resource is also linked to other resources) removes the pre-selected attribute from the attribution for all linked resources.
- ..., opens a menu with the following buttons:
- Revert, discards the changes,
- Delete, deletes the attribution of the selected resource only.
- Delete Globally, (shown only if the attribution of the selected resource is also linked to other resources) deletes the attribution for all the linked resources.
The SAVE / SAVE GLOBALLY and Revert buttons are disabled if no change has been made.
When all fields except for the confidence field are empty, pressing the SAVE or the SAVE GLOBALLY button deletes the respective attribution.
The Attribution Details Column, when a signal is selected, shows the HIDE button. It can be used to hide the given
signal in the App for the current input/output files, and it will not have any consequence in the DB. When clicking HIDE for a merged signal, all individual signals that make up the merged signal are hidden.
In the Attribution View all attributions are listed and can be viewed and edited. The page is in structure similar to
the Audit View and has two main components:
- an
Attribution Liston the left, - a
Selected Attribution Panelon the center right (shown only if an attribution has been selected from the list).
All existing attributions are listed and can be selected. Pre-selected
attributions are signaled by an P icon. They can be confirmed, which converts them into attributions
in all views and in the progress bar. However, that is not a requirement. Pre-selected and manual
attributions are both written in the output file. On top there is an icon for opening the filter section. By clicking
on it, a dropdown will be shown with filters that allows for filtering for attributions marked for follow-up, first
party, third party, and other aspects. Additionally, the attribution view has a multi-select mode.
The Selected Attribution Panel looks much like the Selected Resource Panel. The main differences are:
- Only information for the selected attribution are shown, in a fashion almost identical to
the
Selected Resource Panel. They are always editable. - The SAVE and Delete buttons allow saving/deleting the selected attribution. Note that the changes affect multiple resources if the selected attribution is linked to multiple resources.
- A
Resource Listshows the path of all resources linked to the selected attribution. Clicking on a path shows the selected resource in theAudit View.
In the Report View all attributions are shown in a table to provide an overview. On top there is a dropdown list with
filters that allows for filtering for attributions marked for follow-up, first party and not first party. The last two
are mutually exclusive.
Clicking on the edit buttons in the name columns, navigates to the respective attribution in the attribution view.
In the audit view, an attributions can be marked as preferred, to indicate that it is preferred over the displayed signals. This feature does not have any immediate effect on the signals displayed in OpossumUI; instead, it is intended to give additional information to tools that consume .opossum files. A preferred attribution will store origin IDs of signals visible to the user when it was marked as preferred.
Only signals with a source marked as isRelevantForPreference can be preferred over. If no signal source has this flag set, then the feature is disabled.
To mark an attribution as preferred, choose an attribution in the audit view, and open the auditing options menu. You will see an option to mark the attribution as preferred. When an attribution is marked as preferred, preferred = true is written to the .opossum file, and the origin IDs of all visible signals relevant for preference are written in the field preferredOverOriginIds. Preferred attributions are displayed with a star icon.
Note that you are only able to mark an attribution as preferred (or unmark if it was preferred beforehand) if you are in
"QA Mode". To enable this mode click the item "QA Mode" in the View submenu.
If "QA Mode" is enabled the icon will change as in the screenshot below.
If an attribution originates from a signal, a Compare to Original button will be displayed in the row of buttons below the details of the currently selected attribution. Clicking this button opens a popup, where the package coordinates and legal information of both the current attribution and its original signal are displayed side by side. Fields that have changed are highlighted by colored outlines.
You can revert individual fields by pressing the arrow button inside the field. The action can be undone using the same button, which will point in the opposite direction after a revert. Additionally, all changes can be reverted at once by pressing the Revert All button of the popup. Changes are applied to the attribution once the Apply Changes button is pressed, which also closes the popup. To save the changes, you can, for example, use the standard Save button.