Add external references and description to project page

[heubeck]

Description

As a comfort function, it would be great to have the external references as well as the description of a project available on the project page header.

Addressed Issue

• resolves External References available on project and component page #484
• resolves Project description available in project page header #487

Additional Details

External references

On projects and components containing external references the following drop down menu is shown on the right side of the "details" lane:

Opening the drop-down shows the link types with the url as hover tooltip, links are opened in new browser tabs:

Projects/Components without external references keep unchanged:

Project description

Project with a tags and long description:

Full description via tooltip:

Description gets inlined when shrinking the page:

and disappears completely on even smaller pages, like the metrics do.

Checklist

• I have read and understand the contributing guidelines

[nscuro]

Thanks for the PR @heubeck!

Looks good, but I think a stronger / cleaner separation of tags and description would be nice. They should not be on the same "row" (visually).

[heubeck]

Thanks for the PR @heubeck!

Looks good, but I think a stronger / cleaner separation of tags and description would be nice. They should not be on the same "row" (visually).

Did a new proposal, description right to project name and version - updated screenshots.
Happy to take your suggestion, @nscuro if there's another idea.

[nscuro]

@stevespringett What's your opinion on this?

Also CC @msymons

[stevespringett]

I really like the drop down with links for the external references. My concern is that it is inconsistent with the way external references are handed on components. Whatever solution we end up with needs to be consistent between projects and components.

I don't like the long description, but I would be fine with a short description or a truncated (255 character) description with the ability to expand it.

[heubeck]

Thank you for your thoughts.
Did indeed ignore the components on purpose - but must admit you're right 😎.

Will add the external references drop-down the same way in components - but need some weeks due to high utilization atm.

Regarding the project description: Was the best idea I had so far. The header is lots of empty space that can be used to show relevant information at a glace.
Appreciate any concrete proposal to beautify it. The description cannot become longer than in my "long example", not checked the limitation, but longer ones are not accepted by the backend.

[heubeck]

• Added external refs to the component page as well.
• Truncated the project description on 100 chars and added a tooltip for viewing it completely.

PR description updated with new screenshots, WDYT @nscuro, @stevespringett?

[msymons]

@heubeck, one quibble... VCS is an acronym and thus should not be displayed using mixed capitalization (Vcs).

[heubeck]

@heubeck, one quibble... VCS is an acronym and thus should not be displayed using mixed capitalization (Vcs).

thank you @msymons , great remark.
do you have a concrete proposal, how to map the link types to display names?

[msymons]

thank you @msymons , great remark. do you have a concrete proposal, how to map the link types to display names?

The following is the complete list of external references that we need to deal with (and this include CycloneDX v1.5... for instance, note the inclusion of model-card ).

Reference Type	Description
vcs	Version Control System
issue-tracker	Issue or defect tracking system, or an Application Lifecycle Management (ALM) system
website	Website
advisories	Security advisories
bom	Bill-of-materials (SBOM, OBOM, HBOM, SaaSBOM, etc)
mailing-list	Mailing list or discussion group
social	Social media account
chat	Real-time chat platform
documentation	Documentation, guides, or how-to instructions
support	Community or commercial support
distribution	Direct or repository download location
distribution-intake	The location where a component was published to. This is often the same as "distribution" but may also include specialized publishing processes that act as an intermediary
license	The URL to the license file. If a license URL has been defined in the license node, it should also be defined as an external reference for completeness
build-meta	Build-system specific meta file (i.e. pom.xml, package.json, .nuspec, etc)
build-system	URL to an automated build system
release-notes	URL to release notes
security-contact	Specifies a way to contact the maintainer, supplier, or provider in the event of a security incident. Common URIs include links to a disclosure procedure, a mailto (RFC-2368) that specifies an email address, a tel (RFC-3966) that specifies a phone number, or dns (RFC-4501) that specifies the records containing DNS Security TXT
model-card	A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets
attestation	Human or machine-readable statements containing facts, evidence, or testimony
threat-model	An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format
adversary-model	The defined assumptions, goals, and capabilities of an adversary
risk-assessment	Identifies and analyzes the potential of future events that may negatively impact individuals, assets, and/or the environment. Risk assessments may also include judgments on the tolerability of each risk
vulnerability-assertion	A Vulnerability Disclosure Report (VDR) which asserts the known and previously unknown vulnerabilities that affect a component, service, or product including the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on a component, service, or product
exploitability-statement	A Vulnerability Exploitability eXchange (VEX) which asserts the known vulnerabilities that do not affect a product, product family, or organization, and optionally the ones that do. The VEX should include the analysis and findings describing the impact (or lack of impact) that the reported vulnerability has on the product, product family, or organization
pentest-report	Results from an authorized simulated cyberattack on a component or service, otherwise known as a penetration test
static-analysis-report	SARIF or proprietary machine or human-readable report for which static analysis has identified code quality, security, and other potential issues with the source code
dynamic-analysis-report	Dynamic analysis report that has identified issues such as vulnerabilities and misconfigurations
runtime-analysis-report	Report generated by analyzing the call stack of a running application
component-analysis-report	Report generated by Software Composition Analysis (SCA), container analysis, or other forms of component analysis
maturity-report	Report containing a formal assessment of an organization, business unit, or team against a maturity model
certification-report	Industry, regulatory, or other certification from an accredited (if applicable) certification body
quality-metrics	Report or system in which quality metrics can be obtained
codified-infrastructure	Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)
evidence	Data collected through various forms of extraction or analysis
formulation	The observed or declared formulas for how components or services were manufactured or deployed
poam	Plans of Action and Milestones (POAM) compliment an "attestation" external reference. POAM is defined by NIST as a "document that identifies tasks needing to be accomplished. It details resources required to accomplish the elements of the plan, any milestones in meeting the tasks and scheduled completion dates for the milestones".
other	Use this if no other types accurately describe the purpose of the external reference

Thus, would it not be easiest (and consistent) for the listing to replicate this by using lower-case throughout for the Type. ie, vcs Type would be listed as vcs.

It would also be important to check that the implementation can handle 40-odd references.

What might be very useful indeed is to incorporate the "Description" text in some way (tooltips?). After all, how many users will immediately know what poam is? This must just be done in a way that supports localisation (translations for German, Japanese, etc).

A couple more observations...

Will the existing external references listings be removed? One could argue that they would now be redundant once the information is accessible directly via project or component page?

Description comes from the SBOM. Users have complained that they can edit description... but then see it get over-written on the next SBOM upload. Thus, I fear that displaying the Description more prominently without addressing the underlying problem will lead to more users grumbling. I suggested that this might be addressed by the addition of a Notes field, so that one can "have one's cake and eat it". I know that my own users would really appreciate the ability to see project versions that represent feature branches (work in progress) have a prominent diplay of what the purpose of the work is...

[heubeck]

Thank you @msymons for your detailed considerations.

Thus, would it not be easiest (and consistent) for the listing to replicate this by using lower-case throughout for the Type. ie, vcs Type would be listed as vcs.

Did an uppercase for the acronyms and capitalized the others now. Think this is more beautiful than the technical names.

It would also be important to check that the implementation can handle 40-odd references.

Tested it, no issue.

What might be very useful indeed is to incorporate the "Description" text in some way (tooltips?).

Honestly, I think it may overwhelm the UI, but there's also no place, as the tooltip is used for showing the actual urls.

Will the existing external references listings be removed?

Would not hide information from the details modal, just because it's shown elsewhere.

Description comes from the SBOM. Users have complained that they can edit description...

I see. The external references aren't editable in the details modal as well...
Even if I would not consider changes on that as scope of this PR, I think that it's not up to DT to force certain workflows.
In my use-case, the description of projects is patched after bom upload by another api call. Would not restrict the UI here.

Any hard blockers (also from your side, @nscuro / @stevespringett )?
Would love to merge this, if you think it's an improvement all in all.
Will continue to place further proposals when they come into my mind or are wished by my fellows.

[nscuro]

I think this is great and am happy to merge it. Thanks so much @heubeck!

[heubeck]

I think this is great and am happy to merge it. Thanks so much @heubeck!

awesome. thank you so much @nscuro, and all the other participants on this PR.