Migrate reference documentation

.markdownlint-cli2.yaml

@@ -31,6 +31,8 @@ globs:
 
 ignores:
 - "docs/includes/**"
+- "docs/reference/configuration/properties.md"
+- "docs/reference/schemas/**"
 - "existing-docs/**"
 - "site/**"
 - "node_modules/**"

.vale.ini

@@ -27,6 +27,12 @@ BasedOnStyles = Vale, Google, write-good, DependencyTrack
 [docs/**/*.md]
 BasedOnStyles = Vale, Google, write-good, DependencyTrack
 
+# Ignore generated reference files.
+[docs/reference/configuration/properties.md]
+BasedOnStyles =
+[docs/reference/schemas/*.md]
+BasedOnStyles =
+
 # MkDocs abbreviation syntax (*[ABBR]: Definition) triggers false positives
 # for the colon capitalization rule, since `: ` is a syntax delimiter.
 [docs/includes/abbreviations.md]

.vale/styles/config/vocabularies/DependencyTrack/accept.txt

@@ -1,7 +1,14 @@
+(?i)superset
+ACLs
 APIs
+Aiven
+Artifactory
+Atlassian
 BOM
 BOMs
 Bento
+CPEs
+CWEs
 Cognito
 CycloneDX
 DEKs
@@ -10,54 +17,105 @@ Dependency-Track
 Diataxis
 Entra
 Exploitability
+Flashpoint
 GUIDs
+HDDs
+Hackage
 IdP
 IdP's
 IdPs
+JFrog
 JWTs
+Jira
 KEKs
 Keycloak
 LDAPS
+Liquibase
 Mattermost
 MkDocs
+Modus
+ModusCreate
+Modus[Cc]reate
+NVME
+Nixpkgs
+Nixpkgs
 Novell
 OAuth
 OWASP
 OneLogin
+Operandi
+PGTune
+Packagist
+Percona
 PgBouncer
+Postgres
+Protobuf
 SBOM
 SBOMs
+SSDs
+Snyk
+Sonatype
+Timescale
 Tink
+Trivy
 URIs
+VDR
 VEX
+VulnDB
+Webex
+[Aa]llowlist
+[Aa]llowlists
+[Aa]utodetect
 [Bb]ackpressure
+[Bb]locklist
+[Bb]locklists
+[Bb]ooleans
 [Cc]onfig
 [Cc]onfigs
 [Cc]ron
 [Dd]atacenter
 [Dd]atasource
 [Dd]atasources
 [Dd]efault[Mm]ode
+[Dd]eloyments
+[Dd]eployments
 [Dd]ex
+[Dd]tapac
+[Ee]num
+[Ff]ileset
+[Jj]etstack
 [Kk]enna
 [Ll]iveness
 [Mm]icroservices
+[Mm]ixeway
+[Nn]amespace
+[Nn]amespaces
 [Oo]utbox
 [Pp]luggable
+[Pp]ooler
 [Rr]eadiness
+[Rr]ollouts
+[Ss]bomify
 [Ss]ubdomain
+[Ss]uppressions
 [Tt]imespan
 [Tt]inkey
+[Tt]riaged
 [Tt]ruststores
+[Uu]nmanaged
 [Uu]nprefixed
+[Vv]ers
+[Vv]ulns
 apiserver
 autovacuum
 crypto
 eDirectory
 keyset
 keysets
 keytool
+npm
 sAMAccountName
 truststore
 truststore
 walkthroughs
+zstd

.yamllint.yml

@@ -22,6 +22,7 @@ ignore:
 - node_modules/
 - .vale/styles/Google/
 - .vale/styles/write-good/
+- docs/reference/api/*.yaml
 
 rules:
   document-start: disable

docs/concepts/.pages

@@ -1,4 +1,6 @@
 title: Concepts
 nav:
   - index.md
+  - access-control.md
+  - vulnerability-policies.md
   - ...

docs/concepts/access-control.md

@@ -0,0 +1,67 @@
+# Access control
+
+Dependency-Track uses a role-based access control model built around **permissions**,
+**teams**, and **users**. Teams hold permissions, and users inherit the
+permissions of every team they belong to.
+
+## Users
+
+Three types of users exist:
+
+| Type          | Description                                                                                       |
+|:--------------|:--------------------------------------------------------------------------------------------------|
+| Managed User  | A local account created and managed within Dependency-Track.                                      |
+| LDAP User     | Authenticated via an external LDAP directory. See [Configuring LDAP](../guides/administration/configuring-ldap.md). |
+| OIDC User     | Authenticated via an OpenID Connect identity provider. See [Configuring OIDC](../guides/administration/configuring-oidc.md). |
+
+All user types share the same permission model. The authentication mechanism determines
+how the system verifies a user's identity, not what they can access.
+
+### LDAP authentication flow
+
+With LDAP, Dependency-Track authenticates users by performing a service-account
+bind to locate the user's directory entry, then attempting a bind with the user's
+own credentials to verify their password. On success, the system grants access.
+With user provisioning turned on, Dependency-Track creates the account
+automatically on first login.
+
+### OIDC authentication flow
+
+With OIDC, the frontend redirects the user to the identity provider's authorization
+endpoint. After the user authenticates, the IdP returns an ID token to the frontend,
+which forwards it to the API server for validation. The API server verifies the token
+against the IdP's discovery endpoint and extracts the username from the configured
+claim. With user provisioning turned on, Dependency-Track creates accounts on
+first login.
+
+## Teams
+
+A team is a named collection of users and API keys. Teams hold permissions directly;
+individual users do not. This makes it straightforward to manage access for groups of
+people (for example, *Security Engineers*, *Developers*, *CI/CD Pipelines*) or automated systems.
+
+A user can belong to more than one team and inherits the union of all permissions from
+every team they are a member of.
+
+API keys belong to a team and carry the same permissions as that team. They authenticate
+automated access (CI/CD pipelines, integrations) without associating requests with a
+specific human user.
+
+## Portfolio access control
+
+By default, all teams with `VIEW_PORTFOLIO` can see every project. Access Control Lists
+(ACLs) restrict portfolio visibility so that a team can only see the projects explicitly
+assigned to it.
+
+Enable ACLs in **Administration > Access Management > Portfolio Access Control**.
+Once active, every project must be explicitly assigned to at least one team for it to
+be visible to non-administrator users.
+
+ACLs are most useful in multi-tenant scenarios where different teams should not see
+each other's projects. For single-team or open environments, ACLs add management
+overhead without security benefit.
+
+## Further reading
+
+* [Permissions reference](../reference/permissions.md) for the full permissions table
+  and default teams.

docs/concepts/vulnerability-policies.md

@@ -0,0 +1,83 @@
+# Vulnerability policies
+
+Vulnerability policies let organisations encode how specific vulnerabilities should be triaged across
+the portfolio. Where a [standard policy](../reference/vulnerability-policies.md) raises violations, a vulnerability policy acts
+on the finding itself. It applies an analysis (state, justification, vendor response, details),
+optionally overrides the vulnerability's ratings, and can suppress the finding altogether.
+
+Typical use cases include:
+
+* Suppress a CVE that has been assessed as not applicable to a given component or project.
+* Downgrade or upgrade a vulnerability's severity based on organisational context.
+* Centralise triage decisions so that every project benefits from them automatically, including
+  projects imported in the future.
+
+Policies are evaluated every time a project's vulnerabilities are analysed. Analyses applied by a
+policy populate the finding's audit trail in the same way as a manual analysis.
+
+## Why Not VEX?
+
+[CycloneDX VEX] and [VDR] can also communicate triage decisions. Vulnerability policies complement them
+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
+  point in time. 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.
+* **VEX cannot express constraints.** A policy condition can say "apply this decision only while the
+  affected component is reached through Spring Cloud" or "only for projects tagged `3rd-party`". VEX
+  cannot do this.
+* **VEX has no built-in expiration or scope change.** A policy has a validity window and can be edited
+  or removed centrally. When it stops matching, the analyses it applied are automatically reverted.
+
+## Policy Sources
+
+A vulnerability policy originates from one of two sources:
+
+* **User-managed** policies are created and edited directly in Dependency-Track. They can be modified
+  or deleted at any time.
+* **Bundle-managed** policies are synchronised from a remote ZIP archive of YAML files. They appear
+  with a lock icon and cannot be edited or deleted in the UI. To change a bundle policy, edit it in
+  its source repository and re-sync the bundle.
+
+Both sources share a single namespace. Policy names are globally unique across user-managed and
+bundle-managed policies. If a bundle sync encounters a policy whose name is already taken by a
+user-managed policy, the sync fails rather than silently overwriting either side.
+
+## Evaluation
+
+Each policy is evaluated once per `(component, vulnerability)` pair. When multiple policies match the
+same finding, the policy with the highest `priority` value wins, and only its analysis and ratings are
+applied. When two or more matching policies have the same priority, the policy that was created first
+wins.
+
+### Validity Window
+
+A policy is evaluated only while the current time falls within its *Valid From* and *Valid Until*
+timestamps. Both bounds are optional. A policy with neither bound is always active.
+
+When a policy leaves its validity window (for example because *Valid Until* has elapsed, or because the
+policy is deleted), any analyses and rating overrides that were applied by it are automatically
+reverted on the next evaluation. The finding returns to whatever state it would have without the policy,
+or to the decision of the next-highest-priority policy that still matches. This makes it safe to use
+time-bounded policies for temporary suppressions, embargoes, or phased rollouts.
+
+### Operation Modes
+
+Every policy has an operation mode that determines what happens when its condition matches.
+Refer to the [operation modes reference](../reference/vulnerability-policies.md#operation-modes)
+for the full list.
+
+*Log* mode is particularly useful when introducing a new policy. It lets you observe how often a
+policy would match without risking unintended suppression of real findings. Once confident, switch
+to *Apply*.
+
+## Further Reading
+
+* [Vulnerability policies reference](../reference/vulnerability-policies.md) for field
+  definitions, condition variables, the bundle YAML schema, and sync rules.
+* [Managing vulnerability policies](../guides/user/managing-vulnerability-policies.md)
+  for step-by-step procedures.
+
+[CycloneDX VEX]: https://cyclonedx.org/capabilities/vex/
+[VDR]: https://cyclonedx.org/capabilities/vdr/

docs/guides/administration/.pages

@@ -1,10 +1,11 @@
 title: Administration Guides
 nav:
   - index.md
-  - scaling.md
+  - configuring-database.md
   - configuring-observability.md
   - configuring-ldap.md
   - configuring-oidc.md
   - configuring-internal-ca.md
   - configuring-secret-management.md
+  - scaling.md
   - migrating-from-v4.md