diff --git a/context/diataxis-contract.md b/context/diataxis-contract.md index 01196c8..62bdae6 100644 --- a/context/diataxis-contract.md +++ b/context/diataxis-contract.md @@ -71,6 +71,7 @@ correctly and safely. - Step-by-step beginner introductions (→ Tutorials). - Exhaustive parameter listings (→ Reference). - Design rationale or architectural background (→ Concepts). +- REST endpoints or configuration property keys when the procedure is UI-driven (→ Surface language). --- @@ -105,6 +106,7 @@ product. - Step-by-step instructions (→ Tutorials or Guides). - Parameter or API field listings (→ Reference). - Actionable procedures ("do X, then Y") (→ Guides). +- Java field names, REST endpoint paths, or runtime config keys (→ Surface language). --- @@ -186,3 +188,34 @@ Rules: Use relative links between documentation pages. Prefer linking to a specific section (`concepts/vulnerability-analysis.md#data-sources`) over linking to an entire page when the relevant information is in a subsection. + +--- + +## Surface language + +Each Diataxis type has a default surface vocabulary. Match it to the audience +that consults the page. + +- **Concepts**: UI labels and domain terms. Do not use Java field names + (`isLatest`, `accessTeams`, `inactiveSince`), REST endpoint paths, or + runtime configuration property keys. Refer to features the way they appear + in the application. Permission codes and CycloneDX classifier names that + surface verbatim in the product (BOMs, dropdowns, badges) are fine. +- **Guides**: describe procedures via the UI by default. The user's path is + the form, the dropdown, the toggle. Inline REST endpoints, request bodies, + or configuration property keys only when the page is itself a technical + procedure where the API or config file is the user's entry point (for + example, "Upload a BOM via REST API", "Configure with environment + variables"). Otherwise, link to the relevant Reference subsection and keep + prose UI-first. +- **Reference**: structured tables of UI-visible labels, dropdown values, + classifier names, and other product-surface vocabulary belong here. The + dedicated REST API and configuration-property references (the OpenAPI + specs, the `application.properties` table) are the home for low-level + identifiers. Other Reference subsections should also stay UI-first. +- **Tutorials**: same default as Guides. The student is using the UI unless + the tutorial is explicitly an API tutorial. + +When a feature has both a UI label and a technical identifier, prefer the UI +label and link out to Reference for the identifier. The reverse breaks for +users who never see the API or the config file. diff --git a/docs/concepts/.pages b/docs/concepts/.pages index 87d7cc2..e7b18ff 100644 --- a/docs/concepts/.pages +++ b/docs/concepts/.pages @@ -1,6 +1,8 @@ title: Concepts nav: - index.md + - About projects: projects.md + - About tags: tags.md - About access control: access-control.md - About notifications: notifications.md - About time series metrics: time-series-metrics.md diff --git a/docs/concepts/access-control.md b/docs/concepts/access-control.md index 785f23b..b92d8fa 100644 --- a/docs/concepts/access-control.md +++ b/docs/concepts/access-control.md @@ -70,3 +70,5 @@ overhead without security benefit. * [Permissions reference](../reference/permissions.md) for the full permissions table and default teams. +* [About projects](projects.md) for how Dependency-Track models + projects, hierarchies, and collection projects. diff --git a/docs/concepts/changes-in-v5.md b/docs/concepts/changes-in-v5.md index 099f6c2..8efc3f6 100644 --- a/docs/concepts/changes-in-v5.md +++ b/docs/concepts/changes-in-v5.md @@ -109,6 +109,14 @@ shipped as a beta feature in v4 with known gaps and noticeable overhead on larger portfolios. v5 closes those gaps and reworks the implementation so the cost stays bounded as the project count grows. +### Retention policies for projects and metrics + +v5 expires inactive project versions and time-series metrics on +configurable schedules. v4 left both to grow unbounded, so operators +carried stale portfolio data and ever-growing metric tables. See +[Configuring project retention](../guides/administration/configuring-project-retention.md) +and [time-series metrics retention](time-series-metrics.md#daily-partitions-and-bounded-retention). + ### Centralised secrets Credentials for integrations live in one place instead of spreading across diff --git a/docs/concepts/component-policies.md b/docs/concepts/component-policies.md index e998ba2..8839dce 100644 --- a/docs/concepts/component-policies.md +++ b/docs/concepts/component-policies.md @@ -59,7 +59,8 @@ dependency graph, or operate on SPDX license expressions directly. ## Where a policy applies By default, a policy applies to every project in the portfolio. Narrow it to specific projects, to -descendants of those projects, or to projects carrying specific tags. Scoping is flat: a policy +descendants of those projects, or to projects carrying specific +[tags](tags.md). Scoping is flat: a policy either applies to a project or does not. See [Component policies › Assignment](../reference/policies/component-policies.md#assignment) for the exact rules. diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md new file mode 100644 index 0000000..27f1458 --- /dev/null +++ b/docs/concepts/projects.md @@ -0,0 +1,170 @@ +# About projects + +A **project** is the unit of tracking in Dependency-Track. Everything else, from components +to findings to policy violations to metrics, hangs off projects. The **portfolio** is the +set of all projects in an instance, and how you model it shapes what reports, alerts, and +aggregations are useful later. + +This page explains what a project is, how projects relate to each other, and the deliberate +limits of the model. + +## What a project is + +Each project has: + +- A name and an optional version that together identify it. +- A classifier naming the kind of thing the project represents (an app, a library, a + container image, a firmware image, and so on, matching CycloneDX). See the + [classifier list](../reference/projects.md#classifiers). +- Optional ecosystem identifiers: a Package URL, a CPE, or a SWID tag. +- Descriptive metadata such as a group, a description, authors, a supplier, a manufacturer, + and external references. +- Tags (categorical labels) and project properties (typed key-value metadata). +- An optional parent, forming a hierarchy. +- An access list controlling which teams can see it. +- Lifecycle state: an active flag, the timestamp of the last BOM import, the timestamp of + the last vulnerability analysis, and the current risk score. + + + +## What Dependency-Track does *not* assume + +A few modelling decisions are deliberately left to the user. Knowing them up front avoids +arguments later: + +- **Dependency-Track does not prescribe what a project is.** A project can map to a single + library, a deployable service, an environment of a service, or an entire product line. + Pick the granularity that matches how you triage and report. +- **Versions are opaque strings.** Dependency-Track does not parse, compare, or sort them. + Semver-like ordering is not assumed. The "latest version" pointer is a manually maintained + flag (see [Versions](#versions)), not a computed one. +- **Projects cannot depend on projects.** Component-level dependencies live inside a BOM. The + only relationship Dependency-Track tracks between projects is the parent-child hierarchy + below, and that hierarchy is organizational, not a dependency graph. If service A consumes + service B, that fact is not expressible as a project relation. +- **A name and version together identify a project globally.** That pair is unique across + the entire instance, independent of where the project sits in the hierarchy. The same + name and version cannot exist under two different parents. + +## Active and inactive projects + +A project is **active** by default. Marking it inactive records the time and changes its +behavior: + +- It disappears from active portfolio views unless the viewer opts in to show inactive + projects. +- It cannot serve as a parent. +- It becomes eligible for retention-driven deletion (see [Retention](#retention)). Active + projects never are. + +A project with active children cannot become inactive. Mark the children first, or accept +that the parent stays around for as long as something underneath stays live. + +## Hierarchies + +A project can have one parent and any number of children. Hierarchies are organizational: +they let you group by product, environment, team, or any other axis that fits how you work. + +Two things flow through the hierarchy: + +- **Access control.** A team that can see a parent can also see the parent's descendants. + See [Access control](#access-control) below. +- **Aggregated metrics on collection projects.** A [collection project](#collection-projects) reads + metrics from its children to produce its own. Regular parents do not. The risk score on a + regular parent reflects only that parent's own components, not its children. + +Constraints worth remembering: + +- A project cannot be its own ancestor. Dependency-Track rejects cycles. +- The hierarchy does not affect identity. A name and version pair remains globally unique, + so the same combination cannot appear under two different parents. + +(Inactive projects cannot serve as a parent either. See [Active and inactive projects](#active-and-inactive-projects).) + + + +## Collection projects + +A **collection project** is a parent whose only role is to combine metrics from its +children. It holds no components or services of its own. Instead, it surfaces the metrics +of its children using one of three modes: + +| Mode | Behavior | +|:---------------------------|:--------------------------------------------------------------------| +| Roll up every direct child | Combines metrics from every direct child. | +| Roll up by tag | Combines metrics from direct children carrying a chosen tag. | +| Roll up the latest version | Combines metrics from direct children marked as the latest version. | + +Collection projects are useful for product or portfolio aggregations that span versions, +services, or environments without forcing every child to share a tag scheme. They differ +from regular parents in three important ways: + +- They have no classifier. The classifier field disappears once a project becomes a + collection project. +- They cannot have components, services, or a dependency graph. The detail page hides those + tabs and shows a *Collection Projects* tab listing children instead. +- They do not accept BOM uploads. + +For when to reach for which mode and how to set them up, see +[Organizing projects into hierarchies](../guides/user/organizing-projects.md). + + + +## Versions + +Two or more projects can share a name. Together they represent the version history of one +logical thing. A *latest version* flag marks one of them as current. At most one version +per name carries the flag. + +The latest-version flag drives: + +- The latest-version collection mode. +- The badge URLs that resolve a project by name without specifying a version. +- The *LATEST VERSION* badge in the project header. + +Because Dependency-Track does not parse version strings, nothing here is automatic. You +set the flag manually when promoting a release. Cloning a project produces a new sibling +with chosen inclusions (components, services, tags, properties, audit history, access list, +policy violations) and is the typical path for starting a new version. See +[Managing project versions](../guides/user/managing-project-versions.md). + +## Tags and properties + +A project carries two kinds of metadata. A **tag** is a categorical label that many +projects can share. Policies, alerts, the tag-filtered collection mode, and the project +list filter all read tags. For the wider model see [About tags](tags.md). A **project +property** is a typed key-value pair (group, name, value, type, optional description) +scoped to one project. The policy engine, alerting, and collection logic do not consult +properties. Use a tag for a label that may apply to many projects, and a property for +per-project structured data you want to read back later. + +## Retention + +By default, inactive projects stick around indefinitely. When the operator turns on +retention, a scheduled maintenance task deletes inactive projects according to one of two +policies: + +- **By age**: delete inactive projects older than a configured cutoff. +- **By version count**: keep the most recent N inactive versions per name, and delete the + rest. + +Active projects are never touched. See +[Configuring project retention](../guides/administration/configuring-project-retention.md). + +## Access control + +Each project has an access list. A team can see a project when: + +- The team appears on that project's access list, **or** on the access list of the + project's ancestors. Granting a team access to a parent also grants access to every + descendant. +- The team holds the `PORTFOLIO_ACCESS_CONTROL_BYPASS` permission, which overrides the + access list entirely. + +Use this when designing a hierarchy: shared access concerns sit at parents, and the +children inherit them automatically. To revoke inherited access, remove the team from +the ancestor that granted it. A descendant cannot opt out on its own. + +For the wider model (users, teams, and which permissions gate which actions), see +[About access control](access-control.md) and the +[Permissions reference](../reference/permissions.md). diff --git a/docs/concepts/tags.md b/docs/concepts/tags.md new file mode 100644 index 0000000..406831b --- /dev/null +++ b/docs/concepts/tags.md @@ -0,0 +1,53 @@ +# About tags + +A **tag** is a short, shared label. You can attach the same tag to +[projects](projects.md), [component](component-policies.md) and +[vulnerability](vulnerability-policies.md) policies, vulnerabilities, and +[alerts](notifications.md), and the rest of the system reads tags to scope behavior. +Tags are deliberately lightweight: a name and nothing else. + +## What a tag is + +A tag is just a name. Names are unique across the instance, so two attachments of the +same name refer to the same tag. A tag has no value, no type, no namespace, no +description. If you need richer metadata bound to a project, use +[project properties](projects.md#tags-and-properties) instead. + +Tags are many-to-many with the things they label. A project can carry many tags, and a +tag can label many projects. Removing a tag from one project does not affect any other. + +## What tags do + +Tags are a scoping primitive. Different parts of the system look at the same tag set: + +- **Project filtering.** The project list can filter by tag. +- **Policy assignment.** A component or vulnerability policy can target only projects + carrying specific tags. See [About component policies](component-policies.md) and + [About vulnerability policies](vulnerability-policies.md). +- **Collection projects.** The tag-based collection mode aggregates only the children + carrying the configured tag. See + [About projects › Collection projects](projects.md#collection-projects). +- **Alerts.** An [alert](notifications.md) can fire only for projects carrying specific tags. +- **Vulnerability tagging.** You can attach tags to vulnerabilities for triage and + reporting. + +## Tags versus project properties + +Both attach metadata to a project, but they answer different questions: + +- Reach for a **tag** when the value is a label that may apply to many projects, and you + expect the policy engine, alerting, or the tag-filtered collection mode to read it. +- Reach for a **project property** when the value is per-project structured data (a + typed key with a value) that you want to read back later, but no built-in feature + consumes it. + +Properties carry types and group names, while tags do not. If you find yourself encoding two +pieces of information into one tag (`team:platform`, `env=prod`), that is a signal to +reach for a property, or for two separate tags, instead. + +## Lifecycle + +Tags come into being implicitly on first use. Attaching a name that does not exist +creates the tag. Detaching the last attachment leaves an orphan tag, which the +maintenance task cleans up on its next run. Tags carry no per-tag access control. Any +user who can edit a project can also tag it. diff --git a/docs/concepts/vulnerability-policies.md b/docs/concepts/vulnerability-policies.md index 739149c..7e66c42 100644 --- a/docs/concepts/vulnerability-policies.md +++ b/docs/concepts/vulnerability-policies.md @@ -22,8 +22,8 @@ rather than replace them. The important differences are: * **VEX analyses are static.** A VEX statement records a decision for a specific finding at a specific moment. Vulnerability policies are rules. A single policy can match many findings now and in - the future, based on conditions such as component version ranges, project tags, or dependency graph - relationships. + the future, based on conditions such as component version ranges, + [project tags](tags.md), or dependency graph relationships. * **VEX cannot express constraints.** A policy condition can say "apply this decision only while the affected component sits behind a specific transitive dependency" or "only for projects tagged `3rd-party`". VEX cannot do this. diff --git a/docs/guides/administration/.pages b/docs/guides/administration/.pages index a63930f..077b23b 100644 --- a/docs/guides/administration/.pages +++ b/docs/guides/administration/.pages @@ -12,6 +12,7 @@ nav: - configuring-oidc.md - managing-notification-templates.md - debugging-notifications.md + - configuring-project-retention.md - backing-up.md - upgrading-instances.md - migrating-from-v4.md diff --git a/docs/guides/administration/configuring-project-retention.md b/docs/guides/administration/configuring-project-retention.md new file mode 100644 index 0000000..2ba2721 --- /dev/null +++ b/docs/guides/administration/configuring-project-retention.md @@ -0,0 +1,85 @@ +# Configuring project retention + +A scheduled maintenance task can delete **inactive** projects according to a retention +policy. By default the task is off. This guide covers what the task does, how to choose a +policy, and how to configure it. + +For background on what marking a project inactive means, see +[Managing project versions › Retire an old version](../user/managing-project-versions.md#retire-an-old-version) +and [About projects › Retention](../../concepts/projects.md#retention). + +## What the task does + +The maintenance task runs periodically and, when retention is on, deletes inactive +projects whose retirement falls outside the configured policy. Each deletion writes a +line to the app log. + +It never touches active projects. Marking a project inactive is the gate. Once a project +is inactive, the policy below decides whether it sticks around. + +Deletion is permanent. The project, its components, audit history, properties, and access +list go with it. + +## Pick a policy + +Two modes are available. Pick exactly one. + +### By age + +Delete inactive projects whose retirement is older than a chosen number of days. The UI +labels this mode *AGE*, with a slider for the cutoff in days (default 30). + +Use this when "old" is the right concept: a project that retired long enough ago is no +longer interesting. + +### By version count + +For each project name, keep the most recent inactive versions and delete the rest. +Recency follows the time at which each project went inactive. The UI labels this mode +*VERSIONS*, with a slider for the number of versions to keep (default 2). + +Use this when you want a bounded archive ("always keep the last two retired releases"), +regardless of how long ago the projects became inactive. + +## Configure it + +Open *Administration > Configuration > Maintenance* and find the *Projects Retention* +section. + +1. Toggle *Enable Inactive Project Deletion* on. +2. Pick a *Project Retention Type*: *AGE* or *VERSIONS*. +3. Set the slider for the chosen mode (days, or version count). +4. Save. If the change widens what the task deletes, a *Destructive Action Confirmation* + dialog appears. Confirm to apply. + + + + + + + +## Turn retention off + +Toggle *Enable Inactive Project Deletion* off in the same panel. The next time the +maintenance task runs it logs that retention is off and deletes nothing. + +## What deletion takes with it + +Deleting a project cascades to everything scoped to it: its components and services, the +dependency graph, the audit history (analyses, comments, suppressions), project +properties, project-tag attachments, and access-list entries. Resources shared across +projects are not affected. Tags themselves remain (an orphan tag is later cleaned up by +the [tag-maintenance task](../../concepts/tags.md#lifecycle)). Vulnerability records +remain, and any other project that referenced shared data continues to do so. +Dependency-Track offers no soft-delete and no undo. + +## Operational notes + +- Active projects remain untouched. The only way to make a project eligible is to mark it + inactive. +- The task processes in batches and may run for a while on the first execution after you + turn it on. Each deletion produces a log line, so tail logs to audit a deployment. +- The task acquires a database lock so only one API server runs it at a time, even in a + scaled-out deployment. +- Dependency-Track fires a project's notifications as part of normal flow up to deletion. + The deletion itself does not emit a portfolio notification. diff --git a/docs/guides/user/.pages b/docs/guides/user/.pages index 6bc4214..91d9cdc 100644 --- a/docs/guides/user/.pages +++ b/docs/guides/user/.pages @@ -1,6 +1,8 @@ title: User guides nav: - index.md + - organizing-projects.md + - managing-project-versions.md - managing-component-policies.md - triaging-policy-violations.md - managing-vulnerability-policies.md diff --git a/docs/guides/user/managing-project-versions.md b/docs/guides/user/managing-project-versions.md new file mode 100644 index 0000000..a829b25 --- /dev/null +++ b/docs/guides/user/managing-project-versions.md @@ -0,0 +1,98 @@ +# Managing project versions + +A project's name and version together identify it. Tracking a release history means creating +sibling projects with the same name but different version strings, marking the current one +as latest, and eventually retiring the old ones. + +For background on how versions fit the wider model, including the fact that Dependency-Track +treats version strings as opaque, see +[About projects › Versions](../../concepts/projects.md#versions). The actions in this guide +require portfolio management permissions. See the +[Permissions reference](../../reference/permissions.md) for the exact set. + +## New version, or overwrite? + +Two ways to update a project after a release: + +- **Upload a new BOM with the same name and version.** Dependency-Track reconciles the + component list by identity: matching components stay (along with their audit + decisions), Dependency-Track removes components no longer in the BOM, and adds the + new ones. Analysis re-runs, and the project keeps its identity. Use this for in-place + updates of an unreleased or rolling version (a `dev` or `main` line). +- **Create a new version.** Preserve the existing project as a record of that release and + start tracking the next one separately. Use this for every release you intend to look + back at. + +The rest of this guide covers the second case. + +## Clone to a new version + +The fastest way to start a new version is to clone an existing one. Cloning produces a new +sibling project with the same name and a version you choose. + +1. Open the source project. +2. From the version dropdown in the project header, pick *Add Version*. +3. Enter the new *Version* string. +4. Choose what to carry over: + - *Tags*: keep the project's tags on the clone. + - *Properties*: copy custom key-value properties. + - *Components*: copy the component list. Required if you want to copy services or + audit history. + - *Services*: copy the services declared in the source. + - *Audit History*: carry over analysis decisions (analysis state, justifications, + comments, suppressions). + - *ACL*: carry over the source project's access list. + - *Make Clone Latest*: mark the new version as latest and clear the flag on the + previous latest. +5. Save. + +If you skip *Include Components*, the clone starts empty and the next BOM upload populates +it. Use this approach when the new version's BOM arrives from CI shortly after. + +Cloning copies row-by-row, so cloning a project with components plus audit history scales +with project size. On large projects expect the operation to take noticeable time. Prefer +cloning without components when CI repopulates them shortly after. + + + +## Mark a version as latest + +The *latest version* flag is manual. Dependency-Track does not infer it from version +strings. Set it in either of two places: + +- The *Make Clone Latest* toggle in the *Add Version* modal (the most common path). +- The *Is latest version* toggle on the *General* tab of the *Project Details* modal. + +At most one version per project name carries the flag. Marking a new version as latest +clears the flag on the previous one. + +The flag drives the latest-version collection mode (see +[Organizing projects into hierarchies](organizing-projects.md#choose-a-collection-logic)), +the badge URLs that resolve a project by name without a version, and the +*LATEST VERSION* badge in the project header. + + + +## Retire an old version + +When a release is no longer in production, mark its project inactive. To do so, open +*Project Details* and toggle *Active* off in the *General* tab. The toggle stays +unavailable while the project has active children. Mark the children inactive first. + +For what marking a project inactive means (visibility, parenthood, retention eligibility), +see [About projects › Active and inactive projects](../../concepts/projects.md#active-and-inactive-projects). + + + +Inactive projects remain visible to anyone who toggles *Show inactive projects* on. +Dependency-Track keeps their audit history, tags, properties, and access list until +retention deletes them. + + + +## Automatic deletion of retired versions + +Configure retention so the maintenance task deletes them on a schedule, by age (delete +inactive projects older than N days) or by version count (keep the last N inactive versions +per name). See [Configuring project retention](../administration/configuring-project-retention.md). +Retention only acts on inactive projects. Active ones remain untouched. diff --git a/docs/guides/user/organizing-projects.md b/docs/guides/user/organizing-projects.md new file mode 100644 index 0000000..507d596 --- /dev/null +++ b/docs/guides/user/organizing-projects.md @@ -0,0 +1,122 @@ +# Organizing projects into hierarchies + +Projects can sit flat in the portfolio, or you can nest them under parents. This guide +covers nesting: setting parents, deciding when a parent should be a *collection project*, +and choosing among the three aggregation modes. + +For the underlying model and its constraints, see +[About projects](../../concepts/projects.md). The actions in this guide require portfolio +management permissions. See the [Permissions reference](../../reference/permissions.md) +for the exact set. + +## Tags or hierarchy? + +Tags and hierarchies overlap as ways of organizing the portfolio. They are not mutually +exclusive, and a useful rule of thumb is: + +- Reach for **tags** when the grouping is cross-cutting (`pci`, `external-facing`, + `team-platform`) and a project may belong to many groups at once. +- Reach for a **hierarchy** when the grouping is structural (a product made of services, a + service tracked across environments, a service tracked across releases) and each project + has one natural parent. + +Hierarchies also propagate access control to descendants and unlock collection-project +aggregations. Tags do not. The rest of this guide covers hierarchies. + +## Set a parent + +Set the parent when creating a project, or change it later by editing. + +1. Open *Projects* and click *Create Project*, or open an existing project and click its + edit (pencil) icon. +2. In the *General* tab, find the *Parent* field. Start typing. The picker searches the + portfolio asynchronously and excludes the project's own descendants. +3. Pick a parent and save. + +## Make the parent a collection project + +A regular parent has its own components and BOMs. A **collection project** has neither. It +exists only to combine metrics from its children. Switch to a collection project when: + +- The parent is a logical grouping (`Acme Web Platform`, `Mobile App`) rather than something + with its own SBOM. +- You want a single risk number, vulnerability count, and violation count for the group. +- You don't want the parent to accept BOM uploads. + +To convert (or create) a parent as a collection project, in the *Create Project* or *Edit +Project* form's *General* tab: + +1. Toggle *Collection project* on. The *Classifier* field disappears. Collection projects + have no classifier. +2. Choose a *Project Collection Logic* (see the next section). +3. If you picked the tag-filtered logic, fill in the *Collection Tag* input. +4. Save. + +Once a project has any components or services, Dependency-Track refuses to convert it to +a collection project. Empty the project, or clone its useful state into a child, before +flipping the toggle. + + + +## Choose a collection logic + +The *Project Collection Logic* dropdown offers three modes. Pick the one whose semantics +match the question the parent should answer. + +### Roll up every direct child + +In the dropdown, pick *AGGREGATE_DIRECT_CHILDREN*. This mode rolls up every direct child, +irrespective of tag or version. + +Use it when every child is in scope and the parent should reflect the union of their state. +A typical pattern: a parent representing a product, with one child per microservice that is +live in production. + +Be aware that *every* child counts, including stale or experimental ones. If you keep many +old versions of children around, prefer one of the other two modes. + +### Roll up children carrying a tag + +In the dropdown, pick *AGGREGATE_DIRECT_CHILDREN_WITH_TAG* and fill in the *Collection Tag* +input. The aggregation rolls up only direct children carrying that tag. + +Use it to slice the same set of children different ways. A common pattern is to create a few +collection projects under the same parent (one tagged `prod`, one tagged `staging`, one +tagged `dev`), each aggregating only the children in that environment. + + + +### Roll up the latest version of each child + +In the dropdown, pick *AGGREGATE_LATEST_VERSION_CHILDREN*. The aggregation rolls up only +direct children marked as the latest version. + +Use it when each child has many versions and you want the parent to reflect the current +release. Promoting a new release is a single flip of the latest-version flag (see +[Managing project versions](managing-project-versions.md)), and the aggregation follows +automatically. + +## Worked patterns + +A few hierarchies that come up often: + +- **Product, service, environment.** A collection-project parent for the product, regular + parents for each service, regular children per environment (`dev`, `qa`, `prod`). Tag the + environment children. Use the tag-filtered mode at the product level if you want a + per-environment aggregation. +- **Service, version.** A collection-project parent per service using the latest-version + mode, with a regular child per version. Cloning a new version with *Make Clone Latest* + updates the aggregation automatically. +- **Team, owned services.** A collection-project parent per team using the all-children + mode, with each owned service as a child. Useful for ownership reports and team-scoped + notifications. + + + +## See the children of a collection project + +Open the parent. Instead of *Components*, *Services*, and *Dependency Graph*, the detail +page shows a *Collection Projects* tab listing the children that contribute to the +aggregation, with their per-child metrics. + + diff --git a/docs/reference/.pages b/docs/reference/.pages index 1d5caa1..2077766 100644 --- a/docs/reference/.pages +++ b/docs/reference/.pages @@ -1,6 +1,7 @@ title: Reference nav: - index.md + - Projects: projects.md - API: api - Configuration: configuration - Datasources: datasources diff --git a/docs/reference/badges.md b/docs/reference/badges.md index ae44c84..cc47b7c 100644 --- a/docs/reference/badges.md +++ b/docs/reference/badges.md @@ -4,6 +4,10 @@ Dependency-Track provides SVG badges that display a project's current vulnerabil and policy violation metrics. Badges can be embedded in README files, dashboards, or internal documentation to give at-a-glance visibility into a project's security posture. +Badge URLs reference a project by UUID, by `(name, version)`, or by name alone. The +name-only form resolves to whichever version carries the latest-version flag. See +[Managing project versions](../guides/user/managing-project-versions.md#mark-a-version-as-latest). + ## Badge Types ### Vulnerable Components diff --git a/docs/reference/permissions.md b/docs/reference/permissions.md index fa90b73..f739cfa 100644 --- a/docs/reference/permissions.md +++ b/docs/reference/permissions.md @@ -13,6 +13,9 @@ variants. ### Portfolio +For procedures, see [Organizing projects into hierarchies](../guides/user/organizing-projects.md) +and [Managing project versions](../guides/user/managing-project-versions.md). + | Permission | Description | |:----------------------------------|:-----------------------------------------------------------------------| | `BOM_UPLOAD` | Upload CycloneDX Software Bills of Materials. | diff --git a/docs/reference/projects.md b/docs/reference/projects.md new file mode 100644 index 0000000..3902de5 --- /dev/null +++ b/docs/reference/projects.md @@ -0,0 +1,89 @@ +# Projects + +UI reference for the project form, the project detail page, and the project-related +administration panels. See [About projects](../concepts/projects.md) for background and +the user guides for procedures: + +- [Organizing projects into hierarchies](../guides/user/organizing-projects.md) +- [Managing project versions](../guides/user/managing-project-versions.md) +- [Configuring project retention](../guides/administration/configuring-project-retention.md) + +For request and response schemas, see the [v1](api/v1.md) and [v2](api/v2.md) OpenAPI +specifications. + +## Classifiers + +Project classifiers mirror the CycloneDX `metadata.component.type` enumeration. The +values appear verbatim in the *Classifier* dropdown of the project form. + +| Classifier | Description | +|:-------------------------|:----------------------------------| +| `APPLICATION` | A software app. | +| `FRAMEWORK` | A software framework. | +| `LIBRARY` | A software library. | +| `CONTAINER` | A container image. | +| `PLATFORM` | A computing platform. | +| `OPERATING_SYSTEM` | An operating system. | +| `DEVICE` | A physical device. | +| `DEVICE_DRIVER` | A driver for a physical device. | +| `FIRMWARE` | Device firmware. | +| `FILE` | A standalone file. | +| `MACHINE_LEARNING_MODEL` | A machine-learning model. | +| `DATA` | A dataset. | + +A collection project has no classifier. Switching a project to collection mode hides the +*Classifier* field. + +## Collection logic + +The *Project Collection Logic* dropdown configures aggregation on a collection project. +While set, the project cannot have its own components, services, or dependency graph, +and it does not accept BOM uploads. + +| Value | Aggregation | +|:-------------------------------------|:---------------------------------------------------------------------------------------------------------| +| `AGGREGATE_DIRECT_CHILDREN` | All direct children contribute to the parent's metrics. | +| `AGGREGATE_DIRECT_CHILDREN_WITH_TAG` | Only direct children carrying the configured *Collection Tag* contribute. The *Collection Tag* is mandatory. | +| `AGGREGATE_LATEST_VERSION_CHILDREN` | Only direct children marked as the latest version contribute. | + +## Identity + +| Field | Required | Limit | +|:--------|:--------:|:----------------------------------------------------------------------------| +| Name | Yes | Up to 255 characters. | +| Version | No | Up to 255 characters. Treated as opaque text, not parsed or sorted. | + +The pair of name and version is unique across the instance, independent of where the +project sits in the hierarchy. + +## Identifiers + +The project form exposes ecosystem identifiers used for vulnerability matching. + +| Field | Limit | Purpose | +|:------------|-----------:|:-------------------------------------------------------------------| +| PURL | 1024 chars | Package URL. Primary identifier for vulnerability matching. | +| CPE | 255 chars | CPE 2.2 or 2.3 identifier. Used for NVD-style matching. | +| SWID Tag ID | 255 chars | SWID tag identifier. Rarely used in practice. | + +## Tags and properties + +A project may carry any number of tags and any number of project properties. + +| Entity | Limits | Notes | +|:-----------------|:------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------| +| Tag | Name up to 255 printable characters. Unique across the instance. | Many-to-many with projects. See [About tags](../concepts/tags.md). | +| Project property | Group and name 1 to 255 characters, no control characters. Value up to 1024 characters. Type is mandatory. | Per-project key-value metadata, scoped to the project. | + +## Retention configuration + +Configured at *Administration > Configuration > Maintenance > Projects Retention*. See +[Configuring project retention](../guides/administration/configuring-project-retention.md) +for the setup procedure. + +| Control | Default | Purpose | +|:-------------------------------------|:-------------|:-----------------------------------------------------------------------------------------------------------------------| +| *Enable Inactive Project Deletion* | Off | Master switch. While off, the maintenance task does nothing. | +| *Project Retention Type* | Unset | *AGE* deletes by retirement age. *VERSIONS* keeps the most recent inactive versions per project name. | +| *AGE* slider | 30 days | Cutoff for the *AGE* mode. The next task run deletes inactive projects older than this. | +| *VERSIONS* slider | 2 versions | Number of most recent inactive versions kept per project name in *VERSIONS* mode. The task removes older versions. |