diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 444a8262..d6a0e2c5 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -31,6 +31,8 @@ globs: ignores: - "docs/includes/**" +- "docs/reference/configuration/properties.md" +- "docs/reference/schemas/**" - "existing-docs/**" - "site/**" - "node_modules/**" diff --git a/.vale.ini b/.vale.ini index 13c058eb..2183c1f7 100644 --- a/.vale.ini +++ b/.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] diff --git a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt b/.vale/styles/config/vocabularies/DependencyTrack/accept.txt index 22fefcf1..4a3eeaab 100644 --- a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt +++ b/.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,27 +17,59 @@ 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 @@ -38,18 +77,35 @@ VEX [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 @@ -57,7 +113,9 @@ eDirectory keyset keysets keytool +npm sAMAccountName truststore truststore walkthroughs +zstd diff --git a/.yamllint.yml b/.yamllint.yml index d0054466..8f8bb76a 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -22,6 +22,7 @@ ignore: - node_modules/ - .vale/styles/Google/ - .vale/styles/write-good/ +- docs/reference/api/*.yaml rules: document-start: disable diff --git a/docs/concepts/.pages b/docs/concepts/.pages index ba540a3d..a0c5ace1 100644 --- a/docs/concepts/.pages +++ b/docs/concepts/.pages @@ -1,4 +1,6 @@ title: Concepts nav: - index.md + - access-control.md + - vulnerability-policies.md - ... diff --git a/docs/concepts/access-control.md b/docs/concepts/access-control.md new file mode 100644 index 00000000..fe11b11d --- /dev/null +++ b/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. diff --git a/docs/concepts/vulnerability-policies.md b/docs/concepts/vulnerability-policies.md new file mode 100644 index 00000000..27f404bf --- /dev/null +++ b/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/ diff --git a/docs/guides/administration/.pages b/docs/guides/administration/.pages index 969861f0..0bc4e770 100644 --- a/docs/guides/administration/.pages +++ b/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 diff --git a/docs/guides/administration/configuring-database.md b/docs/guides/administration/configuring-database.md new file mode 100644 index 00000000..8735d2e3 --- /dev/null +++ b/docs/guides/administration/configuring-database.md @@ -0,0 +1,256 @@ +# Configuring the database + +This guide covers choosing, deploying, and tuning a PostgreSQL database for +Dependency-Track. For the technical specification (version requirements, required +extensions, tuning parameters), see the +[database reference](../../reference/configuration/database.md). + +## Choosing a hosting solution + +Depending on available resources, individual preferences, or organizational policies, +you will have to choose between a managed or self-hosted solution. + +### Managed solutions + +The official PostgreSQL website hosts a [list of well-known commercial hosting providers]. + +Popular choices include: + +* [Amazon RDS for PostgreSQL](https://aws.amazon.com/rds/postgresql/) +* [Aiven for PostgreSQL](https://aiven.io/postgresql) +* [Azure Database for PostgreSQL](https://azure.microsoft.com/en-us/products/postgresql/) +* [Google Cloud SQL for PostgreSQL](https://cloud.google.com/sql/docs/postgres/) + +We are not actively testing against cloud offerings. But as a rule of thumb, solutions offering "vanilla" PostgreSQL, +or extensions of it (for example [Neon] or [Timescale]), will most definitely work with Dependency-Track. + +The same is not necessarily true for platforms based on heavily modified PostgreSQL, or even entire re-implementations +such as [CockroachDB] or [YugabyteDB]. Such solutions make certain trade-offs to achieve higher levels of scalability, +which might impact functionality that Dependency-Track relies on. If you'd like to see support for those, please [let us know]. + +### Self-hosting + +#### Bare Metal / Docker + +For Docker deployments, use the official [`postgres`](https://hub.docker.com/_/postgres) image. + +!!! warning + Do **not** use the `latest` tag. You may end up doing a major version upgrade without knowing it, + ultimately breaking your database. Pin the tag to at least the major version (for example, `16`), or better + yet the minor version (for example, `16.2`). Refer to [Upgrades](#upgrades) for upgrade instructions. + +For bare metal deployments, it's usually best to install PostgreSQL from your distribution's package repository. +See for example: + +* [PostgreSQL instructions for Debian](https://wiki.debian.org/PostgreSql) +* [Install and configure PostgreSQL on Ubuntu](https://ubuntu.com/server/docs/databases-postgresql) +* [Using PostgreSQL with Red Hat Enterprise Linux](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_using_database_servers/using-postgresql_configuring-and-using-database-servers) + +To get the most out of your Dependency-Track installation, we recommend to run PostgreSQL on a separate machine +than the application containers. You want PostgreSQL to be able to leverage the entire machine's resources, +without being impacted by other applications. + +For smaller and non-critical deployments, it is totally fine to run everything on a single machine. + +#### Upgrades + +Follow the [official upgrading guide]. Be sure to select the version of the documentation that corresponds to the +PostgreSQL version you are running. + +!!! warning + Pay attention to the fact that **major version upgrades usually require a backup-and-restore cycle**, due to potentially + breaking changes in the underlying data storage format. Minor version upgrades are usually safe to perform in a + rolling manner. + +#### Kubernetes + +We generally advise **against** running PostgreSQL on Kubernetes, unless you *really* know what you're doing. +Wielding heavy machinery such as [Postgres Operator] is not something to do lightheartedly. + +If you know what you're doing, you definitely don't need advice from us. + +## Basic tuning + +You should be aware that the default PostgreSQL configuration is *extremely* conservative. +It is intended to make PostgreSQL usable on minimal hardware, which is great for testing, +but can seriously cripple performance in production environments. +Not adjusting it to your specific setup will most certainly leave performance on the table. + +If you're lucky enough to have access to professional database administrators, ask them for help. +They will know your organisation's best practices and can guide you in adjusting it for Dependency-Track. + +If you're not as lucky, we can wholeheartedly recommend [PGTune]. Given a bit of basic info about your system, +it will provide a sensible baseline configuration. For the *DB Type* option, select `Online transaction processing system`. + +![Example output of PGTune](../../images/operations_database_pgtune.png) + +The `postgresql.conf` is usually located at `/var/lib/postgresql/data/postgresql.conf`. +Most of these settings require a restart of the application. + +In a Docker Compose setup, you can alternatively apply the desired configuration via command line flags. +For example: + +```yaml +services: + postgres: + image: postgres:17 + command: >- + -c 'shared_buffers=2GB' + -c 'effective_cache_size=6GB' +``` + +## Advanced tuning + +For larger deployments, you may eventually run into situations where database performance degrades +with just the basic configuration applied. Oftentimes, tweaking advanced settings can resolve +such problems. But knowing which knobs to turn is a challenge in itself. + +If you happen to be in this situation, make sure you have database monitoring set up. +Changing advanced configuration options blindly can potentially cause more damage than it helps. + +Below, you'll find a few options that, based on our observations with large-scale deployments, +make sense to tweak. Refer to the +[database reference](../../reference/configuration/database.md#tuning-parameters) for the parameter +specifications. + +!!! note + Got more tips to configure or tune PostgreSQL, that may be helpful to others? + We'd love to include it in the docs. Please raise a PR. + +### `autovacuum_vacuum_scale_factor` + +The default causes [autovacuum][Autovacuum] to start way too late on large tables with lots of churn, +yielding long execution times. Reduction in scale factor causes autovacuum to happen more often, +making each execution less time-intensive. + +The `COMPONENT` table is very frequently inserted into, updated, and deleted from. +This causes lots of dead tuples that PostgreSQL needs to clean up. Because autovacuum also performs +[`ANALYZE`](https://www.postgresql.org/docs/current/sql-analyze.html), slow vacuuming can cause the +query planner to choose inefficient execution plans. + +```sql +ALTER TABLE "COMPONENT" SET (AUTOVACUUM_VACUUM_SCALE_FACTOR = 0.02); +``` + +### `default_toast_compression` + +`lz4` compression is faster and more efficient than `pglz`, +at the expense of slightly worse compression ratios. + +Consider switching to lz4 if you're more likely to be limited +by CPU utilisation than storage space. + +```sql +ALTER SYSTEM SET (DEFAULT_TOAST_COMPRESSION = 'lz4'); +``` + +### `wal_compression` + +Enabling WAL compression significantly reduces I/O on write-heavy systems. +The cost of slightly increased CPU utilisation is more than worth it. + +If your instance is importing BOMs in large volumes and / or high frequency, +the WAL will fill up fast, and you'll find yourself limited by I/O. +This is particularly true when using HDDs instead of SSDs or NVME storage. + +```sql +ALTER SYSTEM SET (WAL_COMPRESSION = 'zstd'); +``` + +## Centralised connection pooling + +For large deployments (that is, upwards of 5 instances), it can become undesirable for +each instance to maintain its own connection pool. In this case, you can leverage +centralised connection pools such as [PgBouncer]. + +!!! warning + When using a central connection pooler, you **must** disable local connection pooling + for all data sources, using [`dt.datasource..pool.enabled=false`](../../reference/configuration/properties.md#dtdatasourcepoolenabled). + +### Constraints + +Before proceeding, take note of the following constraints: + +* Only `session` and `transaction` pooling modes are supported. `transaction` is recommended. +* Initialisation tasks, which include database migrations, **must** connect to the + database directly, bypassing the connection pooler, when using pooling mode `transaction`. + * To prevent concurrent initialisation, session-level PostgreSQL advisory locks are used, + which are not supported with the `transaction` pooling mode. + * To facilitate this, initialisation tasks can be executed in dedicated containers, + and / or using separate data sources. + +### Example + +```yaml linenums="1" +services: + postgres: + image: postgres + environment: + POSTGRES_DB: "dtrack" + POSTGRES_USER: "dtrack" + POSTGRES_PASSWORD: "dtrack" + + pgbouncer: + image: bitnami/pgbouncer + environment: + POSTGRESQL_HOST: "postgres" + POSTGRESQL_PORT: "5432" + POSTGRESQL_USERNAME: "dtrack" + POSTGRESQL_PASSWORD: "dtrack" + POSTGRESQL_DATABASE: "dtrack" + PGBOUNCER_DATABASE: "dtrack" + PGBOUNCER_PORT: "6432" + PGBOUNCER_POOL_MODE: "transaction" + PGBOUNCER_DEFAULT_POOL_SIZE: "30" + + apiserver: + image: ghcr.io/dependencytrack/hyades-apiserver + environment: + # Configure the default data source: + # - Points to PgBouncer, NOT Postgres directly. + # - Pooling is DISABLED. + DT_DATASOURCE_URL: "jdbc:postgresql://pgbouncer:6432/dtrack" + DT_DATASOURCE_USERNAME: "dtrack" + DT_DATASOURCE_PASSWORD: "dtrack" + DT_DATASOURCE_POOL_ENABLED: "false" + # Configure the data source for initialisation tasks: + # - Points to Postgres directly, NOT PgBouncer. + # - Pooling is DISABLED. + DT_DATASOURCE_INIT_URL: "jdbc:postgresql://postgres:5432/dtrack" + DT_DATASOURCE_INIT_USERNAME: "dtrack" + DT_DATASOURCE_INIT_PASSWORD: "dtrack" + DT_DATASOURCE_INIT_POOL_ENABLED: "false" + # Configure initialisation tasks to use the above data source. + DT_INIT_TASKS_DATASOURCE_NAME: "init" +``` + +## Schema migration credentials + +It is possible to use different credentials for migrations than for the application itself. +This can be achieved by configuring a separate data source, and instructing the init tasks to use it: + +```ini linenums="1" +# Configure a data source named "init-tasks". +dt.datasource.init-tasks.url=jdbc:postgresql://localhost:5432/dtrack +dt.datasource.init-tasks.username=my-init-task-user +dt.datasource.init-tasks.password=my-init-task-pass + +# Configure init tasks to use the data source. +init.tasks.datasource.name=init-tasks + +# If the data source is only meant for init tasks, there is no need to +# keep it around after the tasks completed. +init.tasks.datasource.close-after-use=true +``` + +[Autovacuum]: https://www.postgresql.org/docs/current/routine-vacuuming.html +[CockroachDB]: https://www.cockroachlabs.com/ +[Neon]: https://neon.tech/ +[PGTune]: https://pgtune.leopard.in.ua/ +[PgBouncer]: https://www.pgbouncer.org/ +[Postgres Operator]: https://github.com/zalando/postgres-operator +[Timescale]: https://www.timescale.com/ +[YugabyteDB]: https://www.yugabyte.com/ +[let us know]: https://github.com/DependencyTrack/hyades/issues/new?assignees=&labels=enhancement&projects=&template=enhancement-request.yml +[list of well-known commercial hosting providers]: https://www.postgresql.org/support/professional_hosting/ +[official upgrading guide]: https://www.postgresql.org/docs/current/upgrading.html diff --git a/docs/guides/administration/configuring-ldap.md b/docs/guides/administration/configuring-ldap.md index 847cdcb3..5fd9aac5 100644 --- a/docs/guides/administration/configuring-ldap.md +++ b/docs/guides/administration/configuring-ldap.md @@ -4,15 +4,6 @@ Dependency-Track can authenticate users against an LDAP directory such as Micros Active Directory, ApacheDS, or any other LDAP-compatible server. Once enabled, users log in with their directory credentials rather than a locally managed password. -## How LDAP authentication works - -1. The user enters their credentials on the Dependency-Track login page. -2. Dependency-Track binds to the LDAP server using the configured service account. -3. The user's entry is located in the directory using the configured username format. -4. A bind attempt is made with the user's credentials to verify their password. -5. If successful, the user is granted access. If [user provisioning](#user-provisioning) - is enabled, their account is created automatically on first login. - ## Prerequisites - A service account in the LDAP directory with read access to users and groups. diff --git a/docs/guides/administration/configuring-observability.md b/docs/guides/administration/configuring-observability.md index 1d7ca42d..b5a1e2d4 100644 --- a/docs/guides/administration/configuring-observability.md +++ b/docs/guides/administration/configuring-observability.md @@ -1,66 +1,94 @@ # Configuring observability -Dependency-Track exposes health check and metrics endpoints via a dedicated management server. -It runs on a separate port, and potentially different bind address, independently of the main app server. - -The management server's bind address and port are configurable: - -- [`dt.management.host`](../../reference/configuration/properties.md#dtmanagementhost) (default: `0.0.0.0`) -- [`dt.management.port`](../../reference/configuration/properties.md#dtmanagementport) (default: `9000`) +Dependency-Track exposes health check and metrics endpoints via a dedicated management server, +running on a separate port independently of the main app server. !!! tip All observability-related configuration properties are documented in the [configuration reference](../../reference/configuration/properties.md), under the *Observability* category. -## Health checks - -Health check endpoints follow the [MicroProfile Health] specification. -They return JSON responses with an overall `status` (`UP` or `DOWN`) -and individual check results. The HTTP status code is `200` when healthy, `503` otherwise. - -The following endpoints are available on the management server: - -| Endpoint | Description | -|:------------------|:--------------------------------------| -| `/health` | Aggregate status of all health checks | -| `/health/live` | Liveness checks | -| `/health/ready` | Readiness checks | -| `/health/started` | Startup checks | - -These endpoints map directly to Kubernetes [probe types] and can be used as-is -in `livenessProbe`, `readinessProbe`, and `startupProbe` configurations. +## Configuring Kubernetes health probes + +The management server exposes health check endpoints that follow the [MicroProfile Health] +specification and map directly to Kubernetes [probe types]. + +Add the following probes to your Deployment manifest, adjusting the port if you changed +[`dt.management.port`](../../reference/configuration/properties.md#dtmanagementport) +(default: `9000`): + +```yaml linenums="1" +containers: + - name: apiserver + livenessProbe: + httpGet: + path: /health/live + port: 9000 + initialDelaySeconds: 15 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /health/ready + port: 9000 + initialDelaySeconds: 15 + periodSeconds: 10 + startupProbe: + httpGet: + path: /health/started + port: 9000 + initialDelaySeconds: 10 + failureThreshold: 30 + periodSeconds: 5 +``` -## Metrics +The aggregate endpoint `/health` returns the combined status of all checks. -When enabled, Prometheus metrics are served at the `/metrics` endpoint of the management server, -using the [Prometheus text exposition format]. +## Enabling Prometheus metrics scraping -Metrics are off by default. Enable them via -[`dt.metrics.enabled`](../../reference/configuration/properties.md#dtmetricsenabled). +Metrics are disabled by default. Enable them via +[`dt.metrics.enabled`](../../reference/configuration/properties.md#dtmetricsenabled): -Access to the metrics endpoint can optionally be protected with HTTP Basic authentication: +```ini +dt.metrics.enabled=true +``` -- [`dt.metrics.auth.username`](../../reference/configuration/properties.md#dtmetricsauthusername) -- [`dt.metrics.auth.password`](../../reference/configuration/properties.md#dtmetricsauthpassword) +Once enabled, metrics are served at `/metrics` on the management port in the +[Prometheus text exposition format]. + +If you want to protect the endpoint with HTTP Basic authentication, set both +[`dt.metrics.auth.username`](../../reference/configuration/properties.md#dtmetricsauthusername) and +[`dt.metrics.auth.password`](../../reference/configuration/properties.md#dtmetricsauthpassword). + +Add a scrape target to your Prometheus configuration: + +```yaml linenums="1" +scrape_configs: + - job_name: dependency-track + metrics_path: /metrics + static_configs: + - targets: + - "apiserver:9000" + # Uncomment if you enabled authentication: + # basic_auth: + # username: "metrics" + # password: "changeme" +``` -Both must be set for authentication to take effect. +## Adjusting log levels -## Logging +By default, Dependency-Track logs at `INFO` level for application loggers and `WARN` for all others. +To troubleshoot a specific area, raise the log level for the relevant logger: -By default, Dependency-Track logs at `INFO` level for app loggers (`alpine`, `org.dependencytrack`, -`org.eclipse.jetty`) and `WARN` for all others. +```properties +dt.logging.level."org.dependencytrack"=DEBUG +``` -Log levels can be configured per logger as follows: +The special logger name `ROOT` applies to all loggers that are not explicitly configured: ```properties -dt.logging.level."org.dependencytrack"=DEBUG -dt.logging.level."org.eclipse.jetty"=WARN dt.logging.level."ROOT"=ERROR ``` -The special logger name `ROOT` applies to all loggers that are not explicitly configured. - Refer to the [environment variable mapping](../../reference/configuration/application.md#environment-variable-mapping) documentation for how to express these properties as environment variables. diff --git a/docs/guides/administration/configuring-oidc.md b/docs/guides/administration/configuring-oidc.md index c7334c85..659fbea5 100644 --- a/docs/guides/administration/configuring-oidc.md +++ b/docs/guides/administration/configuring-oidc.md @@ -9,17 +9,6 @@ locally managed password. The API server validates tokens; the frontend initiates the OIDC flow. Both must be configured with the same issuer and client ID. -## How OIDC authentication works - -1. The user clicks the **Login with SSO** button on the Dependency-Track frontend. -2. The frontend redirects to the IdP's authorization endpoint. -3. The user authenticates with the IdP and is redirected back with an ID token. -4. The frontend passes the ID token to the API server for validation. -5. The API server verifies the token against the IdP's discovery endpoint and extracts - the username from the configured claim. -6. If [user provisioning](#user-provisioning) is enabled, the account is created on - first login. Otherwise the account must exist in advance. - ## Prerequisites - An OIDC-compatible identity provider with a configured client (app). diff --git a/docs/guides/administration/configuring-secret-management.md b/docs/guides/administration/configuring-secret-management.md index ff7621a8..7780d37a 100644 --- a/docs/guides/administration/configuring-secret-management.md +++ b/docs/guides/administration/configuring-secret-management.md @@ -40,41 +40,15 @@ The provider may be configured using the following properties: #### Key management -Encryption of secrets involves two types of keys: +Secrets are encrypted using [envelope encryption]: each secret gets its own +data encryption key (DEK), which is itself encrypted by a key encryption key (KEK). +The KEK is stored in a [keyset][keysets] file managed by [Google Tink]. -* The key encryption key (KEK) -* Data encryption keys (DEKs) - -When creating a secret, Dependency-Track generates a new DEK, -and encrypts the secret value with it. It then encrypts the DEK -with the KEK. Both the encrypted DEK and the encrypted secret value -are then stored in the database. - -!!! info - The encrypted DEK is [tagged](https://developers.google.com/tink/design/keysets#keyids) - with the ID of the KEK that encrypted it. - -When reading a secret, the encrypted DEK and encrypted secret value -are read from the database. The DEK is then decrypted with the KEK, -which then allows the secret value to be decrypted using the DEK. - -Dependency-Track uses [Google Tink]'s concept of [keysets] -to enable rotation of KEKs. A KEK keyset is created automatically -on startup. Or, a [manually created keyset](#creating-kek-keysets) -may be provided. - -The KEK keyset uses [Google Tink]'s JSON serialization, -and is not encrypted itself. For production deployments, -**mount the KEK keyset at runtime** using +A KEK keyset is created automatically on startup, or a +[manually created keyset](#creating-kek-keysets) may be provided. +For production deployments, **mount the KEK keyset at runtime** using [Kubernetes secrets] or similar mechanisms, and ensure that the keyset file is only readable by the app user. -Refer to [Creating KEK keysets](#creating-kek-keysets) for an example. - -!!! note - [Google Tink] [supports](https://developers.google.com/tink/key-management-overview#create_kek) - a small selection of key management systems (KMS), which may be used to manage the KEK keyset. - Dependency-Track does not yet use this capability. If this is important to you, - please raise an enhancement request. #### Config-based KEK diff --git a/docs/guides/administration/scaling.md b/docs/guides/administration/scaling.md index 9f1d8aee..d021b60d 100644 --- a/docs/guides/administration/scaling.md +++ b/docs/guides/administration/scaling.md @@ -8,9 +8,10 @@ adding instances, splitting workloads, and tuning concurrency. Deploy multiple instances pointing at the same database. No additional infrastructure (message brokers, caches, etc.) is needed. -Work distribution is handled by the embedded [durable execution engine](../../concepts/architecture/design/durable-execution.md). -Lease-based leader election ensures single-instance operations (scheduling, maintenance) -run on exactly one node. All other work is distributed across the cluster automatically. +Work distribution is handled by the embedded +[durable execution engine](../../concepts/architecture/design/durable-execution.md). +All work is distributed across the cluster automatically; single-instance +operations (scheduling, maintenance) are handled via leader election. ### File storage @@ -62,68 +63,34 @@ services: ## Concurrency control Task execution concurrency can be controlled at two levels: -local (per-instance) and global (cluster-wide). Both complement each other: -queue capacity controls how much work is queued, while worker concurrency -controls how fast that work is processed. +local (per-instance) and global (cluster-wide). For a detailed explanation, refer to the [durable execution design doc](../../concepts/architecture/design/durable-execution.md#concurrency-control). ### Local (worker concurrency) -Each worker limits how many tasks it processes concurrently, per instance. +Each worker limits how many tasks it processes concurrently per instance. Isolated task queues prevent one workload from starving others. -Workers are configured via: - -```ini -dt.dex-engine...max-concurrency= -``` - -Where `` is either `workflow-worker` or `activity-worker`. - -| Worker Type | Worker Name | Queue | Default Concurrency | -|-------------------|--------------------------------|---------------------------------|--------------------:| -| `workflow-worker` | `default` | `default` | 100 | -| `activity-worker` | `default` | `default` | 25 | -| `activity-worker` | `vuln-analysis` | `vuln-analyses` | 10 | -| `activity-worker` | `artifact-import` | `artifact-imports` | 10 | -| `activity-worker` | `package-metadata-resolution` | `package-metadata-resolutions` | 10 | -| `activity-worker` | `notification` | `notifications` | 5 | -| `activity-worker` | `vuln-analysis-reconciliation` | `vuln-analysis-reconciliations` | 5 | -| `activity-worker` | `policy-evaluation` | `policy-evaluations` | 5 | -| `activity-worker` | `metrics-update` | `metrics-updates` | 5 | - For example, to increase vulnerability analysis concurrency to 20: ```ini dt.dex-engine.activity-worker.vuln-analysis.max-concurrency=20 ``` +For all available workers, queues, and their defaults, see the +[dex engine reference](../../reference/configuration/dex-engine.md#workers). + ### Global (queue capacity) Task queue capacity limits how many tasks can be pending across the entire cluster. -When a queue reaches capacity, the scheduler stops creating new tasks for that queue, -providing backpressure. Workflow runs remain in their current state until capacity -becomes available. - -The default capacities are: - -| Type | Queue | Default Capacity | -|------------|---------------------------------|-----------------:| -| `workflow` | `default` | 1000 | -| `activity` | `default` | 1000 | -| `activity` | `artifact-imports` | 25 | -| `activity` | `metrics-updates` | 25 | -| `activity` | `notifications` | 25 | -| `activity` | `package-metadata-resolutions` | 25 | -| `activity` | `policy-evaluations` | 25 | -| `activity` | `vuln-analyses` | 25 | -| `activity` | `vuln-analysis-reconciliations` | 25 | +When a queue reaches capacity, the scheduler provides backpressure by pausing +new task creation. Queue capacity is modifiable at runtime in the administrator panel under *Workflows* -> *Task Queues*, -or via REST API. As last resort, it can be controlled by directly modifying the -`dex_workflow_task_queue` and `dex_activity_task_queue` database tables. +or via REST API. For default capacities, see the +[dex engine reference](../../reference/configuration/dex-engine.md#task-queues). ## Vertical scaling @@ -153,56 +120,37 @@ More CPU benefits worker throughput; more memory benefits caching and large BOM ### Buffers -The durable execution engine batches certain write operations to reduce database -round-trips. Each buffer has a configurable flush interval and max batch size. - +The durable execution engine batches write operations to reduce database round-trips. Increasing flush intervals and batch sizes improves throughput at the cost of -higher end-to-end latency. Decreasing them reduces latency but increases -database load. Should generally not be modified unless evidence suggests +higher end-to-end latency. Should generally not be modified unless evidence suggests that the defaults are problematic. -Configuration: - -- [`dt.dex-engine.task-event-buffer.flush-interval-ms`](../../reference/configuration/properties.md#dtdex-enginetask-event-bufferflush-interval-ms) -- [`dt.dex-engine.task-event-buffer.max-batch-size`](../../reference/configuration/properties.md#dtdex-enginetask-event-buffermax-batch-size) -- [`dt.dex-engine.external-event-buffer.flush-interval-ms`](../../reference/configuration/properties.md#dtdex-engineexternal-event-bufferflush-interval-ms) -- [`dt.dex-engine.external-event-buffer.max-batch-size`](../../reference/configuration/properties.md#dtdex-engineexternal-event-buffermax-batch-size) -- [`dt.dex-engine.activity-task-heartbeat-buffer.flush-interval-ms`](../../reference/configuration/properties.md#dtdex-engineactivity-task-heartbeat-bufferflush-interval-ms) -- [`dt.dex-engine.activity-task-heartbeat-buffer.max-batch-size`](../../reference/configuration/properties.md#dtdex-engineactivity-task-heartbeat-buffermax-batch-size) +Refer to the buffer properties in the +[configuration reference](../../reference/configuration/properties.md#dtdex-enginetask-event-bufferflush-interval-ms). ### Run history cache Workflow run event histories are cached in memory to avoid redundant database reads -during replay. Increase `max-size` on worker nodes with high workflow concurrency. -This trades memory for reduced database load. +during replay. Increase `max-size` on worker nodes with high workflow concurrency +to trade memory for reduced database load. -Configuration: - -- [`dt.dex-engine.run-history-cache.max-size`](../../reference/configuration/properties.md#dtdex-enginerun-history-cachemax-size) -- [`dt.dex-engine.run-history-cache.evict-after-access-ms`](../../reference/configuration/properties.md#dtdex-enginerun-history-cacheevict-after-access-ms) +Refer to [`dt.dex-engine.run-history-cache.*`](../../reference/configuration/properties.md#dtdex-enginerun-history-cachemax-size). ### Maintenance The maintenance worker periodically deletes completed workflow runs. At high volume, completed runs accumulate and can increase vacuum and WAL pressure. -Shortening retention or increasing batch size can help keep the database lean, -but larger deletion batches cause more I/O per maintenance cycle. - -Configuration: +Shortening retention or increasing batch size can help keep the database lean. -- [`dt.dex-engine.maintenance.run-retention-duration`](../../reference/configuration/properties.md#dtdex-enginemaintenancerun-retention-duration) -- [`dt.dex-engine.maintenance.run-deletion-batch-size`](../../reference/configuration/properties.md#dtdex-enginemaintenancerun-deletion-batch-size) +Refer to [`dt.dex-engine.maintenance.*`](../../reference/configuration/properties.md#dtdex-enginemaintenancerun-retention-duration). ### Notification outbox relay The outbox relay polls for pending notifications and submits them for publishing. -Increase `batch-size` for environments with high notification volume. -Decrease `poll-interval-ms` for lower notification latency. - -Configuration: +Increase `batch-size` for high notification volume, or decrease `poll-interval-ms` +for lower latency. -- [`notification.outbox-relay.poll-interval-ms`](../../reference/configuration/properties.md#dtnotificationoutbox-relaypoll-interval-ms) -- [`notification.outbox-relay.batch-size`](../../reference/configuration/properties.md#dtnotificationoutbox-relaybatch-size) +Refer to [`notification.outbox-relay.*`](../../reference/configuration/properties.md#dtnotificationoutbox-relaypoll-interval-ms). ## Separate database for dex @@ -240,10 +188,11 @@ and background processing. - **5+ instances**: Consider centralised pooling (for example, PgBouncer) and turn off local pooling. - Ensure PostgreSQL's `max_connections` accounts for the sum of all pools. -Refer to [Data Sources - Connection Pooling](../../reference/configuration/datasources.md#connection-pooling) for details. +Refer to [Data Sources](../../reference/configuration/datasources.md#connection-pool-properties) for pool properties, +and [Centralised connection pooling](configuring-database.md#centralised-connection-pooling) for PgBouncer setup. ## Database tuning PostgreSQL tuning (autovacuum, WAL compression, `shared_buffers`, etc.) can -impact performance at scale. Refer to [Database](../../reference/configuration/database.md) -for recommendations. +impact performance at scale. Refer to [Configuring the database](configuring-database.md) +for tuning recommendations. diff --git a/docs/guides/upgrading/v0.7.0.md b/docs/guides/upgrading/v0.7.0.md index b73ebc00..7a8fa459 100644 --- a/docs/guides/upgrading/v0.7.0.md +++ b/docs/guides/upgrading/v0.7.0.md @@ -156,12 +156,12 @@ * **The `LOGGING_LEVEL` environment variable has been removed**. Log levels are now configured via `dt.logging.level.""` per-logger properties. - Refer to the [logging documentation](../administration/configuring-observability.md#logging) for details. + Refer to the [logging documentation](../administration/configuring-observability.md#adjusting-log-levels) for details. * The following init task configurations have been removed and replaced with `init.tasks.datasource.name`: * `init.tasks.database.url` * `init.tasks.database.username` * `init.tasks.database.password` -* Refer to the [schema migrations](../../reference/configuration/database.md#schema-migrations) documentation +* Refer to [schema migration credentials](../administration/configuring-database.md#schema-migration-credentials) for an example of how to run init tasks with separate database credentials. [hyades/#1910]: https://github.com/DependencyTrack/hyades/issues/1910 diff --git a/docs/guides/user/.pages b/docs/guides/user/.pages index 50b8575f..23a47a5f 100644 --- a/docs/guides/user/.pages +++ b/docs/guides/user/.pages @@ -2,3 +2,5 @@ title: User Guides nav: - index.md - managing-secrets.md + - managing-vulnerability-policies.md + - managing-private-vulnerabilities.md diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_bundles-modal.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_bundles-modal.png new file mode 100644 index 00000000..1a6c32ed Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_bundles-modal.png differ diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_analysis.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_analysis.png new file mode 100644 index 00000000..5242e417 Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_analysis.png differ diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_condition.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_condition.png new file mode 100644 index 00000000..634fd2ba Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_condition.png differ diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_general.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_general.png new file mode 100644 index 00000000..6b0be768 Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_general.png differ diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_ratings.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_ratings.png new file mode 100644 index 00000000..fbf86c32 Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_editor_ratings.png differ diff --git a/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_list.png b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_list.png new file mode 100644 index 00000000..cc5c961d Binary files /dev/null and b/docs/guides/user/images/managing-vulnerability-policies/vuln-policies_list.png differ diff --git a/docs/guides/user/managing-private-vulnerabilities.md b/docs/guides/user/managing-private-vulnerabilities.md new file mode 100644 index 00000000..e017208e --- /dev/null +++ b/docs/guides/user/managing-private-vulnerabilities.md @@ -0,0 +1,13 @@ +# Managing private vulnerabilities + +Dependency-Track includes a built-in private vulnerability repository for managing +vulnerabilities that are not (yet) publicly documented. For field definitions and +matching behaviour, see the +[private vulnerability repository reference](../../reference/datasources/private-vulnerability-repository.md). + +## Creating a vulnerability + +Navigate to **Vulnerabilities** in the sidebar and click **Create Vulnerability**. + +The `VULNERABILITY_MANAGEMENT` permission is required to create and modify internal +vulnerabilities. diff --git a/docs/guides/user/managing-vulnerability-policies.md b/docs/guides/user/managing-vulnerability-policies.md new file mode 100644 index 00000000..c600f150 --- /dev/null +++ b/docs/guides/user/managing-vulnerability-policies.md @@ -0,0 +1,48 @@ +# Managing vulnerability policies + +Vulnerability policies are managed under *Policy Management* > *Vulnerability Policies*. The required +permission is `POLICY_MANAGEMENT`, or one of the finer-grained `POLICY_MANAGEMENT_CREATE`, +`POLICY_MANAGEMENT_READ`, `POLICY_MANAGEMENT_UPDATE`, `POLICY_MANAGEMENT_DELETE`. + +For background on what vulnerability policies are and how they work, see the +[concepts page](../../concepts/vulnerability-policies.md). For field definitions and the bundle YAML +schema, see the [reference page](../../reference/vulnerability-policies.md). + +![Vulnerability policy list](./images/managing-vulnerability-policies/vuln-policies_list.png) + +## Creating a Policy + +1. Click *Create Policy* to open the editor. +2. On the *General* tab, provide a name, optional description and author, an operation mode, and a + priority between `0` and `100`. Higher values are evaluated first. Optionally set a validity window. +3. On the *Condition* tab, write a CEL expression. The editor offers autocompletion for the available + variables and functions, and a template dropdown with common patterns. +4. On the *Analysis* tab, pick the state and any additional analysis fields to apply when the policy + matches. +5. On the *Ratings* tab, optionally add up to three rating overrides. +6. Click *Create*. + +![Policy editor - General tab](./images/managing-vulnerability-policies/vuln-policies_editor_general.png) + +![Policy editor - Condition tab](./images/managing-vulnerability-policies/vuln-policies_editor_condition.png) + +![Policy editor - Analysis tab](./images/managing-vulnerability-policies/vuln-policies_editor_analysis.png) + +![Policy editor - Ratings tab](./images/managing-vulnerability-policies/vuln-policies_editor_ratings.png) + +## Editing and Deleting + +User-managed policies can be edited or deleted from the list view. Bundle-managed policies appear +read-only and must be changed at the bundle source. + +## Configuring the Bundle Source + +Configure the bundle URL and (optionally) credentials on the API server. Refer to the +[bundle configuration properties](../../reference/vulnerability-policies.md#bundle-configuration) +for the full list. + +Once the URL is configured, Dependency-Track fetches the bundle on the configured schedule. A bundle +whose digest matches the last successful sync is skipped. An administrator may also trigger an immediate +sync from *Policy Management* > *Vulnerability Policies* > *Bundles* > *Sync*. + +![Bundles management modal](./images/managing-vulnerability-policies/vuln-policies_bundles-modal.png) diff --git a/docs/images/operations_database_pgtune.png b/docs/images/operations_database_pgtune.png new file mode 100644 index 00000000..6d41d466 Binary files /dev/null and b/docs/images/operations_database_pgtune.png differ diff --git a/docs/images/reference/expression-condition.png b/docs/images/reference/expression-condition.png new file mode 100644 index 00000000..08d8b1a8 Binary files /dev/null and b/docs/images/reference/expression-condition.png differ diff --git a/docs/reference/.pages b/docs/reference/.pages index c1c60537..44b932ba 100644 --- a/docs/reference/.pages +++ b/docs/reference/.pages @@ -1,4 +1,18 @@ title: Reference nav: - index.md - - ... + - API: api + - Configuration: configuration + - Datasources: datasources + - Notifications: notifications + - Vulnerability Analysis: + - Vulnerability Analyzers: analyzers.md + - Vulnerability Policies: vulnerability-policies.md + - CEL Expressions: cel-expressions.md + - Access Control: + - Permissions: permissions.md + - Integrations: + - Badges: badges.md + - File Formats: file-formats.md + - Community Integrations: community-integrations.md + - Schemas: schemas diff --git a/docs/reference/analyzers.md b/docs/reference/analyzers.md new file mode 100644 index 00000000..ad8f1866 --- /dev/null +++ b/docs/reference/analyzers.md @@ -0,0 +1,151 @@ +# Vulnerability Analyzers + +Dependency-Track ships with the following vulnerability analyzers. Each analyzer +can be individually enabled and configured via the administration UI. + +!!! info "Alias synchronisation" + Some analyzers support *alias synchronisation*. Vulnerability aliases map + equivalent identifiers across databases. For example, a CVE identifier and + its corresponding GitHub Security Advisory (GHSA) identifier. Enabling alias + synchronisation allows Dependency-Track to correlate these identifiers, giving + a more complete picture of each vulnerability across sources. + +## Internal + +Matches components against Dependency-Track's own vulnerability database. This includes +vulnerabilities mirrored from sources such as the NVD, GitHub Advisories, and OSV. +The internal analyzer is enabled by default. + +Uses both CPE and PURL matching. + +!!! note + The internal analyzer does not communicate with any external service. It queries + only the local database. + +### Configuration + +| Option | Required when enabled | Description | +|---------|-----------------------|--------------------------------| +| Enabled | - | Whether the analyzer is active | + +![Internal analyzer configuration](./images/analyzers/analyzer-config_internal.png) + +!!! tip "Data source configuration" + Because the analyzer operates entirely read-only, it is possible to use a separate + [data source](./configuration/datasources.md) for it, which can + help to reduce load on the main database. + + This can be achieved using + [`dt.vuln-analyzer.internal.datasource.name`](./configuration/properties.md#dtvuln-analyzerinternaldatasourcename). + Since it is an infrastructure concern, it cannot be configured through the UI. + +## OSS Index + +Integrates with [Sonatype OSS Index][oss-index] for vulnerability intelligence. + +Uses PURL matching. Supports the following ecosystems: + +* `cargo` +* `cocoapods` +* `composer` +* `conan` +* `conda` +* `cran` +* `gem` +* `golang` +* `maven` +* `npm` +* `nuget` +* `pypi` +* `rpm` +* `swift` + +### Configuration + +| Option | Required when enabled | Description | +|--------------------|-----------------------|-------------------------------------------------------------------| +| Enabled | - | Whether the analyzer is active | +| Alias sync enabled | - | Whether to synchronise vulnerability aliases | +| API URL | Yes | OSS Index API base URL (default: `https://ossindex.sonatype.org`) | +| Username | Yes | OSS Index account username | +| API token | Yes | OSS Index API token. Must be a [managed secret]. | + +![OSS Index analyzer configuration](./images/analyzers/analyzer-config_oss-index.png) + +## Snyk + +Integrates with the [Snyk][snyk] vulnerability database. + +Uses PURL matching. Supports the following ecosystems: + +* `cargo` +* `cocoapods` +* `composer` +* `gem` +* `generic` +* `hex` +* `golang` +* `maven` +* `npm` +* `nuget` +* `pypi` +* `swift` + +### Configuration + +| Option | Required when enabled | Description | +|--------------------|-----------------------|---------------------------------------------------------| +| Enabled | - | Whether the analyzer is active | +| Alias sync enabled | - | Whether to synchronise vulnerability aliases | +| API base URL | Yes | Snyk REST API base URL (default: `https://api.snyk.io`) | +| Organisation ID | Yes | Snyk organisation identifier | +| API token | Yes | Snyk API token. Must be a [managed secret]. | + +![Snyk analyzer configuration](./images/analyzers/analyzer-config_snyk.png) + +## Trivy + +Integrates with a [Trivy][trivy] server instance for vulnerability scanning. + +Uses PURL matching. + +!!! warning + Trivy requires a separately deployed Trivy server. Dependency-Track does not + bundle or manage the Trivy server process. + +### Configuration + +| Option | Required when enabled | Description | +|----------------|-----------------------|------------------------------------------------------------------------| +| Enabled | - | Whether the analyzer is active | +| API URL | Yes | URL of the Trivy server | +| API token | Yes | Authentication token for the Trivy server. Must be a [managed secret]. | +| Ignore unfixed | - | Whether to exclude vulnerabilities without a known fix | +| Scan library | - | Scan language/library packages (enabled by default) | +| Scan OS | - | Scan OS-level packages (disabled by default) | + +![Trivy analyzer configuration](./images/analyzers/analyzer-config_trivy.png) + +## VulnDB + +Integrates with [Flashpoint VulnDB][vulndb], a commercial vulnerability intelligence service. + +Uses CPE matching. + +### Configuration + +| Option | Required when enabled | Description | +|-------------------------|-----------------------|-------------------------------------------------------------------------| +| Enabled | - | Whether the analyzer is active | +| Alias sync enabled | - | Whether to synchronise vulnerability aliases | +| API URL | Yes | VulnDB API URL (default: `https://vulndb.flashpoint.io`) | +| OAuth 2.0 client ID | Yes | OAuth 2.0 client ID for authentication | +| OAuth 2.0 client secret | Yes | OAuth 2.0 client secret for authentication. Must be a [managed secret]. | + +![VulnDB analyzer configuration](./images/analyzers/analyzer-config_vulndb.png) + +[managed secret]: ../guides/user/managing-secrets.md +[oss-index]: https://ossindex.sonatype.org/ +[snyk]: https://snyk.io/ +[trivy]: https://trivy.dev/ +[vulndb]: https://flashpoint.io/resources/datasheets/vulndb/ diff --git a/docs/reference/api/.pages b/docs/reference/api/.pages new file mode 100644 index 00000000..46633233 --- /dev/null +++ b/docs/reference/api/.pages @@ -0,0 +1,3 @@ +nav: + - REST API v1: v1.md + - REST API v2: v2.md diff --git a/docs/reference/api/openapi-v1.yaml b/docs/reference/api/openapi-v1.yaml new file mode 100644 index 00000000..9ffbbe8f --- /dev/null +++ b/docs/reference/api/openapi-v1.yaml @@ -0,0 +1,12377 @@ +openapi: 3.0.1 +info: + contact: + name: The Dependency-Track Authors + url: https://github.com/DependencyTrack/dependency-track + description: REST API of OWASP Dependency-Track + license: + name: Apache-2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + title: OWASP Dependency-Track + version: 5.7.0-alpha.3-SNAPSHOT +servers: +- url: /api +paths: + /v1/acl/mapping: + put: + description:

Requires permission ACCESS_MANAGEMENT

+ operationId: addMapping + requestBody: + content: + '*/*': + schema: + $ref: "#/components/schemas/AclMappingRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/AclMappingRequest" + description: Mapping created successfully + "401": + description: Unauthorized + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Team or project could not be found + "409": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A mapping with the same team and project already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds an ACL mapping + tags: + - acl + /v1/acl/mapping/team/{teamUuid}/project/{projectUuid}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteMapping + parameters: + - description: The UUID of the team to delete the mapping for + in: path + name: teamUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to delete the mapping for + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Mapping removed successfully + "401": + description: Unauthorized + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Team or project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes an ACL mapping + tags: + - acl + /v1/acl/team/{uuid}: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: retrieveProjects + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the team to retrieve mappings for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + - description: Optionally excludes children projects from being returned + in: query + name: onlyRoot + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: Projects assigned to the specified team + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + "404": + description: The UUID of the team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the projects assigned to the specified team + tags: + - acl + /v1/analysis: + get: + description:

Requires permission VIEW_VULNERABILITY

+ operationId: retrieveAnalysis + parameters: + - description: The UUID of the project + in: query + name: project + schema: + type: string + format: uuid + - description: The UUID of the component + in: query + name: component + required: true + schema: + type: string + format: uuid + - description: The UUID of the vulnerability + in: query + name: vulnerability + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Analysis" + description: An analysis trail + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: "The project, component, or vulnerability could not be found" + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Retrieves an analysis trail + tags: + - analysis + put: + description:

Requires permission VULNERABILITY_ANALYSIS + or VULNERABILITY_ANALYSIS_UPDATE

+ operationId: updateAnalysis + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/AnalysisRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Analysis" + description: The created analysis + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: "The project, component, or vulnerability could not be found" + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Records an analysis decision + tags: + - analysis + /v1/badge/violations/project/{name}/{version}: + get: + operationId: getProjectPolicyViolationsBadge_1 + parameters: + - description: The name of the project to query on + in: path + name: name + required: true + schema: + type: string + - description: The version of the project to query on + in: path + name: version + required: true + schema: + type: string + responses: + "200": + content: + image/svg+xml: + schema: + type: string + description: A badge displaying current policy violation metrics of a project + in SVG format + "403": + description: Badges are disabled + "404": + description: The project could not be found + summary: Returns a policy violations badge for a specific project + tags: + - badge + /v1/badge/violations/project/{uuid}: + get: + operationId: getProjectPolicyViolationsBadge + parameters: + - description: The UUID of the project to retrieve a badge for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + image/svg+xml: + schema: + type: string + description: A badge displaying current policy violation metrics of a project + in SVG format + "403": + description: Badges are disabled + "404": + description: The project could not be found + summary: Returns a policy violations badge for a specific project + tags: + - badge + /v1/badge/vulns/project/{name}/{version}: + get: + operationId: getProjectVulnerabilitiesBadge_1 + parameters: + - description: The name of the project to query on + in: path + name: name + required: true + schema: + type: string + - description: The version of the project to query on + in: path + name: version + required: true + schema: + type: string + responses: + "200": + content: + image/svg+xml: + schema: + type: string + description: A badge displaying current vulnerability metrics for a project + in SVG format + "403": + description: Badges are disabled + "404": + description: The project could not be found + summary: Returns current metrics for a specific project + tags: + - badge + /v1/badge/vulns/project/{uuid}: + get: + operationId: getProjectVulnerabilitiesBadge + parameters: + - description: The UUID of the project to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + image/svg+xml: + schema: + type: string + description: A badge displaying current vulnerability metrics for a project + in SVG format + "403": + description: Badges are disabled + "404": + description: The project could not be found + summary: Returns current metrics for a specific project + tags: + - badge + /v1/bom: + post: + description: |- +

+ Expects CycloneDX and a valid project UUID. If a UUID is not specified, + then the projectName and projectVersion must be specified. + Optionally, if autoCreate is specified and true and the project does not exist, + the project will be created. In this scenario, the principal making the request will + additionally need the PORTFOLIO_MANAGEMENT, PORTFOLIO_MANAGEMENT_CREATE, + or PROJECT_CREATION_UPLOAD permission. +

+

+ MediaType supported for BOM artifact is 'application/xml', 'application/json' or 'application/x.vnd.cyclonedx+protobuf'. + The BOM will be validated against the CycloneDX schema. If schema validation fails, + a response with problem details in RFC 9457 format will be returned. In this case, + the response's content type will be application/problem+json. +

+

Requires permission BOM_UPLOAD

+ operationId: UploadBom + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + autoCreate: + type: boolean + default: false + bom: + type: string + isLatest: + type: boolean + default: false + parentName: + type: string + parentUUID: + type: string + parentVersion: + type: string + project: + type: string + projectName: + type: string + projectTags: + type: string + projectVersion: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking BOM processing progress + "400": + description: The uploaded BOM is invalid + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Upload a supported bill of material format document + tags: + - bom + put: + description: |- +

+ Expects CycloneDX and a valid project UUID. If a UUID is not specified, + then the projectName and projectVersion must be specified. + Optionally, if autoCreate is specified and true and the project does not exist, + the project will be created. In this scenario, the principal making the request will + additionally need the PORTFOLIO_MANAGEMENT, PORTFOLIO_MANAGEMENT_CREATE, + or PROJECT_CREATION_UPLOAD permission. +

+

+ The BOM will be validated against the CycloneDX schema. If schema validation fails, + a response with problem details in RFC 9457 format will be returned. In this case, + the response's content type will be application/problem+json. +

+

+ The maximum allowed length of the bom value is 20'000'000 characters. + When uploading large BOMs, the POST endpoint is preferred, + as it does not have this limit. +

+

Requires permission BOM_UPLOAD

+ operationId: UploadBomBase64Encoded + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/BomSubmitRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking BOM processing progress + "400": + description: The uploaded BOM is invalid + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Upload a supported bill of material format document + tags: + - bom + /v1/bom/cyclonedx/component/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: exportComponentAsCycloneDx + parameters: + - description: The UUID of the component to export + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The format to output (defaults to JSON) + in: query + name: format + schema: + type: string + - description: "The CycloneDX Spec variant exported (defaults to: '1.5')" + in: query + name: version + schema: + type: string + responses: + "200": + content: + application/vnd.cyclonedx+json: + schema: + type: string + application/vnd.cyclonedx+xml: + schema: + type: string + description: Dependency metadata for a specific component in CycloneDX format + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns dependency metadata for a specific component in CycloneDX format + tags: + - bom + /v1/bom/cyclonedx/project/{uuid}: + get: + description: | +

Requires permission VIEW_PORTFOLIO

+

+ The withVulnerabilities and vdr variants + further require any of the following permissions: +

    +
  • VIEW_VULNERABILITY
    • +
  • VULNERABILITY_ANALYSIS
    • +
  • VULNERABILITY_ANALYSIS_READ
    • +
+

+ operationId: exportProjectAsCycloneDx + parameters: + - description: The UUID of the project to export + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The format to output (defaults to JSON) + in: query + name: format + schema: + type: string + - description: Specifies the CycloneDX variant to export. Value options are + 'inventory' and 'withVulnerabilities'. (defaults to 'inventory') + in: query + name: variant + schema: + type: string + - description: Force the resulting BOM to be downloaded as a file (defaults + to 'false') + in: query + name: download + schema: + type: boolean + - description: "The CycloneDX Spec variant exported (defaults to: '1.5')" + in: query + name: version + schema: + type: string + responses: + "200": + content: + application/octet-stream: + schema: + type: string + application/vnd.cyclonedx+json: + schema: + type: string + application/vnd.cyclonedx+xml: + schema: + type: string + description: Dependency metadata for a project in CycloneDX format + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns dependency metadata for a project in CycloneDX format + tags: + - bom + /v1/calculator/cvss: + get: + operationId: getCvssScores + parameters: + - description: A valid CVSSv2 or CVSSv3 vector + in: query + name: vector + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Score" + description: The calculated scores + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns the CVSS base score, impact sub-score and exploitability sub-score" + tags: + - calculator + /v1/calculator/owasp: + get: + operationId: getOwaspRRScores + parameters: + - description: A valid OWASP Risk Rating vector + in: query + name: vector + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Score" + description: The calculated scores + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns the OWASP Risk Rating likelihood score, technical impact score\ + \ and business impact score" + tags: + - calculator + /v1/component: + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: updateComponent + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Component" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Component" + description: The updated component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a component + tags: + - component + /v1/component/hash/{hash}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentByHash + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: "The MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384,\ + \ SHA3-512, BLAKE2b-256, BLAKE2b-384, BLAKE2b-512, or BLAKE3 hash of the\ + \ component to retrieve" + in: path + name: hash + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Component" + description: A list of components that have the specified hash value + headers: + X-Total-Count: + description: The total number of components + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of components that have the specified hash value + tags: + - component + /v1/component/identity: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentByIdentity + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The group of the component + in: query + name: group + schema: + type: string + - description: The name of the component + in: query + name: name + schema: + type: string + - description: The version of the component + in: query + name: version + schema: + type: string + - description: The purl of the component + in: query + name: purl + schema: + type: string + - description: The cpe of the component + in: query + name: cpe + schema: + type: string + - description: The swidTagId of the component + in: query + name: swidTagId + schema: + type: string + - description: The project the component belongs to + in: query + name: project + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Component" + description: A list of components that have the specified component identity + headers: + X-Total-Count: + description: The total number of components + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns a list of components that have the specified component identity.\ + \ This resource accepts coordinates (group, name, version) or purl, cpe, or\ + \ swidTagId" + tags: + - component + /v1/component/internal/identify: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: identifyInternalComponents + responses: + "204": + description: Identification requested successfully + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Requests the identification of internal components in the portfolio + tags: + - component + /v1/component/project/{projectUuid}/dependencyGraph/{componentUuids}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getDependencyGraphForComponent + parameters: + - description: The UUID of the project to get the expanded dependency graph + for + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + - description: List of UUIDs of the components (separated by |) to get the expanded + dependency graph for + in: path + name: componentUuids + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: object + description: The expanded dependency graph to every occurrence of a component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: |- + - The UUID of the project could not be found + - The UUID of the component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the expanded dependency graph to every occurrence of a component + tags: + - component + /v1/component/project/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getAllComponents + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project to retrieve components for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally exclude recent components so only outdated components + are returned + in: query + name: onlyOutdated + schema: + type: boolean + - description: Optionally exclude transitive dependencies so only direct dependencies + are returned + in: query + name: onlyDirect + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Component" + description: A list of all components for a given project + headers: + X-Total-Count: + description: The total number of components + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all components for a given project + tags: + - component + put: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: createComponent + parameters: + - description: The UUID of the project to create a component for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Component" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Component" + description: The created component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new component + tags: + - component + /v1/component/{uuid}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT

+ operationId: deleteComponent + parameters: + - description: The UUID of the component to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Component removed successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a component + tags: + - component + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentByUuid + parameters: + - description: The UUID of the component to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes third-party metadata about the component + from external repositories + in: query + name: includeRepositoryMetaData + schema: + type: boolean + - in: query + name: includeIntegrityMetaData + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Component" + description: A component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific component + tags: + - component + /v1/component/{uuid}/occurrence: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getOccurrences + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ComponentOccurrence" + description: The occurrences of a component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the occurrences of a component + tags: + - component + /v1/component/{uuid}/property: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProperties + parameters: + - description: The UUID of the component to retrieve properties for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ComponentProperty" + description: A list of all properties for the specified component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all properties for the specified component + tags: + - componentProperty + put: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_CREATE

+ operationId: createProperty + parameters: + - description: The UUID of the component to create a property for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ComponentProperty" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/ComponentProperty" + description: The created component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component could not be found + "409": + description: A property with the specified component/group/name combination + already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new component property + tags: + - componentProperty + /v1/component/{uuid}/property/{propertyUuid}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: deleteProperty + parameters: + - description: The UUID of the component to delete a property from + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the component property to delete + in: path + name: propertyUuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Property removed successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component or component property could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a config property + tags: + - componentProperty + /v1/configProperty: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getConfigProperties + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ConfigProperty" + description: A list of all ConfigProperties for the specified groupName + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all ConfigProperties for the specified groupName + tags: + - configProperty + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: updateConfigProperty + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConfigProperty" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConfigProperty" + description: The updated config property + "401": + description: Unauthorized + "404": + description: The config property could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a config property + tags: + - configProperty + /v1/configProperty/aggregate: + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: updateConfigProperty_1 + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ConfigProperty" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ConfigProperty" + description: The updated config properties + "401": + description: Unauthorized + "404": + description: One or more config properties could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates an array of config properties + tags: + - configProperty + /v1/configProperty/public/{groupName}/{propertyName}: + get: + description:

+ operationId: getPublicConfigProperty + parameters: + - description: The group name of the value to retrieve + in: path + name: groupName + required: true + schema: + type: string + - description: The property name of the value to retrieve + in: path + name: propertyName + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConfigProperty" + description: Public ConfigProperty returned + "403": + description: This is not a public visible ConfigProperty + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a public ConfigProperty + tags: + - configProperty + /v1/cwe: + get: + description: Returns a list of all CWEs + operationId: getCwes + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Cwe" + description: A list of all CWEs + headers: + X-Total-Count: + description: The total number of CWEs + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + tags: + - cwe + /v1/cwe/{cweId}: + get: + operationId: getCwe + parameters: + - description: The CWE ID of the CWE to retrieve + in: path + name: cweId + required: true + schema: + type: integer + format: int32 + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Cwe" + description: A CWE matching the provided ID + "401": + description: Unauthorized + "404": + description: The CWE could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific CWE + tags: + - cwe + /v1/dependencyGraph/component/{uuid}/directDependencies: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentsAndServicesByComponentUuid + parameters: + - description: The UUID of the component + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DependencyGraphResponse" + description: A list of specific components and services from component UUID + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: Any component can be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of specific components and services from component UUID + tags: + - dependencyGraph + /v1/dependencyGraph/project/{uuid}/directDependencies: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentsAndServicesByProjectUuid + parameters: + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DependencyGraphResponse" + description: A list of specific components and services from project UUID + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: Any component can be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of specific components and services from project UUID + tags: + - dependencyGraph + /v1/event/token/{uuid}: + get: + description: |- +

+ This endpoint is intended to be used in conjunction with other API calls which return a token for asynchronous tasks. + The token can then be queried using this endpoint to determine if the task is complete: +

    +
  • A value of true indicates processing is occurring.
    • +
  • A value of false indicates that no processing is occurring for the specified token.
    • +
+ However, a value of false also does not confirm the token is valid, + only that no processing is associated with the specified token. +

+ operationId: isTokenBeingProcessed + parameters: + - description: The UUID of the token to query + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/IsTokenBeingProcessedResponse" + description: The processing status of the provided token + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Determines if there are any tasks associated with the token that are\ + \ being processed, or in the queue to be processed." + tags: + - event + /v1/finding: + get: + description:

Requires permission VIEW_VULNERABILITY

+ operationId: getAllFindings_1 + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Show inactive projects + in: query + name: showInactive + schema: + type: boolean + - description: Show suppressed findings + in: query + name: showSuppressed + schema: + type: boolean + - description: Filter by severity + in: query + name: severity + schema: + type: string + - description: Filter by analysis status + in: query + name: analysisStatus + schema: + type: string + - description: Filter by vendor response + in: query + name: vendorResponse + schema: + type: string + - description: Filter published from this date + in: query + name: publishDateFrom + schema: + type: string + - description: Filter published to this date + in: query + name: publishDateTo + schema: + type: string + - description: Filter attributed on from this date + in: query + name: attributedOnDateFrom + schema: + type: string + - description: Filter attributed on to this date + in: query + name: attributedOnDateTo + schema: + type: string + - description: Filter the text input in these fields + in: query + name: textSearchField + schema: + type: string + - description: Filter by this text input + in: query + name: textSearchInput + schema: + type: string + - description: Filter CVSSv2 from this value + in: query + name: cvssv2From + schema: + type: string + - description: Filter CVSSv2 from this Value + in: query + name: cvssv2To + schema: + type: string + - description: Filter CVSSv3 from this value + in: query + name: cvssv3From + schema: + type: string + - description: Filter CVSSv3 from this Value + in: query + name: cvssv3To + schema: + type: string + - description: Filter EPSS from this value + in: query + name: epssFrom + schema: + type: string + - description: Filter EPSS to this value + in: query + name: epssTo + schema: + type: string + - description: Filter EPSS Percentile from this value + in: query + name: epssPercentileFrom + schema: + type: string + - description: Filter EPSS Percentile to this value + in: query + name: epssPercentileTo + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Finding" + description: A list of all findings + headers: + X-Total-Count: + description: The total number of findings + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all findings + tags: + - finding + /v1/finding/grouped: + get: + description:

Requires permission VIEW_VULNERABILITY

+ operationId: getAllFindings + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Show inactive projects + in: query + name: showInactive + schema: + type: boolean + - description: Filter by severity + in: query + name: severity + schema: + type: string + - description: Filter published from this date + in: query + name: publishDateFrom + schema: + type: string + - description: Filter published to this date + in: query + name: publishDateTo + schema: + type: string + - description: Filter the text input in these fields + in: query + name: textSearchField + schema: + type: string + - description: Filter by this text input + in: query + name: textSearchInput + schema: + type: string + - description: Filter CVSSv2 from this value + in: query + name: cvssv2From + schema: + type: string + - description: Filter CVSSv2 to this value + in: query + name: cvssv2To + schema: + type: string + - description: Filter CVSSv3 from this value + in: query + name: cvssv3From + schema: + type: string + - description: Filter CVSSv3 to this value + in: query + name: cvssv3To + schema: + type: string + - description: Filter EPSS from this value + in: query + name: epssFrom + schema: + type: string + - description: Filter EPSS to this value + in: query + name: epssTo + schema: + type: string + - description: Filter EPSS Percentile from this value + in: query + name: epssPercentileFrom + schema: + type: string + - description: Filter EPSS Percentile to this value + in: query + name: epssPercentileTo + schema: + type: string + - description: Filter occurrences in projects from this value + in: query + name: occurrencesFrom + schema: + type: string + - description: Filter occurrences in projects to this value + in: query + name: occurrencesTo + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Finding" + description: A list of all findings grouped by vulnerability + headers: + X-Total-Count: + description: The total number of findings + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all findings grouped by vulnerability + tags: + - finding + /v1/finding/portfolio/analyze: + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: analyzePortfolio + responses: + "200": + description: Analysis triggered successfully + "304": + description: Analysis is already in progress + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Triggers Vulnerability Analysis for the entire portfolio + tags: + - finding + /v1/finding/project/{uuid}: + get: + description:

Requires permission VIEW_VULNERABILITY

+ operationId: getFindingsByProject + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes suppressed findings + in: query + name: suppressed + schema: + type: boolean + - description: Optionally limit findings to specific sources of vulnerability + intelligence + in: query + name: source + schema: + type: string + enum: + - NVD + - NPM + - GITHUB + - VULNDB + - OSSINDEX + - RETIREJS + - INTERNAL + - OSV + - SNYK + - CSAF + - in: header + name: accept + schema: + type: string + - description: Whether to include only projects with existing analysis. + in: query + name: hasAnalysis + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Finding" + application/sarif+json: + schema: + type: string + description: "A list of all findings for a specific project, or a SARIF\ + \ file" + headers: + X-Total-Count: + description: The total number of findings + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns a list of all findings for a specific project or generates\ + \ SARIF file if Accept: application/sarif+json header is provided" + tags: + - finding + /v1/finding/project/{uuid}/analyze: + post: + description:

Requires permission VULNERABILITY_ANALYSIS

+ operationId: analyzeProject + parameters: + - description: The UUID of the project to analyze + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking analysis progress + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Triggers Vulnerability Analysis on a specific project + tags: + - finding + /v1/finding/project/{uuid}/export: + get: + description:

Requires permission VIEW_VULNERABILITY

+ operationId: exportFindingsByProject + parameters: + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: string + description: The findings for the specified project as FPF + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the findings for the specified project as FPF + tags: + - finding + /v1/ldap/groups: + get: + description: |- +

+ This API performs a pass-through query to the configured LDAP server. + Search criteria results are cached using default Alpine CacheManager policy. +

+

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: retrieveLdapGroups + responses: + "200": + content: + application/json: + schema: + type: array + items: + type: string + description: DNs of all accessible groups within the directory + headers: + X-Total-Count: + description: The total number of ldap groups that match the specified + search criteria + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the DNs of all accessible groups within the directory + tags: + - ldap + /v1/ldap/mapping: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: addMapping_1 + requestBody: + content: + '*/*': + schema: + $ref: "#/components/schemas/MappedLdapGroupRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/MappedLdapGroup" + description: The created mapping + "401": + description: Unauthorized + "404": + description: The UUID of the team could not be found + "409": + description: A mapping with the same team and dn already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds a mapping + tags: + - ldap + /v1/ldap/mapping/{uuid}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteMapping_1 + parameters: + - description: The UUID of the mapping to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Mapping removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the mapping could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes a mapping + tags: + - ldap + /v1/ldap/team/{uuid}: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: retrieveLdapGroups_1 + parameters: + - description: The UUID of the team to retrieve mappings for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/MappedLdapGroup" + description: DNs of all groups mapped to the specified team + "401": + description: Unauthorized + "404": + description: The UUID of the team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the DNs of all groups mapped to the specified team + tags: + - ldap + /v1/license: + get: + operationId: getLicenses + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/License" + description: A list of all licenses with complete metadata for each license + headers: + X-Total-Count: + description: The total number of licenses + schema: + format: integeger + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all licenses with complete metadata for each license + tags: + - license + put: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: createLicense + requestBody: + content: + '*/*': + schema: + $ref: "#/components/schemas/License" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/License" + description: The created license + "401": + description: Unauthorized + "409": + description: A license with the specified ID already exists. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new custom license + tags: + - license + /v1/license/concise: + get: + operationId: getLicenseListing + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/License" + description: A concise listing of all licenses + headers: + X-Total-Count: + description: The total number of licenses + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a concise listing of all licenses + tags: + - license + /v1/license/{licenseId}: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: deleteLicense + parameters: + - description: The SPDX License ID of the license to delete + in: path + name: licenseId + required: true + schema: + type: string + responses: + "204": + description: License removed successfully + "401": + description: Unauthorized + "404": + description: The license could not be found + "409": + description: Only custom licenses can be deleted. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a custom license + tags: + - license + get: + operationId: getLicense + parameters: + - description: The SPDX License ID of the license to retrieve + in: path + name: licenseId + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/License" + description: A specific license + "401": + description: Unauthorized + "404": + description: The license could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific license + tags: + - license + /v1/licenseGroup: + get: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

+ operationId: getLicenseGroups + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/LicenseGroup" + description: A list of all license groups + headers: + X-Total-Count: + description: The total number of license groups + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all license groups + tags: + - licenseGroup + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: updateLicenseGroup + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + description: The updated license group + "401": + description: Unauthorized + "404": + description: The license group could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a license group + tags: + - licenseGroup + put: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_CREATE

+ operationId: createLicenseGroup + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + description: The created license group + "401": + description: Unauthorized + "409": + description: A license group with the specified name already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new license group + tags: + - licenseGroup + /v1/licenseGroup/{uuid}: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

+ operationId: deleteLicenseGroup + parameters: + - description: The UUID of the license group to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: License group removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the license group could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a license group + tags: + - licenseGroup + get: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

+ operationId: getLicenseGroup + parameters: + - description: The UUID of the license group to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + description: A specific license group + "401": + description: Unauthorized + "404": + description: The license group could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific license group + tags: + - licenseGroup + /v1/licenseGroup/{uuid}/license/{licenseUuid}: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: removeLicenseFromLicenseGroup + parameters: + - description: A valid license group + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: A valid license + in: path + name: licenseUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + description: The updated license group + "304": + description: The license is not a member with the license group + "401": + description: Unauthorized + "404": + description: The license group or license could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes the license from the license group. + tags: + - licenseGroup + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: addLicenseToLicenseGroup + parameters: + - description: A valid license group + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: A valid license + in: path + name: licenseUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/LicenseGroup" + description: The updated license group + "304": + description: The license group already has the specified license assigned + "401": + description: Unauthorized + "404": + description: The license group or license could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds the license to the specified license group. + tags: + - licenseGroup + /v1/metrics/component/{uuid}/current: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentCurrentMetrics + parameters: + - description: The UUID of the component to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DependencyMetrics" + description: Current metrics for a specific component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested component is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns current metrics for a specific component + tags: + - metrics + /v1/metrics/component/{uuid}/days/{days}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentMetricsXDays + parameters: + - description: The UUID of the component to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The number of days back to retrieve metrics for + in: path + name: days + required: true + schema: + type: integer + format: int32 + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DependencyMetrics" + description: X days of historical metrics for a specific component + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested component is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns X days of historical metrics for a specific component + tags: + - metrics + /v1/metrics/component/{uuid}/refresh: + get: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: RefreshComponentMetrics + parameters: + - description: The UUID of the component to refresh metrics on + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Refresh requested successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested component is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Requests a refresh of a specific components metrics + tags: + - metrics + /v1/metrics/component/{uuid}/since/{date}: + get: + description: |- +

Date format must be YYYYMMDD

+

Requires permission VIEW_PORTFOLIO

+ operationId: getComponentMetricsSince + parameters: + - description: The UUID of the component to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The start date to retrieve metrics for + in: path + name: date + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DependencyMetrics" + description: Historical metrics for a specific component from a specific + date + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested component is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns historical metrics for a specific component from a specific + date + tags: + - metrics + /v1/metrics/portfolio/current: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getPortfolioCurrentMetrics + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PortfolioMetrics" + description: Current metrics for the entire portfolio + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns current metrics for the entire portfolio + tags: + - metrics + /v1/metrics/portfolio/refresh: + get: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: RefreshPortfolioMetrics + responses: + "200": + description: Refresh requested successfully + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Requests a refresh of the portfolio metrics + tags: + - metrics + /v1/metrics/portfolio/since/{date}: + get: + description: |- +

Date format must be YYYYMMDD

+

Requires permission VIEW_PORTFOLIO

+ operationId: getPortfolioMetricsSince + parameters: + - description: The start date to retrieve metrics for + in: path + name: date + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/PortfolioMetrics" + description: Historical metrics for the entire portfolio from a specific + date + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns historical metrics for the entire portfolio from a specific + date + tags: + - metrics + /v1/metrics/portfolio/{days}/days: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getPortfolioMetricsXDays + parameters: + - description: The number of days back to retrieve metrics for + in: path + name: days + required: true + schema: + type: integer + format: int32 + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/PortfolioMetrics" + description: X days of historical metrics for the entire portfolio + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns X days of historical metrics for the entire portfolio + tags: + - metrics + /v1/metrics/project/{uuid}/current: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectCurrentMetrics + parameters: + - description: The UUID of the project to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectMetrics" + description: Current metrics for a specific project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns current metrics for a specific project + tags: + - metrics + /v1/metrics/project/{uuid}/days/{days}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectMetricsXDays + parameters: + - description: The UUID of the project to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The number of days back to retrieve metrics for + in: path + name: days + required: true + schema: + type: integer + format: int32 + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ProjectMetrics" + description: X days of historical metrics for a specific project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns X days of historical metrics for a specific project + tags: + - metrics + /v1/metrics/project/{uuid}/refresh: + get: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: RefreshProjectMetrics + parameters: + - description: The UUID of the project to refresh metrics on + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Refresh requested successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Requests a refresh of a specific projects metrics + tags: + - metrics + /v1/metrics/project/{uuid}/since/{date}: + get: + description: |- +

Date format must be YYYYMMDD

+

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectMetricsSince + parameters: + - description: The UUID of the project to retrieve metrics for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The start date to retrieve metrics for + in: path + name: date + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ProjectMetrics" + description: Historical metrics for a specific project from a specific date + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns historical metrics for a specific project from a specific date + tags: + - metrics + /v1/metrics/vulnerability: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getVulnerabilityMetrics + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/VulnerabilityMetrics" + description: The sum of all vulnerabilities in the database by year and + month + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the sum of all vulnerabilities in the database by year and + month + tags: + - metrics + /v1/notification/publisher: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getAllNotificationPublishers + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/NotificationPublisher" + description: A list of all notification publishers + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all notification publishers + tags: + - notification + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: updateNotificationPublisher + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateNotificationPublisherRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationPublisher" + description: The updated notification publisher + "400": + description: Invalid notification class or trying to modify a default publisher + "401": + description: Unauthorized + "404": + description: The notification publisher could not be found + "409": + description: Conflict with an existing publisher's name + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a notification publisher + tags: + - notification + put: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: createNotificationPublisher + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateNotificationPublisherRequest" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationPublisher" + description: The created notification publisher + "400": + description: Invalid notification class or trying to modify a default publisher + "401": + description: Unauthorized + "409": + description: Conflict with an existing publisher's name + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new notification publisher + tags: + - notification + /v1/notification/publisher/test/{uuid}: + post: + description:

Requires permission SYSTEM_CONFIGURATION

+ operationId: testNotificationRule + parameters: + - description: The UUID of the rule to test + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Test notification dispatched successfully + "401": + description: Unauthorized + "404": + description: Notification rule not found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Dispatches a rule notification test + tags: + - notification + /v1/notification/publisher/{notificationPublisherUuid}: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: deleteNotificationPublisher + parameters: + - description: The UUID of the notification publisher to delete + in: path + name: notificationPublisherUuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Notification publisher removed successfully + "400": + description: Deleting a default notification publisher is forbidden + "401": + description: Unauthorized + "404": + description: The UUID of the notification publisher could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a notification publisher and all related notification rules + tags: + - notification + /v1/notification/publisher/{uuid}/configSchema: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getNotificationPublisherConfigSchema + parameters: + - in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: string + additionalProperties: true + description: Publisher config JSON schema + "204": + description: Publisher has no configuration + "401": + description: Unauthorized + "404": + description: The UUID of the notification publisher could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Get notification publisher config schema + tags: + - notification + /v1/notification/rule: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: deleteNotificationRule + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + responses: + "204": + description: Notification rule removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the notification rule could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a notification rule + tags: + - notification + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getAllNotificationRules + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The notification trigger type to filter on + in: query + name: triggerType + schema: + type: string + enum: + - EVENT + - SCHEDULE + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/NotificationRule" + description: A list of all notification rules + headers: + X-Total-Count: + description: The total number of notification rules + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all notification rules + tags: + - notification + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: updateNotificationRule + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateNotificationRuleRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The updated notification rule + "400": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/InvalidNotificationFilterExpressionProblemDetails" + description: Invalid filter expression + "401": + description: Unauthorized + "404": + description: The UUID of the notification rule could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a notification rule + tags: + - notification + put: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: createNotificationRule + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateNotificationRuleRequest" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The created notification rule + "401": + description: Unauthorized + "404": + description: The UUID of the notification publisher could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new notification rule + tags: + - notification + /v1/notification/rule/scheduled: + put: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: createScheduledNotificationRule + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateScheduledNotificationRuleRequest" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The created scheduled notification rule + "401": + description: Unauthorized + "404": + description: The UUID of the notification publisher could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new scheduled notification rule + tags: + - notification + /v1/notification/rule/{ruleUuid}/project/{projectUuid}: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: removeProjectFromRule + parameters: + - description: The UUID of the rule to remove the project from + in: path + name: ruleUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to remove from the rule + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The updated notification rule + "304": + description: The rule does not have the specified project assigned + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The notification rule or project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes a project from a notification rule + tags: + - notification + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: addProjectToRule + parameters: + - description: The UUID of the rule to add a project to + in: path + name: ruleUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to add to the rule + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The updated notification rule + "304": + description: The rule already has the specified project assigned + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The notification rule or project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds a project to a notification rule + tags: + - notification + /v1/notification/rule/{ruleUuid}/team/{teamUuid}: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: removeTeamFromRule + parameters: + - description: The UUID of the rule to remove the project from + in: path + name: ruleUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to remove from the rule + in: path + name: teamUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The updated notification rule + "304": + description: The rule does not have the specified team assigned + "401": + description: Unauthorized + "404": + description: The notification rule or team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes a team from a notification rule + tags: + - notification + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: addTeamToRule + parameters: + - description: The UUID of the rule to add a team to + in: path + name: ruleUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the team to add to the rule + in: path + name: teamUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/NotificationRule" + description: The updated notification rule + "304": + description: The rule already has the specified team assigned + "401": + description: Unauthorized + "404": + description: The notification rule or team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds a team to a notification rule + tags: + - notification + /v1/oidc/available: + get: + operationId: isAvailable + responses: + "200": + content: + text/plain: + schema: + type: boolean + description: Whether OpenID Connect is available + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Indicates if OpenID Connect is available for this application + tags: + - oidc + /v1/oidc/group: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: retrieveGroups + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/OidcGroup" + description: A list of all groups + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all groups + tags: + - oidc + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: updateGroup + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OidcGroup" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/OidcGroup" + description: The updated group + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates group + tags: + - oidc + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: createGroup + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OidcGroup" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/OidcGroup" + description: The created group + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates group + tags: + - oidc + /v1/oidc/group/{groupUuid}/team/{teamUuid}/mapping: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteMapping_2 + parameters: + - description: The UUID of the group to delete a mapping for + in: path + name: groupUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the team to delete a mapping for + in: path + name: teamUuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Mapping removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the mapping could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a mapping + tags: + - oidc + /v1/oidc/group/{uuid}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteGroup + parameters: + - description: The UUID of the group to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Group removed successfully + "401": + description: Unauthorized + "404": + description: The group could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a group + tags: + - oidc + /v1/oidc/group/{uuid}/team: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: retrieveTeamsMappedToGroup + parameters: + - description: The UUID of the mapping to retrieve the team for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Team" + description: A list of teams associated with the specified group + "401": + description: Unauthorized + "404": + description: The UUID of the mapping could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of teams associated with the specified group + tags: + - oidc + /v1/oidc/mapping: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: addMapping_2 + requestBody: + content: + '*/*': + schema: + $ref: "#/components/schemas/MappedOidcGroupRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/MappedOidcGroup" + description: The created mapping + "401": + description: Unauthorized + "404": + description: The UUID of the team or group could not be found + "409": + description: A mapping with the same team and group name already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds a mapping + tags: + - oidc + /v1/oidc/mapping/{uuid}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteMappingByUuid + parameters: + - description: The UUID of the mapping to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Mapping removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the mapping could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a mapping + tags: + - oidc + /v1/permission: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getAllPermissions + responses: + "200": + content: + application/json: + schema: + type: string + enum: + - BOM_UPLOAD + - VIEW_PORTFOLIO + - PORTFOLIO_ACCESS_CONTROL_BYPASS + - PORTFOLIO_MANAGEMENT + - PORTFOLIO_MANAGEMENT_CREATE + - PORTFOLIO_MANAGEMENT_READ + - PORTFOLIO_MANAGEMENT_UPDATE + - PORTFOLIO_MANAGEMENT_DELETE + - VIEW_VULNERABILITY + - VULNERABILITY_ANALYSIS + - VULNERABILITY_ANALYSIS_CREATE + - VULNERABILITY_ANALYSIS_READ + - VULNERABILITY_ANALYSIS_UPDATE + - VIEW_POLICY_VIOLATION + - VULNERABILITY_MANAGEMENT + - VULNERABILITY_MANAGEMENT_CREATE + - VULNERABILITY_MANAGEMENT_READ + - VULNERABILITY_MANAGEMENT_UPDATE + - VULNERABILITY_MANAGEMENT_DELETE + - POLICY_VIOLATION_ANALYSIS + - ACCESS_MANAGEMENT + - ACCESS_MANAGEMENT_CREATE + - ACCESS_MANAGEMENT_READ + - ACCESS_MANAGEMENT_UPDATE + - ACCESS_MANAGEMENT_DELETE + - SECRET_MANAGEMENT + - SECRET_MANAGEMENT_CREATE + - SECRET_MANAGEMENT_UPDATE + - SECRET_MANAGEMENT_DELETE + - SYSTEM_CONFIGURATION + - SYSTEM_CONFIGURATION_CREATE + - SYSTEM_CONFIGURATION_READ + - SYSTEM_CONFIGURATION_UPDATE + - SYSTEM_CONFIGURATION_DELETE + - PROJECT_CREATION_UPLOAD + - POLICY_MANAGEMENT + - POLICY_MANAGEMENT_CREATE + - POLICY_MANAGEMENT_READ + - POLICY_MANAGEMENT_UPDATE + - POLICY_MANAGEMENT_DELETE + - TAG_MANAGEMENT + - TAG_MANAGEMENT_DELETE + - VIEW_BADGES + description: A list of all permissions + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all permissions + tags: + - permission + /v1/permission/team: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: setTeamPermissions + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/TeamPermissionsSetRequest" + description: Team UUID and requested permissions + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + description: The updated team + "304": + description: The team already has the specified permission(s) + "400": + description: Bad request + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Replaces a team's permissions with the specified list + tags: + - permission + /v1/permission/user: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: setUserPermissions + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UserPermissionsSetRequest" + description: A username and valid list permission + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user is already has the specified permission(s) + "400": + description: Bad request + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Replaces a users's permissions with the specified list + tags: + - permission + /v1/permission/{permission}/team/{uuid}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: removePermissionFromTeam + parameters: + - description: A valid team uuid + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: A valid permission + in: path + name: permission + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + description: The updated team + "304": + description: The team already has the specified permission assigned + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + tags: + - permission + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: addPermissionToTeam + parameters: + - description: A valid team uuid + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: A valid permission + in: path + name: permission + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + description: The updated team + "304": + description: The team already has the specified permission assigned + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + tags: + - permission + /v1/permission/{permission}/user/{username}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: removePermissionFromUser + parameters: + - description: A valid username + in: path + name: username + required: true + schema: + type: string + - description: A valid permission + in: path + name: permission + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user already has the specified permission assigned + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes the permission from the user. + tags: + - permission + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: addPermissionToUser + parameters: + - description: A valid username + in: path + name: username + required: true + schema: + type: string + - description: A valid permission + in: path + name: permission + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user already has the specified permission assigned + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds the permission to the specified username. + tags: + - permission + /v1/policy: + get: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

+ operationId: getPolicies + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Policy" + description: A list of all policies + headers: + X-Total-Count: + description: The total number of policies + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all policies + tags: + - policy + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: updatePolicy + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + description: The updated policy + "401": + description: Unauthorized + "404": + description: The policy could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a policy + tags: + - policy + put: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_CREATE

+ operationId: createPolicy + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + description: The created policy + "401": + description: Unauthorized + "409": + description: A policy with the specified name already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new policy + tags: + - policy + /v1/policy/condition: + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: updatePolicyCondition + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyCondition" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyCondition" + description: The updated policy condition + "401": + description: Unauthorized + "404": + description: The UUID of the policy condition could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a policy condition + tags: + - policyCondition + /v1/policy/condition/{uuid}: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: deletePolicyCondition + parameters: + - description: The UUID of the policy condition to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Policy condition removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the policy condition could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a policy condition from an existing policy + tags: + - policyCondition + /v1/policy/{policyUuid}/project/{projectUuid}: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

+ operationId: removeProjectFromPolicy + parameters: + - description: The UUID of the policy to remove the project from + in: path + name: policyUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to remove from the policy + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + description: The updated policy + "304": + description: The policy does not have the specified project assigned + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The policy or project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes a project from a policy + tags: + - policy + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: addProjectToPolicy + parameters: + - description: The UUID of the policy to add a project to + in: path + name: policyUuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the project to add to the rule + in: path + name: projectUuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + description: The updated policy + "304": + description: The policy already has the specified project assigned + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The policy or project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds a project to a policy + tags: + - policy + /v1/policy/{uuid}: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

+ operationId: deletePolicy + parameters: + - description: The UUID of the policy to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Policy removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the policy could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a policy + tags: + - policy + get: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

+ operationId: getPolicy + parameters: + - description: The UUID of the policy to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Policy" + description: A specific policy + "401": + description: Unauthorized + "404": + description: The policy could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific policy + tags: + - policy + /v1/policy/{uuid}/condition: + put: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: createPolicyCondition + parameters: + - description: The UUID of the policy + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyCondition" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyCondition" + description: The created policy condition + "401": + description: Unauthorized + "404": + description: The UUID of the policy could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new policy condition for an existing policy + tags: + - policyCondition + /v1/project: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjects + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The optional name of the project to query on + in: query + name: name + schema: + type: string + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + - description: Optionally excludes children projects from being returned + in: query + name: onlyRoot + schema: + type: boolean + - description: The UUID of the team which projects shall be excluded + in: query + name: notAssignedToTeamWithUuid + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all projects + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects + tags: + - project + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: updateProject + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: The updated project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: "Access to the project, the provided parent, or the previous\ + \ latest project version, is forbidden" + "404": + description: The UUID of the project could not be found + "409": + description: |- +
    +
  • An inactive Parent cannot be selected as parent, or
    • +
  • Project cannot be set to inactive if active children are present, or
    • +
  • A project with the specified name already exists, or
    • +
  • A project cannot select itself as a parent
    • +
+ security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a project + tags: + - project + put: + description: |- +

If a parent project exists, parent.uuid is required

+

+ When portfolio access control is enabled, one or more teams to grant access + to can be provided via accessTeams. Either uuid or + name of a team must be specified. Only teams which the authenticated + principal is a member of can be assigned. Principals with ACCESS_MANAGEMENT + permission can assign any team. +

+

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_CREATE

+ operationId: createProject + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: The created project + "400": + description: Bad Request + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: "Access to the provided parent project, or previous latest\ + \ project version, is forbidden" + "409": + description: |- +
    +
  • An inactive Parent cannot be selected as parent, or
    • +
  • A project with the specified name already exists
    • +
+ security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new project + tags: + - project + /v1/project/batchDelete: + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: deleteProjects + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxItems: 1000 + minItems: 1 + uniqueItems: true + responses: + "204": + description: Projects removed successfully + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a list of projects specified by their UUIDs + tags: + - project + /v1/project/classifier/{classifier}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectsByClassifier + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The classifier to query on + in: path + name: classifier + required: true + schema: + type: string + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + - description: Optionally excludes children projects from being returned + in: query + name: onlyRoot + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all projects by classifier + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects by classifier + tags: + - project + /v1/project/clone: + put: + deprecated: true + description: |- +

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_CREATE

+

Deprecated! Use /api/v2/projects/{uuid}/clone instead.

+ operationId: cloneProject + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CloneProjectRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking cloning progress + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: "Access to the requested project, or the previous latest project\ + \ version, is forbidden" + "404": + description: The UUID of the project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Clones a project + tags: + - project + /v1/project/concise: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectsConcise + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name to filter on. Must be exact match. + in: query + name: name + schema: + type: string + - description: Version to filter on. Must be exact match. + in: query + name: version + schema: + type: string + - description: Classifier to filter on. Must be exact match. + in: query + name: classifier + schema: + type: string + - description: Tag to filter on. Must be exact match. + in: query + name: tag + schema: + type: string + - description: Team to filter on. Must be exact match. + in: query + name: team + schema: + type: string + - description: "Whether to show only active, or only inactive projects." + in: query + name: active + schema: + type: boolean + - description: "Whether to show only root projects, i.e. those without a parent." + in: query + name: onlyRoot + schema: + type: boolean + - description: Whether to include metrics in the response. + in: query + name: includeMetrics + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ConciseProject" + description: A list of all projects in concise representation + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns a list of all projects, in a concise representation." + tags: + - project + /v1/project/concise/{uuid}/children: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectChildrenConcise + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: UUID of the project + in: path + name: uuid + required: true + schema: + type: string + - description: Name to filter on. Must be exact match. + in: query + name: name + schema: + type: string + - description: Version to filter on. Must be exact match. + in: query + name: version + schema: + type: string + - description: Classifier to filter on. Must be exact match. + in: query + name: classifier + schema: + type: string + - description: Tag to filter on. Must be exact match. + in: query + name: tag + schema: + type: string + - description: Team to filter on. Must be exact match. + in: query + name: team + schema: + type: string + - description: "Whether to show only active, or only inactive projects. Omitting\ + \ the filter will show both." + in: query + name: active + schema: + type: boolean + - description: Whether to include metrics in the response. + in: query + name: includeMetrics + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ConciseProject" + description: A list of all child projects in a concise representation + headers: + X-Total-Count: + description: The total number of child projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Returns a list of a given project's children, in a concise representation." + tags: + - project + /v1/project/latest/{name}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getLatestProjectByName + parameters: + - description: The name of the project to retrieve the latest version of + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: The latest version of the specified project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the latest version of a project by its name + tags: + - project + /v1/project/lookup: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectByNameAndVersion + parameters: + - description: The name of the project to query on + in: query + name: name + required: true + schema: + type: string + - description: The version of the project to query on + in: query + name: version + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: A specific project by its name and version + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific project by its name and version + tags: + - project + /v1/project/tag/{tag}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectsByTag + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The tag to query on + in: path + name: tag + required: true + schema: + type: string + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + - description: Optionally excludes children projects from being returned + in: query + name: onlyRoot + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all projects by tag + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects by tag + tags: + - project + /v1/project/withoutDescendantsOf/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProjectsWithoutDescendantsOf + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project which descendants will be excluded + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The optional name of the project to query on + in: query + name: name + schema: + type: string + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all projects without the descendants of the selected + project + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects without the descendants of the selected + project + tags: + - project + /v1/project/{uuid}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: deleteProject + parameters: + - description: The UUID of the project to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Project removed successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the project could not be found + "500": + description: Unable to delete components of the project + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a project + tags: + - project + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getProject + parameters: + - description: The UUID of the project to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: A specific project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific project + tags: + - project + patch: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: patchProject + parameters: + - description: The UUID of the project to modify + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + description: The updated project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: "Access to the requested project, the provided parent, or the\ + \ previous latest project version, is forbidden" + "404": + description: The UUID of the project could not be found + "409": + description: |- +
    +
  • An inactive Parent cannot be selected as parent, or
    • +
  • Project cannot be set to inactive if active children are present, or
    • +
  • A project with the specified name already exists, or
    • +
  • A project cannot select itself as a parent
    • +
+ security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Partially updates a project + tags: + - project + /v1/project/{uuid}/children: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getChildrenProjects + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project to get the children from + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all children for a project + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all children for a project + tags: + - project + /v1/project/{uuid}/children/classifier/{classifier}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getChildrenProjectsByClassifier + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The classifier to query on + in: path + name: classifier + required: true + schema: + type: string + - description: The UUID of the project to get the children from + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all children for a project by classifier + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all children for a project by classifier + tags: + - project + /v1/project/{uuid}/children/tag/{tag}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getChildrenProjectsByTag + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The tag to query on + in: path + name: tag + required: true + schema: + type: string + - description: The UUID of the project to get the children from + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + description: A list of all children for a project by tag + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all children for a project by tag + tags: + - project + /v1/project/{uuid}/property: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: deleteProperty_1 + parameters: + - description: The UUID of the project to delete a property from + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectProperty" + responses: + "204": + description: Project property removed successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project or project property could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a config property + tags: + - projectProperty + get: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_READ

+ operationId: getProperties_1 + parameters: + - description: The UUID of the project to retrieve properties for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ProjectProperty" + description: A list of all ProjectProperties for the specified project + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all ProjectProperties for the specified project + tags: + - projectProperty + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: updateProperty + parameters: + - description: The UUID of the project to create a property for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectProperty" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectProperty" + description: The updated project property + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a project property + tags: + - projectProperty + put: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_CREATE

+ operationId: createProperty_1 + parameters: + - description: The UUID of the project to create a property for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectProperty" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectProperty" + description: The created project property + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + "409": + description: A property with the specified project/group/name combination + already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new project property + tags: + - projectProperty + /v1/repository: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getRepositories + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Repository" + description: A list of all repositories + headers: + X-Total-Count: + description: The total number of repositories + schema: + type: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all repositories + tags: + - repository + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: updateRepository + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Repository" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Repository" + description: The updated repository + "401": + description: Unauthorized + "404": + description: The UUID of the repository could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a repository + tags: + - repository + put: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_CREATE

+ operationId: createRepository + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Repository" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Repository" + description: The created repository + "401": + description: Unauthorized + "409": + description: A repository with the specified identifier already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new repository + tags: + - repository + /v1/repository/latest: + get: + operationId: getRepositoryMetaComponent + parameters: + - description: The Package URL for the component to query + in: query + name: purl + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/RepositoryMetaComponent" + description: The latest version of the component available in the configured + repositories + "204": + description: "The request was successful, but no repositories are configured\ + \ to support the specified Package URL" + "400": + description: The specified Package URL is invalid and not in the correct + format + "401": + description: Unauthorized + "404": + description: The repository metadata for the specified component cannot + be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Attempts to resolve the latest version of the component available in + the configured repositories + tags: + - repository + /v1/repository/{type}: + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getRepositoriesByType + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The type of repositories to retrieve + in: path + name: type + required: true + schema: + type: string + enum: + - MAVEN + - NPM + - GEM + - PYPI + - NUGET + - HEX + - COMPOSER + - CARGO + - GO_MODULES + - CPAN + - GITHUB + - HACKAGE + - NIXPKGS + - UNSUPPORTED + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Repository" + description: A list of repositories that support the provided type + headers: + X-Total-Count: + description: The total number of repositories + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns repositories that support the specific type + tags: + - repository + /v1/repository/{uuid}: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_DELETE

+ operationId: deleteRepository + parameters: + - description: The UUID of the repository to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Repository removed successfully + "401": + description: Unauthorized + "404": + description: The UUID of the repository could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a repository + tags: + - repository + /v1/service: + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: updateService + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceComponent" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceComponent" + description: The updated service + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the service could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a service + tags: + - service + /v1/service/project/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getAllServices + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ServiceComponent" + description: A list of all services for a given project + headers: + X-Total-Count: + description: The total number of services + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all services for a given project + tags: + - service + put: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_CREATE

+ operationId: createService + parameters: + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceComponent" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceComponent" + description: The created service + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new service + tags: + - service + /v1/service/{uuid}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: deleteService + parameters: + - description: The UUID of the service to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Service removed successfully + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The UUID of the service could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a service + tags: + - service + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getServiceByUuid + parameters: + - description: The UUID of the service to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceComponent" + description: A specific service + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The service could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific service + tags: + - service + /v1/tag: + delete: + description: | +

A tag can only be deleted if no projects or policies are assigned to it.

+

+ Principals with PORTFOLIO_MANAGEMENT permission, and access + to all assigned projects (if portfolio ACL is enabled), can delete + a tag with assigned projects. +

+

+ Principals with POLICY_MANAGEMENT permission can delete tags + with assigned policies. +

+

Requires permission TAG_MANAGEMENT or TAG_MANAGEMENT_DELETE

+ operationId: deleteTags + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + maxItems: 100 + minItems: 1 + uniqueItems: true + description: Names of the tags to delete + responses: + "204": + description: Tags deleted successfully. + "400": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/TagOperationProblemDetails" + description: Operation failed + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes one or more tags. + tags: + - tag + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getAllTags + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TagListResponseItem" + description: A list of all tags + headers: + X-Total-Count: + description: The total number of tags + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all tags + tags: + - tag + put: + description:

Requires permission TAG_MANAGEMENT

+ operationId: createTags + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + maxItems: 100 + minItems: 1 + uniqueItems: true + description: Names of the tags to create + required: true + responses: + "201": + description: Tags created successfully. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates one or more tags. + tags: + - tag + /v1/tag/policy/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getTagsForPolicy + parameters: + - description: The UUID of the policy + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Tag" + description: A list of all tags associated with a given policy + headers: + X-Total-Count: + description: The total number of tags + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all tags associated with a given policy + tags: + - tag + /v1/tag/{name}/collectionProject: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getTaggedCollectionProjects + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name of the tag to get collection projects for + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TaggedCollectionProjectListResponseItem" + description: A list of all collection projects that use the given tag for + their collection logic + headers: + X-Total-Count: + description: The total number of collection projects + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all collection projects that use the given tag for + their collection logic. + tags: + - tag + /v1/tag/{name}/notificationRule: + delete: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: untagNotificationRules + parameters: + - description: Name of the tag + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of notification rules to untag + required: true + responses: + "204": + description: Notification rules untagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Untags one or more notification rules. + tags: + - tag + get: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_READ

+ operationId: getTaggedNotificationRules + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name of the tag to get notification rules for + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TaggedPolicyListResponseItem" + description: A list of all notification rules assigned to the given tag + headers: + X-Total-Count: + description: The total number of notification rules + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all notification rules assigned to the given tag. + tags: + - tag + post: + description:

Requires permission SYSTEM_CONFIGURATION or + SYSTEM_CONFIGURATION_UPDATE

+ operationId: tagNotificationRules + parameters: + - description: Name of the tag to assign + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of notification rules to tag + required: true + responses: + "204": + description: Notification rules tagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Tags one or more notification rules. + tags: + - tag + /v1/tag/{name}/policy: + delete: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: untagPolicies + parameters: + - description: Name of the tag + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of policies to untag + required: true + responses: + "204": + description: Policies untagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Untags one or more policies. + tags: + - tag + get: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

+ operationId: getTaggedPolicies + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name of the tag to get policies for. + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TaggedPolicyListResponseItem" + description: A list of all policies assigned to the given tag + headers: + X-Total-Count: + description: The total number of policies + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all policies assigned to the given tag. + tags: + - tag + post: + description:

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

+ operationId: tagPolicies + parameters: + - description: Name of the tag to assign + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of policies to tag + required: true + responses: + "204": + description: Policies tagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Tags one or more policies. + tags: + - tag + /v1/tag/{name}/project: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: untagProjects + parameters: + - description: Name of the tag + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of projects to untag + required: true + responses: + "204": + description: Projects untagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Untags one or more projects. + tags: + - tag + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getTaggedProjects + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name of the tag to get projects for. + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TaggedProjectListResponseItem" + description: A list of all projects assigned to the given tag + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects assigned to the given tag. + tags: + - tag + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: tagProjects + parameters: + - description: Name of the tag to assign + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of projects to tag + required: true + responses: + "204": + description: Projects tagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Tags one or more projects. + tags: + - tag + /v1/tag/{name}/vulnerability: + delete: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_UPDATE

+ operationId: untagVulnerabilities + parameters: + - description: Name of the tag + in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + format: uuid + maxLength: 100 + minLength: 1 + maxItems: 100 + minItems: 1 + description: UUIDs of vulnerabilities to untag + required: true + responses: + "204": + description: Vulnerabilities untagged successfully. + "404": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: A tag with the provided name does not exist. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Untags one or more vulnerabilities. + tags: + - tag + get: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_READ

+ operationId: getTaggedVulnerabilities + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Name of the tag to get vulnerabilities for. + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TaggedVulnerabilityListResponseItem" + description: A list of all vulnerabilities assigned to the given tag + headers: + X-Total-Count: + description: The total number of vulnerabilities + schema: + format: integer + style: simple + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all vulnerabilities assigned to the given tag. + tags: + - tag + /v1/team: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteTeam + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + responses: + "204": + description: Team removed successfully + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a team + tags: + - team + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getTeams + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Team" + description: A list of all teams + headers: + X-Total-Count: + description: The total number of teams + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all teams + tags: + - team + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: updateTeam + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + description: The updated team + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a team's fields + tags: + - team + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: createTeam + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + application/problem+json: + schema: + $ref: "#/components/schemas/Team" + description: The created team + "401": + description: Unauthorized + "409": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/TeamAlreadyExistsProblemDetails" + description: Team already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new team + tags: + - team + /v1/team/key/{publicIdOrKey}: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteApiKey + parameters: + - description: The public ID for the API key or for Legacy the full Key to delete + in: path + name: publicIdOrKey + required: true + schema: + type: string + responses: + "204": + description: API key removed successfully + "401": + description: Unauthorized + "404": + description: The API key could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes the specified API key + tags: + - team + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: regenerateApiKey + parameters: + - description: The public ID for the API key or for Legacy the complete Key + to regenerate + in: path + name: publicIdOrKey + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ApiKey" + description: The re-generated API key + "401": + description: Unauthorized + "404": + description: The API key could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Regenerates an API key by removing the specified key, generating a\ + \ new one and returning its value" + tags: + - team + /v1/team/key/{publicIdOrKey}/comment: + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: updateApiKeyComment + parameters: + - description: The public ID for the API key or for Legacy the complete Key + to comment on + in: path + name: publicIdOrKey + required: true + schema: + type: string + requestBody: + content: + text/plain: + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ApiKey" + description: The updated API key + "401": + description: Unauthorized + "404": + description: The API key could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates an API key's comment + tags: + - team + /v1/team/self: + get: + operationId: getSelf + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/TeamSelfResponse" + description: Information about the current team + "400": + description: Invalid API key supplied + "401": + description: Unauthorized + "404": + description: No Team for the given API key found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns information about the current team. + tags: + - team + /v1/team/visible: + get: + description:

+ operationId: availableTeams + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/VisibleTeams" + description: The Visible Teams + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of Teams that are visible + tags: + - team + /v1/team/{uuid}: + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getTeam + parameters: + - description: The UUID of the team to retrieve + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Team" + description: A specific team + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific team + tags: + - team + /v1/team/{uuid}/key: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: generateApiKey + parameters: + - description: The UUID of the team to generate a key for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/ApiKey" + description: The created API key + "401": + description: Unauthorized + "404": + description: The team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Generates an API key and returns its value + tags: + - team + /v1/user/forceChangePassword: + post: + description: "Upon a successful login, a bearer token will be returned in the\ + \ response body." + operationId: forceChangePassword + requestBody: + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + confirmPassword: + type: string + newPassword: + type: string + password: + type: string + username: + type: string + responses: + "200": + description: Password changed successfully + "401": + description: Unauthorized + "403": + description: Forbidden + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: "Asserts login credentials and upon successful authentication, verifies\ + \ passwords match and changes users password" + tags: + - user + /v1/user/ldap: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteLdapUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/LdapUser" + responses: + "204": + description: LDAP user removed successfully + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a user. + tags: + - user + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getLdapUsers + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/LdapUser" + description: A list of all LDAP users + headers: + X-Total-Count: + description: The total number of LDAP users + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all LDAP users + tags: + - user + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: createLdapUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/LdapUser" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/LdapUser" + description: The created LDAP user + "400": + description: Username cannot be null or blank. + "401": + description: Unauthorized + "409": + description: A user with the same username already exists. Cannot create + new user + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new user that references an existing LDAP object. + tags: + - user + /v1/user/login: + post: + description: "Upon a successful login, a bearer token will be returned in the\ + \ response body." + operationId: validateCredentials + requestBody: + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + password: + type: string + username: + type: string + responses: + "200": + content: + text/plain: + schema: + type: string + description: A bearer token to be used for authenticating with the REST + API + "401": + description: Unauthorized + "403": + description: Forbidden + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Assert login credentials + tags: + - user + /v1/user/logout: + post: + description: Invalidates the current session. No-op when authenticated via API + key. + operationId: logout + parameters: + - in: header + name: Authorization + schema: + type: string + responses: + "204": + description: Session invalidated + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Invalidates the current session + tags: + - user + /v1/user/managed: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteManagedUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + responses: + "204": + description: User removed successfully + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a user. + tags: + - user + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getManagedUsers + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ManagedUser" + description: A list of all managed users + headers: + X-Total-Count: + description: The total number of managed users + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all managed users + tags: + - user + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: updateManagedUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + description: The updated user + "400": + description: Missing required field + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates a managed user. + tags: + - user + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: createManagedUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + description: The created user + "400": + description: Missing required field + "401": + description: Unauthorized + "409": + description: A user with the same username already exists. Cannot create + new user + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new user. + tags: + - user + /v1/user/membership: + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: setUserTeams + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/TeamsSetRequest" + description: Username and list of UUIDs to assign to user + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user is already a member of the specified team(s) + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Bad request + "401": + description: Unauthorized + "404": + description: The user or team(s) could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Sets specified teams to a user. + tags: + - user + /v1/user/oidc: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: deleteOidcUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OidcUser" + responses: + "204": + description: OIDC user removed successfully + "401": + description: Unauthorized + "404": + description: The user could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes an OpenID Connect user. + tags: + - user + get: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

+ operationId: getOidcUsers + responses: + "200": + description: A list of all OIDC users + headers: + X-Total-Count: + description: The total number of OIDC users + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all OIDC users + tags: + - user + put: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

+ operationId: createOidcUser + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OidcUser" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/OidcUser" + description: The created OIDC user + "400": + description: Username cannot be null or blank. + "401": + description: Unauthorized + "409": + description: A user with the same username already exists. Cannot create + new user + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new user that references an existing OpenID Connect user. + tags: + - user + /v1/user/oidc/login: + post: + description: "Upon a successful login, a bearer token will be returned in the\ + \ response body." + operationId: validateOidcAccessToken + requestBody: + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + accessToken: + type: string + idToken: + type: string + description: An OAuth2 access token + required: + - idToken + responses: + "200": + content: + text/plain: + schema: + type: string + description: A bearer token to be used for authenticating with the REST + API + "204": + description: No Content + "401": + description: Unauthorized + "403": + description: Forbidden + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Login with OpenID Connect + tags: + - user + /v1/user/self: + get: + operationId: getSelf_1 + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: Information about the current logged in user + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns information about the current logged in user. + tags: + - user + post: + operationId: updateSelf + requestBody: + content: + '*/*': + schema: + $ref: "#/components/schemas/ManagedUser" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ManagedUser" + description: The updated user + "400": + description: An invalid payload was submitted or the user is not a managed + user. + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates information about the current logged in user. + tags: + - user + /v1/user/self/permissions: + get: + description: "Returns all permissions the authenticated user has, including\ + \ those inherited from teams." + operationId: getSelfPermissions + responses: + "200": + content: + application/json: + schema: + type: array + items: + type: string + description: A list of effective permission names + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns the effective permissions of the authenticated user + tags: + - user + /v1/user/{username}/membership: + delete: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

+ operationId: removeTeamFromUser + parameters: + - description: A valid username + in: path + name: username + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/IdentifiableObject" + description: The UUID of the team to un-associate username from + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user was not a member of the specified team + "401": + description: Unauthorized + "404": + description: The user or team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes the username from the specified team. + tags: + - user + post: + description:

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

+ operationId: addTeamToUser + parameters: + - description: A valid username + in: path + name: username + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/IdentifiableObject" + description: The UUID of the team to associate username with + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/User" + description: The updated user + "304": + description: The user is already a member of the specified team + "401": + description: Unauthorized + "404": + description: The user or team could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Adds the username to the specified team. + tags: + - user + /v1/vex: + post: + description: |- +

+ Expects CycloneDX and a valid project UUID. If a UUID is not specified, + then the projectName and projectVersion must be specified. +

+

+ The VEX will be validated against the CycloneDX schema. If schema validation fails, + a response with problem details in RFC 9457 format will be returned. In this case, + the response's content type will be application/problem+json. +

+

Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_UPDATE

+ operationId: uploadVex_1 + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + project: + type: string + projectName: + type: string + projectVersion: + type: string + vex: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking VEX processing progress + "400": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/InvalidBomProblemDetails" + description: Invalid VEX + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Upload a supported VEX document + tags: + - vex + put: + description: |- +

+ Expects CycloneDX and a valid project UUID. If a UUID is not specified, + then the projectName and projectVersion must be specified. +

+

+ The VEX will be validated against the CycloneDX schema. If schema validation fails, + a response with problem details in RFC 9457 format will be returned. In this case, + the response's content type will be application/problem+json. +

+

+ The maximum allowed length of the vex value is 20'000'000 characters. + When uploading large VEX files, the POST endpoint is preferred, + as it does not have this limit. +

+

Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_UPDATE

+ operationId: uploadVex + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/VexSubmitRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/BomUploadResponse" + description: Token to be used for checking VEX processing progress + "400": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/InvalidBomProblemDetails" + description: Invalid VEX + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Upload a supported VEX document + tags: + - vex + /v1/vex/cyclonedx/project/{uuid}: + get: + description:

Requires permission VULNERABILITY_ANALYSIS + or VULNERABILITY_ANALYSIS_READ

+ operationId: exportProjectAsCycloneDx_1 + parameters: + - description: The UUID of the project to export + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Force the resulting VEX to be downloaded as a file (defaults + to 'false') + in: query + name: download + schema: + type: boolean + - description: "The CycloneDX Spec variant exported (defaults to: '1.5')" + in: query + name: version + schema: + type: string + responses: + "200": + content: + application/octet-stream: + schema: + type: string + application/vnd.cyclonedx+json: + schema: + type: string + description: A VEX for a project in CycloneDX format + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a VEX for a project in CycloneDX format + tags: + - vex + /v1/violation: + get: + description:

Requires permission VIEW_POLICY_VIOLATION

+ operationId: getViolations + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Optionally includes suppressed violations + in: query + name: suppressed + schema: + type: boolean + - description: Optionally includes inactive projects + in: query + name: showInactive + schema: + type: boolean + - description: Filter by violation state + in: query + name: violationState + schema: + type: string + - description: Filter by risk type + in: query + name: riskType + schema: + type: string + - description: Filter by policy + in: query + name: policy + schema: + type: string + - description: Filter by analysis state + in: query + name: analysisState + schema: + type: string + - description: Filter occurred on from + in: query + name: occurredOnDateFrom + schema: + type: string + - description: Filter occurred on to + in: query + name: occurredOnDateTo + schema: + type: string + - description: Filter the text input in these fields + in: query + name: textSearchField + schema: + type: string + - description: Filter by this text input + in: query + name: textSearchInput + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/PolicyViolation" + description: A list of all policy violations for the entire portfolio + headers: + X-Total-Count: + description: The total number of policy violations + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all policy violations for the entire portfolio + tags: + - violation + /v1/violation/analysis: + get: + description:

Requires permission VIEW_POLICY_VIOLATION

+ operationId: retrieveAnalysis_1 + parameters: + - description: The UUID of the component + in: query + name: component + required: true + schema: + type: string + format: uuid + - description: The UUID of the policy violation + in: query + name: policyViolation + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ViolationAnalysis" + description: A violation analysis trail + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component or policy violation could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Retrieves a violation analysis trail + tags: + - violationanalysis + put: + description:

Requires permission POLICY_VIOLATION_ANALYSIS

+ operationId: updateAnalysis_1 + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ViolationAnalysisRequest" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ViolationAnalysis" + description: The created violation analysis + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component or policy violation could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Records a violation analysis decision + tags: + - violationanalysis + /v1/violation/component/{uuid}: + get: + description:

Requires permission VIEW_POLICY_VIOLATION

+ operationId: getViolationsByComponent + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the component + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes suppressed violations + in: query + name: suppressed + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/PolicyViolation" + description: A list of all policy violations for a specific component + headers: + X-Total-Count: + description: The total number of policy violations + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all policy violations for a specific component + tags: + - violation + /v1/violation/project/{uuid}: + get: + description:

Requires permission VIEW_POLICY_VIOLATION

+ operationId: getViolationsByProject + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the project + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes suppressed violations + in: query + name: suppressed + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/PolicyViolation" + description: A list of all policy violations for a specific project + headers: + X-Total-Count: + description: The total number of policy violations + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all policy violations for a specific project + tags: + - violation + /v1/vulnerability: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getAllVulnerabilities + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + description: A list of all vulnerabilities + headers: + X-Total-Count: + description: The total number of vulnerabilities + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all vulnerabilities + tags: + - vulnerability + post: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_UPDATE

+ operationId: updateVulnerability + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + description: The updated vulnerability + "401": + description: Unauthorized + "404": + description: The vulnerability could not be found + "406": + description: The vulnId may not be changed + security: + - ApiKeyAuth: [] + - BearerAuth: [] + tags: + - vulnerability + put: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_CREATE

+ operationId: createVulnerability + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + responses: + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + description: The created vulnerability + "401": + description: Unauthorized + "409": + description: A vulnerability with the specified vulnId already exists + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Creates a new vulnerability + tags: + - vulnerability + /v1/vulnerability/component/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getVulnerabilitiesByComponent + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: The UUID of the component to retrieve vulnerabilities for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes suppressed vulnerabilities + in: query + name: suppressed + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + description: A list of all vulnerabilities for a specific component + headers: + X-Total-Count: + description: The total number of vulnerabilities + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all vulnerabilities for a specific component + tags: + - vulnerability + /v1/vulnerability/project/{uuid}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getVulnerabilitiesByProject + parameters: + - description: The UUID of the project to retrieve vulnerabilities for + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: Optionally includes suppressed vulnerabilities + in: query + name: suppressed + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + description: A list of all vulnerabilities for a specific project + headers: + X-Total-Count: + description: The total number of vulnerabilities + schema: + format: integer + style: simple + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The project could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all vulnerabilities for a specific project + tags: + - vulnerability + /v1/vulnerability/source/{source}/vuln/{vulnId}/component/{component}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: unassignVulnerability_1 + parameters: + - description: The vulnerability source + in: path + name: source + required: true + schema: + type: string + - description: The vulnId + in: path + name: vulnId + required: true + schema: + type: string + - description: The UUID of the component + in: path + name: component + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Assignment removal successful + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The vulnerability or component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes assignment of a vulnerability from a component + tags: + - vulnerability + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: assignVulnerability_1 + parameters: + - description: The vulnerability source + in: path + name: source + required: true + schema: + type: string + - description: The vulnId + in: path + name: vulnId + required: true + schema: + type: string + - description: The UUID of the component + in: path + name: component + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Assignment successful + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The vulnerability or component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Assigns a vulnerability to a component + tags: + - vulnerability + /v1/vulnerability/source/{source}/vuln/{vuln}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getVulnerabilityByVulnId + parameters: + - in: path + name: source + required: true + schema: + type: string + - in: path + name: vuln + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + description: A specific vulnerability + "401": + description: Unauthorized + "404": + description: The vulnerability could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific vulnerability + tags: + - vulnerability + /v1/vulnerability/source/{source}/vuln/{vuln}/projects: + get: + description: |- +

Requires permission VIEW_PORTFOLIO

Optional query parameter searchText. The search is case insensitive. + So if a search is done for project 'abc' and a project named 'aBc' exists in the knowledgebase, + then the latter would appear in the search results

+ operationId: getAffectedProject + parameters: + - description: The page to return. To be used in conjunction with pageSize. + in: query + name: pageNumber + schema: + type: string + default: "1" + - description: Number of elements to return per page. To be used in conjunction + with pageNumber. + in: query + name: pageSize + schema: + type: string + default: "100" + - description: Offset to start returning elements from. To be used in conjunction + with limit. + in: query + name: offset + schema: + type: string + - description: Number of elements to return per page. To be used in conjunction + with offset. + in: query + name: limit + schema: + type: string + - description: Name of the resource field to sort on. + in: query + name: sortName + schema: + type: string + - description: Ordering of items when sorting with sortName. + in: query + name: sortOrder + schema: + type: string + enum: + - "asc, desc" + - description: Optional case-insensitive substring match on project name. + in: query + name: searchText + schema: + type: string + - in: path + name: source + required: true + schema: + type: string + - in: path + name: vuln + required: true + schema: + type: string + - description: Optionally excludes inactive projects from being returned + in: query + name: excludeInactive + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/AffectedProject" + description: A list of all projects affected by a specific vulnerability + headers: + X-Total-Count: + description: The total number of projects + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all projects affected by a specific vulnerability + tags: + - vulnerability + /v1/vulnerability/tag/{tag}: + get: + description:

Requires permission VIEW_PORTFOLIO

+ operationId: getVulnerabilitiesByTag + parameters: + - description: The tag to query on + in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + description: A list of all tagged vulnerabilities + headers: + X-Total-Count: + description: The total number of vulnerabilities with the tag + schema: + format: integer + style: simple + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a list of all vulnerabilities by tag + tags: + - vulnerability + /v1/vulnerability/vulnId: + get: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_CREATE

+ operationId: generateInternalVulnerabilityIdentifier + responses: + "200": + content: + application/json: + schema: + type: string + description: An internal vulnerability identifier + "401": + description: Unauthorized + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Generates an internal vulnerability identifier + tags: + - vulnerability + /v1/vulnerability/{uuid}: + delete: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_DELETE

+ operationId: deleteVulnerability + parameters: + - description: The UUID of the vulnerability to delete + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Vulnerability removed successfully + "401": + description: Unauthorized + "403": + description: Access to the specified vulnerability is forbidden + "404": + description: The UUID of the vulnerability could not be found + "412": + description: Portfolio components or services are affected by this vulnerability. + Unable to delete. + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Deletes a vulnerability + tags: + - vulnerability + get: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_READ

+ operationId: getVulnerabilityByUuid + parameters: + - description: The UUID of the vulnerability + in: path + name: uuid + required: true + schema: + type: string + format: uuid + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + description: A specific vulnerability + "401": + description: Unauthorized + "404": + description: The vulnerability could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Returns a specific vulnerability + tags: + - vulnerability + /v1/vulnerability/{uuid}/component/{component}: + delete: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_DELETE

+ operationId: unassignVulnerability + parameters: + - description: The UUID of the vulnerability + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the component + in: path + name: component + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Assignment removal successful + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The vulnerability or component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Removes assignment of a vulnerability from a component + tags: + - vulnerability + post: + description:

Requires permission PORTFOLIO_MANAGEMENT or + PORTFOLIO_MANAGEMENT_UPDATE

+ operationId: assignVulnerability + parameters: + - description: The UUID of the vulnerability + in: path + name: uuid + required: true + schema: + type: string + format: uuid + - description: The UUID of the component + in: path + name: component + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Assignment successful + "401": + description: Unauthorized + "403": + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ProblemDetails" + description: Access to the requested project is forbidden + "404": + description: The vulnerability or component could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Assigns a vulnerability to a component + tags: + - vulnerability + /v1/vulnerability/{uuid}/tags: + post: + description:

Requires permission VULNERABILITY_MANAGEMENT + or VULNERABILITY_MANAGEMENT_UPDATE

+ operationId: updateVulnerabilityTags + parameters: + - description: UUID of the vulnerability + in: path + name: uuid + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/Vulnerability" + description: The updated vulnerability + "401": + description: Unauthorized + "404": + description: The vulnerability could not be found + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Updates tags for a vulnerability + tags: + - vulnerability + /v1/workflow/token/{uuid}/status: + get: + description:

Requires permission BOM_UPLOAD

+ operationId: getWorkflowStates + parameters: + - description: The UUID of the token to query + in: path + name: uuid + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/WorkflowState" + description: A list of workflow states + "401": + description: Unauthorized + "404": + description: Workflow does not exist + security: + - ApiKeyAuth: [] + - BearerAuth: [] + summary: Retrieves workflow states associated with the token received from bom + upload . + tags: + - workflow + /version: + get: + description: Returns a simple json object containing the name of the application + and the version + operationId: getVersion + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/About" + description: Application version information + summary: Returns application version information + tags: + - version +components: + schemas: + About: + type: object + properties: + application: + type: string + framework: + $ref: "#/components/schemas/Framework" + providerData: + type: object + additionalProperties: + type: object + systemUuid: + type: string + timestamp: + type: string + uuid: + type: string + version: + type: string + AclMappingRequest: + type: object + properties: + project: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + team: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + required: + - project + - team + AffectedComponent: + type: object + properties: + affectedVersionAttributions: + type: array + items: + $ref: "#/components/schemas/AffectedVersionAttribution" + identity: + type: string + identityType: + type: string + enum: + - CPE + - PURL + uuid: + type: string + format: uuid + version: + type: string + versionEndExcluding: + type: string + versionEndIncluding: + type: string + versionStartExcluding: + type: string + versionStartIncluding: + type: string + versionType: + type: string + enum: + - EXACT + - RANGE + AffectedProject: + type: object + properties: + active: + type: boolean + affectedComponentUuids: + type: array + items: + type: string + format: uuid + dependencyGraphAvailable: + type: boolean + name: + type: string + uuid: + type: string + format: uuid + version: + type: string + AffectedVersionAttribution: + type: object + properties: + firstSeen: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + lastSeen: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + source: + type: string + enum: + - NVD + - NPM + - GITHUB + - VULNDB + - OSSINDEX + - RETIREJS + - INTERNAL + - OSV + - SNYK + - CSAF + uuid: + type: string + format: uuid + required: + - firstSeen + - lastSeen + Analysis: + type: object + properties: + analysisComments: + type: array + items: + $ref: "#/components/schemas/AnalysisComment" + analysisDetails: + type: string + analysisJustification: + type: string + enum: + - CODE_NOT_PRESENT + - CODE_NOT_REACHABLE + - REQUIRES_CONFIGURATION + - REQUIRES_DEPENDENCY + - REQUIRES_ENVIRONMENT + - PROTECTED_BY_COMPILER + - PROTECTED_AT_RUNTIME + - PROTECTED_AT_PERIMETER + - PROTECTED_BY_MITIGATING_CONTROL + - NOT_SET + analysisResponse: + type: string + enum: + - CAN_NOT_FIX + - WILL_NOT_FIX + - UPDATE + - ROLLBACK + - WORKAROUND_AVAILABLE + - NOT_SET + analysisState: + type: string + enum: + - EXPLOITABLE + - IN_TRIAGE + - FALSE_POSITIVE + - NOT_AFFECTED + - RESOLVED + - NOT_SET + cvssV2Score: + type: number + cvssV2Vector: + type: string + cvssV3Score: + type: number + cvssV3Vector: + type: string + cvssV4Score: + type: number + cvssV4Vector: + type: string + isSuppressed: + type: boolean + owaspScore: + type: number + owaspVector: + type: string + severity: + type: string + enum: + - CRITICAL + - HIGH + - MEDIUM + - LOW + - INFO + - UNASSIGNED + required: + - analysisDetails + - analysisJustification + - analysisResponse + - analysisState + AnalysisComment: + type: object + properties: + comment: + type: string + commenter: + type: string + timestamp: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + required: + - comment + - timestamp + AnalysisRequest: + type: object + properties: + analysisDetails: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + analysisJustification: + type: string + enum: + - CODE_NOT_PRESENT + - CODE_NOT_REACHABLE + - REQUIRES_CONFIGURATION + - REQUIRES_DEPENDENCY + - REQUIRES_ENVIRONMENT + - PROTECTED_BY_COMPILER + - PROTECTED_AT_RUNTIME + - PROTECTED_AT_PERIMETER + - PROTECTED_BY_MITIGATING_CONTROL + - NOT_SET + analysisResponse: + type: string + enum: + - CAN_NOT_FIX + - WILL_NOT_FIX + - UPDATE + - ROLLBACK + - WORKAROUND_AVAILABLE + - NOT_SET + analysisState: + type: string + enum: + - EXPLOITABLE + - IN_TRIAGE + - FALSE_POSITIVE + - NOT_AFFECTED + - RESOLVED + - NOT_SET + comment: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + component: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + isSuppressed: + type: boolean + writeOnly: true + project: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + suppressed: + type: boolean + vulnerability: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + required: + - component + - vulnerability + ApiKey: + type: object + properties: + comment: + type: string + maxLength: 255 + minLength: 0 + created: + type: string + format: date-time + key: + type: string + lastUsed: + type: string + format: date-time + legacy: + type: boolean + maskedKey: + type: string + publicId: + type: string + maxLength: 8 + minLength: 5 + BomSubmitRequest: + type: object + properties: + autoCreate: + type: boolean + bom: + type: string + description: Base64 encoded BOM + example: ewogICJib21Gb3JtYXQiOiAiQ3ljbG9uZURYIiwKICAic3BlY1ZlcnNpb24iOiAiMS40IiwKICAiY29tcG9uZW50cyI6IFsKICAgIHsKICAgICAgInR5cGUiOiAibGlicmFyeSIsCiAgICAgICJuYW1lIjogImFjbWUtbGliIiwKICAgICAgInZlcnNpb24iOiAiMS4wLjAiCiAgICB9CiAgXQp9 + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" + isLatest: + type: boolean + parentName: + type: string + example: Example Application Parent + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + parentUUID: + type: string + example: 5341f53c-611b-4388-9d9c-731026dc5eec + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + parentVersion: + type: string + example: 1.0.0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + project: + type: string + example: 38640b33-4ba9-4733-bdab-cbfc40c6f8aa + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + projectName: + type: string + example: Example Application + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + projectTags: + type: array + example: "tag1, tag2" + items: + $ref: "#/components/schemas/Tag" + projectVersion: + type: string + example: 1.0.0 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + required: + - bom + - project + - projectName + - projectVersion + BomUploadResponse: + type: object + properties: + projectUuid: + type: string + format: uuid + description: UUID of the project the BOM was uploaded for + token: + type: string + format: uuid + description: Token used to check task progress + required: + - projectUuid + - token + CelExpressionError: + type: object + description: Errors identified during CEL expression compilation + properties: + column: + type: integer + format: int32 + line: + type: integer + format: int32 + message: + type: string + CloneProjectRequest: + type: object + properties: + includeACL: + type: boolean + writeOnly: true + includeAuditHistory: + type: boolean + writeOnly: true + includeComponents: + type: boolean + writeOnly: true + includeDependencies: + type: boolean + writeOnly: true + includePolicyViolations: + type: boolean + writeOnly: true + includeProperties: + type: boolean + writeOnly: true + includeServices: + type: boolean + writeOnly: true + includeTags: + type: boolean + writeOnly: true + makeCloneLatest: + type: boolean + writeOnly: true + project: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + version: + type: string + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + required: + - project + - version + Component: + type: object + properties: + author: + type: string + authors: + type: array + items: + $ref: "#/components/schemas/OrganizationalContact" + blake2b_256: + type: string + pattern: "^[0-9a-f]{64}$" + blake2b_384: + type: string + pattern: "^[0-9a-f]{96}$" + blake2b_512: + type: string + pattern: "^[0-9a-f]{128}$" + blake3: + type: string + pattern: "^[A-Fa-f0-9]*$" + children: + type: array + items: + $ref: "#/components/schemas/Component" + classifier: + type: string + enum: + - APPLICATION + - FRAMEWORK + - LIBRARY + - CONTAINER + - OPERATING_SYSTEM + - DEVICE + - FIRMWARE + - FILE + - PLATFORM + - DEVICE_DRIVER + - MACHINE_LEARNING_MODEL + - DATA + componentMetaInformation: + $ref: "#/components/schemas/ComponentMetaInformation" + copyright: + type: string + maxLength: 1024 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + cpe: + type: string + maxLength: 255 + minLength: 0 + pattern: "(cpe:2\\.3:[aho\\*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\\ + [\\\\\\*\\?!\"#$$%&'\\(\\)\\+,/:;<=>@\\[\\]\\^`\\{\\|}~]))+(\\?*|\\*?))|[\\\ + *\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[\\*\\-]))(:(((\\\ + ?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\[\\\\\\*\\?!\"#$$%&'\\(\\)\\+,/:;<=>@\\\ + [\\]\\^`\\{\\|}~]))+(\\?*|\\*?))|[\\*\\-])){4})|([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9\\\ + ._\\-~%]*){0,6})" + dependencyGraph: + type: array + items: + type: string + uniqueItems: true + description: + type: string + maxLength: 1024 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + directDependencies: + type: string + expandDependencyGraph: + type: boolean + extension: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{Alnum}!@#$%^&{}\\[\\]()_+\\-=,.~'` ]{1,255}$" + externalReferences: + type: array + items: + $ref: "#/components/schemas/ExternalReference" + filename: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{Alnum}:/\\\\!@#$%^&{}\\[\\]()_+\\-=,.~'` ]{1,255}$" + group: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + isInternal: + type: boolean + lastInheritedRiskScore: + type: number + format: double + license: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + licenseExpression: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + licenseUrl: + type: string + maxLength: 255 + minLength: 0 + pattern: "^((((https?|ftps?|sftp|imap|rtsp|rtmp|sip|sips|git|ssh|telnet|nntp|file)://)|(mailto:|news:))(%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@&=+$,A-Za-z0-9])+)([).!';/?:,][[:blank:]])?$" + md5: + type: string + pattern: "^[0-9a-fA-F]{32}$" + metrics: + $ref: "#/components/schemas/DependencyMetrics" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + notes: + type: string + occurrenceCount: + type: integer + format: int64 + parent: + $ref: "#/components/schemas/Component" + project: + $ref: "#/components/schemas/Project" + properties: + type: array + items: + $ref: "#/components/schemas/ComponentProperty" + publisher: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + purl: + type: string + maxLength: 1024 + minLength: 0 + purlCoordinates: + type: string + maxLength: 1024 + minLength: 0 + readOnly: true + repositoryMeta: + $ref: "#/components/schemas/RepositoryMetaComponent" + resolvedLicense: + $ref: "#/components/schemas/License" + sha1: + type: string + pattern: "^[0-9a-fA-F]{40}$" + sha256: + type: string + pattern: "^[0-9a-fA-F]{64}$" + sha384: + type: string + pattern: "^[0-9a-fA-F]{96}$" + sha3_256: + type: string + pattern: "^[0-9a-fA-F]{64}$" + sha3_384: + type: string + pattern: "^[0-9a-fA-F]{96}$" + sha3_512: + type: string + pattern: "^[0-9a-fA-F]{128}$" + sha512: + type: string + pattern: "^[0-9a-fA-F]{128}$" + supplier: + $ref: "#/components/schemas/OrganizationalEntity" + swidTagId: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + uuid: + type: string + format: uuid + version: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + vulnerabilities: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + required: + - classifier + - name + - project + - uuid + ComponentMetaInformation: + type: object + properties: + integrityMatchStatus: + type: string + enum: + - HASH_MATCH_PASSED + - HASH_MATCH_FAILED + - HASH_MATCH_UNKNOWN + - COMPONENT_MISSING_HASH + integrityRepoUrl: + type: string + lastFetched: + type: string + format: date-time + publishedDate: + type: string + format: date-time + ComponentOccurrence: + type: object + properties: + createdAt: + type: string + format: date-time + id: + type: string + format: uuid + line: + type: integer + format: int32 + location: + type: string + offset: + type: integer + format: int32 + symbol: + type: string + ComponentProperty: + type: object + properties: + description: + type: string + maxLength: 255 + minLength: 0 + pattern: "\\P{Cc}+" + groupName: + type: string + maxLength: 255 + minLength: 1 + pattern: "\\P{Cc}+" + propertyName: + type: string + maxLength: 255 + minLength: 1 + pattern: "\\P{Cc}+" + propertyType: + type: string + enum: + - BOOLEAN + - INTEGER + - NUMBER + - STRING + - TIMESTAMP + - URL + - UUID + propertyValue: + type: string + maxLength: 1024 + minLength: 0 + pattern: "\\P{Cc}+" + uuid: + type: string + format: uuid + required: + - propertyName + - propertyType + - uuid + ConciseProject: + type: object + description: A concise representation of a project + properties: + active: + type: boolean + description: Whether the project is active + classifier: + type: string + description: Classifier of the project + enum: + - APPLICATION + - FRAMEWORK + - LIBRARY + - CONTAINER + - OPERATING_SYSTEM + - DEVICE + - FIRMWARE + - FILE + - PLATFORM + - DEVICE_DRIVER + - MACHINE_LEARNING_MODEL + - DATA + collectionLogic: + type: string + description: Collection logic for aggregating child metrics + enum: + - AGGREGATE_DIRECT_CHILDREN + - AGGREGATE_DIRECT_CHILDREN_WITH_TAG + - AGGREGATE_LATEST_VERSION_CHILDREN + group: + type: string + description: Group or namespace of the project + hasChildren: + type: boolean + description: Whether the project has children + isLatest: + type: boolean + description: Whether the project version is latest + lastBomImport: + type: number + description: Timestamp of the last BOM import + example: 1719499619599 + lastBomImportFormat: + type: string + description: Format of the last imported BOM + lastRiskScore: + type: number + format: double + description: Last observed risk score + metrics: + $ref: "#/components/schemas/ConciseProjectMetrics" + name: + type: string + description: Name of the project + tags: + type: array + description: Tags associated with the project + items: + $ref: "#/components/schemas/Tag" + teams: + type: array + description: Teams associated with the project + items: + $ref: "#/components/schemas/Team" + uuid: + type: string + format: uuid + description: UUID of the project + version: + type: string + description: Version of the project + required: + - active + - hasChildren + - name + - uuid + ConciseProjectMetrics: + type: object + description: A concise representation of a project's metrics + properties: + components: + type: integer + format: int32 + description: Total number of components + critical: + type: integer + format: int32 + description: Number of vulnerabilities with critical severity + high: + type: integer + format: int32 + description: Number of vulnerabilities with high severity + inheritedRiskScore: + type: number + format: double + description: The inherited risk score + low: + type: integer + format: int32 + description: Number of vulnerabilities with low severity + medium: + type: integer + format: int32 + description: Number of vulnerabilities with medium severity + policyViolationsFail: + type: integer + format: int32 + description: Number of policy violations with status FAIL + policyViolationsInfo: + type: integer + format: int32 + description: Number of policy violations with status WARN + policyViolationsLicenseTotal: + type: integer + format: int32 + description: Number of license policy violations + policyViolationsOperationalTotal: + type: integer + format: int32 + description: Number of operational policy violations + policyViolationsSecurityTotal: + type: integer + format: int32 + description: Number of security policy violations + policyViolationsTotal: + type: integer + format: int32 + description: Total number of policy violations + policyViolationsWarn: + type: integer + format: int32 + description: Number of policy violations with status WARN + unassigned: + type: integer + format: int32 + description: Number of vulnerabilities with unassigned severity + vulnerabilities: + type: integer + format: int32 + description: Total number of vulnerabilities + required: + - components + - critical + - high + - inheritedRiskScore + - low + - medium + - policyViolationsFail + - policyViolationsInfo + - policyViolationsLicenseTotal + - policyViolationsOperationalTotal + - policyViolationsSecurityTotal + - policyViolationsTotal + - policyViolationsWarn + - unassigned + - vulnerabilities + ConfigProperty: + type: object + properties: + description: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + groupName: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + propertyName: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + propertyType: + type: string + enum: + - BOOLEAN + - INTEGER + - NUMBER + - STRING + - TIMESTAMP + - URL + - UUID + propertyValue: + type: string + pattern: "[\\P{Cc}]+" + required: + - groupName + - propertyName + - propertyType + CreateNotificationPublisherRequest: + type: object + properties: + description: + type: string + extensionName: + type: string + minLength: 1 + name: + type: string + minLength: 1 + template: + type: string + templateMimeType: + type: string + required: + - extensionName + - name + CreateNotificationRuleRequest: + type: object + properties: + level: + type: string + enum: + - INFORMATIONAL + - WARNING + - ERROR + name: + type: string + minLength: 1 + publisher: + $ref: "#/components/schemas/Publisher" + scope: + type: string + enum: + - SYSTEM + - PORTFOLIO + required: + - level + - name + - publisher + - scope + CreateScheduledNotificationRuleRequest: + type: object + properties: + level: + type: string + enum: + - INFORMATIONAL + - WARNING + - ERROR + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + publisher: + $ref: "#/components/schemas/Publisher" + scope: + type: string + enum: + - SYSTEM + - PORTFOLIO + required: + - level + - name + - publisher + - scope + Cwe: + type: object + properties: + cweId: + type: integer + format: int32 + name: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + DataClassification: + type: object + properties: + direction: + type: string + enum: + - INBOUND + - OUTBOUND + - BI_DIRECTIONAL + - UNKNOWN + name: + type: string + DependencyGraphResponse: + type: object + properties: + directDependencies: + type: string + latestVersion: + type: string + name: + type: string + purl: + type: string + uuid: + type: string + format: uuid + version: + type: string + DependencyMetrics: + type: object + properties: + critical: + type: integer + format: int32 + findingsAudited: + type: integer + format: int32 + findingsTotal: + type: integer + format: int32 + findingsUnaudited: + type: integer + format: int32 + firstOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + high: + type: integer + format: int32 + inheritedRiskScore: + type: number + format: double + lastOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + low: + type: integer + format: int32 + medium: + type: integer + format: int32 + policyViolationsAudited: + type: integer + format: int32 + policyViolationsFail: + type: integer + format: int32 + policyViolationsInfo: + type: integer + format: int32 + policyViolationsLicenseAudited: + type: integer + format: int32 + policyViolationsLicenseTotal: + type: integer + format: int32 + policyViolationsLicenseUnaudited: + type: integer + format: int32 + policyViolationsOperationalAudited: + type: integer + format: int32 + policyViolationsOperationalTotal: + type: integer + format: int32 + policyViolationsOperationalUnaudited: + type: integer + format: int32 + policyViolationsSecurityAudited: + type: integer + format: int32 + policyViolationsSecurityTotal: + type: integer + format: int32 + policyViolationsSecurityUnaudited: + type: integer + format: int32 + policyViolationsTotal: + type: integer + format: int32 + policyViolationsUnaudited: + type: integer + format: int32 + policyViolationsWarn: + type: integer + format: int32 + suppressed: + type: integer + format: int32 + unassigned: + type: integer + format: int32 + vulnerabilities: + type: integer + format: int32 + required: + - firstOccurrence + - lastOccurrence + Epss: + type: object + properties: + cve: + type: string + minLength: 1 + percentile: + type: number + score: + type: number + required: + - cve + ExternalReference: + type: object + properties: + comment: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + type: + type: string + enum: + - vcs + - issue-tracker + - website + - advisories + - bom + - mailing-list + - social + - chat + - documentation + - support + - source-distribution + - distribution + - distribution-intake + - license + - build-meta + - build-system + - release-notes + - security-contact + - model_card + - attestation + - threat-model + - adversary-model + - risk-assessment + - vulnerability-assertion + - exploitability-statement + - pentest-report + - static-analysis-report + - dynamic-analysis-report + - runtime-analysis-report + - component-analysis-report + - maturity-report + - certification-report + - codified-infrastructure + - quality-metrics + - log + - configuration + - evidence + - formulation + - rfc-9116 + - electronic-signature + - digital-signature + - other + url: + type: string + minLength: 1 + required: + - url + Finding: + type: object + properties: + analysis: + type: object + additionalProperties: + type: object + attribution: + type: object + additionalProperties: + type: object + component: + type: object + additionalProperties: + type: object + matrix: + type: string + vulnerability: + type: object + additionalProperties: + type: object + Framework: + type: object + properties: + name: + type: string + timestamp: + type: string + uuid: + type: string + version: + type: string + IdentifiableObject: + type: object + properties: + uuid: + type: string + InvalidBomProblemDetails: + type: object + allOf: + - $ref: "#/components/schemas/ProblemDetails" + - type: object + properties: + errors: + type: array + description: Errors identified during schema validation + items: + type: string + description: Errors identified during schema validation + required: + - detail + - status + - title + InvalidNotificationFilterExpressionProblemDetails: + type: object + allOf: + - $ref: "#/components/schemas/ProblemDetails" + - type: object + properties: + errors: + type: array + description: Errors identified during CEL expression compilation + items: + $ref: "#/components/schemas/CelExpressionError" + required: + - detail + - status + - title + IsTokenBeingProcessedResponse: + type: object + properties: + processing: + type: boolean + required: + - processing + LdapUser: + type: object + properties: + dn: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + email: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + username: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + required: + - dn + - username + License: + type: object + properties: + isCustomLicense: + type: boolean + isDeprecatedLicenseId: + type: boolean + isFsfLibre: + type: boolean + isOsiApproved: + type: boolean + licenseComments: + type: string + licenseGroups: + type: array + items: + $ref: "#/components/schemas/LicenseGroup" + licenseId: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[a-zA-Z0-9_.\\-+]*$" + licenseText: + type: string + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + seeAlso: + type: array + items: + type: string + standardLicenseHeader: + type: string + standardLicenseTemplate: + type: string + uuid: + type: string + format: uuid + required: + - licenseId + - name + - uuid + LicenseGroup: + type: object + properties: + licenses: + type: array + items: + $ref: "#/components/schemas/License" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + riskWeight: + type: integer + format: int32 + uuid: + type: string + format: uuid + required: + - name + - uuid + ManagedUser: + type: object + properties: + confirmPassword: + type: string + email: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + forcePasswordChange: + type: boolean + fullname: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + lastPasswordChange: + type: string + format: date-time + newPassword: + type: string + nonExpiryPassword: + type: boolean + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + suspended: + type: boolean + teams: + type: array + items: + $ref: "#/components/schemas/Team" + username: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + required: + - lastPasswordChange + - username + MappedLdapGroup: + type: object + properties: + dn: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + uuid: + type: string + format: uuid + required: + - dn + - uuid + MappedLdapGroupRequest: + type: object + properties: + dn: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + team: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + required: + - dn + - team + MappedOidcGroup: + type: object + properties: + group: + $ref: "#/components/schemas/OidcGroup" + uuid: + type: string + format: uuid + required: + - uuid + MappedOidcGroupRequest: + type: object + properties: + group: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + team: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + required: + - group + - team + NotificationPublisher: + type: object + properties: + defaultPublisher: + type: boolean + description: + type: string + maxLength: 1024 + minLength: 0 + extensionName: + type: string + maxLength: 1024 + minLength: 1 + name: + type: string + maxLength: 255 + minLength: 1 + template: + type: string + templateMimeType: + type: string + maxLength: 255 + minLength: 1 + uuid: + type: string + format: uuid + required: + - extensionName + - name + - templateMimeType + - uuid + NotificationRule: + type: object + properties: + enabled: + type: boolean + filterExpression: + type: string + logSuccessfulPublish: + type: boolean + message: + type: string + maxLength: 1024 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + notificationLevel: + type: string + enum: + - INFORMATIONAL + - WARNING + - ERROR + notifyChildren: + type: boolean + notifyOn: + type: array + items: + type: string + enum: + - CONFIGURATION + - DATASOURCE_MIRRORING + - REPOSITORY + - INTEGRATION + - FILE_SYSTEM + - ANALYZER + - NEW_VULNERABILITY + - NEW_VULNERABLE_DEPENDENCY + - VULNERABILITY_RETRACTED + - PROJECT_AUDIT_CHANGE + - BOM_CONSUMED + - BOM_PROCESSED + - BOM_PROCESSING_FAILED + - BOM_VALIDATION_FAILED + - VEX_CONSUMED + - VEX_PROCESSED + - POLICY_VIOLATION + - PROJECT_CREATED + - PROJECT_VULN_ANALYSIS_COMPLETE + - USER_CREATED + - USER_DELETED + - NEW_VULNERABILITIES_SUMMARY + - NEW_POLICY_VIOLATIONS_SUMMARY + uniqueItems: true + projects: + type: array + items: + $ref: "#/components/schemas/Project" + publisher: + $ref: "#/components/schemas/NotificationPublisher" + publisherConfig: + type: string + scheduleCron: + type: string + description: Schedule of this rule as cron expression. Must not be set for + rules with trigger type EVENT. + scheduleLastTriggeredAt: + type: integer + format: int64 + description: "When the schedule last triggered, as UNIX epoch timestamp\ + \ in milliseconds" + readOnly: true + scheduleNextTriggerAt: + type: integer + format: int64 + description: "When the schedule triggers next, as UNIX epoch timestamp in\ + \ milliseconds" + readOnly: true + scheduleSkipUnchanged: + type: boolean + description: Whether to skip emitting a scheduled notification if it doesn't + contain any changes since its last emission. Must not be set for rules + with trigger type EVENT. + scope: + type: string + enum: + - SYSTEM + - PORTFOLIO + tags: + type: array + items: + $ref: "#/components/schemas/Tag" + uniqueItems: true + teams: + type: array + items: + $ref: "#/components/schemas/Team" + uniqueItems: true + triggerType: + type: string + enum: + - EVENT + - SCHEDULE + readOnly: true + uuid: + type: string + format: uuid + required: + - name + - scope + - triggerType + - uuid + OidcGroup: + type: object + properties: + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + uuid: + type: string + format: uuid + required: + - name + - uuid + OidcUser: + type: object + properties: + email: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + subjectIdentifier: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + username: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + required: + - username + OrganizationalContact: + type: object + properties: + email: + type: string + name: + type: string + phone: + type: string + OrganizationalEntity: + type: object + properties: + contacts: + type: array + items: + $ref: "#/components/schemas/OrganizationalContact" + name: + type: string + urls: + type: array + items: + type: string + Permission: + type: object + properties: + description: + type: string + ldapUsers: + type: array + items: + $ref: "#/components/schemas/LdapUser" + managedUsers: + type: array + items: + $ref: "#/components/schemas/ManagedUser" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[a-zA-Z_0-9]*$" + oidcUsers: + type: array + items: + $ref: "#/components/schemas/OidcUser" + required: + - name + Policy: + type: object + properties: + global: + type: boolean + includeChildren: + type: boolean + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + onlyLatestProjectVersion: + type: boolean + operator: + type: string + enum: + - ALL + - ANY + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + policyConditions: + type: array + items: + $ref: "#/components/schemas/PolicyCondition" + projects: + type: array + items: + $ref: "#/components/schemas/Project" + tags: + type: array + items: + $ref: "#/components/schemas/Tag" + uniqueItems: true + uuid: + type: string + format: uuid + violationState: + type: string + enum: + - INFO + - WARN + - FAIL + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + required: + - name + - operator + - uuid + - violationState + PolicyCondition: + type: object + properties: + operator: + type: string + enum: + - IS + - IS_NOT + - MATCHES + - NO_MATCH + - NUMERIC_GREATER_THAN + - NUMERIC_LESS_THAN + - NUMERIC_EQUAL + - NUMERIC_NOT_EQUAL + - NUMERIC_GREATER_THAN_OR_EQUAL + - NUMERIC_LESSER_THAN_OR_EQUAL + - CONTAINS_ALL + - CONTAINS_ANY + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + policy: + $ref: "#/components/schemas/Policy" + subject: + type: string + enum: + - AGE + - COORDINATES + - CPE + - EXPRESSION + - LICENSE + - LICENSE_GROUP + - PACKAGE_URL + - SEVERITY + - SWID_TAGID + - VERSION + - COMPONENT_HASH + - CWE + - VULNERABILITY_ID + - VERSION_DISTANCE + - EPSS + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + uuid: + type: string + format: uuid + value: + type: string + maxLength: 2147483647 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + violationType: + type: string + enum: + - LICENSE + - SECURITY + - OPERATIONAL + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + required: + - operator + - subject + - uuid + - value + PolicyViolation: + type: object + properties: + analysis: + $ref: "#/components/schemas/ViolationAnalysis" + component: + $ref: "#/components/schemas/Component" + policyCondition: + $ref: "#/components/schemas/PolicyCondition" + project: + $ref: "#/components/schemas/Project" + text: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + timestamp: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + type: + type: string + enum: + - LICENSE + - SECURITY + - OPERATIONAL + uuid: + type: string + format: uuid + required: + - timestamp + - uuid + PortfolioMetrics: + type: object + properties: + components: + type: integer + format: int32 + critical: + type: integer + format: int32 + findingsAudited: + type: integer + format: int32 + findingsTotal: + type: integer + format: int32 + findingsUnaudited: + type: integer + format: int32 + firstOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + high: + type: integer + format: int32 + inheritedRiskScore: + type: number + format: double + lastOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + low: + type: integer + format: int32 + medium: + type: integer + format: int32 + policyViolationsAudited: + type: integer + format: int32 + policyViolationsFail: + type: integer + format: int32 + policyViolationsInfo: + type: integer + format: int32 + policyViolationsLicenseAudited: + type: integer + format: int32 + policyViolationsLicenseTotal: + type: integer + format: int32 + policyViolationsLicenseUnaudited: + type: integer + format: int32 + policyViolationsOperationalAudited: + type: integer + format: int32 + policyViolationsOperationalTotal: + type: integer + format: int32 + policyViolationsOperationalUnaudited: + type: integer + format: int32 + policyViolationsSecurityAudited: + type: integer + format: int32 + policyViolationsSecurityTotal: + type: integer + format: int32 + policyViolationsSecurityUnaudited: + type: integer + format: int32 + policyViolationsTotal: + type: integer + format: int32 + policyViolationsUnaudited: + type: integer + format: int32 + policyViolationsWarn: + type: integer + format: int32 + projects: + type: integer + format: int32 + suppressed: + type: integer + format: int32 + unassigned: + type: integer + format: int32 + vulnerabilities: + type: integer + format: int32 + vulnerableComponents: + type: integer + format: int32 + vulnerableProjects: + type: integer + format: int32 + required: + - firstOccurrence + - lastOccurrence + ProblemDetails: + type: object + description: An RFC 9457 problem object + properties: + detail: + type: string + description: Human-readable explanation specific to this occurrence of the + problem + example: Example detail + instance: + type: string + format: uri + description: Reference URI that identifies the specific occurrence of the + problem + example: https://api.example.org/foo/bar/example-instance + status: + type: integer + format: int32 + description: HTTP status code generated by the origin server for this occurrence + of the problem + example: 400 + title: + type: string + description: "Short, human-readable summary of the problem type" + example: Example title + type: + type: string + format: uri + description: A URI reference that identifies the problem type + example: https://api.example.org/foo/bar/example-problem + required: + - detail + - status + - title + Project: + type: object + properties: + accessTeams: + type: array + items: + $ref: "#/components/schemas/Team" + uniqueItems: true + writeOnly: true + active: + type: boolean + author: + type: string + authors: + type: array + items: + $ref: "#/components/schemas/OrganizationalContact" + bomRef: + type: string + children: + type: array + items: + $ref: "#/components/schemas/Project" + classifier: + type: string + enum: + - APPLICATION + - FRAMEWORK + - LIBRARY + - CONTAINER + - OPERATING_SYSTEM + - DEVICE + - FIRMWARE + - FILE + - PLATFORM + - DEVICE_DRIVER + - MACHINE_LEARNING_MODEL + - DATA + collectionLogic: + type: string + enum: + - AGGREGATE_DIRECT_CHILDREN + - AGGREGATE_DIRECT_CHILDREN_WITH_TAG + - AGGREGATE_LATEST_VERSION_CHILDREN + collectionTag: + $ref: "#/components/schemas/Tag" + cpe: + type: string + maxLength: 255 + minLength: 0 + pattern: "(cpe:2\\.3:[aho\\*\\-](:(((\\?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\\ + [\\\\\\*\\?!\"#$$%&'\\(\\)\\+,/:;<=>@\\[\\]\\^`\\{\\|}~]))+(\\?*|\\*?))|[\\\ + *\\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[\\*\\-]))(:(((\\\ + ?*|\\*?)([a-zA-Z0-9\\-\\._]|(\\\\[\\\\\\*\\?!\"#$$%&'\\(\\)\\+,/:;<=>@\\\ + [\\]\\^`\\{\\|}~]))+(\\?*|\\*?))|[\\*\\-])){4})|([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9\\\ + ._\\-~%]*){0,6})" + description: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + directDependencies: + type: string + externalReferences: + type: array + items: + $ref: "#/components/schemas/ExternalReference" + group: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + inactiveSince: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + readOnly: true + isLatest: + type: boolean + lastBomImport: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + lastBomImportFormat: + type: string + lastInheritedRiskScore: + type: number + format: double + lastVulnerabilityAnalysis: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + manufacturer: + $ref: "#/components/schemas/OrganizationalEntity" + metadata: + $ref: "#/components/schemas/ProjectMetadata" + metrics: + $ref: "#/components/schemas/ProjectMetrics" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + parent: + $ref: "#/components/schemas/Project" + publisher: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + purl: + type: string + maxLength: 1024 + minLength: 0 + supplier: + $ref: "#/components/schemas/OrganizationalEntity" + swidTagId: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + tags: + type: array + items: + $ref: "#/components/schemas/Tag" + uniqueItems: true + uuid: + type: string + format: uuid + version: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + versions: + type: array + items: + $ref: "#/components/schemas/ProjectVersion" + required: + - lastBomImport + - name + - uuid + ProjectMetadata: + type: object + properties: + authors: + type: array + items: + $ref: "#/components/schemas/OrganizationalContact" + supplier: + $ref: "#/components/schemas/OrganizationalEntity" + tools: + $ref: "#/components/schemas/Tools" + readOnly: true + ProjectMetrics: + type: object + properties: + components: + type: integer + format: int32 + critical: + type: integer + format: int32 + findingsAudited: + type: integer + format: int32 + findingsTotal: + type: integer + format: int32 + findingsUnaudited: + type: integer + format: int32 + firstOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + high: + type: integer + format: int32 + inheritedRiskScore: + type: number + format: double + lastOccurrence: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + low: + type: integer + format: int32 + medium: + type: integer + format: int32 + policyViolationsAudited: + type: integer + format: int32 + policyViolationsFail: + type: integer + format: int32 + policyViolationsInfo: + type: integer + format: int32 + policyViolationsLicenseAudited: + type: integer + format: int32 + policyViolationsLicenseTotal: + type: integer + format: int32 + policyViolationsLicenseUnaudited: + type: integer + format: int32 + policyViolationsOperationalAudited: + type: integer + format: int32 + policyViolationsOperationalTotal: + type: integer + format: int32 + policyViolationsOperationalUnaudited: + type: integer + format: int32 + policyViolationsSecurityAudited: + type: integer + format: int32 + policyViolationsSecurityTotal: + type: integer + format: int32 + policyViolationsSecurityUnaudited: + type: integer + format: int32 + policyViolationsTotal: + type: integer + format: int32 + policyViolationsUnaudited: + type: integer + format: int32 + policyViolationsWarn: + type: integer + format: int32 + suppressed: + type: integer + format: int32 + unassigned: + type: integer + format: int32 + vulnerabilities: + type: integer + format: int32 + vulnerableComponents: + type: integer + format: int32 + required: + - firstOccurrence + - lastOccurrence + ProjectProperty: + type: object + properties: + description: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + groupName: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + propertyName: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + propertyType: + type: string + enum: + - BOOLEAN + - INTEGER + - NUMBER + - STRING + - TIMESTAMP + - URL + - UUID + propertyValue: + type: string + maxLength: 1024 + minLength: 0 + pattern: "[\\P{Cc}]+" + required: + - groupName + - propertyName + - propertyType + ProjectVersion: + type: object + properties: + active: + type: boolean + uuid: + type: string + format: uuid + version: + type: string + Publisher: + type: object + properties: + uuid: + type: string + format: uuid + required: + - uuid + Repository: + type: object + properties: + authenticationRequired: + type: boolean + enabled: + type: boolean + identifier: + type: string + minLength: 1 + internal: + type: boolean + password: + type: string + resolutionOrder: + type: integer + format: int32 + type: + type: string + enum: + - MAVEN + - NPM + - GEM + - PYPI + - NUGET + - HEX + - COMPOSER + - CARGO + - GO_MODULES + - CPAN + - GITHUB + - HACKAGE + - NIXPKGS + - UNSUPPORTED + url: + type: string + minLength: 1 + username: + type: string + uuid: + type: string + format: uuid + required: + - authenticationRequired + - enabled + - identifier + - internal + - resolutionOrder + - type + - url + - uuid + RepositoryMetaComponent: + type: object + properties: + lastCheck: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + latestVersion: + type: string + name: + type: string + namespace: + type: string + repositoryType: + type: string + enum: + - MAVEN + - NPM + - GEM + - PYPI + - NUGET + - HEX + - COMPOSER + - CARGO + - GO_MODULES + - CPAN + - GITHUB + - HACKAGE + - NIXPKGS + - UNSUPPORTED + Score: + type: object + properties: + businessImpact: + type: string + enum: + - HIGH + - MEDIUM + - LOW + businessImpactScore: + type: number + format: double + likelihood: + type: string + enum: + - HIGH + - MEDIUM + - LOW + likelihoodScore: + type: number + format: double + technicalImpact: + type: string + enum: + - HIGH + - MEDIUM + - LOW + technicalImpactScore: + type: number + format: double + ServiceComponent: + type: object + properties: + authenticated: + type: boolean + bomRef: + type: string + children: + type: array + items: + $ref: "#/components/schemas/ServiceComponent" + crossesTrustBoundary: + type: boolean + data: + type: array + items: + $ref: "#/components/schemas/DataClassification" + description: + type: string + maxLength: 1024 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + endpoints: + type: array + items: + type: string + externalReferences: + type: array + items: + $ref: "#/components/schemas/ExternalReference" + group: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + lastInheritedRiskScore: + type: number + format: double + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + notes: + type: string + parent: + $ref: "#/components/schemas/ServiceComponent" + project: + $ref: "#/components/schemas/Project" + provider: + $ref: "#/components/schemas/OrganizationalEntity" + uuid: + type: string + format: uuid + version: + type: string + maxLength: 255 + minLength: 0 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + vulnerabilities: + type: array + items: + $ref: "#/components/schemas/Vulnerability" + required: + - name + - project + - uuid + Tag: + type: object + properties: + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + required: + - name + TagListResponseItem: + type: object + properties: + collectionProjectCount: + type: integer + format: int64 + description: Number of collection projects assigned to this tag + name: + type: string + description: Name of the tag + notificationRuleCount: + type: integer + format: int64 + description: Number of notification rules assigned to this tag + policyCount: + type: integer + format: int64 + description: Number of policies assigned to this tag + projectCount: + type: integer + format: int64 + description: Number of projects assigned to this tag + vulnerabilityCount: + type: integer + format: int64 + description: Number of vulnerabilities assigned to this tag + required: + - collectionProjectCount + - name + - notificationRuleCount + - policyCount + - projectCount + - vulnerabilityCount + TagOperationProblemDetails: + type: object + allOf: + - $ref: "#/components/schemas/ProblemDetails" + - type: object + properties: + errors: + type: object + additionalProperties: + type: string + description: "Errors encountered during the operation, grouped by tag\ + \ name" + description: "Errors encountered during the operation, grouped by tag\ + \ name" + required: + - detail + - status + - title + TaggedCollectionProjectListResponseItem: + type: object + properties: + name: + type: string + description: Name of the collection project + uuid: + type: string + format: uuid + description: UUID of the collection project + version: + type: string + description: Version of the collection project + required: + - name + - uuid + TaggedPolicyListResponseItem: + type: object + properties: + name: + type: string + description: Name of the policy + uuid: + type: string + format: uuid + description: UUID of the policy + required: + - name + - uuid + TaggedProjectListResponseItem: + type: object + properties: + name: + type: string + description: Name of the project + uuid: + type: string + format: uuid + description: UUID of the project + version: + type: string + description: Version of the project + required: + - name + - uuid + TaggedVulnerabilityListResponseItem: + type: object + properties: + source: + type: string + description: Source of the vulnerability + uuid: + type: string + format: uuid + description: UUID of the vulnerability + vulnId: + type: string + description: Vulnerability ID + required: + - source + - uuid + - vulnId + Team: + type: object + properties: + apiKeys: + type: array + items: + $ref: "#/components/schemas/ApiKey" + ldapUsers: + type: array + items: + $ref: "#/components/schemas/LdapUser" + managedUsers: + type: array + items: + $ref: "#/components/schemas/ManagedUser" + mappedLdapGroups: + type: array + items: + $ref: "#/components/schemas/MappedLdapGroup" + mappedOidcGroups: + type: array + items: + $ref: "#/components/schemas/MappedOidcGroup" + name: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + oidcUsers: + type: array + items: + $ref: "#/components/schemas/OidcUser" + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + uuid: + type: string + format: uuid + required: + - name + - uuid + TeamAlreadyExistsProblemDetails: + type: object + properties: + detail: + type: string + description: Human-readable explanation specific to this occurrence of the + problem + example: Example detail + instance: + type: string + format: uri + description: Reference URI that identifies the specific occurrence of the + problem + example: https://api.example.org/foo/bar/example-instance + status: + type: integer + format: int32 + description: HTTP status code generated by the origin server for this occurrence + of the problem + example: 400 + teamName: + type: string + description: Name of the existing team + teamUuid: + type: string + format: uuid + description: UUID of the existing team + title: + type: string + description: "Short, human-readable summary of the problem type" + example: Example title + type: + type: string + format: uri + description: A URI reference that identifies the problem type + example: https://api.example.org/foo/bar/example-problem + required: + - detail + - status + - title + TeamPermissionsSetRequest: + type: object + properties: + permissions: + type: array + items: + type: string + enum: + - BOM_UPLOAD + - VIEW_PORTFOLIO + - PORTFOLIO_ACCESS_CONTROL_BYPASS + - PORTFOLIO_MANAGEMENT + - PORTFOLIO_MANAGEMENT_CREATE + - PORTFOLIO_MANAGEMENT_READ + - PORTFOLIO_MANAGEMENT_UPDATE + - PORTFOLIO_MANAGEMENT_DELETE + - VIEW_VULNERABILITY + - VULNERABILITY_ANALYSIS + - VULNERABILITY_ANALYSIS_CREATE + - VULNERABILITY_ANALYSIS_READ + - VULNERABILITY_ANALYSIS_UPDATE + - VIEW_POLICY_VIOLATION + - VULNERABILITY_MANAGEMENT + - VULNERABILITY_MANAGEMENT_CREATE + - VULNERABILITY_MANAGEMENT_READ + - VULNERABILITY_MANAGEMENT_UPDATE + - VULNERABILITY_MANAGEMENT_DELETE + - POLICY_VIOLATION_ANALYSIS + - ACCESS_MANAGEMENT + - ACCESS_MANAGEMENT_CREATE + - ACCESS_MANAGEMENT_READ + - ACCESS_MANAGEMENT_UPDATE + - ACCESS_MANAGEMENT_DELETE + - SECRET_MANAGEMENT + - SECRET_MANAGEMENT_CREATE + - SECRET_MANAGEMENT_UPDATE + - SECRET_MANAGEMENT_DELETE + - SYSTEM_CONFIGURATION + - SYSTEM_CONFIGURATION_CREATE + - SYSTEM_CONFIGURATION_READ + - SYSTEM_CONFIGURATION_UPDATE + - SYSTEM_CONFIGURATION_DELETE + - PROJECT_CREATION_UPLOAD + - POLICY_MANAGEMENT + - POLICY_MANAGEMENT_CREATE + - POLICY_MANAGEMENT_READ + - POLICY_MANAGEMENT_UPDATE + - POLICY_MANAGEMENT_DELETE + - TAG_MANAGEMENT + - TAG_MANAGEMENT_DELETE + - VIEW_BADGES + uniqueItems: true + team: + type: string + minLength: 1 + required: + - permissions + - team + TeamSelfResponse: + type: object + properties: + name: + type: string + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + uuid: + type: string + format: uuid + TeamsSetRequest: + type: object + properties: + teams: + type: array + items: + type: string + uniqueItems: true + username: + type: string + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + required: + - teams + - username + Tools: + type: object + properties: + components: + type: array + items: + $ref: "#/components/schemas/Component" + services: + type: array + items: + $ref: "#/components/schemas/ServiceComponent" + UpdateNotificationPublisherRequest: + type: object + properties: + description: + type: string + extensionName: + type: string + minLength: 1 + name: + type: string + minLength: 1 + template: + type: string + templateMimeType: + type: string + uuid: + type: string + format: uuid + required: + - extensionName + - name + - uuid + UpdateNotificationRuleRequest: + type: object + properties: + enabled: + type: boolean + filterExpression: + type: string + maxLength: 2048 + minLength: 0 + level: + type: string + enum: + - INFORMATIONAL + - WARNING + - ERROR + logSuccessfulPublish: + type: boolean + name: + type: string + minLength: 1 + notifyChildren: + type: boolean + notifyOn: + type: array + items: + type: string + enum: + - CONFIGURATION + - DATASOURCE_MIRRORING + - REPOSITORY + - INTEGRATION + - FILE_SYSTEM + - ANALYZER + - NEW_VULNERABILITY + - NEW_VULNERABLE_DEPENDENCY + - VULNERABILITY_RETRACTED + - PROJECT_AUDIT_CHANGE + - BOM_CONSUMED + - BOM_PROCESSED + - BOM_PROCESSING_FAILED + - BOM_VALIDATION_FAILED + - VEX_CONSUMED + - VEX_PROCESSED + - POLICY_VIOLATION + - PROJECT_CREATED + - PROJECT_VULN_ANALYSIS_COMPLETE + - USER_CREATED + - USER_DELETED + - NEW_VULNERABILITIES_SUMMARY + - NEW_POLICY_VIOLATIONS_SUMMARY + uniqueItems: true + publisherConfig: + type: string + scheduleCron: + type: string + scheduleSkipUnchanged: + type: boolean + scope: + type: string + enum: + - SYSTEM + - PORTFOLIO + tags: + type: array + items: + $ref: "#/components/schemas/Tag" + uniqueItems: true + uuid: + type: string + format: uuid + required: + - level + - name + - scope + - uuid + User: + type: object + properties: + email: + type: string + maxLength: 255 + minLength: 0 + pattern: "[\\P{Cc}]+" + permissions: + type: array + items: + $ref: "#/components/schemas/Permission" + teams: + type: array + items: + $ref: "#/components/schemas/Team" + username: + type: string + maxLength: 255 + minLength: 1 + pattern: "[\\P{Cc}]+" + required: + - username + UserPermissionsSetRequest: + type: object + properties: + permissions: + type: array + items: + type: string + enum: + - BOM_UPLOAD + - VIEW_PORTFOLIO + - PORTFOLIO_ACCESS_CONTROL_BYPASS + - PORTFOLIO_MANAGEMENT + - PORTFOLIO_MANAGEMENT_CREATE + - PORTFOLIO_MANAGEMENT_READ + - PORTFOLIO_MANAGEMENT_UPDATE + - PORTFOLIO_MANAGEMENT_DELETE + - VIEW_VULNERABILITY + - VULNERABILITY_ANALYSIS + - VULNERABILITY_ANALYSIS_CREATE + - VULNERABILITY_ANALYSIS_READ + - VULNERABILITY_ANALYSIS_UPDATE + - VIEW_POLICY_VIOLATION + - VULNERABILITY_MANAGEMENT + - VULNERABILITY_MANAGEMENT_CREATE + - VULNERABILITY_MANAGEMENT_READ + - VULNERABILITY_MANAGEMENT_UPDATE + - VULNERABILITY_MANAGEMENT_DELETE + - POLICY_VIOLATION_ANALYSIS + - ACCESS_MANAGEMENT + - ACCESS_MANAGEMENT_CREATE + - ACCESS_MANAGEMENT_READ + - ACCESS_MANAGEMENT_UPDATE + - ACCESS_MANAGEMENT_DELETE + - SECRET_MANAGEMENT + - SECRET_MANAGEMENT_CREATE + - SECRET_MANAGEMENT_UPDATE + - SECRET_MANAGEMENT_DELETE + - SYSTEM_CONFIGURATION + - SYSTEM_CONFIGURATION_CREATE + - SYSTEM_CONFIGURATION_READ + - SYSTEM_CONFIGURATION_UPDATE + - SYSTEM_CONFIGURATION_DELETE + - PROJECT_CREATION_UPLOAD + - POLICY_MANAGEMENT + - POLICY_MANAGEMENT_CREATE + - POLICY_MANAGEMENT_READ + - POLICY_MANAGEMENT_UPDATE + - POLICY_MANAGEMENT_DELETE + - TAG_MANAGEMENT + - TAG_MANAGEMENT_DELETE + - VIEW_BADGES + uniqueItems: true + username: + type: string + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + required: + - permissions + - username + VexSubmitRequest: + type: object + properties: + project: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + projectName: + type: string + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + projectVersion: + type: string + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + vex: + type: string + pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" + required: + - project + - projectName + - projectVersion + - vex + ViolationAnalysis: + type: object + properties: + analysisComments: + type: array + items: + $ref: "#/components/schemas/ViolationAnalysisComment" + analysisState: + type: string + enum: + - APPROVED + - REJECTED + - NOT_SET + isSuppressed: + type: boolean + violationAnalysisState: + type: string + enum: + - APPROVED + - REJECTED + - NOT_SET + writeOnly: true + required: + - analysisState + ViolationAnalysisComment: + type: object + properties: + comment: + type: string + commenter: + type: string + timestamp: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + required: + - comment + - timestamp + ViolationAnalysisRequest: + type: object + properties: + analysisState: + type: string + enum: + - APPROVED + - REJECTED + - NOT_SET + comment: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + component: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + isSuppressed: + type: boolean + writeOnly: true + policyViolation: + type: string + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" + suppressed: + type: boolean + required: + - component + - policyViolation + VisibleTeams: + type: object + properties: + name: + type: string + uuid: + type: string + format: uuid + Vulnerability: + type: object + properties: + affectedActiveProjectCount: + type: integer + format: int32 + affectedComponents: + type: array + items: + $ref: "#/components/schemas/AffectedComponent" + affectedInactiveProjectCount: + type: integer + format: int32 + affectedProjectCount: + type: integer + format: int32 + aliases: + type: array + items: + $ref: "#/components/schemas/VulnerabilityAlias" + components: + type: array + items: + $ref: "#/components/schemas/Component" + created: + type: string + format: date-time + credits: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + cvssV2BaseScore: + type: number + cvssV2ExploitabilitySubScore: + type: number + cvssV2ImpactSubScore: + type: number + cvssV2Vector: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + cvssV3BaseScore: + type: number + cvssV3ExploitabilitySubScore: + type: number + cvssV3ImpactSubScore: + type: number + cvssV3Vector: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + cvssV4Score: + type: number + cvssV4Vector: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + cwes: + type: array + items: + $ref: "#/components/schemas/Cwe" + description: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + detail: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + epss: + $ref: "#/components/schemas/Epss" + epssPercentile: + type: number + epssScore: + type: number + friendlyVulnId: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + owaspRRBusinessImpactScore: + type: number + owaspRRLikelihoodScore: + type: number + owaspRRTechnicalImpactScore: + type: number + owaspRRVector: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + patchedVersions: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + published: + type: string + format: date-time + recommendation: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + references: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + serviceComponents: + type: array + items: + $ref: "#/components/schemas/ServiceComponent" + severity: + type: string + enum: + - CRITICAL + - HIGH + - MEDIUM + - LOW + - INFO + - UNASSIGNED + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + source: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + subTitle: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + tags: + type: array + items: + $ref: "#/components/schemas/Tag" + uniqueItems: true + title: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + updated: + type: string + format: date-time + uuid: + type: string + format: uuid + vulnId: + type: string + maxLength: 255 + minLength: 1 + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]*$" + vulnerableVersions: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + required: + - friendlyVulnId + - source + - uuid + - vulnId + VulnerabilityAlias: + type: object + properties: + csafId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + cveId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + ghsaId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + gsdId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + internalId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + osvId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + snykId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + sonatypeId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + vulnDbId: + type: string + pattern: "^[\\p{IsWhite_Space}\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\n\\r\\t]*$" + VulnerabilityMetrics: + type: object + properties: + count: + type: integer + format: int32 + measuredAt: + type: integer + format: int64 + description: UNIX epoch timestamp in milliseconds + month: + type: integer + format: int32 + year: + type: integer + format: int32 + required: + - measuredAt + WorkflowState: + type: object + properties: + failureReason: + type: string + parent: + $ref: "#/components/schemas/WorkflowState" + startedAt: + type: string + format: date-time + status: + type: string + enum: + - PENDING + - TIMED_OUT + - COMPLETED + - FAILED + - CANCELLED + - NOT_APPLICABLE + step: + type: string + enum: + - BOM_CONSUMPTION + - BOM_PROCESSING + - VULN_ANALYSIS + - REPO_META_ANALYSIS + - POLICY_EVALUATION + - METRICS_UPDATE + - POLICY_BUNDLE_SYNC + - PROJECT_CLONE + token: + type: string + format: uuid + updatedAt: + type: string + format: date-time + required: + - status + - step + - token + securitySchemes: + ApiKeyAuth: + in: header + name: X-Api-Key + type: apiKey + ApiKeyQueryAuth: + in: query + name: apiKey + type: apiKey + BearerAuth: + scheme: Bearer + type: http diff --git a/docs/reference/api/openapi-v2.yaml b/docs/reference/api/openapi-v2.yaml new file mode 100644 index 00000000..aa1a4021 --- /dev/null +++ b/docs/reference/api/openapi-v2.yaml @@ -0,0 +1,3813 @@ +openapi: 3.0.3 +info: + title: OWASP Dependency-Track + description: |- + # REST API of OWASP Dependency-Track + + ## Pagination + + This API implements token-based pagination. + Collection responses have the following structure: + + ```json + { + "items": [...], + "next_page_token": "abcdefg", + "total": { + "count": 100, + "type": "EXACT" + } + } + ``` + + `next_page_token` is present when more items exist, and absent otherwise. + To fetch the next page, pass it as the `page_token` query parameter. + + To navigate backwards, clients should keep track of previous page tokens + as they paginate through collections. The API does *not* provide + backward navigation! + + Collections that support sorting will only consider the `sort_by` + and `sort_direction` query parameters for the request of the first + page. For subsequent pages, sorting preferences are bound to the + page token. + + Page tokens are opaque strings. Clients should not try to interpret + or generate them. Their format may change without notice. + + The `total` object discloses how many items exist in the collection + *across all pages*. Because counting is expensive, some collections + that hold *a lot* of items may return partial counts (type `AT_LEAST`) + instead of exact counts (type `EXACT`). Which type to expect is usually + documented in the operation's description. + + ## Sorting + + Items in a collection can be sorted using the `sort_by` and `sort_direction` + query parameters. Which fields are sortable is documented in the respective + operation's description. + + Note that if no sortable fields are documented for an operation, + sorting is not supported *at all*. + contact: + name: The Dependency-Track Authors + url: https://github.com/DependencyTrack/dependency-track + email: dependencytrack@owasp.org + license: + name: Apache-2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 2.0.0 +servers: +- url: /api/v2 +security: +- apiKeyAuth: [] +- bearerAuth: [] +tags: +- name: Advisories + description: Endpoints related to advisories +- name: Components + description: Endpoints related to components +- name: Extensions + description: Endpoints related to extensions +- name: Projects + description: Endpoints related to projects +- name: Secrets + description: Endpoints related to secrets +- name: Task Queues + description: Endpoints related to task queue management +- name: Vulnerability Policies + description: Endpoints related to vulnerability policies +- name: Workflows + description: Endpoints related to workflows +paths: + /advisories: + get: + tags: + - Advisories + summary: List all advisories + description: |- + Returns a paginated list of advisories, sorted by name in ascending order. + + Always reports `EXACT` total counts. + + Requires the `VULNERABILITY_MANAGEMENT` or `VULNERABILITY_MANAGEMENT_READ` permission. + operationId: listAdvisories + parameters: + - name: format + in: query + description: "Filter advisories by format (e.g., CSAF)" + required: false + schema: + type: string + - name: search_text + in: query + description: Search text to filter advisories + required: false + schema: + type: string + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + responses: + "200": + description: Paginated list of advisories + content: + application/json: + schema: + $ref: "#/components/schemas/list-advisories-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - Advisories + summary: Upload advisory document + description: Requires permission VULNERABILITY_ANALYSIS_CREATE + operationId: uploadAdvisory + parameters: + - name: format + in: query + description: The format of the advisory document + required: true + schema: + type: string + enum: + - CSAF + requestBody: + content: + multipart/form-data: + schema: + required: + - file + type: object + properties: + file: + type: string + description: The advisory document file to upload + format: binary + required: true + responses: + "201": + description: Advisory Uploaded + headers: + Location: + description: URL of the created advisory + schema: + type: string + format: uri + content: + application/json: + schema: + $ref: "#/components/schemas/upload-advisory-response" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "500": + description: Internal Server Error + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + default: + $ref: "#/components/responses/generic-error" + /advisories/{id}: + get: + tags: + - Advisories + summary: Get advisory details + description: Requires permission VULNERABILITY_ANALYSIS_READ + operationId: getAdvisoryById + parameters: + - name: id + in: path + description: The ID of the advisory to view + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Advisory details + content: + application/json: + schema: + $ref: "#/components/schemas/get-advisory-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + delete: + tags: + - Advisories + summary: Delete advisory + description: Requires permission VULNERABILITY_ANALYSIS_UPDATE + operationId: deleteAdvisory + parameters: + - name: id + in: path + description: The ID of the advisory to delete + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Advisory Deleted + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /advisories/{id}/mark-seen: + post: + tags: + - Advisories + summary: Mark advisory as seen + description: Requires permission VULNERABILITY_ANALYSIS_UPDATE + operationId: markAdvisoryAsSeen + parameters: + - name: id + in: path + description: The ID of the advisory to mark as seen + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Advisory Marked as Seen + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /components: + get: + tags: + - Components + summary: List all components + description: |- + Retrieves a list of all components matching the provided filter criteria. + + Text filters are case-insensitive. + + ### Sortable fields + + Sorting is supported for the following fields: + + * `name` + * `version` + * `group` + * `purl` + * `cpe` + * `last_inherited_risk_score` + + Requires permission VIEW_PORTFOLIO + operationId: listComponents + parameters: + - name: group_contains + in: query + description: Filter by group (substring match) + schema: + type: string + - name: name_contains + in: query + description: Filter by name (substring match) + schema: + type: string + - name: version_contains + in: query + description: Filter by version (substring match) + schema: + type: string + - name: purl_prefix + in: query + description: |- + Filter by PURL (prefix match). + + Must be a valid PURL, with at least `pkg:/` populated. + schema: + type: string + - name: cpe + in: query + description: |- + Filter by CPE (exact match). + + Must be a valid CPE. + schema: + type: string + - name: swid_tag_id_contains + in: query + description: Filter by SWID Tag ID (substring match) + schema: + type: string + - name: hash_type + in: query + description: The hash type to filter by + schema: + type: string + enum: + - MD5 + - SHA1 + - SHA_256 + - SHA_384 + - SHA_512 + - SHA3_256 + - SHA3_384 + - SHA3_512 + - BLAKE2B_256 + - BLAKE2B_384 + - BLAKE2B_512 + - BLAKE3 + - name: hash + in: query + description: |- + Filter by hash value (exact match). + + Requires `hash_type` to be set. + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: sort_direction + in: query + schema: + $ref: "#/components/schemas/sort-direction" + - name: sort_by + in: query + description: Field to sort by. Refer to the operation description for information + about which fields are sortable. + schema: + maxLength: 255 + minLength: 1 + type: string + responses: + "200": + description: A list of components matching the provided filters + content: + application/json: + schema: + $ref: "#/components/schemas/list-components-response" + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/json-schema-validation-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - Components + summary: Creates a new component for the project + description: Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_UPDATE + operationId: createComponent + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/create-component-request" + required: true + responses: + "201": + description: Component Created + headers: + Location: + description: URL of the created component + schema: + type: string + format: uri + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + /csaf-aggregators: + get: + tags: + - CSAF + summary: List CSAF aggregators + description: |- + Returns a paginated list of CSAF aggregators, sorted by namespace in ascending order. + + Always reports `EXACT` total counts. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listCsafAggregators + parameters: + - name: search_text + in: query + description: "Search text to filter aggregators. Has \"contains\" semantics\ + \ on the `namespace`, `name`, and `url` fields. Is treated case-insensitively." + schema: + type: string + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + responses: + "200": + description: Paginated list of CSAF aggregators + content: + application/json: + schema: + $ref: "#/components/schemas/list-csaf-aggregators-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - CSAF + summary: Create a new CSAF aggregator + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_CREATE` + permission. + operationId: createCsafAggregator + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/create-csaf-aggregator-request" + required: true + responses: + "201": + description: CSAF aggregator created + headers: + Location: + description: URL of the created aggregator + schema: + type: string + format: uri + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-aggregator" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "409": + description: A CSAF aggregator with the specified URL already exists + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + default: + $ref: "#/components/responses/generic-error" + /csaf-aggregators/{id}: + get: + tags: + - CSAF + summary: Get a CSAF aggregator + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` + permission. + operationId: getCsafAggregator + parameters: + - name: id + in: path + description: The ID of the CSAF aggregator + required: true + schema: + type: string + format: uuid + responses: + "200": + description: CSAF aggregator + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-aggregator" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + delete: + tags: + - CSAF + summary: Delete a CSAF aggregator + description: |- + **Warning**: Deleting an aggregator will also delete all providers + that were discovered from it. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_DELETE` permission. + operationId: deleteCsafAggregator + parameters: + - name: id + in: path + description: The ID of the CSAF aggregator to delete + required: true + schema: + type: string + format: uuid + responses: + "204": + description: CSAF source deleted + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + patch: + tags: + - CSAF + summary: Update a CSAF aggregator + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` + permission. + operationId: updateCsafAggregator + parameters: + - name: id + in: path + description: The ID of the CSAF aggregator to update + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-csaf-aggregator-request" + required: true + responses: + "200": + description: CSAF aggregator updated + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-aggregator" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /csaf-aggregators/{id}/provider-discovery: + post: + tags: + - CSAF + summary: Trigger CSAF provider discovery for an aggregator + description: |- + Triggers the discovery of CSAF providers from a given aggregator. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` permission. + operationId: triggerCsafProviderDiscovery + parameters: + - name: id + in: path + description: The ID of the CSAF aggregator to trigger provider discovery for + required: true + schema: + type: string + format: uuid + responses: + "202": + description: Discovery triggered + headers: + Location: + description: URL of the aggregator + schema: + type: string + format: uri + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + /csaf-providers: + get: + tags: + - CSAF + summary: List CSAF provider + description: |- + Returns a paginated list of CSAF providers, sorted by namespace in ascending order. + + Always reports `EXACT` total counts. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listCsafProviders + parameters: + - name: discovered + in: query + description: "Whether to only include providers that were discovered from\ + \ aggregators (`true`), or those that weren't (`false`). Omitting this parameter\ + \ includes all providers." + schema: + type: boolean + - name: search_text + in: query + description: |- + Search text to filter providers. + Has "contains" semantics on the `namespace`, `name`, and `url` fields. + Is treated case-insensitively. + schema: + type: string + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + responses: + "200": + description: Paginated list of CSAF providers + content: + application/json: + schema: + $ref: "#/components/schemas/list-csaf-providers-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - CSAF + summary: Create a new CSAF provider + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_CREATE` + permission. + operationId: createCsafProvider + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/create-csaf-provider-request" + required: true + responses: + "201": + description: CSAF provider created + headers: + Location: + description: URL of the created provider + schema: + type: string + format: uri + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-provider" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "409": + description: A CSAF provider with the specified URL already exists + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + default: + $ref: "#/components/responses/generic-error" + /csaf-providers/{id}: + get: + tags: + - CSAF + summary: Get a CSAF provider + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` + permission. + operationId: getCsafProvider + parameters: + - name: id + in: path + description: The ID of the CSAF provider + required: true + schema: + type: string + format: uuid + responses: + "200": + description: CSAF provider + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-provider" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + delete: + tags: + - CSAF + summary: Delete a CSAF provider + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_DELETE` + permission. + operationId: deleteCsafProvider + parameters: + - name: id + in: path + description: The ID of the CSAF provider to delete + required: true + schema: + type: string + format: uuid + responses: + "204": + description: CSAF provider deleted + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + patch: + tags: + - CSAF + summary: Update a CSAF provider + description: Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` + permission. + operationId: updateCsafProvider + parameters: + - name: id + in: path + description: The ID of the CSAF provider to update + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-csaf-provider-request" + required: true + responses: + "200": + description: CSAF provider updated + content: + application/json: + schema: + $ref: "#/components/schemas/csaf-provider" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /extension-points: + get: + tags: + - Extensions + summary: List all extension points + description: |- + Returns a list of extension points, sorted by name in ascending order. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listExtensionPoints + responses: + "200": + description: List of extension points + content: + application/json: + schema: + $ref: "#/components/schemas/list-extension-points-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + /extension-points/{extensionPointName}/extensions: + get: + tags: + - Extensions + summary: List all extensions + description: |- + Returns a list of extensions for a given extension point, sorted by name in ascending order. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listExtensions + parameters: + - name: extensionPointName + in: path + description: Name of the extension point + required: true + schema: + type: string + responses: + "200": + description: List of extensions + content: + application/json: + schema: + $ref: "#/components/schemas/list-extensions-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /extension-points/{extensionPointName}/extensions/{extensionName}/config: + get: + tags: + - Extensions + summary: Get extension configuration + description: |- + Returns the configuration of an extension. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: getExtensionConfig + parameters: + - name: extensionPointName + in: path + description: Name of the extension point + required: true + schema: + type: string + - name: extensionName + in: path + description: Name of the extension + required: true + schema: + type: string + responses: + "200": + description: List of extensions + content: + application/json: + schema: + $ref: "#/components/schemas/get-extension-config-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + put: + tags: + - Extensions + summary: Update extension configuration + description: |- + Updates the configuration of an extension. + + **Do not use clear text credentials in the supplied config**. + Fields annotated with `x-secret-ref` in the config schema expect + a name of a managed secret, which is resolved internally by the API. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` permission. + operationId: updateExtensionConfig + parameters: + - name: extensionPointName + in: path + description: Name of the extension point + required: true + schema: + type: string + - name: extensionName + in: path + description: Name of the extension + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-extension-config-request" + required: true + responses: + "204": + description: Configuration updated + "304": + description: Not Modified + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/json-schema-validation-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /extension-points/{extensionPointName}/extensions/{extensionName}/config-schema: + get: + tags: + - Extensions + summary: Get extension configuration schema + description: |- + Returns the JSON schema for an extension's configuration. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: getExtensionConfigSchema + parameters: + - name: extensionPointName + in: path + description: Name of the extension point + required: true + schema: + type: string + - name: extensionName + in: path + description: Name of the extension + required: true + schema: + type: string + responses: + "200": + description: Extension config schema + content: + application/json: + schema: + $ref: "#/components/schemas/extension-config-schema" + "204": + description: Extension has no config schema + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /extension-points/{extensionPointName}/extensions/{extensionName}/test: + post: + tags: + - Extensions + summary: Test extension + description: |- + Tests an extension. + + If the extension is configurable (i.e. `/config-schema` returns status `200`), + a valid configuration **must** be provided in the test request. + The configuration is validated against the applicable JSON schema. + + **Do not use clear text credentials in the supplied config**. + Fields annotated with `x-secret-ref` in the config schema expect + a name of a managed secret, which is resolved internally by the API. + + Test results contain one or more checks, each of which can have a status of + `PASSED`, `FAILED`, or `SKIPPED`. If *at least one* check is `FAILED`, + the entire test should be considered `FAILED`. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` permission. + operationId: testExtension + parameters: + - name: extensionPointName + in: path + description: Name of the extension point + required: true + schema: + type: string + - name: extensionName + in: path + description: Name of the extension + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/test-extension-request" + required: true + responses: + "200": + description: Test result + content: + application/json: + schema: + $ref: "#/components/schemas/test-extension-response" + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/json-schema-validation-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /projects/{uuid}/advisories: + get: + tags: + - Projects + summary: List advisories affecting a project + description: |- + Returns a paginated list of advisories affecting the project, sorted by ID in ascending order. + + Requires the `VIEW_VULNERABILITY` permission. + operationId: listAdvisoriesForProject + parameters: + - name: uuid + in: path + description: The UUID of the project + required: true + schema: + type: string + format: uuid + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + responses: + "200": + description: Paginated list of advisories affecting the project + content: + application/json: + schema: + $ref: "#/components/schemas/list-project-advisories-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /projects/{uuid}/advisories/{advisoryId}/findings: + get: + tags: + - Projects + summary: List findings by project and advisory + description: Requires permission VIEW_VULNERABILITY + operationId: getFindingsByProjectAdvisory + parameters: + - name: uuid + in: path + description: The UUID of the project + required: true + schema: + type: string + format: uuid + - name: advisoryId + in: path + description: The advisory ID + required: true + schema: + type: string + format: uuid + responses: + "200": + description: List of findings for the project and advisory + content: + application/json: + schema: + $ref: "#/components/schemas/list-project-advisory-findings-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /projects/{uuid}/clone: + post: + tags: + - Projects + summary: Clones a given project. + description: Requires permission PORTFOLIO_MANAGEMENT + operationId: cloneProject + parameters: + - name: uuid + in: path + description: The UUID of the project to clone + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/clone-project-request" + responses: + "201": + description: Project cloned + headers: + Location: + description: URL of the cloned project + schema: + type: string + format: uri + content: + application/json: + schema: + $ref: "#/components/schemas/clone-project-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + /projects/{uuid}/components: + get: + tags: + - Projects + summary: Retrieves a list of all components for a given project. + description: Requires permission VIEW_PORTFOLIO + operationId: listProjectComponents + parameters: + - name: uuid + in: path + description: The UUID of the project to retrieve components for + required: true + schema: + type: string + format: uuid + - name: only_outdated + in: query + description: Optionally exclude recent components so only outdated components + are returned + schema: + type: boolean + - name: only_direct + in: query + description: Optionally exclude transitive dependencies so only direct dependencies + are returned + schema: + type: boolean + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + responses: + "200": + description: A list of all components for a given project + content: + application/json: + schema: + $ref: "#/components/schemas/list-project-components-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /task-queues/{type}: + get: + tags: + - Task Queues + summary: List task queues + description: |- + Returns a paginated list of task queues of the given type. + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listTaskQueues + parameters: + - name: type + in: path + description: Type of task queues to list + required: true + schema: + $ref: "#/components/schemas/task-queue-type" + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + responses: + "200": + description: Paginated list of task queues + content: + application/json: + schema: + $ref: "#/components/schemas/list-task-queues-response" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + /task-queues/{type}/{name}: + patch: + tags: + - Task Queues + summary: Update a task queue + description: |- + Updates the status and/or capacity of a task queue. + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` permission. + operationId: updateTaskQueue + parameters: + - name: type + in: path + description: Type of the task queue + required: true + schema: + $ref: "#/components/schemas/task-queue-type" + - name: name + in: path + description: Name of the task queue + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-task-queue-request" + required: true + responses: + "204": + description: Task queue updated + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /secrets: + get: + tags: + - Secrets + summary: List secret metadata + description: |- + Returns a paginated list of secret metadata. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listSecretMetadata + parameters: + - name: q + in: query + description: Optional search text to filter secrets by. Filtering uses case-insensitive + "starts with" semantics on the secret name. + schema: + type: string + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + responses: + "200": + description: Paginated list of secret metadata + content: + application/json: + schema: + $ref: "#/components/schemas/list-secrets-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - Secrets + summary: Create a secret + description: |- + Creates a new secret. + + Requires the `SECRET_MANAGEMENT` or `SECRET_MANAGEMENT_CREATE` permission. + + Administrators can configure the secret manager to be read-only. + In that case, create requests will be rejected with status code `400`. + operationId: createSecret + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/create-secret-request" + required: true + responses: + "201": + description: Secret created + headers: + Location: + description: URL of the created secret + schema: + type: string + format: uri + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + /secrets/{name}: + get: + tags: + - Secrets + summary: Get secret metadata + description: |- + Returns metadata about a given secret. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: getSecretMetadata + parameters: + - name: name + in: path + description: The name of the secret + required: true + schema: + $ref: "#/components/schemas/secret-name" + responses: + "200": + description: Secret metadata + content: + application/json: + schema: + $ref: "#/components/schemas/secret-metadata" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + delete: + tags: + - Secrets + summary: Delete a secret + description: |- + Deletes an existing secret. + + Requires the `SECRET_MANAGEMENT` or `SECRET_MANAGEMENT_DELETE` permission. + + Administrators can configure the secret manager to be read-only. + In that case, delete requests will be rejected with status code `400`. + operationId: deleteSecret + parameters: + - name: name + in: path + description: The name of the secret + required: true + schema: + $ref: "#/components/schemas/secret-name" + responses: + "204": + description: Secret deleted + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + patch: + tags: + - Secrets + summary: Update a secret + description: |- + Updates an existing secret. + + Requires the `SECRET_MANAGEMENT` or `SECRET_MANAGEMENT_UPDATE` permission. + + Administrators can configure the secret manager to be read-only. + In that case, update requests will be rejected with status code `400`. + operationId: updateSecret + parameters: + - name: name + in: path + description: The name of the secret + required: true + schema: + $ref: "#/components/schemas/secret-name" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-secret-request" + required: true + responses: + "204": + description: Secret updated + "304": + description: Not modified + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /vuln-policies: + get: + tags: + - Vulnerability Policies + summary: List vulnerability policies + description: |- + Returns a paginated list of vulnerability policies, sorted by priority + (ascending) and name (ascending). + + Reports `EXACT` total counts for up to 500 items, and `AT_LEAST` past that. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_READ`. + operationId: listVulnPolicies + parameters: + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: name + in: query + description: "Filter by name (partial match, case-insensitive)" + schema: + type: string + responses: + "200": + description: Paginated list of vulnerability policies + content: + application/json: + schema: + $ref: "#/components/schemas/list-vuln-policies-response" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - Vulnerability Policies + summary: Create a vulnerability policy + description: |- + Creates a user-managed vulnerability policy. + + CEL conditions are compiled server-side. On compilation failure, + a 400 response with structured error details is returned. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_CREATE`. + operationId: createVulnPolicy + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/create-vuln-policy-request" + required: true + responses: + "201": + description: Policy created + headers: + Location: + description: URL of the created policy + schema: + type: string + format: uri + content: + application/json: + schema: + required: + - uuid + type: object + properties: + uuid: + type: string + format: uuid + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-vuln-policy-condition-problem-details" + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + /vuln-policies/{uuid}: + get: + tags: + - Vulnerability Policies + summary: Get a vulnerability policy + description: |- + Returns a vulnerability policy. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_READ`. + operationId: getVulnPolicy + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy + required: true + schema: + type: string + format: uuid + responses: + "200": + description: The vulnerability policy + content: + application/json: + schema: + $ref: "#/components/schemas/get-vuln-policy-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + put: + tags: + - Vulnerability Policies + summary: Replace a vulnerability policy + description: |- + Replaces a user-managed vulnerability policy with the provided data. + + Policies managed by a bundle can not be modified. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_UPDATE`. + operationId: updateVulnPolicy + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy + required: true + schema: + type: string + format: uuid + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/update-vuln-policy-request" + required: true + responses: + "204": + description: Policy updated + "400": + description: Bad Request + content: + application/problem+json: + schema: + anyOf: + - $ref: "#/components/schemas/invalid-vuln-policy-condition-problem-details" + - $ref: "#/components/schemas/invalid-request-problem-details" + - $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + "409": + $ref: "#/components/responses/generic-conflict-error" + default: + $ref: "#/components/responses/generic-error" + delete: + tags: + - Vulnerability Policies + summary: Delete a vulnerability policy + description: |- + Deletes a user-managed vulnerability policy. + + Policies managed by a bundle can not be deleted. + + Analysis records matched by this policy are reset upon deletion. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_DELETE`. + operationId: deleteVulnPolicy + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Policy deleted + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /vuln-policy-bundles: + get: + tags: + - Vulnerability Policies + summary: List vulnerability policy bundles + description: |- + Returns a list of vulnerability policy bundles. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_READ`. + operationId: listVulnPolicyBundles + responses: + "200": + description: List of vulnerability policy bundles + content: + application/json: + schema: + $ref: "#/components/schemas/list-vuln-policy-bundles-response" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + /vuln-policy-bundles/{uuid}: + delete: + tags: + - Vulnerability Policies + summary: Delete a vulnerability policy bundle + description: |- + Deletes a vulnerability policy bundle and cascade-deletes all associated policies. + + Analysis records matched by deleted policies are reset. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_DELETE`. + operationId: deleteVulnPolicyBundle + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy bundle + required: true + schema: + type: string + format: uuid + responses: + "204": + description: Bundle deleted + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /vuln-policy-bundles/{uuid}/sync: + get: + tags: + - Vulnerability Policies + summary: Get bundle synchronization status + description: |- + Returns the status of the most recent synchronization for a given + vulnerability policy bundle. + + Returns 404 if no synchronization has been triggered yet. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_READ`. + operationId: getVulnPolicyBundleSyncStatus + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy bundle + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Synchronization status + content: + application/json: + schema: + $ref: "#/components/schemas/vuln-policy-bundle-sync-status" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + post: + tags: + - Vulnerability Policies + summary: Trigger bundle synchronization + description: |- + Triggers synchronization of the vulnerability policy bundle. + + Requires permission `POLICY_MANAGEMENT` or `POLICY_MANAGEMENT_UPDATE`. + operationId: triggerVulnPolicyBundleSync + parameters: + - name: uuid + in: path + description: UUID of the vulnerability policy bundle + required: true + schema: + type: string + format: uuid + responses: + "202": + description: Synchronization triggered + headers: + Location: + description: URL of the synchronization status endpoint + schema: + type: string + format: uri + "400": + description: Bad Request + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + "409": + description: Synchronization already in progress + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + default: + $ref: "#/components/responses/generic-error" + /workflow-instances/{id}: + get: + tags: + - Workflows + summary: Get a workflow instance + description: |- + Returns run metadata of a given workflow instance. + + Multiple runs can share an instance ID, but only a single run can exist + in non-terminal state at any given time. Thus, this operation only + returns metadata if a run in non-terminal state exists. + + To list all runs for an instance ID, including terminated ones, + use the `/workflow-runs` endpoint and filter by `workflow_instance_id`. + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: getWorkflowInstance + parameters: + - name: id + in: path + description: ID of the workflow instance + required: true + schema: + type: string + responses: + "200": + description: Workflow run metadata + content: + application/json: + schema: + $ref: "#/components/schemas/workflow-run-metadata" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /workflow-runs: + get: + tags: + - Workflows + summary: List all workflow runs + description: |- + Returns a paginated list of workflow runs. + + ### Sortable fields + + Sorting is supported for the for the following fields: + + * `id` + * `created_at` + * `completed_at` + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listWorkflowRuns + parameters: + - name: workflow_name + in: query + description: Name of the workflow to filter by. Must be an exact match. + schema: + type: string + - name: workflow_version + in: query + description: Version of the workflow to filter by. Must be an exact match. + schema: + maximum: 100 + minimum: 1 + type: integer + format: int32 + - name: workflow_instance_id + in: query + description: Workflow instance ID to filter by. Must be an exact match. + schema: + type: string + - name: status + in: query + description: Status to filter by + schema: + $ref: "#/components/schemas/workflow-run-status" + - name: created_at_from + in: query + description: Filter runs created on or after this timestamp. + schema: + $ref: "#/components/schemas/timestamp" + - name: created_at_to + in: query + description: Filter runs created before this timestamp. + schema: + $ref: "#/components/schemas/timestamp" + - name: completed_at_from + in: query + description: Filter runs completed on or after this timestamp. + schema: + $ref: "#/components/schemas/timestamp" + - name: completed_at_to + in: query + description: Filter runs completed before this timestamp. + schema: + $ref: "#/components/schemas/timestamp" + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: sort_direction + in: query + schema: + $ref: "#/components/schemas/sort-direction" + - name: sort_by + in: query + description: Field to sort by. Refer to the operation description for information + about which fields are sortable. + schema: + maxLength: 255 + minLength: 1 + type: string + responses: + "200": + description: Paginated list of workflow runs + content: + application/json: + schema: + $ref: "#/components/schemas/list-workflow-runs-response" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" + /workflow-runs/{id}: + get: + tags: + - Workflows + summary: Get a workflow run + description: |- + Returns metadata of a given workflow run. + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: getWorkflowRun + parameters: + - name: id + in: path + description: ID of the workflow run + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Workflow run metadata + content: + application/json: + schema: + $ref: "#/components/schemas/workflow-run-metadata" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + "404": + $ref: "#/components/responses/generic-not-found-error" + default: + $ref: "#/components/responses/generic-error" + /workflow-runs/{id}/events: + get: + tags: + - Workflows + summary: List all events of a workflow run + description: |- + Returns a paginated list of workflow run events, sorted by sequence number. + + **Note:** This is an internal API endpoint and may change without notice. + + Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission. + operationId: listWorkflowRunEvents + parameters: + - name: id + in: path + description: ID of the workflow run + required: true + schema: + type: string + format: uuid + - name: from_sequence_number + in: query + description: |- + Sequence number of the last seen event. + May be used to continuously poll for new events. + Can not be used together with `page_token`. + schema: + minimum: 0 + type: integer + format: int32 + - name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + - name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + - name: sort_direction + in: query + schema: + $ref: "#/components/schemas/sort-direction" + responses: + "200": + description: Paginated list of workflow run events + content: + application/json: + schema: + $ref: "#/components/schemas/list-workflow-run-events-response" + "400": + $ref: "#/components/responses/invalid-request-error" + "401": + $ref: "#/components/responses/generic-unauthorized-error" + "403": + $ref: "#/components/responses/generic-forbidden-error" + default: + $ref: "#/components/responses/generic-error" +components: + schemas: + list-advisories-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-advisories-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + upload-advisory-response: + required: + - id + type: object + properties: + id: + type: string + description: The unique identifier of the created advisory + format: uuid + problem-details: + required: + - detail + - title + type: object + properties: + type: + type: string + description: A URI reference that identifies the problem type + format: uri + default: about:blank + status: + maximum: 599 + minimum: 400 + type: integer + description: HTTP status code generated by the origin server for this occurrence + of the problem + format: int32 + example: 500 + title: + maxLength: 255 + type: string + description: "Short, human-readable summary of the problem type" + detail: + maxLength: 1024 + type: string + description: Human-readable explanation specific to this occurrence of the + problem + instance: + type: string + description: Reference URI that identifies the specific occurrence of the + problem + format: uri + description: An RFC 9457 problem object. + externalDocs: + url: https://www.rfc-editor.org/rfc/rfc9457.html + x-parent: true + get-advisory-response: + required: + - content + type: object + properties: + content: + type: string + description: The full content of the advisory document + nullable: true + allOf: + - $ref: "#/components/schemas/list-advisories-response-item" + sort-direction: + type: string + enum: + - ASC + - DESC + list-components-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-components-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + json-schema-validation-problem-details: + required: + - errors + type: object + properties: + errors: + type: array + description: List of JSON Schema validation errors + items: + $ref: "#/components/schemas/json-schema-validation-error" + allOf: + - $ref: "#/components/schemas/problem-details" + create-component-request: + required: + - name + - project_uuid + type: object + properties: + project_uuid: + type: string + format: uuid + name: + maxLength: 255 + type: string + description: + maxLength: 255 + type: string + group: + maxLength: 255 + type: string + version: + maxLength: 255 + type: string + classifier: + $ref: "#/components/schemas/classifier" + filename: + maxLength: 255 + type: string + extension: + maxLength: 255 + type: string + hashes: + $ref: "#/components/schemas/hashes" + cpe: + maxLength: 255 + type: string + publisher: + maxLength: 255 + type: string + supplier: + $ref: "#/components/schemas/organizational-entity" + authors: + type: array + items: + $ref: "#/components/schemas/organizational-contact" + purl: + maxLength: 1024 + type: string + swid_tag_id: + maxLength: 255 + type: string + internal: + type: boolean + copyright: + maxLength: 255 + type: string + license: + maxLength: 255 + type: string + license_expression: + maxLength: 255 + type: string + license_url: + maxLength: 255 + type: string + notes: + maxLength: 255 + type: string + invalid-request-problem-details: + required: + - errors + type: object + properties: + errors: + type: array + items: + $ref: "#/components/schemas/constraint-violation-error" + allOf: + - $ref: "#/components/schemas/problem-details" + list-csaf-aggregators-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/csaf-aggregator" + allOf: + - $ref: "#/components/schemas/paginated-response" + create-csaf-aggregator-request: + required: + - enabled + - name + - namespace + - url + type: object + properties: + namespace: + type: string + format: uri + name: + minLength: 1 + type: string + description: The name of the CSAF aggregator + url: + type: string + description: The URL of the CSAF aggregator + format: uri + enabled: + type: boolean + description: Whether the aggregator is enabled + csaf-aggregator: + required: + - created_at + - enabled + - id + - name + - namespace + - url + type: object + properties: + id: + type: string + format: uuid + url: + type: string + format: uri + namespace: + type: string + format: uri + name: + type: string + enabled: + type: boolean + last_discovery_at: + $ref: "#/components/schemas/timestamp" + created_at: + $ref: "#/components/schemas/timestamp" + updated_at: + $ref: "#/components/schemas/timestamp" + update-csaf-aggregator-request: + required: + - enabled + type: object + properties: + enabled: + type: boolean + description: Whether the aggregator is enabled + list-csaf-providers-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/csaf-provider" + allOf: + - $ref: "#/components/schemas/paginated-response" + create-csaf-provider-request: + required: + - enabled + - name + - namespace + - url + type: object + properties: + namespace: + type: string + format: uri + name: + minLength: 1 + type: string + description: The name of the CSAF provider + url: + type: string + description: The URL of the CSAF provider + format: uri + enabled: + type: boolean + description: Whether the provider is enabled + csaf-provider: + required: + - created_at + - enabled + - id + - name + - namespace + - url + type: object + properties: + id: + type: string + format: uuid + url: + type: string + format: uri + namespace: + type: string + format: uri + name: + type: string + enabled: + type: boolean + description: Whether the aggregator is enabled. + discovered_from: + type: string + description: "ID of the aggregator that the provider was discovered from,\ + \ **if** it was discovered." + format: uuid + discovered_at: + $ref: "#/components/schemas/timestamp" + latest_document_release_date: + $ref: "#/components/schemas/timestamp" + created_at: + $ref: "#/components/schemas/timestamp" + updated_at: + $ref: "#/components/schemas/timestamp" + update-csaf-provider-request: + required: + - enabled + type: object + properties: + enabled: + type: boolean + description: Whether the provider is enabled + list-extension-points-response: + required: + - extension_points + type: object + properties: + extension_points: + type: array + items: + $ref: "#/components/schemas/list-extension-points-response-item" + list-extensions-response: + required: + - extensions + type: object + properties: + extensions: + type: array + items: + $ref: "#/components/schemas/list-extensions-response-item" + get-extension-config-response: + required: + - config + type: object + properties: + config: + type: object + additionalProperties: true + update-extension-config-request: + required: + - config + type: object + properties: + config: + type: object + additionalProperties: true + extension-config-schema: + required: + - $schema + type: object + properties: + $schema: + type: string + format: uri + additionalProperties: true + test-extension-request: + type: object + properties: + config: + type: object + additionalProperties: true + test-extension-response: + required: + - checks + type: object + properties: + checks: + type: array + items: + $ref: "#/components/schemas/extension-test-check" + list-project-advisories-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-project-advisories-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + list-project-advisory-findings-response: + required: + - data + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/list-project-advisory-findings-response-item" + clone-project-request: + required: + - version + type: object + properties: + version: + minLength: 1 + type: string + description: Version of the cloned project. + version_is_latest: + type: boolean + description: "Whether to mark the cloned project version as latest. If another\ + \ version is already marked as latest, it will be atomically un-unmarked\ + \ as part of the cloning operation." + default: false + includes: + uniqueItems: true + type: array + description: |- + List of items to include in the clone: + + * `ACL`: Include portfolio ACL definitions. + * `COMPONENTS`: Include components. + * `FINDINGS`: Include findings. + * Has no effect unless `COMPONENTS` is also included. + * `FINDINGS_AUDIT_HISTORY`: Include audit history of findings. + * Has no effect unless `FINDINGS` is also included. + * `POLICY_VIOLATIONS`: Include policy violations. + * Has no effect unless `COMPONENTS` is also included. + * `POLICY_VIOLATIONS_AUDIT_HISTORY`: Include audit history of policy violations. + * Has no effect unless `POLICY_VIOLATIONS` is also included. + * `PROPERTIES`: Include project properties. + * `SERVICES`: Include services. + * `TAGS`: Include project tags. + items: + $ref: "#/components/schemas/clone-project-include" + default: [] + clone-project-response: + required: + - uuid + type: object + properties: + uuid: + type: string + description: UUID of the cloned project. + format: uuid + list-project-components-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-project-components-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + task-queue-type: + type: string + enum: + - ACTIVITY + - WORKFLOW + list-task-queues-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/task-queue" + allOf: + - $ref: "#/components/schemas/paginated-response" + update-task-queue-request: + type: object + properties: + status: + $ref: "#/components/schemas/task-queue-status" + capacity: + minimum: 1 + type: integer + format: int32 + list-secrets-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/secret-metadata" + allOf: + - $ref: "#/components/schemas/paginated-response" + create-secret-request: + required: + - name + - value + type: object + properties: + name: + $ref: "#/components/schemas/secret-name" + description: + maxLength: 255 + type: string + value: + maxLength: 4096 + minLength: 1 + type: string + secret-name: + pattern: "^[a-zA-Z0-9_-]{1,64}$" + type: string + example: MY_SECRET + secret-metadata: + required: + - name + type: object + properties: + name: + $ref: "#/components/schemas/secret-name" + description: + type: string + created_at: + $ref: "#/components/schemas/timestamp" + updated_at: + $ref: "#/components/schemas/timestamp" + update-secret-request: + type: object + properties: + description: + maxLength: 255 + type: string + description: The new description. Omit this field to retain the current + description. + value: + maxLength: 4096 + minLength: 1 + type: string + description: The new value. Omit this field to retain the current value. + list-vuln-policies-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-vuln-policies-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + create-vuln-policy-request: + required: + - analysis + - condition + - name + type: object + properties: + name: + maxLength: 255 + minLength: 1 + type: string + description: + maxLength: 512 + type: string + author: + maxLength: 255 + type: string + condition: + maxLength: 4096 + minLength: 1 + type: string + analysis: + $ref: "#/components/schemas/vuln-policy-analysis" + ratings: + maxItems: 3 + type: array + items: + $ref: "#/components/schemas/vuln-policy-rating" + operation_mode: + $ref: "#/components/schemas/vuln-policy-operation-mode" + priority: + maximum: 100 + minimum: 0 + type: integer + format: int32 + default: 0 + valid_from: + $ref: "#/components/schemas/timestamp" + valid_until: + $ref: "#/components/schemas/timestamp" + invalid-vuln-policy-condition-problem-details: + required: + - errors + type: object + properties: + errors: + type: array + items: + $ref: "#/components/schemas/vuln-policy-condition-error" + allOf: + - $ref: "#/components/schemas/problem-details" + get-vuln-policy-response: + required: + - analysis + - condition + - name + - operation_mode + - priority + - source + - uuid + type: object + properties: + uuid: + type: string + format: uuid + name: + type: string + description: + type: string + author: + type: string + condition: + type: string + analysis: + $ref: "#/components/schemas/vuln-policy-analysis" + ratings: + maxItems: 3 + type: array + items: + $ref: "#/components/schemas/vuln-policy-rating" + operation_mode: + $ref: "#/components/schemas/vuln-policy-operation-mode" + priority: + maximum: 100 + minimum: 0 + type: integer + format: int32 + source: + $ref: "#/components/schemas/vuln-policy-source" + valid_from: + $ref: "#/components/schemas/timestamp" + valid_until: + $ref: "#/components/schemas/timestamp" + created: + $ref: "#/components/schemas/timestamp" + updated: + $ref: "#/components/schemas/timestamp" + update-vuln-policy-request: + required: + - analysis + - condition + - name + type: object + properties: + name: + maxLength: 255 + minLength: 1 + type: string + description: + maxLength: 512 + type: string + author: + maxLength: 255 + type: string + condition: + maxLength: 4096 + minLength: 1 + type: string + analysis: + $ref: "#/components/schemas/vuln-policy-analysis" + ratings: + maxItems: 3 + type: array + items: + $ref: "#/components/schemas/vuln-policy-rating" + operation_mode: + $ref: "#/components/schemas/vuln-policy-operation-mode" + priority: + maximum: 100 + minimum: 0 + type: integer + format: int32 + default: 0 + valid_from: + $ref: "#/components/schemas/timestamp" + valid_until: + $ref: "#/components/schemas/timestamp" + list-vuln-policy-bundles-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-vuln-policy-bundles-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + vuln-policy-bundle-sync-status: + required: + - status + type: object + properties: + status: + type: string + description: Status of the synchronization. + enum: + - PENDING + - RUNNING + - COMPLETED + - FAILED + started_at: + $ref: "#/components/schemas/timestamp" + completed_at: + $ref: "#/components/schemas/timestamp" + failure_reason: + type: string + description: Reason for why the synchronization failed. + workflow-run-metadata: + required: + - created_at + - id + - priority + - status + - task_queue_name + - workflow_name + - workflow_version + type: object + properties: + id: + type: string + format: uuid + workflow_name: + type: string + workflow_version: + maximum: 100 + minimum: 1 + type: integer + format: int32 + workflow_instance_id: + type: string + task_queue_name: + type: string + status: + $ref: "#/components/schemas/workflow-run-status" + priority: + maximum: 100 + minimum: 0 + type: integer + format: int32 + concurrency_key: + type: string + labels: + type: object + additionalProperties: + type: string + created_at: + $ref: "#/components/schemas/timestamp" + updated_at: + $ref: "#/components/schemas/timestamp" + started_at: + $ref: "#/components/schemas/timestamp" + completed_at: + $ref: "#/components/schemas/timestamp" + workflow-run-status: + type: string + enum: + - CREATED + - RUNNING + - SUSPENDED + - FAILED + - COMPLETED + - CANCELLED + timestamp: + type: integer + description: "Epoch timestamp in milliseconds since January 1, 1970 UTC." + format: int64 + example: 1752209050377 + list-workflow-runs-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/workflow-run-metadata" + allOf: + - $ref: "#/components/schemas/paginated-response" + list-workflow-run-events-response: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/list-workflow-run-events-response-item" + allOf: + - $ref: "#/components/schemas/paginated-response" + paginated-response: + type: object + properties: + next_page_token: + type: string + description: Token to retrieve the next page. Absent when no more items + exist. + total: + $ref: "#/components/schemas/total-count" + x-parent: true + list-advisories-response-item: + required: + - affected_component_count + - affected_project_count + - id + - last_fetched + - name + - publisher + - title + - url + - version + type: object + properties: + id: + type: string + description: The unique identifier of the advisory + format: uuid + publisher: + type: string + description: The publisher of the advisory + name: + type: string + description: The name/tracking ID of the advisory + version: + type: string + description: The version of the advisory + title: + type: string + description: The title of the advisory + url: + type: string + description: The URL of the advisory + format: uri + seen_at: + $ref: "#/components/schemas/timestamp" + last_fetched: + $ref: "#/components/schemas/timestamp" + format: + type: string + description: "The format of the advisory (e.g., CSAF)" + affected_component_count: + type: integer + description: The number of affected components. Reports counts up to 1001. + A number of 1001 should be interpreted as "more than 1000 components". + format: int32 + affected_project_count: + type: integer + description: The number of affected projects. Reports counts up to 1001. + A number of 1001 should be interpreted as "more than 1000 projects". + format: int32 + list-components-response-item: + type: object + properties: + name: + maxLength: 255 + type: string + version: + maxLength: 255 + type: string + group: + maxLength: 255 + type: string + classifier: + maxLength: 255 + type: string + hashes: + $ref: "#/components/schemas/hashes" + cpe: + maxLength: 255 + type: string + purl: + maxLength: 1024 + type: string + swid_tag_id: + maxLength: 255 + type: string + internal: + type: boolean + copyright: + maxLength: 255 + type: string + license: + maxLength: 255 + type: string + license_expression: + maxLength: 255 + type: string + license_url: + maxLength: 255 + type: string + resolved_license: + $ref: "#/components/schemas/license" + last_inherited_risk_score: + type: number + format: double + uuid: + type: string + format: uuid + project: + $ref: "#/components/schemas/component-project" + metrics: + $ref: "#/components/schemas/dependency-metrics" + json-schema-validation-error: + required: + - instance_location + - message + type: object + properties: + instance_location: + type: string + description: JSON Pointer to the location in the instance that failed validation + example: /config/port + evaluation_path: + type: string + description: JSON Pointer to the location in the schema during evaluation + example: /properties/config/properties/port + schema_location: + type: string + description: Schema location that generated the error + example: https://example.com/schemas/config#/properties/config/properties/port + keyword: + type: string + description: The validation keyword that failed + example: type + message: + type: string + description: Human-readable error message + example: Value must be a number + description: |- + A JSON Schema validation error as per + . + classifier: + type: string + enum: + - APPLICATION + - FRAMEWORK + - LIBRARY + - CONTAINER + - OPERATING_SYSTEM + - DEVICE + - FIRMWARE + - FILE + - PLATFORM + - DEVICE_DRIVER + - MACHINE_LEARNING_MODEL + - DATA + hashes: + type: object + properties: + sha1: + maxLength: 40 + type: string + sha256: + maxLength: 64 + type: string + sha384: + maxLength: 96 + type: string + sha512: + maxLength: 128 + type: string + sha3_256: + maxLength: 64 + type: string + sha3_384: + maxLength: 96 + type: string + sha3_512: + maxLength: 128 + type: string + blake2b_256: + maxLength: 64 + type: string + blake2b_384: + maxLength: 96 + type: string + blake2b_512: + maxLength: 128 + type: string + blake3: + maxLength: 255 + type: string + md5: + maxLength: 32 + type: string + organizational-entity: + type: object + properties: + name: + maxLength: 255 + type: string + description: Name of the organizational entity + urls: + type: array + items: + maxLength: 255 + type: string + contacts: + type: array + items: + $ref: "#/components/schemas/organizational-contact" + organizational-contact: + type: object + properties: + name: + maxLength: 255 + type: string + description: Name of the organizational contact + email: + maxLength: 255 + type: string + description: Email of the organizational contact + phone: + maxLength: 255 + type: string + description: Phone of the organizational contact + constraint-violation-error: + required: + - message + type: object + properties: + path: + type: string + description: Path to the invalid field in the request + value: + type: string + description: The invalid value + message: + type: string + description: Message explaining the error + list-extension-points-response-item: + required: + - name + type: object + properties: + name: + type: string + list-extensions-response-item: + required: + - name + type: object + properties: + name: + type: string + extension-test-check: + required: + - name + - status + type: object + properties: + name: + type: string + example: connection + status: + $ref: "#/components/schemas/extension-test-check-status" + message: + type: string + example: Connection failed + list-project-advisories-response-item: + required: + - findings_count + - format + - id + - last_fetched + - name + - publisher + - title + - url + - version + type: object + properties: + id: + type: string + description: The unique identifier of the advisory + format: uuid + publisher: + type: string + description: The publisher of the advisory + name: + type: string + description: The name/tracking ID of the advisory + version: + type: string + description: The version of the advisory + title: + type: string + description: The title of the advisory + url: + type: string + description: The URL of the advisory + format: uri + seen_at: + $ref: "#/components/schemas/timestamp" + last_fetched: + $ref: "#/components/schemas/timestamp" + format: + type: string + description: "The format of the advisory (e.g., CSAF)" + findings_count: + type: integer + description: The number of findings for this advisory in the project + format: int64 + list-project-advisory-findings-response-item: + required: + - component_uuid + - confidence + - desc + - group + - name + - version + type: object + properties: + name: + type: string + description: The name of the component + confidence: + maximum: 100 + minimum: 0 + type: integer + description: The confidence/matching percentage of the finding as integer + ranging 0...100 + format: int32 + desc: + type: string + description: The description of the component + group: + type: string + description: The group of the component + version: + type: string + description: The version of the component + component_uuid: + type: string + description: The UUID of the component + format: uuid + clone-project-include: + type: string + enum: + - ACL + - COMPONENTS + - FINDINGS + - FINDINGS_AUDIT_HISTORY + - POLICY_VIOLATIONS + - POLICY_VIOLATIONS_AUDIT_HISTORY + - PROPERTIES + - SERVICES + - TAGS + list-project-components-response-item: + type: object + properties: + name: + maxLength: 255 + type: string + version: + maxLength: 255 + type: string + group: + maxLength: 255 + type: string + classifier: + maxLength: 255 + type: string + hashes: + $ref: "#/components/schemas/hashes" + cpe: + maxLength: 255 + type: string + purl: + maxLength: 1024 + type: string + swid_tag_id: + maxLength: 255 + type: string + internal: + type: boolean + copyright: + maxLength: 255 + type: string + license: + maxLength: 255 + type: string + license_expression: + maxLength: 255 + type: string + license_url: + maxLength: 255 + type: string + resolved_license: + $ref: "#/components/schemas/license" + occurrence_count: + minimum: 0 + type: integer + format: int64 + last_inherited_risk_score: + type: number + format: double + uuid: + type: string + format: uuid + task-queue: + required: + - capacity + - created_at + - depth + - name + - status + type: object + properties: + name: + type: string + status: + $ref: "#/components/schemas/task-queue-status" + capacity: + minimum: 1 + type: integer + format: int32 + depth: + minimum: 0 + type: integer + format: int32 + created_at: + $ref: "#/components/schemas/timestamp" + updated_at: + $ref: "#/components/schemas/timestamp" + task-queue-status: + type: string + enum: + - ACTIVE + - PAUSED + list-vuln-policies-response-item: + required: + - name + - operation_mode + - priority + - source + - uuid + type: object + properties: + uuid: + type: string + format: uuid + name: + type: string + description: + type: string + author: + type: string + priority: + type: integer + format: int32 + operation_mode: + $ref: "#/components/schemas/vuln-policy-operation-mode" + source: + $ref: "#/components/schemas/vuln-policy-source" + vuln-policy-analysis: + required: + - state + type: object + properties: + state: + type: string + enum: + - EXPLOITABLE + - IN_TRIAGE + - FALSE_POSITIVE + - NOT_AFFECTED + - RESOLVED + justification: + type: string + enum: + - CODE_NOT_PRESENT + - CODE_NOT_REACHABLE + - REQUIRES_CONFIGURATION + - REQUIRES_DEPENDENCY + - REQUIRES_ENVIRONMENT + - PROTECTED_BY_COMPILER + - PROTECTED_AT_RUNTIME + - PROTECTED_AT_PERIMETER + - PROTECTED_BY_MITIGATING_CONTROL + vendor_response: + type: string + enum: + - CAN_NOT_FIX + - WILL_NOT_FIX + - UPDATE + - ROLLBACK + - WORKAROUND_AVAILABLE + details: + type: string + suppress: + type: boolean + default: false + vuln-policy-rating: + required: + - method + - severity + type: object + properties: + method: + type: string + enum: + - CVSSV2 + - CVSSV3 + - CVSSV4 + - OWASP + severity: + type: string + enum: + - CRITICAL + - HIGH + - MEDIUM + - LOW + - INFO + vector: + type: string + score: + type: number + format: double + vuln-policy-operation-mode: + type: string + enum: + - DISABLED + - APPLY + - LOG + vuln-policy-condition-error: + required: + - column + - line + - message + type: object + properties: + line: + type: integer + description: Line number where the error occurred + format: int32 + column: + type: integer + description: Column number where the error occurred + format: int32 + message: + type: string + description: Description of the error + vuln-policy-source: + type: string + enum: + - USER + - BUNDLE + list-vuln-policy-bundles-response-item: + required: + - url + - uuid + type: object + properties: + uuid: + type: string + format: uuid + url: + type: string + hash: + type: string + last_successful_sync: + $ref: "#/components/schemas/timestamp" + created: + $ref: "#/components/schemas/timestamp" + updated: + $ref: "#/components/schemas/timestamp" + list-workflow-run-events-response-item: + required: + - event + - sequence_number + type: object + properties: + sequence_number: + type: integer + format: int32 + event: + type: object + additionalProperties: true + total-count: + required: + - count + - type + type: object + properties: + count: + minimum: 0 + type: integer + description: "The total number of records across all pages. Might be an\ + \ exact count, or a lower bound. Refer to the `type` field for the applicable\ + \ semantics." + format: int64 + type: + $ref: "#/components/schemas/total-count-type" + license: + type: object + properties: + name: + maxLength: 255 + type: string + license_id: + maxLength: 255 + type: string + uuid: + type: string + format: uuid + osi_approved: + type: boolean + fsf_libre: + type: boolean + custom_license: + type: boolean + component-project: + type: object + properties: + name: + maxLength: 255 + type: string + version: + maxLength: 255 + type: string + uuid: + type: string + format: uuid + dependency-metrics: + type: object + properties: + critical: + type: integer + format: int32 + high: + type: integer + format: int32 + medium: + type: integer + format: int32 + low: + type: integer + format: int32 + unassigned: + type: integer + format: int32 + vulnerabilities: + type: integer + format: int32 + suppressed: + type: integer + format: int32 + inherited_risk_score: + type: number + format: double + findings_total: + type: integer + format: int32 + findings_audited: + type: integer + format: int32 + findings_unaudited: + type: integer + format: int32 + policy_violations_fail: + type: integer + format: int32 + policy_violations_warn: + type: integer + format: int32 + policy_violations_info: + type: integer + format: int32 + policy_violations_total: + type: integer + format: int32 + policy_violations_audited: + type: integer + format: int32 + policy_violations_unaudited: + type: integer + format: int32 + policy_violations_security_total: + type: integer + format: int32 + policy_violations_security_audited: + type: integer + format: int32 + policy_violations_security_unaudited: + type: integer + format: int32 + policy_violations_license_total: + type: integer + format: int32 + policy_violations_license_audited: + type: integer + format: int32 + policy_violations_license_unaudited: + type: integer + format: int32 + policy_violations_operational_total: + type: integer + format: int32 + policy_violations_operational_audited: + type: integer + format: int32 + policy_violations_operational_unaudited: + type: integer + format: int32 + extension-test-check-status: + type: string + enum: + - PASSED + - FAILED + - SKIPPED + total-count-type: + type: string + enum: + - AT_LEAST + - EXACT + responses: + generic-unauthorized-error: + description: Unauthorized + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + example: + type: about:blank + status: 401 + title: Unauthorized + detail: Not authorized to access the requested resource. + generic-forbidden-error: + description: Forbidden + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + example: + type: about:blank + status: 403 + title: Forbidden + detail: Not permitted to access the requested resource. + generic-error: + description: Unexpected error + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + invalid-request-error: + description: Bad request + content: + application/problem+json: + schema: + $ref: "#/components/schemas/invalid-request-problem-details" + example: + type: about:blank + status: 400 + title: Bad Request + detail: The request could not be processed because it failed validation. + errors: + - path: foo.bar + value: baz + message: Must be a number + generic-not-found-error: + description: Not found + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + example: + type: about:blank + status: 404 + title: Not Found + detail: The requested resource could not be found. + generic-conflict-error: + description: Forbidden + content: + application/problem+json: + schema: + $ref: "#/components/schemas/problem-details" + example: + type: about:blank + status: 409 + title: Conflict + detail: The resource already exists. + parameters: + page-token: + name: page_token + in: query + description: Opaque token pointing to a specific position in a collection + schema: + type: string + pagination-limit: + name: limit + in: query + description: Maximum number of items to retrieve from the collection + schema: + maximum: 1000 + minimum: 1 + type: integer + format: int32 + default: 100 + sort-direction: + name: sort_direction + in: query + schema: + $ref: "#/components/schemas/sort-direction" + sort-by: + name: sort_by + in: query + description: Field to sort by. Refer to the operation description for information + about which fields are sortable. + schema: + maxLength: 255 + minLength: 1 + type: string + securitySchemes: + apiKeyAuth: + type: apiKey + description: Authentication via API key + name: X-Api-Key + in: header + bearerAuth: + type: http + description: Authentication via Bearer token + scheme: Bearer diff --git a/docs/reference/api/v1.md b/docs/reference/api/v1.md new file mode 100644 index 00000000..78c24fad --- /dev/null +++ b/docs/reference/api/v1.md @@ -0,0 +1,8 @@ +--- +hide: + - toc +--- + +# REST API v1 + + diff --git a/docs/reference/api/v2.md b/docs/reference/api/v2.md new file mode 100644 index 00000000..f1f56916 --- /dev/null +++ b/docs/reference/api/v2.md @@ -0,0 +1,8 @@ +--- +hide: + - toc +--- + +# REST API v2 + + diff --git a/docs/reference/badges.md b/docs/reference/badges.md new file mode 100644 index 00000000..c30059fa --- /dev/null +++ b/docs/reference/badges.md @@ -0,0 +1,95 @@ +# Badges + +Dependency-Track provides SVG badges that display a project's current vulnerability +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 Types + +### Vulnerable Components + +Displays a severity breakdown of vulnerable components in the project. The badge shows +the highest severity present, or *no vulns* if no active findings exist. + +Suppressed vulnerabilities are excluded from badge counts. + +**By project name and version:** + +```text +https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey} +``` + +**By project UUID:** + +```text +https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey} +``` + +### Policy Violations + +Displays the current policy violation state. Shows *violations* if any active (non-suppressed) +violations are present, or *no violations* otherwise. + +**By project name and version:** + +```text +https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey} +``` + +**By project UUID:** + +```text +https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey} +``` + +## Embedding Badges + +=== "Markdown" + + ```markdown + ![Vulnerabilities](https://dtrack.example.com/api/v1/badge/vulns/project/my-app/1.0.0?apiKey=odt_...) + ![Policy Violations](https://dtrack.example.com/api/v1/badge/violations/project/my-app/1.0.0?apiKey=odt_...) + ``` + +=== "HTML" + + ```html + Vulnerabilities + Policy Violations + ``` + +## Access Configuration + +Badge requests require authentication. Two approaches are available: + +### API Key in URL + +Pass the API key as a query parameter (`?apiKey={apiKey}`). This is the simplest +approach for static badge URLs embedded in documentation. + +```text +https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey=odt_... +``` + +### API Key in Header + +Pass the API key in the `X-Api-Key` request header. This is appropriate for server-side +badge proxies where the key should not appear in URLs. + +```shell +curl -H "X-Api-Key: odt_..." \ + "https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}" +``` + +## Required Permission + +The API key (or the team it belongs to) must have the `VIEW_BADGES` permission. + +Dependency-Track creates a default **Badge Viewers** team with this permission and a +pre-generated API key on first startup. You may use this key for badge access, but +rotate it before going to production. + +!!! warning + API keys in badge URLs are visible to anyone who can view the source of the page + embedding them. Use a dedicated, low-privilege API key with only the `VIEW_BADGES` + permission for this purpose, and avoid reusing keys from more privileged teams. diff --git a/docs/reference/cel-expressions.md b/docs/reference/cel-expressions.md new file mode 100644 index 00000000..7a25f21e --- /dev/null +++ b/docs/reference/cel-expressions.md @@ -0,0 +1,533 @@ +# CEL Expressions + +Dependency-Track uses the [Common Expression Language] (CEL) for policy conditions and +[notification filter expressions](notifications/filter-expressions.md). This page describes +the available variables, functions, and expression patterns. + +For instructions on creating CEL-based policy conditions, see +[Managing vulnerability policies](../guides/user/managing-vulnerability-policies.md). + +## Syntax + +The CEL syntax is similar to other [C-style languages] like Java and JavaScript. +However, CEL is not [Turing-complete]. As such, it does *not* support constructs like `if` statements or loops (that is, `for`, `while`). + +As a compensation for missing loops, CEL offers [macros] like `all`, `exists`, `exists_one`, `map`, and `filter`. +Refer to the [macros] documentation for more details, or have a look at the [examples](#examples) to see how they may +be utilized in practice. + +CEL syntax is described thoroughly in the official [language definition]. + +## Evaluation Context + +Conditions are scoped to individual components. +Each condition is evaluated for every single component in a project. + +The context in which expressions are evaluated in contains the following variables: + +| Variable | Type | Description | +|:------------|:------------------------------------------------|:---------------------------------------------| +| `component` | [Component] | The component being evaluated | +| `project` | [Project] | The project the component is part of | +| `vulns` | list([Vulnerability]) | Vulnerabilities the component is affected by | +| `now` | [`google.protobuf.Timestamp`][protobuf-ts-docs] | The current time at the start of evaluation | + +!!! note + Many fields on [Component], [Project], and [Vulnerability] are optional. + Use the `has()` macro to [check for presence of optional fields](#optional-field-checking) + before accessing them. + +## Examples + +### Component age + +Besides out-of-date versions, component age is another indicator of potential risk. Components may be on the latest +available version, but still be 20 years old. + +The following expression matches [Component]s that are two years old, or even older, using the `now` +variable and timestamp arithmetic: + +```js linenums="1" +has(component.published_at) + && component.published_at < now - duration("17520h") // ~2 years +``` + +### Component blacklist + +The following expression matches on the [Component]'s [Package URL], using a regular expression in [RE2] syntax. +Additionally, it checks whether the [Component]'s version falls into a given [vers] range using +[`matches_range`](#matches_range), consisting of multiple constraints. + +```js linenums="1" +component.purl.matches("^pkg:maven/com.acme/acme-lib\\b.*") + && component.matches_range("vers:maven/>0|<1|!=0.2.4") +``` + +The expression will match: + +* `pkg:maven/com.acme/acme-lib@0.1.0` +* `pkg:maven/com.acme/acme-lib@0.9.9` + +but not: + +* `pkg:maven/com.acme/acme-library@0.1.0` +* `pkg:maven/com.acme/acme-lib@0.2.4` + +### Dependency graph traversal + +The following expression matches [Component]s that are a (possibly transitive) dependency of a [Component] +with name `foo`, *but only if* a [Component] with name `bar` is also present in the [Project]. + +```js linenums="1" +component.is_dependency_of(v1.Component{name: "foo"}) + && project.depends_on(v1.Component{name: "bar"}) +``` + +To check whether a component is a *direct* (that is, non-transitive) dependency: + +```js linenums="1" +component.is_direct_dependency_of(v1.Component{name: "foo"}) +``` + +To check whether a component is *exclusively* introduced through another component +(that is, no other path in the dependency graph leads to it): + +```js linenums="1" +component.is_exclusive_dependency_of(v1.Component{name: "foo"}) +``` + +Dependency graph functions support the following [Component] fields for matching: + +| Field | `re:` prefix | `vers:` prefix | +|:--------------|:------------:|:--------------:| +| `uuid` | | | +| `group` | ✅ | | +| `name` | ✅ | | +| `version` | ✅ | ✅ | +| `classifier` | | | +| `cpe` | ✅ | | +| `purl` | ✅ | | +| `swid_tag_id` | ✅ | | +| `is_internal` | | | + +The `re:` prefix enables [RE2] regex matching on the field value: + +```js linenums="1" +project.depends_on(v1.Component{name: "re:^acme-.*"}) +``` + +The `vers:` prefix enables [vers] range matching on the `version` field: + +```js linenums="1" +project.depends_on(v1.Component{ + name: "acme-lib", + version: "vers:maven/>1.0.0|<2.0.0" +}) +``` + +!!! note + When constructing objects like [Component] on-the-fly, it is necessary to use their version namespace, + that is, `v1`. This is required in order to perform type checking, as well as ensuring backward compatibility. + +### License expression allowlist + +The following expression matches non-internal [Component]s whose [SPDX license expression][SPDX license expressions] +cannot be satisfied using only the approved set of licenses. +License-with-exception combinations are listed as a single compound entry. + +```js linenums="1" +!spdx_expr_allows(component.license_expression, [ + "MIT", "Apache-2.0", "BSD-3-Clause", + "GPL-2.0-only WITH Classpath-exception-2.0" +]) +``` + +When components don't have a license expression, `component.resolved_license.id` can be used as a fallback. +A single license ID is a valid SPDX expression, so it gets the same version-aware treatment: + +```js linenums="1" +!spdx_expr_allows( + has(component.license_expression) + ? component.license_expression + : component.resolved_license.id, + ["MIT", "Apache-2.0"] +) +``` + +### License blacklist + +The following expression matches [Component]s that are **not** internal to the organization, +and have either: + +* No resolved [License] at all +* A resolved [License] that is not part of the `Permissive` license group + +```js linenums="1" +!component.is_internal && ( + !has(component.resolved_license) + || !component.resolved_license.groups.exists(licenseGroup, + licenseGroup.name == "Permissive") +) +``` + +### Vulnerability blacklist + +The following expression matches [Component]s in [Project]s tagged as `3rd-party`, with at least one [Vulnerability] +being any of the given blacklisted IDs. + +```js linenums="1" +"3rd-party" in project.tags + && vulns.exists(vuln, vuln.id in [ + "CVE-2017-5638", // struts RCE + "CVE-2021-44228", // log4shell + "CVE-2022-22965", // spring4shell + ]) +``` + +### Vulnerabilities with high severity in public facing projects + +The following expression matches [Component]s in [Project]s tagged as `public-facing`, with at least one `HIGH` +or `CRITICAL` +[Vulnerability], where the [CVSSv3] attack vector is `Network`. + +```js linenums="1" +"public-facing" in project.tags + && vulns.exists(vuln, + vuln.severity in ["HIGH", "CRITICAL"] + && vuln.cvssv3_vector.matches(".*/AV:N/.*") + ) +``` + +### Version distance + +The [`version_distance`](#version_distance) function allows matching based on how far behind a component's version +is from the latest known version. The distance is specified using a [VersionDistance] object with `epoch`, `major`, +`minor`, and `patch` fields. + +The following expression matches components that are more than one major version behind: + +```js linenums="1" +component.version_distance(">=", v1.VersionDistance{major: 1}) +``` + +### Optional field checking + +CEL does not have a concept of `null`. Accessing a field that is not set +returns its default value (for example, `""` for strings, `0` for numbers, `false` for booleans), which can +lead to misleading matches. Use the `has()` macro to check for field presence before accessing it: + +```js linenums="1" +has(component.published_at) + && component.published_at < now - duration("8760h") +``` + +```js linenums="1" +has(project.metadata) && has(project.metadata.tools) +``` + +## SPDX License Expressions + +The `spdx_expr_*` functions evaluate [SPDX license expressions]. They operate on expression strings +(typically `component.license_expression`) and can also be used with `component.resolved_license.id` +as a fallback for components without a license expression. + +All license ID comparisons are **case-insensitive** per the SPDX specification. + +### Version equivalence + +Deprecated license IDs are treated as equivalent to their modern counterparts. +For example, `GPL-2.0` and `GPL-2.0-only` are considered the same license. + +### Version ranges + +The `+` operator and `-or-later` suffix are understood as "this version or any later +version in the same license family." For example, `GPL-3.0-only` satisfies an allow-list containing +`GPL-2.0-or-later`, and `Apache-1.0+` satisfies an allow-list containing `Apache-2.0`. + +### Deprecated `WITH`-compounds + +Legacy compound IDs like `GPL-2.0-with-classpath-exception` are automatically +resolved to their modern `WITH` expression form (`GPL-2.0-only WITH Classpath-exception-2.0`). + +### `WITH` composites + +License-with-exception combinations are treated as atomic composites. The full +compound (for example, `"GPL-2.0-only WITH Classpath-exception-2.0"`) must appear as a single entry in +allow-lists, not as separate license and exception IDs. The license part uses version-aware matching +(for example, `GPL-2.0 WITH ...` matches `GPL-2.0-only WITH ...`), while the exception part requires an exact match. + +## Function Reference + +For type definitions, refer to the [schema reference](schemas/policy.md). + +In addition to the [standard definitions] of the CEL specification, Dependency-Track offers the following functions. + +### `depends_on` + +Checks whether a [Project] contains a [Component] matching the given criteria. +Useful for enforcing policies only when specific components are present in a project. + +| Name | Type | Description | +|:------------|:------------|:----------------------------------------------------------------| +| *receiver* | [Project] | The project to check | +| `component` | [Component] | Criteria to match against. Supports `re:` and `vers:` prefixes. | + +**Returns:** `true` if a matching component exists in the project. + +```js linenums="1" +project.depends_on(v1.Component{name: "baz"}) +``` + +```mermaid +graph TD + P["Project"]:::match --> A["foo"] + P --> B["bar"] + A --> C["baz"]:::criteria + A --> D["qux"] + B --> D + classDef match stroke:#22c55e,stroke-width:3 + classDef criteria fill:#22c55e,color:#fff +``` + +!!! tip + `project` matches because `baz` exists in its dependency graph. + +### `is_dependency_of` + +Checks whether a [Component] is a (possibly transitive) dependency of another [Component]. + +| Name | Type | Description | +|:------------|:------------|:---------------------------------------------------------------------------| +| *receiver* | [Component] | The component being evaluated | +| `component` | [Component] | Criteria to match the parent against. Supports `re:` and `vers:` prefixes. | + +**Returns:** `true` if the receiver is a dependency (direct or transitive) of a matching component. + +```js linenums="1" +component.is_dependency_of(v1.Component{name: "foo"}) +``` + +```mermaid +graph TD + P["Project"] --> A["foo"]:::criteria + P --> B["bar"] + A --> C["baz"]:::match + A --> D["qux"]:::match + B --> D + classDef match stroke:#22c55e,stroke-width:3 + classDef criteria fill:#22c55e,color:#fff +``` + +!!! tip + `baz` and `qux` match since both are dependencies of `foo`. + `qux` matches even though it's also reachable through `bar`. + +### `is_direct_dependency_of` + +Checks whether a [Component] is a *direct* (non-transitive) dependency of another [Component]. + +| Name | Type | Description | +|:------------|:------------|:---------------------------------------------------------------------------| +| *receiver* | [Component] | The component being evaluated | +| `component` | [Component] | Criteria to match the parent against. Supports `re:` and `vers:` prefixes. | + +**Returns:** `true` if the receiver is a direct dependency of a matching component. + +```js linenums="1" +component.is_direct_dependency_of(v1.Component{name: "foo"}) +``` + +```mermaid +graph TD + P["Project"] --> A["foo"]:::criteria + P --> B["bar"] + A --> C["baz"]:::match + A --> D["qux"]:::match + B --> D + classDef match stroke:#22c55e,stroke-width:3 + classDef criteria fill:#22c55e,color:#fff +``` + +!!! tip + `baz` and `qux` match since both are direct children of `foo`. + +With a deeper graph, transitive dependencies do **not** match: + +```mermaid +graph TD + A["foo"]:::criteria --> C["baz"]:::match + C --> E["deep"]:::nomatch + classDef match stroke:#22c55e,stroke-width:3 + classDef criteria fill:#22c55e,color:#fff + classDef nomatch stroke:#ef4444,stroke-width:3,stroke-dasharray:5 +``` + +!!! tip + `baz` matches since it's a direct child of `foo`. + `deep` does **not** match, as it's a transitive dependency. + +### `is_exclusive_dependency_of` + +Checks whether a [Component] is *exclusively* introduced through another [Component]. +Returns `true` only if every path from the project root to the receiver passes through a matching component. + +| Name | Type | Description | +|:------------|:------------|:---------------------------------------------------------------------------| +| *receiver* | [Component] | The component being evaluated | +| `component` | [Component] | Criteria to match the parent against. Supports `re:` and `vers:` prefixes. | + +**Returns:** `true` if the receiver is exclusively introduced through a matching component. + +```js linenums="1" +component.is_exclusive_dependency_of(v1.Component{name: "foo"}) +``` + +```mermaid +graph TD + P["Project"] --> A["foo"]:::criteria + P --> B["bar"] + A --> C["baz"]:::match + A --> D["qux"]:::nomatch + B --> D + classDef match stroke:#22c55e,stroke-width:3 + classDef criteria fill:#22c55e,color:#fff + classDef nomatch stroke:#ef4444,stroke-width:3,stroke-dasharray:5 +``` + +!!! tip + `baz` matches since it's only reachable through `foo`. + `qux` does **not** match, as it's also reachable through `bar`. + +### `matches_range` + +Checks whether a [Component]'s or [Project]'s version falls within a [vers] range. + +| Name | Type | Description | +|:-----------|:-------------------------|:-----------------------------------------------------------| +| *receiver* | [Component] or [Project] | The component or project to check | +| `range` | `string` | A [vers] range string (for example, `"vers:maven/>1.0.0\|<2.0.0"`) | + +**Returns:** `true` if the version is within the specified range. + +```js linenums="1" +component.matches_range("vers:maven/>0|<1|!=0.2.4") +``` + +Currently supported versioning schemes: + +| Versioning Scheme | Ecosystem | +|:------------------|:---------------------------------| +| `deb` | Debian / Ubuntu | +| `generic` | Generic / Any | +| `golang` | Go | +| `maven` | Java / Maven | +| `npm` | JavaScript / NodeJS | +| `rpm` | CentOS / Fedora / Red Hat / SUSE | + +!!! note + If the ecosystem of the components to match against is known upfront, it's good practice to use the according + versioning scheme in `matches_range`. This helps with accuracy, as versioning schemes have different nuances + across ecosystems, which makes comparisons error-prone. + +### `spdx_expr_allows` + +Checks whether an [SPDX license expression][SPDX license expressions] can be satisfied +using only licenses from the given set. For `OR` expressions, at least one branch must +be satisfiable. For `AND` expressions, all children must be satisfiable. `WITH` expressions +are treated as atomic composites (see below). + +| Name | Type | Description | +|:-------------|:---------------|:---------------------------------------------------------| +| `expression` | `string` | An SPDX license expression | +| `ids` | `list(string)` | Allowed licenses, including `WITH` composites if needed | + +**Returns:** `true` if the expression is satisfiable with the given IDs. + +```js linenums="1" +spdx_expr_allows(component.license_expression, ["MIT", "Apache-2.0"]) +// "MIT" => true (MIT is allowed) +// "MIT OR GPL-3.0-only" => true (MIT branch is satisfiable) +// "MIT AND Apache-2.0" => true (both are allowed) +// "MIT AND GPL-3.0-only" => false (GPL-3.0-only is not allowed) +// "GPL-3.0-only" => false (not in the allowed set) +``` + +Version-range matching is applied automatically: + +```js linenums="1" +spdx_expr_allows(component.license_expression, ["GPL-2.0-or-later"]) +// "GPL-2.0-only" => true (2.0 is within 2.0-or-later range) +// "GPL-3.0-only" => true (3.0 is within 2.0-or-later range) +// "GPL-1.0-only" => false (1.0 is below 2.0) +// "GPL-2.0" => true (deprecated ID, equivalent to GPL-2.0-only) +``` + +!!! tip + `WITH` expressions (license-with-exception) are matched as a single unit. + The allowed set must contain the full compound entry, not the license and exception separately: + + ```js linenums="1" + spdx_expr_allows(component.license_expression, [ + "GPL-2.0-only WITH Classpath-exception-2.0" + ]) + // "GPL-2.0-only WITH Classpath-exception-2.0" => true (composite matches) + // "GPL-2.0-only" => false (plain license, not in set) + // "GPL-2.0-only WITH LLVM-exception" => false (different composite) + ``` + +### `spdx_expr_requires_any` + +Checks whether at least one of the given license IDs is required in every possible satisfaction +of an [SPDX license expression][SPDX license expressions]. For `OR` expressions, at least one of +the IDs must be required in all branches. For `AND` expressions, at least one of the IDs must be +required in at least one child. + +| Name | Type | Description | +|:-------------|:----------------|:---------------------------| +| `expression` | `string` | An SPDX license expression | +| `ids` | `list(string)` | License IDs to check | + +**Returns:** `true` if at least one of the IDs is always required. + +```js linenums="1" +spdx_expr_requires_any(component.license_expression, ["GPL-2.0-only", "GPL-3.0-only"]) +// "GPL-2.0-only AND MIT" => true (GPL-2.0-only always required) +// "GPL-2.0-only OR GPL-3.0-only" => true (every branch requires one) +// "GPL-2.0 AND MIT" => true (GPL-2.0 is equivalent to GPL-2.0-only) +// "GPL-2.0-only OR MIT" => false (MIT branch requires neither) +``` + +### `version_distance` + +Checks whether the distance between a [Component]'s current version and its latest known version +matches a given [VersionDistance]. + +| Name | Type | Description | +|:-----------|:------------------|:----------------------------------------------------| +| *receiver* | [Component] | The component to check | +| `operator` | `string` | Numeric comparator: `<`, `<=`, `=`, `!=`, `>`, `>=` | +| `distance` | [VersionDistance] | The version distance to compare against | + +**Returns:** `true` if the version distance satisfies the comparison. + +```js linenums="1" +component.version_distance(">=", v1.VersionDistance{major: 1}) +``` + +[C-style languages]: https://en.wikipedia.org/wiki/List_of_C-family_programming_languages +[CVSSv3]: https://www.first.org/cvss/v3.0/specification-document +[Common Expression Language]: https://cel.dev/ +[Component]: schemas/policy.md#component +[License]: schemas/policy.md#license +[Package URL]: https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst +[Project]: schemas/policy.md#project +[RE2]: https://github.com/google/re2/wiki/Syntax +[SPDX license expressions]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/ +[Turing-complete]: https://en.wikipedia.org/wiki/Turing_completeness +[VersionDistance]: schemas/policy.md#versiondistance +[Vulnerability]: schemas/policy.md#vulnerability +[language definition]: https://github.com/google/cel-spec/blob/v0.13.0/doc/langdef.md#language-definition +[macros]: https://github.com/google/cel-spec/blob/v0.13.0/doc/langdef.md#macros +[protobuf-ts-docs]: https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp +[standard definitions]: https://github.com/google/cel-spec/blob/v0.13.0/doc/langdef.md#list-of-standard-definitions +[vers]: https://github.com/package-url/vers-spec diff --git a/docs/reference/community-integrations.md b/docs/reference/community-integrations.md new file mode 100644 index 00000000..68e7507c --- /dev/null +++ b/docs/reference/community-integrations.md @@ -0,0 +1,68 @@ +# Community Integrations + +The following tools and integrations have been built by the community on top of +Dependency-Track's API-first design. They are maintained independently and are not +officially supported by the Dependency-Track project. + +!!! note + Dependency-Track's [REST API](api/v1.md) provides full programmatic access to + all platform features. This makes it straightforward to build custom integrations + for tools and workflows not listed here. + +## CI/CD and Build System Plugins + +These plugins automate SBOM upload and vulnerability gate evaluation as part of your +build pipeline. + +| Tool | Integration | Link | +|:-----|:------------|:-----| +| Jenkins | Dependency-Track Jenkins Plugin | [jenkins.io](https://plugins.jenkins.io/dependency-track/) | +| GitHub | OWASP Dependency-Track Check GitHub Action | [GitHub Marketplace](https://github.com/marketplace/actions/owasp-dependency-track-check) | +| Azure DevOps | Azure DevOps Extension | [Visual Studio Marketplace](https://marketplace.visualstudio.com/) | +| Maven | `dependency-track-maven-plugin` | [GitHub](https://github.com/pmckeown/dependency-track-maven-plugin) | + +## Developer Portals + +| Tool | Integration | Link | +|:-----|:------------|:-----| +| Backstage | Dependency-Track Backstage Plugin (TRIMM) | [GitHub](https://github.com/TRIMM/plugin-dependency-track) | + +## Client Libraries + +These libraries provide programmatic access to the Dependency-Track API from your +own tools and automation scripts. + +| Language | Library | Link | +|:---------|:--------|:-----| +| Go | Dependency-Track Client | [GitHub](https://github.com/nscuro/dtrack-client-go) | +| Python | Dependency-Track Client | [GitHub](https://github.com/nscuro/dtrack-client-py) | +| Ruby | Dependency-Track Client | [GitHub](https://github.com/nscuro/dtrack-client-rb) | + +## Security and Vulnerability Management + +| Tool | Integration | Link | +|:-----|:------------|:-----| +| SecObserve | Dependency-Track integration | [GitHub](https://github.com/MaibornWolff/SecObserve) | +| Mixeway Hub | Risk aggregation platform | [mixeway.pl](https://mixeway.pl) | +| SD Elements (Security Compass) | Dependency-Track integration | [securitycompass.com](https://securitycompass.com) | + +## Reporting and Auditing + +| Tool | Description | Link | +|:-----|:------------|:-----| +| Dependency-Track Reporting Tool | Generates reports from Dependency-Track data (Modus Operandi) | [GitHub](https://github.com/ModusCreateOrg/dependency-track-report-tool) | +| dtrack-audit | CLI tool for auditing findings (OZON.ru) | [GitHub](https://github.com/ozonru/dtrack-audit) | +| dtrack-auditor | Policy-driven finding auditor | [GitHub](https://github.com/jetstack/dtrack-auditor) | +| `dependency-track-exporter` | Prometheus metrics exporter (Jetstack) | [GitHub](https://github.com/jetstack/dependency-track-exporter) | + +## Other Utilities + +| Tool | Description | Link | +|:-----|:------------|:-----| +| dtapac | Policy-as-code for Dependency-Track via OPA | [GitHub](https://github.com/nscuro/dtapac) | +| sbomify | SBOM enrichment and sharing | [sbomify.com](https://sbomify.com) | + +--- + +*Know of an integration that should be listed here? Open a pull request on the +[documentation repository](https://github.com/DependencyTrack/hyades).* diff --git a/docs/reference/configuration/.pages b/docs/reference/configuration/.pages new file mode 100644 index 00000000..10fd96ea --- /dev/null +++ b/docs/reference/configuration/.pages @@ -0,0 +1,7 @@ +nav: + - Application: application.md + - Data Sources: datasources.md + - File Storage: file-storage.md + - Database: database.md + - Durable Execution Engine: dex-engine.md + - All Properties: properties.md diff --git a/docs/reference/configuration/application.md b/docs/reference/configuration/application.md index 6d5f71b2..e2c54dfe 100644 --- a/docs/reference/configuration/application.md +++ b/docs/reference/configuration/application.md @@ -1,4 +1,70 @@ -# Application configuration +# Application -!!! warning "Placeholder" - This page has not been written yet. +Dependency-Track's configuration system is based on [MicroProfile Config], +enabling it to support multiple [sources](#sources). + +!!! tip + A comprehensive list of supported config properties can be found in + the [configuration reference](properties.md). + +## Sources + +Config properties are loaded, *in order*, from the following sources: + +1. JVM system properties +2. Environment variables +3. `${cwd}/.env` file +4. `${cwd}/config/application.properties` file +5. `application.properties` embedded in the application + +!!! tip + `${cwd}` refers to the current working directory. + When running an official container image, it is `/opt/owasp/dependency-track`. + +Once a value is found, later sources will not be checked. For example, when Dependency-Track +attempts to look up the config property `foo.bar`, the environment variable `FOO_BAR=123` is +ignored if the JVM was launched with `-Dfoo.bar=321`. + +## Expressions + +Configuration values may use expressions, indicated by `${...}`, to reference each other: + +```ini linenums="1" +dt.datasource.foo.url=jdbc:postgresql://localhost:5432/dtrack +dt.datasource.bar.url=${dt.datasource.foo.url} +``` + +This is useful to avoid redundant definition of identical values. + +## Environment Variable Mapping + +The canonical representation of properties uses alphanumeric characters, +separated by hyphens (`-`) and periods (`.`). For example: + +```ini linenums="1" +foo.BAR-baz=123 +``` + +Environment variables commonly only support alphanumeric characters and underscores (`_`). +To bridge this gap, Dependency-Track will use the following matching strategies, +as [defined](https://download.eclipse.org/microprofile/microprofile-config-3.1/microprofile-config-spec-3.1.html#default_configsources.env.mapping) +by [MicroProfile Config]: + +> 1. Exact match (that is, `foo.BAR-baz`) +> 2. Replace each character that is neither alphanumeric nor `_` with `_` (that is, `foo_BAR_baz`) +> 3. Replace each character that is neither alphanumeric nor `_` with `_`; then convert the name to upper case (that is, `FOO_BAR_BAZ`) + +!!! tip + The [configuration reference](properties.md) includes the correct + environment variable names for each listed config property. + +## Debugging Configuration Resolution + +To verify whether config values are properly resolved and from which source, enable debug logging +via [`dt.config.log.values`](properties.md#dtconfiglogvalues) and +[`dt.logging.level."io.smallrye.config"`](properties.md) set to `DEBUG`. + +!!! warning + This will *not* mask or omit any secrets. **Do not use in production environments.** + +[MicroProfile Config]: https://microprofile.io/specifications/config/ diff --git a/docs/reference/configuration/database.md b/docs/reference/configuration/database.md index 699a4495..10789e61 100644 --- a/docs/reference/configuration/database.md +++ b/docs/reference/configuration/database.md @@ -1,4 +1,124 @@ # Database -!!! warning "Placeholder" - This page has not been written yet. +Dependency-Track requires a [PostgreSQL], or PostgreSQL-compatible database to operate. + +The lowest supported version is 14. You are encouraged to use the [newest available version]. + +For guidance on choosing a hosting solution, deploying, and tuning PostgreSQL, see the +[database configuration guide](../../guides/administration/configuring-database.md). + +## Extensions + +The following PostgreSQL [extensions](https://www.postgresql.org/docs/current/external-extensions.html) +are **required** by Dependency-Track. When choosing a hosting solution, verify that the extensions listed +here are supported. + +* [`pg_trgm`](https://www.postgresql.org/docs/current/pgtrgm.html): *Support for similarity of text using trigram matching* + +!!! note + Dependency-Track will execute the necessary `CREATE EXTENSION IF NOT EXISTS` statements + during [schema migration](#schema-migrations). Enabling extensions manually is not necessary. + +Generally, usage of extensions is limited to those that: + +1. Ship with PostgreSQL [out-of-the-box](https://www.postgresql.org/docs/current/contrib.html) +2. Are [trusted](https://www.postgresql.org/about/featurematrix/detail/347/) by default + +## Tuning Parameters + +The following PostgreSQL parameters are recommended for Dependency-Track deployments. +For context on when and why to apply these, see the +[advanced tuning guide](../../guides/administration/configuring-database.md#advanced-tuning). + +### `autovacuum_vacuum_scale_factor` + + + + + + + + + + + + + + + + + + + + +
Default0.2
Recommendation0.02
Tables +
    +
  • COMPONENT
    • +
+
ReferencesDocumentation
+ +### `default_toast_compression` + + + + + + + + + + + + + + + + +
Defaultpglz
Recommendationlz4
References + +
+ +### `wal_compression` + + + + + + + + + + + + + + + + +
Defaultoff
Recommendationlz4 or zstd
References + +
+ +## Schema Migrations + +Schema migrations are performed automatically by the API server upon startup using [Liquibase]. +Usually no manual action is required when upgrading from an older Dependency-Track version, unless explicitly +stated otherwise in the release notes. + +This behaviour can be turned off by setting [`init.tasks.enabled`](properties.md#dtinittasksenabled) +on the API server container to `false`. + +For configuring separate migration credentials, see the +[schema migration credentials guide](../../guides/administration/configuring-database.md#schema-migration-credentials). + +[Liquibase]: https://www.liquibase.com/ +[PostgreSQL]: https://www.postgresql.org/ +[newest available version]: https://www.postgresql.org/support/versioning/ diff --git a/docs/reference/configuration/datasources.md b/docs/reference/configuration/datasources.md index c9191dfd..c5bb9897 100644 --- a/docs/reference/configuration/datasources.md +++ b/docs/reference/configuration/datasources.md @@ -1,4 +1,75 @@ -# Data sources +# Data Sources -!!! warning "Placeholder" - This page has not been written yet. +Data sources are logical objects through which database connections can be acquired. + +## Property Format + +Data sources are configured using properties in the following format: + +```ini +dt.datasource..= +``` + +For available properties, and their environment variable equivalents, refer to the [configuration reference]. + +!!! tip + When `` is omitted, `default` is assumed. + This means that `dt.datasource.url` and `dt.datasource.default.url` are treated equally. + +The `default` data source is *required*. It serves the REST API +and the vast majority of background processing. + +Certain features accept a *data source name* instead of database connection details, +allowing them to use a dedicated connection pool. For example, the +[*database* secret management provider](../../guides/administration/configuring-secret-management.md#database) +via [`dt.secret-management.database.datasource.name`](properties.md#dtsecret-managementdatabasedatasourcename). + +??? example "Multiple data sources" + + ```ini linenums="1" + # Configure the default data source + dt.datasource.url=jdbc:postgresql://localhost:5432/dtrack + dt.datasource.username=dtrack + dt.datasource.password=dtrack + dt.datasource.pool.enabled=true + dt.datasource.pool.max-size=20 + + # Configure the secret management data source + dt.datasource.secretmgt.url=jdbc:postgresql://localhost:5432/dtrack + dt.datasource.secretmgt.username=secrets + dt.datasource.secretmgt.password=secrets + dt.datasource.secretmgt.pool.enabled=true + dt.datasource.secretmgt.pool.max-size=5 + + # Configure secret management to use separate data source + dt.secret-management.provider=database + dt.secret-management.database.datasource.name=secretmgt + ``` + +!!! note + Data sources are instantiated on first use. You can configure as many + data sources as you like, but unless they're being used by a feature, + they will not be created. + +## Connection Pool Properties + +The following properties control local connection pooling per data source: + +* [`dt.datasource..pool.enabled`](properties.md#dtdatasourcepoolenabled) +* [`dt.datasource..url`](properties.md#dtdatasourceurl) +* [`dt.datasource..username`](properties.md#dtdatasourceusername) +* [`dt.datasource..password`](properties.md#dtdatasourcepassword) +* [`dt.datasource..password-file`](properties.md#dtdatasourcepassword-file) +* [`dt.datasource..pool.max-size`](properties.md#dtdatasourcepoolmax-size) +* [`dt.datasource..pool.min-idle`](properties.md#dtdatasourcepoolmin-idle) +* [`dt.datasource..pool.max-lifetime-ms`](properties.md#dtdatasourcepoolmax-lifetime-ms) +* [`dt.datasource..pool.idle-timeout-ms`](properties.md#dtdatasourcepoolidle-timeout-ms) + +When deploying multiple instances, the total number of connections across all pools +must not exceed the PostgreSQL [`max_connections`](https://postgresqlco.nf/doc/en/param/max_connections/) limit +(default: 100). + +For centralised connection pooling with PgBouncer, see the +[database configuration guide](../../guides/administration/configuring-database.md#centralised-connection-pooling). + +[configuration reference]: database.md diff --git a/docs/reference/configuration/dex-engine.md b/docs/reference/configuration/dex-engine.md new file mode 100644 index 00000000..ae0f5f74 --- /dev/null +++ b/docs/reference/configuration/dex-engine.md @@ -0,0 +1,53 @@ +# Durable Execution Engine + +The durable execution engine (dex) handles background task scheduling and execution. +This page documents its worker types, task queues, and default configuration. + +For tuning guidance, see [Scaling](../../guides/administration/scaling.md#concurrency-control). + +## Workers + +Workers poll task queues and execute tasks. Each worker has a configurable +maximum concurrency that limits how many tasks it processes simultaneously +per instance. + +Worker concurrency is configured via: + +```ini +dt.dex-engine...max-concurrency= +``` + +Where `` is either `workflow-worker` or `activity-worker`. + +| Worker Type | Worker Name | Queue | Default Concurrency | +|-------------------|--------------------------------|---------------------------------|--------------------:| +| `workflow-worker` | `default` | `default` | 100 | +| `activity-worker` | `default` | `default` | 25 | +| `activity-worker` | `vuln-analysis` | `vuln-analyses` | 10 | +| `activity-worker` | `artifact-import` | `artifact-imports` | 10 | +| `activity-worker` | `package-metadata-resolution` | `package-metadata-resolutions` | 10 | +| `activity-worker` | `notification` | `notifications` | 5 | +| `activity-worker` | `vuln-analysis-reconciliation` | `vuln-analysis-reconciliations` | 5 | +| `activity-worker` | `policy-evaluation` | `policy-evaluations` | 5 | +| `activity-worker` | `metrics-update` | `metrics-updates` | 5 | + +## Task queues + +Task queue capacity limits how many tasks can be pending across the entire cluster. +When a queue reaches capacity, the scheduler stops creating new tasks for that queue, +providing backpressure. + +Queue capacity is modifiable at runtime in the administrator panel under +*Workflows* -> *Task Queues*, or via REST API. + +| Type | Queue | Default Capacity | +|------------|---------------------------------|-----------------:| +| `workflow` | `default` | 1000 | +| `activity` | `default` | 1000 | +| `activity` | `artifact-imports` | 25 | +| `activity` | `metrics-updates` | 25 | +| `activity` | `notifications` | 25 | +| `activity` | `package-metadata-resolutions` | 25 | +| `activity` | `policy-evaluations` | 25 | +| `activity` | `vuln-analyses` | 25 | +| `activity` | `vuln-analysis-reconciliations` | 25 | diff --git a/docs/reference/configuration/file-storage.md b/docs/reference/configuration/file-storage.md index fa1c5994..26cfe630 100644 --- a/docs/reference/configuration/file-storage.md +++ b/docs/reference/configuration/file-storage.md @@ -1,4 +1,59 @@ -# File storage +# File Storage -!!! warning "Placeholder" - This page has not been written yet. +Dependency-Track uses file storage for intermediate data during background processing, +including uploaded BOMs, vulnerability analysis results, and large notifications. +Files are short-lived and automatically cleaned up after processing. + +The storage provider is selected via [`dt.file-storage.provider`](properties.md#dtfile-storageprovider). + +Both providers compress stored files using [zstd](https://facebook.github.io/zstd/). The compression level is +configurable per provider (default: 5, range: -7 to 22). Higher levels yield +better compression at the cost of CPU. + +## Providers + +### Local + +The `local` provider stores files on the local filesystem. This is the default. + +```ini +dt.file-storage.provider=local +dt.file-storage.local.directory=/data/storage +``` + +When running multiple instances, all nodes must have access to the same directory. +A shared persistent volume (for example, NFS) works well for this. + +Configuration: + +- [`dt.file-storage.local.directory`](properties.md#dtfile-storagelocaldirectory) +- [`dt.file-storage.local.compression.level`](properties.md#dtfile-storagelocalcompressionlevel) + +### S3 + +The `s3` provider stores files in an S3-compatible object store (AWS S3, MinIO, etc.). +Use this when a shared volume is impractical. + +The bucket must exist before startup. Dependency-Track will verify its existence +and fail to start if it's not found. + +```ini +dt.file-storage.provider=s3 +dt.file-storage.s3.endpoint=https://s3.amazonaws.com +dt.file-storage.s3.bucket=dtrack-files +dt.file-storage.s3.access.key= +dt.file-storage.s3.secret.key= +dt.file-storage.s3.region=us-east-1 +``` + +Configuration: + +- [`dt.file-storage.s3.endpoint`](properties.md#dtfile-storages3endpoint) +- [`dt.file-storage.s3.bucket`](properties.md#dtfile-storages3bucket) +- [`dt.file-storage.s3.access.key`](properties.md#dtfile-storages3accesskey) +- [`dt.file-storage.s3.secret.key`](properties.md#dtfile-storages3secretkey) +- [`dt.file-storage.s3.region`](properties.md#dtfile-storages3region) +- [`dt.file-storage.s3.compression.level`](properties.md#dtfile-storages3compressionlevel) +- [`dt.file-storage.s3.connect-timeout-ms`](properties.md#dtfile-storages3connect-timeout-ms) +- [`dt.file-storage.s3.read-timeout-ms`](properties.md#dtfile-storages3read-timeout-ms) +- [`dt.file-storage.s3.write-timeout-ms`](properties.md#dtfile-storages3write-timeout-ms) diff --git a/docs/reference/configuration/properties.md b/docs/reference/configuration/properties.md index 3852ef78..ccf0cb57 100644 --- a/docs/reference/configuration/properties.md +++ b/docs/reference/configuration/properties.md @@ -1,4 +1,2313 @@ -# Configuration properties + + +# Configuration Properties + +## Glossary + +### Required Properties + +Properties marked with * are required. A required property must never be unset. + +### Property Types + +Configuration properties may use the following types: + +| Type | Description | +|:-----|:------------| +| `boolean` | `true` or `false` | +| `cron` | A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) (e.g. `0 0 * * *`) | +| `double` | A decimal number (e.g. `3.14`) | +| `duration` | An [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g. `PT30S`, `PT5M`, `PT1H`) | +| `enum` | One of a fixed set of values, refer to *Valid Values* | +| `integer` | A whole number (e.g. `42`) | +| `string` | A text value | + + +## CORS + +**`dt.cors.allow.credentials`** [¶](#dtcorsallowcredentials){ .headerlink } +: Controls the content of the `Access-Control-Allow-Credentials` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_CORS_ALLOW_CREDENTIALS
+ +**`dt.cors.allow.headers`** [¶](#dtcorsallowheaders){ .headerlink } +: Controls the content of the `Access-Control-Allow-Headers` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typestring
DefaultOrigin,Content-Type,Authorization,X-Requested-With,Content-Length,Accept,Origin,X-Api-Key,X-Total-Count,*
ENVDT_CORS_ALLOW_HEADERS
+ +**`dt.cors.allow.methods`** [¶](#dtcorsallowmethods){ .headerlink } +: Controls the content of the `Access-Control-Allow-Methods` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typestring
DefaultGET,POST,PUT,PATCH,DELETE,OPTIONS
ENVDT_CORS_ALLOW_METHODS
+ +**`dt.cors.allow.origin`** [¶](#dtcorsalloworigin){ .headerlink } +: Controls the content of the `Access-Control-Allow-Origin` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typestring
Default*
ENVDT_CORS_ALLOW_ORIGIN
+ +**`dt.cors.enabled`** [¶](#dtcorsenabled){ .headerlink } +: Defines whether [Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (CORS) headers shall be included in REST API responses. + + + + + +
Typeboolean
Defaulttrue
ENVDT_CORS_ENABLED
+ +**`dt.cors.expose.headers`** [¶](#dtcorsexposeheaders){ .headerlink } +: Controls the content of the `Access-Control-Expose-Headers` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typestring
DefaultOrigin,Content-Type,Authorization,X-Requested-With,Content-Length,Accept,Origin,X-Api-Key,X-Total-Count
ENVDT_CORS_EXPOSE_HEADERS
+ +**`dt.cors.max.age`** [¶](#dtcorsmaxage){ .headerlink } +: Controls the content of the `Access-Control-Max-Age` response header.
Has no effect when [`dt.cors.enabled`](#dtcorsenabled) is `false`. + + + + + +
Typeinteger
Default3600
ENVDT_CORS_MAX_AGE
+ + + +## Cache + +**`dt.cache."package-metadata-resolver.cargo.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvercargoresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Cargo package metadata resolver response cache entries. + + + + + +
Typeinteger
Default7200000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_CARGO_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.composer.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvercomposerresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Composer package metadata resolver response cache entries. + + + + + +
Typeinteger
Default7200000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_COMPOSER_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.cpan.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvercpanresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for CPAN package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_CPAN_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.gem.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvergemresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for RubyGems package metadata resolver response cache entries. + + + + + +
Typeinteger
Default7200000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_GEM_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.github.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvergithubresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for GitHub package metadata resolver response cache entries. + + + + + +
Typeinteger
Default3600000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_GITHUB_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.gomodules.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvergomodulesresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Go Modules package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_GOMODULES_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.hackage.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolverhackageresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Hackage package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_HACKAGE_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.hex.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolverhexresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Hex package metadata resolver response cache entries. + + + + + +
Typeinteger
Default7200000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_HEX_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.maven.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvermavenresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Maven package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_MAVEN_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.nixpkgs.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvernixpkgsresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Nixpkgs package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_NIXPKGS_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.npm.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvernpmresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for npm package metadata resolver response cache entries. + + + + + +
Typeinteger
Default3600000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_NPM_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.nuget.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolvernugetresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for NuGet package metadata resolver response cache entries. + + + + + +
Typeinteger
Default14400000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_NUGET_RESPONSES__TTL_MS
+ +**`dt.cache."package-metadata-resolver.pypi.responses".ttl-ms`** [¶](#dtcache"package-metadata-resolverpypiresponses"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for PyPI package metadata resolver response cache entries. + + + + + +
Typeinteger
Default7200000
ENVDT_CACHE__PACKAGE_METADATA_RESOLVER_PYPI_RESPONSES__TTL_MS
+ +**`dt.cache."vuln-analyzer.oss-index.results".max-size`** [¶](#dtcache"vuln-analyzeross-indexresults"max-size){ .headerlink } +: Defines the maximum number of entries in the OSS Index result cache. + + + + + +
Typeinteger
Default30000
ENVDT_CACHE__VULN_ANALYZER_OSS_INDEX_RESULTS__MAX_SIZE
+ +**`dt.cache."vuln-analyzer.oss-index.results".ttl-ms`** [¶](#dtcache"vuln-analyzeross-indexresults"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for OSS Index result cache entries. + + + + + +
Typeinteger
Default43200000
ENVDT_CACHE__VULN_ANALYZER_OSS_INDEX_RESULTS__TTL_MS
+ +**`dt.cache."vuln-analyzer.snyk.results".max-size`** [¶](#dtcache"vuln-analyzersnykresults"max-size){ .headerlink } +: Defines the maximum number of entries in the Snyk result cache. + + + + + +
Typeinteger
Default30000
ENVDT_CACHE__VULN_ANALYZER_SNYK_RESULTS__MAX_SIZE
+ +**`dt.cache."vuln-analyzer.snyk.results".ttl-ms`** [¶](#dtcache"vuln-analyzersnykresults"ttl-ms){ .headerlink } +: Defines the TTL in milliseconds for Snyk result cache entries. + + + + + +
Typeinteger
Default43200000
ENVDT_CACHE__VULN_ANALYZER_SNYK_RESULTS__TTL_MS
+ +**`dt.cache.provider`** * [¶](#dtcacheprovider){ .headerlink } +: Defines the cache provider to use. + + + + + + +
Typeenum
Defaultdatabase
Valid Values[database]
ENVDT_CACHE_PROVIDER
+ +**`dt.cache.provider.database.datasource.name`** [¶](#dtcacheproviderdatabasedatasourcename){ .headerlink } +: Defines the name of the data source to be used by the database cache provider. + + + + + +
Typestring
Defaultdefault
ENVDT_CACHE_PROVIDER_DATABASE_DATASOURCE_NAME
+ +**`dt.cache.provider.database.maintenance.initial-delay-ms`** [¶](#dtcacheproviderdatabasemaintenanceinitial-delay-ms){ .headerlink } +: Defines the initial delay in milliseconds after which the database cache provider first performs its maintenance activities, e.g. entry expiration. + + + + + +
Typeinteger
Default60000
ENVDT_CACHE_PROVIDER_DATABASE_MAINTENANCE_INITIAL_DELAY_MS
+ +**`dt.cache.provider.database.maintenance.interval-ms`** [¶](#dtcacheproviderdatabasemaintenanceinterval-ms){ .headerlink } +: Defines the interval in milliseconds in which the database cache provider performs its maintenance activities, e.g. entry expiration. + + + + + +
Typeinteger
Default300000
ENVDT_CACHE_PROVIDER_DATABASE_MAINTENANCE_INTERVAL_MS
+ + + +## Database + +**`dt.database.password`** [¶](#dtdatabasepassword){ .headerlink } +: Specifies the password to use when authenticating to the database. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.password`](#dtdatasourcepassword) instead. + + + + + +
Typestring
Defaultdtrack
ENVDT_DATABASE_PASSWORD
+ +**`dt.database.password.file`** [¶](#dtdatabasepasswordfile){ .headerlink } +: Specifies the file to load the database password from. If set, takes precedence over [`dt.database.password`](#dtdatabasepassword). + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.password`](#dtdatasourcepassword)-file instead. + + + + + + +
Typestring
Defaultnull
Example/var/run/secrets/database-password
ENVDT_DATABASE_PASSWORD_FILE
+ +**`dt.database.pool.enabled`** [¶](#dtdatabasepoolenabled){ .headerlink } +: Specifies if the database connection pool is enabled. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.pool.enabled`](#dtdatasourcepoolenabled) instead. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DATABASE_POOL_ENABLED
+ +**`dt.database.pool.idle.timeout`** [¶](#dtdatabasepoolidletimeout){ .headerlink } +: This property controls the maximum amount of time that a connection is allowed to sit idle in the pool. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.pool.idle-timeout-ms`](#dtdatasourcepoolidle-timeout-ms) instead. + + + + + +
Typeinteger
Default300000
ENVDT_DATABASE_POOL_IDLE_TIMEOUT
+ +**`dt.database.pool.max.lifetime`** [¶](#dtdatabasepoolmaxlifetime){ .headerlink } +: This property controls the maximum lifetime of a connection in the pool. An in-use connection will never be retired, only when it is closed will it then be removed. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.pool.max-lifetime-ms`](#dtdatasourcepoolmax-lifetime-ms) instead. + + + + + +
Typeinteger
Default600000
ENVDT_DATABASE_POOL_MAX_LIFETIME
+ +**`dt.database.pool.max.size`** [¶](#dtdatabasepoolmaxsize){ .headerlink } +: This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.pool.max-size`](#dtdatasourcepoolmax-size) instead. + + + + + +
Typeinteger
Default30
ENVDT_DATABASE_POOL_MAX_SIZE
+ +**`dt.database.pool.min.idle`** [¶](#dtdatabasepoolminidle){ .headerlink } +: This property controls the minimum number of idle connections in the pool. This value should be equal to or less than [`dt.database.pool.max.size`](#dtdatabasepoolmaxsize). Warning: If the value is less than [`dt.database.pool.max.size`](#dtdatabasepoolmaxsize), [`dt.database.pool.idle.timeout`](#dtdatabasepoolidletimeout) will have no effect. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.pool.min-idle`](#dtdatasourcepoolmin-idle) instead. + + + + + +
Typeinteger
Default15
ENVDT_DATABASE_POOL_MIN_IDLE
+ +**`dt.database.url`** [¶](#dtdatabaseurl){ .headerlink } +: Specifies the JDBC URL to use when connecting to the database. For best performance, set the `reWriteBatchedInserts` query parameter to `true`. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.url`](#dtdatasourceurl) instead. + + + + + + +
Typestring
Defaultnull
Examplejdbc:postgresql://localhost:5432/dtrack?reWriteBatchedInserts=true
ENVDT_DATABASE_URL
+ +**`dt.database.username`** [¶](#dtdatabaseusername){ .headerlink } +: Specifies the username to use when authenticating to the database. + + !!! warning "Deprecated" + Since 5.7.0. Use [`dt.datasource.username`](#dtdatasourceusername) instead. + + + + + +
Typestring
Defaultdtrack
ENVDT_DATABASE_USERNAME
+ +**`dt.datasource.password`** [¶](#dtdatasourcepassword){ .headerlink } +: Defines the password to use for the default data source. + + + + + +
Typestring
Default${dt.database.password}
ENVDT_DATASOURCE_PASSWORD
+ +**`dt.datasource.password-file`** [¶](#dtdatasourcepassword-file){ .headerlink } +: Defines the location of the file to load the password for the default data source from. If set, takes precedence over [`dt.datasource.password`](#dtdatasourcepassword). + + + + + +
Typestring
Default${dt.database.password.file}
ENVDT_DATASOURCE_PASSWORD_FILE
+ +**`dt.datasource.pool.enabled`** * [¶](#dtdatasourcepoolenabled){ .headerlink } +: Defines whether connection pooling is enabled for the default data source. + + + + + +
Typeboolean
Default${dt.database.pool.enabled}
ENVDT_DATASOURCE_POOL_ENABLED
+ +**`dt.datasource.pool.idle-timeout-ms`** [¶](#dtdatasourcepoolidle-timeout-ms){ .headerlink } +: Defines the maximum time in milliseconds that a connection is allowed to sit idle in the pool. + + + + + +
Typeinteger
Default${dt.database.pool.idle.timeout}
ENVDT_DATASOURCE_POOL_IDLE_TIMEOUT_MS
+ +**`dt.datasource.pool.max-lifetime-ms`** [¶](#dtdatasourcepoolmax-lifetime-ms){ .headerlink } +: Defines the maximum time in milliseconds for which connections should be kept in the pool for the default data source. Required when [`dt.datasource.pool.enabled`](#dtdatasourcepoolenabled) is `true`. + + + + + +
Typeinteger
Default${dt.database.pool.max.lifetime}
ENVDT_DATASOURCE_POOL_MAX_LIFETIME_MS
+ +**`dt.datasource.pool.max-size`** [¶](#dtdatasourcepoolmax-size){ .headerlink } +: Defines the maximum size of the connection pool for the default data source. Required when [`dt.datasource.pool.enabled`](#dtdatasourcepoolenabled) is `true`. + + + + + +
Typeinteger
Default${dt.database.pool.max.size}
ENVDT_DATASOURCE_POOL_MAX_SIZE
+ +**`dt.datasource.pool.min-idle`** [¶](#dtdatasourcepoolmin-idle){ .headerlink } +: Defines the minimum number of idle connections in the pool for the default data source. Required when [`dt.datasource.pool.enabled`](#dtdatasourcepoolenabled) is `true`. + + + + + +
Typeinteger
Default${dt.database.pool.min.idle}
ENVDT_DATASOURCE_POOL_MIN_IDLE
+ +**`dt.datasource.url`** * [¶](#dtdatasourceurl){ .headerlink } +: Defines the JDBC URL to use for the default data source. + + + + + + +
Typestring
Default${dt.database.url}
Examplejdbc:postgresql://localhost:5432/dtrack?reWriteBatchedInserts=true
ENVDT_DATASOURCE_URL
+ +**`dt.datasource.username`** [¶](#dtdatasourceusername){ .headerlink } +: Defines the username to use for the default data source. + + + + + +
Typestring
Default${dt.database.username}
ENVDT_DATASOURCE_USERNAME
+ +**`dt.dex-engine.datasource.name`** [¶](#dtdex-enginedatasourcename){ .headerlink } +: Defines the name of the data source to be used by the durable execution engine. For larger deployments, it is recommended to use a separate, non-default data source. + + + + + +
Typestring
Defaultdefault
ENVDT_DEX_ENGINE_DATASOURCE_NAME
+ +**`dt.dex-engine.migration.datasource.name`** [¶](#dtdex-enginemigrationdatasourcename){ .headerlink } +: Defines the name of the data source to use for executing database migrations of the durable execution engine. + + + + + +
Typestring
Defaultnull
ENVDT_DEX_ENGINE_MIGRATION_DATASOURCE_NAME
+ +**`dt.init.tasks.datasource.close-after-use`** * [¶](#dtinittasksdatasourceclose-after-use){ .headerlink } +: Defines whether the data source used by init tasks should be closed after all tasks completed. This is useful when a non-default data source was configured, that is not used anywhere else. + + + + + +
Typeboolean
Defaultfalse
ENVDT_INIT_TASKS_DATASOURCE_CLOSE_AFTER_USE
+ +**`dt.init.tasks.datasource.name`** * [¶](#dtinittasksdatasourcename){ .headerlink } +: Defines the name of the data source to be used by init tasks. + + + + + +
Typestring
Defaultdefault
ENVDT_INIT_TASKS_DATASOURCE_NAME
+ + + +## Development + +**`dt.dev.services.enabled`** [¶](#dtdevservicesenabled){ .headerlink } +: Whether dev services shall be enabled.

When enabled, Dependency-Track will automatically launch containers for:
  • Frontend
  • PostgreSQL
at startup, and configures itself to use them. They are disposed when Dependency-Track stops. The containers are exposed on randomized ports, which will be logged during startup.

Trying to enable dev services in a production build will prevent the application from starting.

Note that the containers launched by the API server can not currently be discovered and re-used by other Hyades services. This is a future enhancement tracked in . + + + + + +
Typeboolean
Defaultfalse
ENVDT_DEV_SERVICES_ENABLED
+ +**`dt.dev.services.image.frontend`** [¶](#dtdevservicesimagefrontend){ .headerlink } +: The image to use for the frontend dev services container. + + + + + +
Typestring
Defaultghcr.io/dependencytrack/hyades-frontend:snapshot
ENVDT_DEV_SERVICES_IMAGE_FRONTEND
+ +**`dt.dev.services.image.postgres`** [¶](#dtdevservicesimagepostgres){ .headerlink } +: The image to use for the PostgreSQL dev services container. + + + + + +
Typestring
Defaultpostgres:14-alpine
ENVDT_DEV_SERVICES_IMAGE_POSTGRES
+ +**`dt.dev.services.port.frontend`** [¶](#dtdevservicesportfrontend){ .headerlink } +: The port on which the frontend dev services container shall be exposed on the host. + + + + + +
Typeinteger
Default8081
ENVDT_DEV_SERVICES_PORT_FRONTEND
+ + + +## Durable Execution + +**`dt.dex-engine.activity-task-heartbeat-buffer.flush-interval-ms`** [¶](#dtdex-engineactivity-task-heartbeat-bufferflush-interval-ms){ .headerlink } +: Defines the time in milliseconds between flushes of the activity task heartbeat buffer. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_ACTIVITY_TASK_HEARTBEAT_BUFFER_FLUSH_INTERVAL_MS
+ +**`dt.dex-engine.activity-task-heartbeat-buffer.max-batch-size`** [¶](#dtdex-engineactivity-task-heartbeat-buffermax-batch-size){ .headerlink } +: Defines the maximum number of items of the activity task heartbeat buffer. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_ACTIVITY_TASK_HEARTBEAT_BUFFER_MAX_BATCH_SIZE
+ +**`dt.dex-engine.activity-task-scheduler.poll-interval-ms`** [¶](#dtdex-engineactivity-task-schedulerpoll-interval-ms){ .headerlink } +: Defines the interval in milliseconds in which the activity task scheduler polls for tasks to enqueue for execution. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_ACTIVITY_TASK_SCHEDULER_POLL_INTERVAL_MS
+ +**`dt.dex-engine.activity-worker.artifact-import.enabled`** [¶](#dtdex-engineactivity-workerartifact-importenabled){ .headerlink } +: Defines whether the artifact import activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_ARTIFACT_IMPORT_ENABLED
+ +**`dt.dex-engine.activity-worker.artifact-import.max-concurrency`** * [¶](#dtdex-engineactivity-workerartifact-importmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the artifact import activity worker. + + + + + +
Typeinteger
Default5
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_ARTIFACT_IMPORT_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.default.enabled`** [¶](#dtdex-engineactivity-workerdefaultenabled){ .headerlink } +: Defines whether the default activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_DEFAULT_ENABLED
+ +**`dt.dex-engine.activity-worker.default.max-concurrency`** * [¶](#dtdex-engineactivity-workerdefaultmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the default activity worker. + + + + + +
Typeinteger
Default25
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_DEFAULT_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.metrics-update.enabled`** [¶](#dtdex-engineactivity-workermetrics-updateenabled){ .headerlink } +: Defines whether the metrics update activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_METRICS_UPDATE_ENABLED
+ +**`dt.dex-engine.activity-worker.metrics-update.max-concurrency`** * [¶](#dtdex-engineactivity-workermetrics-updatemax-concurrency){ .headerlink } +: Defines the maximum concurrency of the metrics update activity worker. + + + + + +
Typeinteger
Default5
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_METRICS_UPDATE_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.notification.enabled`** [¶](#dtdex-engineactivity-workernotificationenabled){ .headerlink } +: Defines whether the notification activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_ENABLED
+ +**`dt.dex-engine.activity-worker.notification.max-concurrency`** * [¶](#dtdex-engineactivity-workernotificationmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the notification activity worker. + + + + + +
Typeinteger
Default5
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.notification.poll-backoff.initial-delay-ms`** [¶](#dtdex-engineactivity-workernotificationpoll-backoffinitial-delay-ms){ .headerlink } +: Defines the initial poll backoff delay in milliseconds of the notification activity worker. + + + + + +
Typeinteger
Default200
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_POLL_BACKOFF_INITIAL_DELAY_MS
+ +**`dt.dex-engine.activity-worker.notification.poll-backoff.max-delay-ms`** [¶](#dtdex-engineactivity-workernotificationpoll-backoffmax-delay-ms){ .headerlink } +: Defines the max poll backoff delay in milliseconds of the notification activity worker. + + + + + +
Typeinteger
Default10000
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_POLL_BACKOFF_MAX_DELAY_MS
+ +**`dt.dex-engine.activity-worker.notification.poll-backoff.multiplier`** [¶](#dtdex-engineactivity-workernotificationpoll-backoffmultiplier){ .headerlink } +: Defines the poll backoff delay multiplier of the notification activity worker. + + + + + +
Typedouble
Default2.0
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_POLL_BACKOFF_MULTIPLIER
+ +**`dt.dex-engine.activity-worker.notification.poll-backoff.randomization-factor`** [¶](#dtdex-engineactivity-workernotificationpoll-backoffrandomization-factor){ .headerlink } +: Defines the poll backoff randomization factor of the notification activity worker. + + + + + +
Typedouble
Default0.2
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_NOTIFICATION_POLL_BACKOFF_RANDOMIZATION_FACTOR
+ +**`dt.dex-engine.activity-worker.package-metadata-resolution.enabled`** [¶](#dtdex-engineactivity-workerpackage-metadata-resolutionenabled){ .headerlink } +: Defines whether the package metadata activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_PACKAGE_METADATA_RESOLUTION_ENABLED
+ +**`dt.dex-engine.activity-worker.package-metadata-resolution.max-concurrency`** * [¶](#dtdex-engineactivity-workerpackage-metadata-resolutionmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the package metadata activity worker.

Note that a concurrency of N means that at most N PURLs batches will be resolved concurrently. Each batch performs HTTP requests against package registries. + + + + + +
Typeinteger
Default3
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_PACKAGE_METADATA_RESOLUTION_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.policy-evaluation.enabled`** [¶](#dtdex-engineactivity-workerpolicy-evaluationenabled){ .headerlink } +: Defines whether the policy evaluation activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_POLICY_EVALUATION_ENABLED
+ +**`dt.dex-engine.activity-worker.policy-evaluation.max-concurrency`** * [¶](#dtdex-engineactivity-workerpolicy-evaluationmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the policy evaluation activity worker. + + + + + +
Typeinteger
Default5
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_POLICY_EVALUATION_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.vuln-analysis-reconciliation.enabled`** [¶](#dtdex-engineactivity-workervuln-analysis-reconciliationenabled){ .headerlink } +: Defines whether the vulnerability analysis reconciliation activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_VULN_ANALYSIS_RECONCILIATION_ENABLED
+ +**`dt.dex-engine.activity-worker.vuln-analysis-reconciliation.max-concurrency`** * [¶](#dtdex-engineactivity-workervuln-analysis-reconciliationmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the vulnerability analysis reconciliation activity worker. + + + + + +
Typeinteger
Default5
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_VULN_ANALYSIS_RECONCILIATION_MAX_CONCURRENCY
+ +**`dt.dex-engine.activity-worker.vuln-analysis.enabled`** [¶](#dtdex-engineactivity-workervuln-analysisenabled){ .headerlink } +: Defines whether the notification activity worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_VULN_ANALYSIS_ENABLED
+ +**`dt.dex-engine.activity-worker.vuln-analysis.max-concurrency`** * [¶](#dtdex-engineactivity-workervuln-analysismax-concurrency){ .headerlink } +: Defines the maximum concurrency of the notification activity worker. + + + + + +
Typeinteger
Default10
ENVDT_DEX_ENGINE_ACTIVITY_WORKER_VULN_ANALYSIS_MAX_CONCURRENCY
+ +**`dt.dex-engine.external-event-buffer.flush-interval-ms`** [¶](#dtdex-engineexternal-event-bufferflush-interval-ms){ .headerlink } +: Defines the time in milliseconds between flushes of the external event buffer. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_EXTERNAL_EVENT_BUFFER_FLUSH_INTERVAL_MS
+ +**`dt.dex-engine.external-event-buffer.max-batch-size`** [¶](#dtdex-engineexternal-event-buffermax-batch-size){ .headerlink } +: Defines the maximum number of items of the external event buffer. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_EXTERNAL_EVENT_BUFFER_MAX_BATCH_SIZE
+ +**`dt.dex-engine.leader-election.enabled`** [¶](#dtdex-engineleader-electionenabled){ .headerlink } +: Whether leader election in the durable execution engine should be enabled.

Disabling leader election also disables the workflow task scheduler, activity task scheduler, and maintenance worker, as only the leader node is meant to handle those responsibilities. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_LEADER_ELECTION_ENABLED
+ +**`dt.dex-engine.leader-election.lease-check-interval-ms`** [¶](#dtdex-engineleader-electionlease-check-interval-ms){ .headerlink } +: Defines the interval in milliseconds in which leadership lease acquisition or extension is attempted.

Must be smaller than [`dt.dex-engine.leader-election.lease-duration-ms`](#dtdex-engineleader-electionlease-duration-ms) to avoid frequent leadership changes. + + + + + +
Typeinteger
Default15000
ENVDT_DEX_ENGINE_LEADER_ELECTION_LEASE_CHECK_INTERVAL_MS
+ +**`dt.dex-engine.leader-election.lease-duration-ms`** [¶](#dtdex-engineleader-electionlease-duration-ms){ .headerlink } +: Defines the duration in milliseconds for which leadership leases are acquired. + + + + + +
Typeinteger
Default30000
ENVDT_DEX_ENGINE_LEADER_ELECTION_LEASE_DURATION_MS
+ +**`dt.dex-engine.maintenance.run-deletion-batch-size`** [¶](#dtdex-enginemaintenancerun-deletion-batch-size){ .headerlink } +: Defines the maximum number of completed workflow runs to delete during a single execution of the maintenance worker. Deletion of large volumes of runs in one pass can lead to I/O spikes and increased table bloat.

If retention is not able to keep up with the volumes of runs, consider increasing the interval of the maintenance worker first. + + + + + +
Typeinteger
Default1000
ENVDT_DEX_ENGINE_MAINTENANCE_RUN_DELETION_BATCH_SIZE
+ +**`dt.dex-engine.maintenance.run-retention-duration`** [¶](#dtdex-enginemaintenancerun-retention-duration){ .headerlink } +: Defines the duration in ISO 8601 format after which completed workflow runs become eligible for deletion. + + + + + +
Typeduration
DefaultP1D
ENVDT_DEX_ENGINE_MAINTENANCE_RUN_RETENTION_DURATION
+ +**`dt.dex-engine.maintenance.worker.initial-delay-ms`** [¶](#dtdex-enginemaintenanceworkerinitial-delay-ms){ .headerlink } +: Defines the initial delay in milliseconds after which the maintenance worker will execute for the first time.

Note that only the leader node in the cluster will actually perform maintenance work. For nodes that are not leaders, maintenance is a no-op. + + + + + +
Typeinteger
Default60000
ENVDT_DEX_ENGINE_MAINTENANCE_WORKER_INITIAL_DELAY_MS
+ +**`dt.dex-engine.maintenance.worker.interval-ms`** [¶](#dtdex-enginemaintenanceworkerinterval-ms){ .headerlink } +: Defines the interval in milliseconds at which the maintenance worker will execute.

Note that only the leader node in the cluster will actually perform maintenance work. For nodes that are not leaders, maintenance is a no-op. + + + + + +
Typeinteger
Default1800000
ENVDT_DEX_ENGINE_MAINTENANCE_WORKER_INTERVAL_MS
+ +**`dt.dex-engine.metrics.collector.enabled`** [¶](#dtdex-enginemetricscollectorenabled){ .headerlink } +: Defines whether the metrics collector should be enabled.

The collector is responsible for collecting metrics from the database, such as the distribution of workflow run statuses, task queue capacities and depths, and more.

It is recommended to keep it enabled for monitoring purposes, but may be disabled in case it generates undesired load. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_METRICS_COLLECTOR_ENABLED
+ +**`dt.dex-engine.metrics.collector.initial-delay-ms`** [¶](#dtdex-enginemetricscollectorinitial-delay-ms){ .headerlink } +: Defines the initial delay in milliseconds after which the metrics collector will first run. + + + + + +
Typeinteger
Default15000
ENVDT_DEX_ENGINE_METRICS_COLLECTOR_INITIAL_DELAY_MS
+ +**`dt.dex-engine.metrics.collector.interval-ms`** [¶](#dtdex-enginemetricscollectorinterval-ms){ .headerlink } +: Defines the interval in milliseconds in which the metrics collector runs. + + + + + +
Typeinteger
Default30000
ENVDT_DEX_ENGINE_METRICS_COLLECTOR_INTERVAL_MS
+ +**`dt.dex-engine.run-history-cache.evict-after-access-ms`** [¶](#dtdex-enginerun-history-cacheevict-after-access-ms){ .headerlink } +: Defines the time in milliseconds for which workflow run event histories are cached.

Histories are only cached for non-terminal runs, to improve performance of replay. Cached histories are automatically evicted when the corresponding run terminates. + + + + + +
Typeinteger
Default300000
ENVDT_DEX_ENGINE_RUN_HISTORY_CACHE_EVICT_AFTER_ACCESS_MS
+ +**`dt.dex-engine.run-history-cache.max-size`** [¶](#dtdex-enginerun-history-cachemax-size){ .headerlink } +: Defines the maximum number of workflow runs for which histories may be cached. + + + + + +
Typeinteger
Default1000
ENVDT_DEX_ENGINE_RUN_HISTORY_CACHE_MAX_SIZE
+ +**`dt.dex-engine.task-event-buffer.flush-interval-ms`** [¶](#dtdex-enginetask-event-bufferflush-interval-ms){ .headerlink } +: Defines the time in milliseconds between flushes of the task event buffer.

Increasing this interval may yield better throughput while reducing the database load, but also increases end-to-end latency of workflow and activity executions. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_TASK_EVENT_BUFFER_FLUSH_INTERVAL_MS
+ +**`dt.dex-engine.task-event-buffer.max-batch-size`** [¶](#dtdex-enginetask-event-buffermax-batch-size){ .headerlink } +: Defines the maximum number of items that will be flushed at once.

Increasing this value may yield better throughput, at the expense of higher latency and potentially larger blast radius in case a task event causes failures during the flush.

Since flushes are atomic, a single event failing to be flushed impacts the entire batch. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_TASK_EVENT_BUFFER_MAX_BATCH_SIZE
+ +**`dt.dex-engine.workers.enabled`** [¶](#dtdex-engineworkersenabled){ .headerlink } +: Whether all durable execution task workers should be enabled.

Acts as a global kill switch that takes precedence over individual worker settings. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_WORKERS_ENABLED
+ +**`dt.dex-engine.workflow-task-scheduler.poll-interval-ms`** [¶](#dtdex-engineworkflow-task-schedulerpoll-interval-ms){ .headerlink } +: Defines the interval in milliseconds in which the workflow task scheduler polls for tasks to enqueue for execution. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_WORKFLOW_TASK_SCHEDULER_POLL_INTERVAL_MS
+ +**`dt.dex-engine.workflow-worker.default.enabled`** [¶](#dtdex-engineworkflow-workerdefaultenabled){ .headerlink } +: Defines whether the default workflow worker should be enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_DEX_ENGINE_WORKFLOW_WORKER_DEFAULT_ENABLED
+ +**`dt.dex-engine.workflow-worker.default.max-concurrency`** * [¶](#dtdex-engineworkflow-workerdefaultmax-concurrency){ .headerlink } +: Defines the maximum concurrency of the default workflow worker.

Note that workflow workers do not perform any I/O (although they may block while waiting for semaphores and buffer flushes), and are executed with virtual threads. This means that it's usually perfectly fine to have a high degree of concurrency, without risking excessive resource usage or I/O thrashing. + + + + + +
Typeinteger
Default100
ENVDT_DEX_ENGINE_WORKFLOW_WORKER_DEFAULT_MAX_CONCURRENCY
+ + + +## General + +**`dt.api.key.prefix`** [¶](#dtapikeyprefix){ .headerlink } +: Defines the prefix to be used for API keys. A maximum prefix length of 251 characters is supported. The prefix may also be left empty. + + + + + +
Typestring
Defaultodt_
ENVDT_API_KEY_PREFIX
+ +**`dt.auth.session-timeout-ms`** [¶](#dtauthsession-timeout-ms){ .headerlink } +: Defines the user session timeout in milliseconds. + + + + + +
Typeinteger
Default28800000
ENVDT_AUTH_SESSION_TIMEOUT_MS
+ +**`dt.bcrypt.rounds`** * [¶](#dtbcryptrounds){ .headerlink } +: Specifies the number of bcrypt rounds to use when hashing a user's password. The higher the number the more secure the password, at the expense of hardware resources and additional time to generate the hash. + + + + + +
Typeinteger
Default14
ENVDT_BCRYPT_ROUNDS
+ +**`dt.config.log.values`** [¶](#dtconfiglogvalues){ .headerlink } +: Defines whether config value lookups should be logged.

Logging happens at DEBUG level. To make the logs visible, you must configure `dt.logging.level."io.smallrye.config"=DEBUG`.

Note that this will not mask or omit any secrets. **Do not use in production environments!** + + + + + +
Typeboolean
Defaultfalse
ENVDT_CONFIG_LOG_VALUES
+ +**`dt.config.profile`** [¶](#dtconfigprofile){ .headerlink } +: Defines the configuration profile to apply.

For example, the `web` profile may be used to disable any background processing, effectively turning the node into a web-only instance. + + + + + +
Typestring
Defaultnull
ENVDT_CONFIG_PROFILE
+ +**`dt.data.directory`** * [¶](#dtdatadirectory){ .headerlink } +: Defines the path to the data directory. This directory will hold logs, keys, and any database or index files along with application-specific files or directories. + + + + + +
Typestring
Default${user.home}/.dependency-track
ENVDT_DATA_DIRECTORY
+ +**`dt.init.and.exit`** [¶](#dtinitandexit){ .headerlink } +: Whether to only execute initialization tasks and exit. + + + + + +
Typeboolean
Defaultfalse
ENVDT_INIT_AND_EXIT
+ +**`dt.init.task.database.migration.enabled`** [¶](#dtinittaskdatabasemigrationenabled){ .headerlink } +: Whether to enable the database migration init task. Has no effect unless [`dt.init.tasks.enabled`](#dtinittasksenabled) is `true`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASK_DATABASE_MIGRATION_ENABLED
+ +**`dt.init.task.database.partition.maintenance.enabled`** [¶](#dtinittaskdatabasepartitionmaintenanceenabled){ .headerlink } +: Whether to enable the database partition maintenance init task. Has no effect unless [`dt.init.tasks.enabled`](#dtinittasksenabled) is `true`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASK_DATABASE_PARTITION_MAINTENANCE_ENABLED
+ +**`dt.init.task.database.seeding.enabled`** [¶](#dtinittaskdatabaseseedingenabled){ .headerlink } +: Whether to enable the database seeding init task. Seeding involves populating the database with default objects, such as permissions, users, licenses, etc. Has no effect unless [`dt.init.tasks.enabled`](#dtinittasksenabled) is `true`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASK_DATABASE_SEEDING_ENABLED
+ +**`dt.init.task.dex.engine.database.migration.enabled`** [¶](#dtinittaskdexenginedatabasemigrationenabled){ .headerlink } +: Whether to enable the durable execution engine database migration init task. Has no effect unless [`dt.init.tasks.enabled`](#dtinittasksenabled) is `true`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASK_DEX_ENGINE_DATABASE_MIGRATION_ENABLED
+ +**`dt.init.task.key.generation.enabled`** [¶](#dtinittaskkeygenerationenabled){ .headerlink } +: Whether to enable the key generation init task. Has no effect unless [`dt.init.tasks.enabled`](#dtinittasksenabled) is `true`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASK_KEY_GENERATION_ENABLED
+ +**`dt.init.tasks.enabled`** [¶](#dtinittasksenabled){ .headerlink } +: Whether to execute initialization tasks on startup. + + + + + +
Typeboolean
Defaulttrue
ENVDT_INIT_TASKS_ENABLED
+ +**`dt.telemetry.submission.enabled.default`** [¶](#dttelemetrysubmissionenableddefault){ .headerlink } +: Defines the default value for the telemetry submission enabled setting.

This is only used during initial database seeding. Once the setting exists in the database, it can be toggled via the REST API or the admin UI.

To opt out of telemetry before first startup, set this to `false`. + + + + + +
Typeboolean
Defaulttrue
ENVDT_TELEMETRY_SUBMISSION_ENABLED_DEFAULT
+ +**`dt.tmp.delay.bom.processed.notification`** [¶](#dttmpdelaybomprocessednotification){ .headerlink } +: Delays the BOM_PROCESSED notification until the vulnerability analysis associated with a given BOM upload is completed. The intention being that it is then "safe" to query the API for any identified vulnerabilities. This is specifically for cases where polling the /api/v1/bom/token/ endpoint is not feasible. THIS IS A TEMPORARY FUNCTIONALITY AND MAY BE REMOVED IN FUTURE RELEASES WITHOUT FURTHER NOTICE. + + + + + +
Typeboolean
Defaultfalse
ENVDT_TMP_DELAY_BOM_PROCESSED_NOTIFICATION
+ +**`dt.vulnerability.policy.bundle.auth.bearer.token`** [¶](#dtvulnerabilitypolicybundleauthbearertoken){ .headerlink } +: Defines the bearer token to be used for authentication against the service hosting the vulnerability policy bundle. + + + + + +
Typestring
Defaultnull
ENVDT_VULNERABILITY_POLICY_BUNDLE_AUTH_BEARER_TOKEN
+ +**`dt.vulnerability.policy.bundle.auth.password`** [¶](#dtvulnerabilitypolicybundleauthpassword){ .headerlink } +: Defines the password to be used for basic authentication against the service hosting the vulnerability policy bundle. + + + + + +
Typestring
Defaultnull
ENVDT_VULNERABILITY_POLICY_BUNDLE_AUTH_PASSWORD
+ +**`dt.vulnerability.policy.bundle.auth.username`** [¶](#dtvulnerabilitypolicybundleauthusername){ .headerlink } +: Defines the username to be used for basic authentication against the service hosting the vulnerability policy bundle. + + + + + +
Typestring
Defaultnull
ENVDT_VULNERABILITY_POLICY_BUNDLE_AUTH_USERNAME
+ +**`dt.vulnerability.policy.bundle.url`** [¶](#dtvulnerabilitypolicybundleurl){ .headerlink } +: Defines where to fetch the vulnerability policy bundle from. + + + + + + +
Typestring
Defaultnull
Examplehttps://example.com/bundles/bundle.zip
ENVDT_VULNERABILITY_POLICY_BUNDLE_URL
+ + + +## HTTP + +**`dt.http.proxy.address`** [¶](#dthttpproxyaddress){ .headerlink } +: HTTP proxy address. If set, then [`dt.http.proxy.port`](#dthttpproxyport) must be set too. + + + + + + +
Typestring
Defaultnull
Exampleproxy.example.com
ENVDT_HTTP_PROXY_ADDRESS
+ +**`dt.http.proxy.password`** [¶](#dthttpproxypassword){ .headerlink } +: + + + + + +
Typestring
Defaultnull
ENVDT_HTTP_PROXY_PASSWORD
+ +**`dt.http.proxy.password.file`** [¶](#dthttpproxypasswordfile){ .headerlink } +: Specifies the file to load the HTTP proxy password from. If set, takes precedence over [`dt.http.proxy.password`](#dthttpproxypassword). + + + + + + +
Typestring
Defaultnull
Example/var/run/secrets/http-proxy-password
ENVDT_HTTP_PROXY_PASSWORD_FILE
+ +**`dt.http.proxy.port`** [¶](#dthttpproxyport){ .headerlink } +: + + + + + + +
Typeinteger
Defaultnull
Example8888
ENVDT_HTTP_PROXY_PORT
+ +**`dt.http.proxy.username`** [¶](#dthttpproxyusername){ .headerlink } +: + + + + + +
Typestring
Defaultnull
ENVDT_HTTP_PROXY_USERNAME
+ +**`dt.http.timeout.connection`** [¶](#dthttptimeoutconnection){ .headerlink } +: Defines the connection timeout in seconds for outbound HTTP connections. + + + + + +
Typeinteger
Default30
ENVDT_HTTP_TIMEOUT_CONNECTION
+ +**`dt.http.timeout.pool`** [¶](#dthttptimeoutpool){ .headerlink } +: Defines the request timeout in seconds for outbound HTTP connections. + + + + + +
Typeinteger
Default60
ENVDT_HTTP_TIMEOUT_POOL
+ +**`dt.http.timeout.socket`** [¶](#dthttptimeoutsocket){ .headerlink } +: Defines the socket / read timeout in seconds for outbound HTTP connections. + + + + + +
Typeinteger
Default30
ENVDT_HTTP_TIMEOUT_SOCKET
+ +**`dt.no.proxy`** [¶](#dtnoproxy){ .headerlink } +: + + + + + + +
Typestring
Defaultnull
Examplelocalhost,127.0.0.1
ENVDT_NO_PROXY
+ + + +## LDAP + +**`dt.ldap.attribute.mail`** [¶](#dtldapattributemail){ .headerlink } +: Specifies the LDAP attribute used to store a users email address + + + + + +
Typestring
Defaultmail
ENVDT_LDAP_ATTRIBUTE_MAIL
+ +**`dt.ldap.attribute.name`** [¶](#dtldapattributename){ .headerlink } +: Specifies the Attribute that identifies a users ID.

Example (Microsoft Active Directory):
  • userPrincipalName
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • uid
+ + + + + +
Typestring
DefaultuserPrincipalName
ENVDT_LDAP_ATTRIBUTE_NAME
+ +**`dt.ldap.auth.username.format`** [¶](#dtldapauthusernameformat){ .headerlink } +: Specifies if the username entered during login needs to be formatted prior to asserting credentials against the directory. For Active Directory, the userPrincipal attribute typically ends with the domain, whereas the samAccountName attribute and other directory server implementations do not. The %s variable will be substituted with the username asserted during login.

Example (Microsoft Active Directory):
  • %s@example.com
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • %s
+ + + + + + +
Typestring
Defaultnull
Example%s@example.com
ENVDT_LDAP_AUTH_USERNAME_FORMAT
+ +**`dt.ldap.basedn`** [¶](#dtldapbasedn){ .headerlink } +: Specifies the base DN that all queries should search from + + + + + + +
Typestring
Defaultnull
Exampledc=example,dc=com
ENVDT_LDAP_BASEDN
+ +**`dt.ldap.bind.password`** [¶](#dtldapbindpassword){ .headerlink } +: If anonymous access is not permitted, specify a password for the username used to bind. + + + + + +
Typestring
Defaultnull
ENVDT_LDAP_BIND_PASSWORD
+ +**`dt.ldap.bind.username`** [¶](#dtldapbindusername){ .headerlink } +: If anonymous access is not permitted, specify a username with limited access to the directory, just enough to perform searches. This should be the fully qualified DN of the user. + + + + + +
Typestring
Defaultnull
ENVDT_LDAP_BIND_USERNAME
+ +**`dt.ldap.enabled`** [¶](#dtldapenabled){ .headerlink } +: Defines if LDAP will be used for user authentication. If enabled, `dt.ldap.*` properties should be set accordingly. + + + + + +
Typeboolean
Defaultfalse
ENVDT_LDAP_ENABLED
+ +**`dt.ldap.groups.filter`** [¶](#dtldapgroupsfilter){ .headerlink } +: Specifies the LDAP search filter used to retrieve all groups from the directory.

Example (Microsoft Active Directory):
  • (&(objectClass=group)(objectCategory=Group))
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • (&(objectClass=groupOfUniqueNames))
+ + + + + +
Typestring
Default(&(objectClass=group)(objectCategory=Group))
ENVDT_LDAP_GROUPS_FILTER
+ +**`dt.ldap.groups.search.filter`** [¶](#dtldapgroupssearchfilter){ .headerlink } +: Specifies the LDAP search filter used to search for groups by their name. The `{SEARCH_TERM}` variable will be substituted at runtime.

Example (Microsoft Active Directory):
  • (&(objectClass=group)(objectCategory=Group)(cn=*{SEARCH_TERM}*))
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • (&(objectClass=groupOfUniqueNames)(cn=*{SEARCH_TERM}*))
+ + + + + +
Typestring
Default(&(objectClass=group)(objectCategory=Group)(cn=*{SEARCH_TERM}*))
ENVDT_LDAP_GROUPS_SEARCH_FILTER
+ +**`dt.ldap.security.auth`** [¶](#dtldapsecurityauth){ .headerlink } +: Specifies the LDAP security authentication level to use. Its value is one of the following strings: "none", "simple", "strong". If this property is empty or unspecified, the behaviour is determined by the service provider. + + + + + + +
Typeenum
Defaultsimple
Valid Values[none, simple, strong]
ENVDT_LDAP_SECURITY_AUTH
+ +**`dt.ldap.server.url`** [¶](#dtldapserverurl){ .headerlink } +: Specifies the LDAP server URL.

Examples (Microsoft Active Directory):
  • ldap://ldap.example.com:3268
  • ldaps://ldap.example.com:3269
Examples (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • ldap://ldap.example.com:389
  • ldaps://ldap.example.com:636
+ + + + + +
Typestring
Defaultnull
ENVDT_LDAP_SERVER_URL
+ +**`dt.ldap.team.synchronization`** [¶](#dtldapteamsynchronization){ .headerlink } +: This option will ensure that team memberships for LDAP users are dynamic and synchronized with membership of LDAP groups. When a team is mapped to an LDAP group, all local LDAP users will automatically be assigned to the team if they are a member of the group the team is mapped to. If the user is later removed from the LDAP group, they will also be removed from the team. This option provides the ability to dynamically control user permissions via an external directory. + + + + + +
Typeboolean
Defaultfalse
ENVDT_LDAP_TEAM_SYNCHRONIZATION
+ +**`dt.ldap.user.groups.filter`** [¶](#dtldapusergroupsfilter){ .headerlink } +: Specifies the LDAP search filter to use to query a user and retrieve a list of groups the user is a member of. The `{USER_DN}` variable will be substituted with the actual value of the users DN at runtime.

Example (Microsoft Active Directory):
  • (&(objectClass=group)(objectCategory=Group)(member={USER_DN}))
Example (Microsoft Active Directory - with nested group support):
  • (member:1.2.840.113556.1.4.1941:={USER_DN})
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • (&(objectClass=groupOfUniqueNames)(uniqueMember={USER_DN}))
+ + + + + +
Typestring
Default(member:1.2.840.113556.1.4.1941:={USER_DN})
ENVDT_LDAP_USER_GROUPS_FILTER
+ +**`dt.ldap.user.provisioning`** [¶](#dtldapuserprovisioning){ .headerlink } +: Specifies if mapped LDAP accounts are automatically created upon successful authentication. When a user logs in with valid credentials but an account has not been previously provisioned, an authentication failure will be returned. This allows admins to control specifically which ldap users can access the system and which users cannot. When this value is set to true, a local ldap user will be created and mapped to the ldap account automatically. This automatic provisioning only affects authentication, not authorization. + + + + + +
Typeboolean
Defaultfalse
ENVDT_LDAP_USER_PROVISIONING
+ +**`dt.ldap.users.search.filter`** [¶](#dtldapuserssearchfilter){ .headerlink } +: Specifies the LDAP search filter used to search for users by their name. The {SEARCH_TERM} variable will be substituted at runtime.

Example (Microsoft Active Directory):
  • (&(objectClass=group)(objectCategory=Group)(cn=*{SEARCH_TERM}*))
Example (ApacheDS, Fedora 389 Directory, NetIQ/Novell eDirectory, etc):
  • (&(objectClass=inetOrgPerson)(cn=*{SEARCH_TERM}*))
+ + + + + +
Typestring
Default(&(objectClass=user)(objectCategory=Person)(cn=*{SEARCH_TERM}*))
ENVDT_LDAP_USERS_SEARCH_FILTER
+ + + +## Notification + +**`dt.notification-publisher.console.enabled`** [¶](#dtnotification-publisherconsoleenabled){ .headerlink } +: Defines whether the console notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_CONSOLE_ENABLED
+ +**`dt.notification-publisher.email.allow-local-connections`** [¶](#dtnotification-publisheremailallow-local-connections){ .headerlink } +: Defines whether the email notification publisher is allowed to connect to local hosts. + + + + + +
Typeboolean
Defaultfalse
ENVDT_NOTIFICATION_PUBLISHER_EMAIL_ALLOW_LOCAL_CONNECTIONS
+ +**`dt.notification-publisher.email.enabled`** [¶](#dtnotification-publisheremailenabled){ .headerlink } +: Defines whether the email notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_EMAIL_ENABLED
+ +**`dt.notification-publisher.jira.enabled`** [¶](#dtnotification-publisherjiraenabled){ .headerlink } +: Defines whether the Jira notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_JIRA_ENABLED
+ +**`dt.notification-publisher.kafka.allow-local-connections`** [¶](#dtnotification-publisherkafkaallow-local-connections){ .headerlink } +: Defines whether the Kafka notification publisher is allowed to connect to local hosts. + + + + + +
Typeboolean
Defaultfalse
ENVDT_NOTIFICATION_PUBLISHER_KAFKA_ALLOW_LOCAL_CONNECTIONS
+ +**`dt.notification-publisher.kafka.enabled`** [¶](#dtnotification-publisherkafkaenabled){ .headerlink } +: Defines whether the Kafka notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_KAFKA_ENABLED
+ +**`dt.notification-publisher.mattermost.enabled`** [¶](#dtnotification-publishermattermostenabled){ .headerlink } +: Defines whether the Mattermost notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_MATTERMOST_ENABLED
+ +**`dt.notification-publisher.msteams.enabled`** [¶](#dtnotification-publishermsteamsenabled){ .headerlink } +: Defines whether the Microsoft Teams notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_MSTEAMS_ENABLED
+ +**`dt.notification-publisher.slack.enabled`** [¶](#dtnotification-publisherslackenabled){ .headerlink } +: Defines whether the Slack notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_SLACK_ENABLED
+ +**`dt.notification-publisher.webex.enabled`** [¶](#dtnotification-publisherwebexenabled){ .headerlink } +: Defines whether the WebEx notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_WEBEX_ENABLED
+ +**`dt.notification-publisher.webhook.enabled`** [¶](#dtnotification-publisherwebhookenabled){ .headerlink } +: Defines whether the Webhook notification publisher is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_PUBLISHER_WEBHOOK_ENABLED
+ +**`dt.notification.outbox-relay.batch-size`** * [¶](#dtnotificationoutbox-relaybatch-size){ .headerlink } +: Defines the number of notifications that the outbox relay will process in a batch. + + + + + +
Typeinteger
Default100
ENVDT_NOTIFICATION_OUTBOX_RELAY_BATCH_SIZE
+ +**`dt.notification.outbox-relay.enabled`** * [¶](#dtnotificationoutbox-relayenabled){ .headerlink } +: Defines whether the notification outbox relay should be enabled. When disabled, notifications will still be emitted to the outbox table, but not be delivered. Should generally stay enabled, unless:
  • The relay has a critical issue that impacts the rest of the system
  • You run a multi-node cluster and want more granular control over which nodes run the relay
+ + + + + +
Typeboolean
Defaulttrue
ENVDT_NOTIFICATION_OUTBOX_RELAY_ENABLED
+ +**`dt.notification.outbox-relay.large-notification-threshold-bytes`** * [¶](#dtnotificationoutbox-relaylarge-notification-threshold-bytes){ .headerlink } +: Defines the size in bytes at which notifications are considered "large".

Large notifications will be offloaded to file storage before being sent to the dex engine for publishing. + + + + + +
Typeinteger
Default65536
ENVDT_NOTIFICATION_OUTBOX_RELAY_LARGE_NOTIFICATION_THRESHOLD_BYTES
+ +**`dt.notification.outbox-relay.poll-interval-ms`** * [¶](#dtnotificationoutbox-relaypoll-interval-ms){ .headerlink } +: Defines the interval in milliseconds in which the notification outbox relay will poll for records in the notification outbox table. Increasing this value will cause higher notification latencies, but incurs a lesser load on the database. + + + + + +
Typeinteger
Default1000
ENVDT_NOTIFICATION_OUTBOX_RELAY_POLL_INTERVAL_MS
+ + + +## Observability + +**`dt.management.host`** [¶](#dtmanagementhost){ .headerlink } +: Defines the host for the management server, which exposes health and metrics endpoints independently of the main server. + + + + + +
Typestring
Default0.0.0.0
ENVDT_MANAGEMENT_HOST
+ +**`dt.management.port`** [¶](#dtmanagementport){ .headerlink } +: Defines the port for the management server, which exposes health and metrics endpoints independently of the main server. + + + + + +
Typeinteger
Default9000
ENVDT_MANAGEMENT_PORT
+ +**`dt.metrics.auth.password`** [¶](#dtmetricsauthpassword){ .headerlink } +: Defines the password required to access metrics. Has no effect when [`dt.metrics.auth.username`](#dtmetricsauthusername) is not set. + + + + + +
Typestring
Defaultnull
ENVDT_METRICS_AUTH_PASSWORD
+ +**`dt.metrics.auth.username`** [¶](#dtmetricsauthusername){ .headerlink } +: Defines the username required to access metrics. Has no effect when [`dt.metrics.auth.password`](#dtmetricsauthpassword) is not set. + + + + + +
Typestring
Defaultnull
ENVDT_METRICS_AUTH_USERNAME
+ +**`dt.metrics.enabled`** [¶](#dtmetricsenabled){ .headerlink } +: Defines whether Prometheus metrics will be exposed. If enabled, metrics will be available via the /metrics endpoint of the management server. + + + + + +
Typeboolean
Defaultfalse
ENVDT_METRICS_ENABLED
+ + + +## OpenID Connect + +**`dt.oidc.client.id`** [¶](#dtoidcclientid){ .headerlink } +: Defines the client ID to be used for OpenID Connect. The client ID should be the same as the one configured for the frontend, and will only be used to validate ID tokens. + + + + + +
Typestring
Defaultnull
ENVDT_OIDC_CLIENT_ID
+ +**`dt.oidc.enabled`** [¶](#dtoidcenabled){ .headerlink } +: Defines if OpenID Connect will be used for user authentication. If enabled, `dt.oidc.*` properties should be set accordingly. + + + + + +
Typeboolean
Defaultfalse
ENVDT_OIDC_ENABLED
+ +**`dt.oidc.issuer`** [¶](#dtoidcissuer){ .headerlink } +: Defines the issuer URL to be used for OpenID Connect. This issuer MUST support provider configuration via the `/.well-known/openid-configuration` endpoint. See also:
  • https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
  • https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig
+ + + + + +
Typestring
Defaultnull
ENVDT_OIDC_ISSUER
+ +**`dt.oidc.team.synchronization`** [¶](#dtoidcteamsynchronization){ .headerlink } +: This option will ensure that team memberships for OpenID Connect users are dynamic and synchronized with membership of OpenID Connect groups or assigned roles. When a team is mapped to an OpenID Connect group, all local OpenID Connect users will automatically be assigned to the team if they are a member of the group the team is mapped to. If the user is later removed from the OpenID Connect group, they will also be removed from the team. This option provides the ability to dynamically control user permissions via the identity provider. Note that team synchronization is only performed during user provisioning and after successful authentication. + + + + + +
Typeboolean
Defaultfalse
ENVDT_OIDC_TEAM_SYNCHRONIZATION
+ +**`dt.oidc.teams.claim`** [¶](#dtoidcteamsclaim){ .headerlink } +: Defines the name of the claim that contains group memberships or role assignments in the provider's userinfo endpoint. The claim must be an array of strings, or a comma-delimited string. Most public identity providers do not support group or role management. When using a customizable / on-demand hosted identity provider, name, content, and inclusion in the userinfo endpoint will most likely need to be configured. + + + + + +
Typestring
Defaultgroups
ENVDT_OIDC_TEAMS_CLAIM
+ +**`dt.oidc.user.provisioning`** [¶](#dtoidcuserprovisioning){ .headerlink } +: Specifies if mapped OpenID Connect accounts are automatically created upon successful authentication. When a user logs in with a valid access token but an account has not been previously provisioned, an authentication failure will be returned. This allows admins to control specifically which OpenID Connect users can access the system and which users cannot. When this value is set to true, a local OpenID Connect user will be created and mapped to the OpenID Connect account automatically. This automatic provisioning only affects authentication, not authorization. + + + + + +
Typeboolean
Defaultfalse
ENVDT_OIDC_USER_PROVISIONING
+ +**`dt.oidc.username.claim`** [¶](#dtoidcusernameclaim){ .headerlink } +: Defines the name of the claim that contains the username in the provider's userinfo endpoint. Common claims are `name`, `username`, `preferred_username` or `nickname`. See also:
  • https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse
+ + + + + +
Typestring
Defaultname
ENVDT_OIDC_USERNAME_CLAIM
+ + + +## Secrets + +**`dt.secret-management.cache.enabled`** * [¶](#dtsecret-managementcacheenabled){ .headerlink } +: Defines whether secret caching should be enabled. + + + + + +
Typeboolean
Defaultfalse
ENVDT_SECRET_MANAGEMENT_CACHE_ENABLED
+ +**`dt.secret-management.cache.expire-after-write-ms`** [¶](#dtsecret-managementcacheexpire-after-write-ms){ .headerlink } +: Defines the duration in milliseconds for which secrets should be cached. + + + + + +
Typeinteger
Default60000
ENVDT_SECRET_MANAGEMENT_CACHE_EXPIRE_AFTER_WRITE_MS
+ +**`dt.secret-management.cache.max-size`** [¶](#dtsecret-managementcachemax-size){ .headerlink } +: Defines the maximum number of secrets to keep in the cache. + + + + + +
Typeinteger
Default100
ENVDT_SECRET_MANAGEMENT_CACHE_MAX_SIZE
+ +**`dt.secret-management.database.datasource.name`** [¶](#dtsecret-managementdatabasedatasourcename){ .headerlink } +: Defines the name of the data source to be used by the database secret manager.

Required when [`dt.secret-management.provider`](#dtsecret-managementprovider) is `database`. + + + + + +
Typestring
Defaultdefault
ENVDT_SECRET_MANAGEMENT_DATABASE_DATASOURCE_NAME
+ +**`dt.secret-management.database.kek`** [¶](#dtsecret-managementdatabasekek){ .headerlink } +: Defines a base64-encoded AES-256 key (32 bytes) to use as the key encryption key (KEK) for the database secret manager.

A secure key may be generated using OpenSSL like this: `openssl rand -base64 32`

When set, takes precedence over [`dt.secret-management.database.kek`](#dtsecret-managementdatabasekek)-keyset.path. Unlike the keyset file approach, this option does not support KEK rotation.

Must be the same for all nodes in the cluster. When different keys are detected, the application will fail to start. + + + + + +
Typestring
Defaultnull
ENVDT_SECRET_MANAGEMENT_DATABASE_KEK
+ +**`dt.secret-management.database.kek-keyset.create-if-missing`** [¶](#dtsecret-managementdatabasekek-keysetcreate-if-missing){ .headerlink } +: Defines whether a key encryption keyset should be created if it doesn't already exist. + + + + + +
Typeboolean
Defaulttrue
ENVDT_SECRET_MANAGEMENT_DATABASE_KEK_KEYSET_CREATE_IF_MISSING
+ +**`dt.secret-management.database.kek-keyset.path`** [¶](#dtsecret-managementdatabasekek-keysetpath){ .headerlink } +: Defines the path to the key encryption keyset to use for the database secret manager.

Must point to the same file for all nodes in the cluster, e.g. using a shared volume or mounted k8s secret. When different keysets are detected, the application will fail to start. + + + + + +
Typestring
Default${dt.data.directory}/keys/secret-management-kek.json
ENVDT_SECRET_MANAGEMENT_DATABASE_KEK_KEYSET_PATH
+ +**`dt.secret-management.provider`** * [¶](#dtsecret-managementprovider){ .headerlink } +: Defines the secret management type to use. + + + + + + +
Typeenum
Defaultdatabase
Valid Values[database, env]
ENVDT_SECRET_MANAGEMENT_PROVIDER
+ + + +## Storage + +**`dt.file-storage.local.compression.level`** [¶](#dtfile-storagelocalcompressionlevel){ .headerlink } +: Defines the zstd compression level to use for local file storage. + + + + + + +
Typeinteger
Default5
Valid Values[-7..22]
ENVDT_FILE_STORAGE_LOCAL_COMPRESSION_LEVEL
+ +**`dt.file-storage.local.directory`** [¶](#dtfile-storagelocaldirectory){ .headerlink } +: Defines the local directory where files shall be stored. + + + + + +
Typestring
Default${dt.data.directory}/storage
ENVDT_FILE_STORAGE_LOCAL_DIRECTORY
+ +**`dt.file-storage.provider`** [¶](#dtfile-storageprovider){ .headerlink } +: Defines the file storage provider to use. + + + + + + +
Typeenum
Defaultlocal
Valid Values[local, memory, s3]
ENVDT_FILE_STORAGE_PROVIDER
+ +**`dt.file-storage.s3.access.key`** [¶](#dtfile-storages3accesskey){ .headerlink } +: Defines the S3 access key / username. + + + + + +
Typestring
Defaultnull
ENVDT_FILE_STORAGE_S3_ACCESS_KEY
+ +**`dt.file-storage.s3.bucket`** [¶](#dtfile-storages3bucket){ .headerlink } +: Defines the name of the S3 bucket. The existence of the bucket will be verified during startup. + + + + + +
Typestring
Defaultnull
ENVDT_FILE_STORAGE_S3_BUCKET
+ +**`dt.file-storage.s3.compression.level`** [¶](#dtfile-storages3compressionlevel){ .headerlink } +: Defines the zstd compression level to use for S3 file storage. + + + + + + +
Typeinteger
Default5
Valid Values[-7..22]
ENVDT_FILE_STORAGE_S3_COMPRESSION_LEVEL
+ +**`dt.file-storage.s3.connect-timeout-ms`** [¶](#dtfile-storages3connect-timeout-ms){ .headerlink } +: Defines the HTTP connect timeout for S3 requests in milliseconds. + + + + + +
Typeinteger
Defaultnull
ENVDT_FILE_STORAGE_S3_CONNECT_TIMEOUT_MS
+ +**`dt.file-storage.s3.endpoint`** [¶](#dtfile-storages3endpoint){ .headerlink } +: Defines the S3 endpoint URL. + + + + + +
Typestring
Defaultnull
ENVDT_FILE_STORAGE_S3_ENDPOINT
+ +**`dt.file-storage.s3.read-timeout-ms`** [¶](#dtfile-storages3read-timeout-ms){ .headerlink } +: Defines the HTTP read timeout for S3 requests in milliseconds. + + + + + +
Typeinteger
Defaultnull
ENVDT_FILE_STORAGE_S3_READ_TIMEOUT_MS
+ +**`dt.file-storage.s3.region`** [¶](#dtfile-storages3region){ .headerlink } +: Defines the region of the S3 bucket. + + + + + +
Typestring
Defaultnull
ENVDT_FILE_STORAGE_S3_REGION
+ +**`dt.file-storage.s3.secret.key`** [¶](#dtfile-storages3secretkey){ .headerlink } +: Defines the S3 secret key / password. + + + + + +
Typestring
Defaultnull
ENVDT_FILE_STORAGE_S3_SECRET_KEY
+ +**`dt.file-storage.s3.write-timeout-ms`** [¶](#dtfile-storages3write-timeout-ms){ .headerlink } +: Defines the HTTP write timeout for S3 requests in milliseconds. + + + + + +
Typeinteger
Defaultnull
ENVDT_FILE_STORAGE_S3_WRITE_TIMEOUT_MS
+ + + +## Task Execution + +**`dt.worker.thread.multiplier`** * [¶](#dtworkerthreadmultiplier){ .headerlink } +: Defines a multiplier that is used to calculate the number of threads used by the event subsystem. This property is only used when [`dt.worker.threads`](#dtworkerthreads) is set to 0. A machine with 4 cores and a multiplier of 4, will use (at most) 16 worker threads. + + + + + +
Typeinteger
Default4
ENVDT_WORKER_THREAD_MULTIPLIER
+ +**`dt.worker.threads`** * [¶](#dtworkerthreads){ .headerlink } +: Defines the number of worker threads that the event subsystem will consume. Events occur asynchronously and are processed by the Event subsystem. This value should be large enough to handle most production situations without introducing much delay, yet small enough not to pose additional load on an already resource-constrained server. A value of 0 will instruct Alpine to allocate 1 thread per CPU core. This can further be tweaked using the [`dt.worker.thread.multiplier`](#dtworkerthreadmultiplier) property. + + + + + +
Typeinteger
Default0
ENVDT_WORKER_THREADS
+ + + +## Task Scheduling + +**`dt.task-scheduler.enabled`** [¶](#dttask-schedulerenabled){ .headerlink } +: Defines whether the task scheduler should be enabled.

May be disabled on specific nodes in the cluster to limit the amount of background processing they're doing. Can help with dedicating nodes to only serve web traffic. + + + + + +
Typeboolean
Defaulttrue
ENVDT_TASK_SCHEDULER_ENABLED
+ +**`dt.task.csaf.document.import.cron`** * [¶](#dttaskcsafdocumentimportcron){ .headerlink } +: Cron expression of the CSAF mirroring task. + + + + + +
Typecron
Default0 5 * * *
ENVDT_TASK_CSAF_DOCUMENT_IMPORT_CRON
+ +**`dt.task.defect.dojo.upload.cron`** * [¶](#dttaskdefectdojouploadcron){ .headerlink } +: Cron expression of the DefectDojo upload task. + + + + + +
Typecron
Default0 2 * * *
ENVDT_TASK_DEFECT_DOJO_UPLOAD_CRON
+ +**`dt.task.epss.mirror.cron`** * [¶](#dttaskepssmirrorcron){ .headerlink } +: Cron expression of the EPSS mirroring task. + + + + + +
Typecron
Default0 1 * * *
ENVDT_TASK_EPSS_MIRROR_CRON
+ +**`dt.task.epss.mirror.lock.max.duration`** * [¶](#dttaskepssmirrorlockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the EPSS mirror task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_EPSS_MIRROR_LOCK_MAX_DURATION
+ +**`dt.task.epss.mirror.lock.min.duration`** * [¶](#dttaskepssmirrorlockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the EPSS mirror task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_EPSS_MIRROR_LOCK_MIN_DURATION
+ +**`dt.task.expired-session-cleanup.cron`** * [¶](#dttaskexpired-session-cleanupcron){ .headerlink } +: Cron expression of the expired session cleanup task. + + + + + +
Typecron
Default0 * * * *
ENVDT_TASK_EXPIRED_SESSION_CLEANUP_CRON
+ +**`dt.task.fortify.ssc.upload.cron`** * [¶](#dttaskfortifysscuploadcron){ .headerlink } +: Cron expression of the Fortify SSC upload task. + + + + + +
Typecron
Default0 2 * * *
ENVDT_TASK_FORTIFY_SSC_UPLOAD_CRON
+ +**`dt.task.git.hub.advisory.mirror.cron`** * [¶](#dttaskgithubadvisorymirrorcron){ .headerlink } +: Cron expression of the vulnerability GitHub Advisories mirroring task. + + + + + +
Typecron
Default0 2 * * *
ENVDT_TASK_GIT_HUB_ADVISORY_MIRROR_CRON
+ +**`dt.task.internal.component.identification.cron`** * [¶](#dttaskinternalcomponentidentificationcron){ .headerlink } +: Cron expression of the internal component identification task. + + + + + +
Typecron
Default25 */6 * * *
ENVDT_TASK_INTERNAL_COMPONENT_IDENTIFICATION_CRON
+ +**`dt.task.internal.component.identification.lock.max.duration`** * [¶](#dttaskinternalcomponentidentificationlockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the internal component identification task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_INTERNAL_COMPONENT_IDENTIFICATION_LOCK_MAX_DURATION
+ +**`dt.task.internal.component.identification.lock.min.duration`** * [¶](#dttaskinternalcomponentidentificationlockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the internal component identification task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT90S
ENVDT_TASK_INTERNAL_COMPONENT_IDENTIFICATION_LOCK_MIN_DURATION
+ +**`dt.task.kenna.security.upload.cron`** * [¶](#dttaskkennasecurityuploadcron){ .headerlink } +: Cron expression of the Kenna Security upload task. + + + + + +
Typecron
Default0 2 * * *
ENVDT_TASK_KENNA_SECURITY_UPLOAD_CRON
+ +**`dt.task.ldap.sync.cron`** * [¶](#dttaskldapsynccron){ .headerlink } +: Cron expression of the LDAP synchronization task. + + + + + +
Typecron
Default0 */6 * * *
ENVDT_TASK_LDAP_SYNC_CRON
+ +**`dt.task.ldap.sync.lock.max.duration`** * [¶](#dttaskldapsynclockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the LDAP synchronization task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_LDAP_SYNC_LOCK_MAX_DURATION
+ +**`dt.task.ldap.sync.lock.min.duration`** * [¶](#dttaskldapsynclockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the LDAP synchronization task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT90S
ENVDT_TASK_LDAP_SYNC_LOCK_MIN_DURATION
+ +**`dt.task.metrics.maintenance.cron`** * [¶](#dttaskmetricsmaintenancecron){ .headerlink } +: Cron expression of the metrics maintenance task.

The task creates new partitions for the day for the following tables And deletes records older than the configured metrics retention duration from the following tables:
  • DEPENDENCYMETRICS
  • PROJECTMETRICS
+ + + + + +
Typecron
Default1 * * * *
ENVDT_TASK_METRICS_MAINTENANCE_CRON
+ +**`dt.task.metrics.maintenance.lock.max.duration`** * [¶](#dttaskmetricsmaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the metrics maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_METRICS_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.metrics.maintenance.lock.min.duration`** * [¶](#dttaskmetricsmaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the metrics maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_METRICS_MAINTENANCE_LOCK_MIN_DURATION
+ +**`dt.task.nist.mirror.cron`** * [¶](#dttasknistmirrorcron){ .headerlink } +: Cron expression of the NIST / NVD mirroring task. + + + + + +
Typecron
Default0 4 * * *
ENVDT_TASK_NIST_MIRROR_CRON
+ +**`dt.task.osv.mirror.cron`** * [¶](#dttaskosvmirrorcron){ .headerlink } +: Cron expression of the OSV mirroring task. + + + + + +
Typecron
Default0 3 * * *
ENVDT_TASK_OSV_MIRROR_CRON
+ +**`dt.task.package-metadata-resolution.cron`** * [¶](#dttaskpackage-metadata-resolutioncron){ .headerlink } +: Cron expression of the package metadata resolution task.

Note that package metadata resolution is also triggered by other actions, such as BOM uploads. The scheduled execution is mostly relevant for deployments that may sit idle for a long time. + + + + + +
Typecron
Default0 1 * * *
ENVDT_TASK_PACKAGE_METADATA_RESOLUTION_CRON
+ +**`dt.task.package.metadata.maintenance.cron`** * [¶](#dttaskpackagemetadatamaintenancecron){ .headerlink } +: Cron expression of the package metadata maintenance task.

The task deletes orphaned records from the `PACKAGE_ARTIFACT_METADATA` and `PACKAGE_METADATA` tables. + + + + + +
Typecron
Default0 */12 * * *
ENVDT_TASK_PACKAGE_METADATA_MAINTENANCE_CRON
+ +**`dt.task.package.metadata.maintenance.lock.max.duration`** * [¶](#dttaskpackagemetadatamaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the package metadata maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_PACKAGE_METADATA_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.package.metadata.maintenance.lock.min.duration`** * [¶](#dttaskpackagemetadatamaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the package metadata maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_PACKAGE_METADATA_MAINTENANCE_LOCK_MIN_DURATION
+ +**`dt.task.portfolio-metrics-update.cron`** * [¶](#dttaskportfolio-metrics-updatecron){ .headerlink } +: Cron expression of the portfolio metrics update task. + + + + + +
Typecron
Default10 * * * *
ENVDT_TASK_PORTFOLIO_METRICS_UPDATE_CRON
+ +**`dt.task.project.maintenance.cron`** * [¶](#dttaskprojectmaintenancecron){ .headerlink } +: Cron expression of the project maintenance task.

The task deletes inactive projects based on retention policy. + + + + + +
Typecron
Default0 */4 * * *
ENVDT_TASK_PROJECT_MAINTENANCE_CRON
+ +**`dt.task.project.maintenance.lock.max.duration`** * [¶](#dttaskprojectmaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the project maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_PROJECT_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.project.maintenance.lock.min.duration`** * [¶](#dttaskprojectmaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the project maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_PROJECT_MAINTENANCE_LOCK_MIN_DURATION
+ +**`dt.task.scheduled-notification-dispatch.cron`** * [¶](#dttaskscheduled-notification-dispatchcron){ .headerlink } +: Cron expression for polling scheduled notification rules that are due for dispatch. + + + + + +
Typecron
Default* * * * *
ENVDT_TASK_SCHEDULED_NOTIFICATION_DISPATCH_CRON
+ +**`dt.task.tag.maintenance.cron`** * [¶](#dttasktagmaintenancecron){ .headerlink } +: Cron expression of the tag maintenance task.

The task deletes orphaned tags that are not used anymore. + + + + + +
Typecron
Default0 */12 * * *
ENVDT_TASK_TAG_MAINTENANCE_CRON
+ +**`dt.task.tag.maintenance.lock.max.duration`** * [¶](#dttasktagmaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the tag maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_TAG_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.tag.maintenance.lock.min.duration`** * [¶](#dttasktagmaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the tag maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_TAG_MAINTENANCE_LOCK_MIN_DURATION
+ +**`dt.task.telemetry-submission.cron`** * [¶](#dttasktelemetry-submissioncron){ .headerlink } +: Cron expression of the telemetry submission task.

The task enforces a 24-hour minimum interval between submissions, so the cron expression controls how often the task checks whether a submission is due. + + + + + +
Typecron
Default0 */1 * * *
ENVDT_TASK_TELEMETRY_SUBMISSION_CRON
+ +**`dt.task.vulnerability-policy-bundle-sync.cron`** * [¶](#dttaskvulnerability-policy-bundle-synccron){ .headerlink } +: Cron expression of the vulnerability policy bundle synchronization task.

Has no effect unless [`dt.vulnerability.policy.bundle.url`](#dtvulnerabilitypolicybundleurl) is also configured. + + + + + +
Typecron
Default*/15 * * * *
ENVDT_TASK_VULNERABILITY_POLICY_BUNDLE_SYNC_CRON
+ +**`dt.task.vulnerability.analysis.cron`** * [¶](#dttaskvulnerabilityanalysiscron){ .headerlink } +: Cron expression of the portfolio vulnerability analysis task. + + + + + +
Typecron
Default0 6 * * *
ENVDT_TASK_VULNERABILITY_ANALYSIS_CRON
+ +**`dt.task.vulnerability.analysis.lock.max.duration`** * [¶](#dttaskvulnerabilityanalysislockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the portfolio vulnerability analysis task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_VULNERABILITY_ANALYSIS_LOCK_MAX_DURATION
+ +**`dt.task.vulnerability.analysis.lock.min.duration`** * [¶](#dttaskvulnerabilityanalysislockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the portfolio vulnerability analysis task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT90S
ENVDT_TASK_VULNERABILITY_ANALYSIS_LOCK_MIN_DURATION
+ +**`dt.task.vulnerability.database.maintenance.cron`** * [¶](#dttaskvulnerabilitydatabasemaintenancecron){ .headerlink } +: Cron expression of the vulnerability database maintenance task.

The task deletes orphaned records from the `VULNERABLESOFTWARE` table. + + + + + +
Typecron
Default0 0 * * *
ENVDT_TASK_VULNERABILITY_DATABASE_MAINTENANCE_CRON
+ +**`dt.task.vulnerability.database.maintenance.lock.max.duration`** * [¶](#dttaskvulnerabilitydatabasemaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the vulnerability database maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_VULNERABILITY_DATABASE_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.vulnerability.database.maintenance.lock.min.duration`** * [¶](#dttaskvulnerabilitydatabasemaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the vulnerability database maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_VULNERABILITY_DATABASE_MAINTENANCE_LOCK_MIN_DURATION
+ +**`dt.task.vulnerability.metrics.update.cron`** * [¶](#dttaskvulnerabilitymetricsupdatecron){ .headerlink } +: Cron expression of the vulnerability metrics update task. + + + + + +
Typecron
Default40 * * * *
ENVDT_TASK_VULNERABILITY_METRICS_UPDATE_CRON
+ +**`dt.task.vulnerability.metrics.update.lock.max.duration`** * [¶](#dttaskvulnerabilitymetricsupdatelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the vulnerability metrics update task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT15M
ENVDT_TASK_VULNERABILITY_METRICS_UPDATE_LOCK_MAX_DURATION
+ +**`dt.task.vulnerability.metrics.update.lock.min.duration`** * [¶](#dttaskvulnerabilitymetricsupdatelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the vulnerability metrics update task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT90S
ENVDT_TASK_VULNERABILITY_METRICS_UPDATE_LOCK_MIN_DURATION
+ +**`dt.task.workflow.maintenance.cron`** * [¶](#dttaskworkflowmaintenancecron){ .headerlink } +: Cron expression of the workflow maintenance task.

The task:
  • Transitions workflow steps from PENDING to TIMED_OUT state
  • Transitions workflow steps from TIMED_OUT to FAILED state
  • Transitions children of FAILED steps to CANCELLED state
  • Deletes finished workflows according to the configured retention duration
+ + + + + +
Typecron
Default*/15 * * * *
ENVDT_TASK_WORKFLOW_MAINTENANCE_CRON
+ +**`dt.task.workflow.maintenance.lock.max.duration`** * [¶](#dttaskworkflowmaintenancelockmaxduration){ .headerlink } +: Maximum duration in ISO 8601 format for which the workflow maintenance task will hold a lock.

The duration should be long enough to cover the task's execution duration. + + + + + +
Typeduration
DefaultPT5M
ENVDT_TASK_WORKFLOW_MAINTENANCE_LOCK_MAX_DURATION
+ +**`dt.task.workflow.maintenance.lock.min.duration`** * [¶](#dttaskworkflowmaintenancelockminduration){ .headerlink } +: Minimum duration in ISO 8601 format for which the workflow maintenance task will hold a lock.

The duration should be long enough to cover eventual clock skew across API server instances. + + + + + +
Typeduration
DefaultPT1M
ENVDT_TASK_WORKFLOW_MAINTENANCE_LOCK_MIN_DURATION
+ + + +## Vulnerability Analysis + +**`dt.vuln-analyzer.internal.datasource.name`** [¶](#dtvuln-analyzerinternaldatasourcename){ .headerlink } +: Defines the name of the data source to be used by the internal vulnerability analyzer.

The internal analyzer performs no database writes, so this data source *could* point to a read replica if needed. + + + + + +
Typestring
Defaultdefault
ENVDT_VULN_ANALYZER_INTERNAL_DATASOURCE_NAME
+ +**`dt.vuln-analyzer.internal.enabled`** [¶](#dtvuln-analyzerinternalenabled){ .headerlink } +: Defines whether the internal vulnerability analyzer is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_VULN_ANALYZER_INTERNAL_ENABLED
+ +**`dt.vuln-analyzer.oss-index.allow-local-connections`** [¶](#dtvuln-analyzeross-indexallow-local-connections){ .headerlink } +: Defines whether the OSS Index vulnerability analyzer is allowed to connect to local hosts. + + + + + +
Typeboolean
Defaultfalse
ENVDT_VULN_ANALYZER_OSS_INDEX_ALLOW_LOCAL_CONNECTIONS
+ +**`dt.vuln-analyzer.oss-index.enabled`** [¶](#dtvuln-analyzeross-indexenabled){ .headerlink } +: Defines whether the OSS Index vulnerability analyzer is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_VULN_ANALYZER_OSS_INDEX_ENABLED
+ +**`dt.vuln-analyzer.snyk.api-version`** [¶](#dtvuln-analyzersnykapi-version){ .headerlink } +: Defines the Snyk REST API version to use.

Should only be changed if the default version is discontinued by Snyk and an upgrade of Dependency-Track is not immediately possible. + + + + + +
Typestring
Default2025-11-05
ENVDT_VULN_ANALYZER_SNYK_API_VERSION
+ +**`dt.vuln-analyzer.snyk.enabled`** [¶](#dtvuln-analyzersnykenabled){ .headerlink } +: Defines whether the Snyk vulnerability analyzer is enabled. + + + + + +
Typeboolean
Defaulttrue
ENVDT_VULN_ANALYZER_SNYK_ENABLED
+ -!!! warning "Placeholder" - This page has not been written yet. diff --git a/docs/reference/datasources/.pages b/docs/reference/datasources/.pages new file mode 100644 index 00000000..e96f08f6 --- /dev/null +++ b/docs/reference/datasources/.pages @@ -0,0 +1,8 @@ +nav: + - Overview: index.md + - NVD: nvd.md + - GitHub Advisories: github-advisories.md + - OSV: osv.md + - Private Vulnerability Repository: private-vulnerability-repository.md + - Repositories: repositories.md + - Internal Components: internal-components.md diff --git a/docs/reference/datasources/github-advisories.md b/docs/reference/datasources/github-advisories.md new file mode 100644 index 00000000..f56dc94a --- /dev/null +++ b/docs/reference/datasources/github-advisories.md @@ -0,0 +1,40 @@ +# GitHub Advisories + +The [GitHub Advisory Database](https://github.com/advisories) (GHSA) contains +security advisories for open source packages hosted on GitHub and other ecosystems. +Advisories may or may not overlap with NVD CVE records—GitHub often publishes +advisories for vulnerabilities that are not yet in the NVD, or with more ecosystem- +specific detail. + +## What It Provides + +GitHub Advisories are keyed by PURL and map directly to package ecosystems such as +npm, Maven, PyPI, Go, NuGet, and others. This makes them highly effective for +open source component matching without requiring a CPE. + +Dependency-Track automatically synchronises vulnerability aliases between GHSA and +CVE identifiers where GitHub has made the link explicit. This means a component can +be matched by either its GHSA or CVE identifier, and the finding will not be +duplicated. + +## Mirroring + +Dependency-Track mirrors GitHub Advisories via GitHub's public GraphQL API. The mirror +refreshes daily and on instance startup. + +The mirroring schedule is controlled by +[`dt.task.git.hub.advisory.mirror.cron`](../configuration/properties.md#dttaskgithubadvisorymirrorcron). + +## Configuration + +GitHub Advisory mirroring is configured in the administration UI under +**Administration → Datasources → GitHub Advisories**. + +| Setting | Description | +|:--------|:------------| +| Enabled | Whether GitHub Advisory mirroring is active. Enabled by default. | +| GitHub Personal Access Token | Required. A GitHub PAT with no scopes assigned is sufficient. Without a token, the GraphQL API rejects requests. | + +To create a token, visit [github.com/settings/tokens](https://github.com/settings/tokens) +and generate a classic or fine-grained token. No scopes are required—the public +advisory data is accessible to any authenticated user. diff --git a/docs/reference/datasources/index.md b/docs/reference/datasources/index.md new file mode 100644 index 00000000..9e4daa89 --- /dev/null +++ b/docs/reference/datasources/index.md @@ -0,0 +1,34 @@ +# Vulnerability Datasources + +Vulnerability datasources are the upstream feeds from which Dependency-Track populates +its internal vulnerability database. The [internal analyzer](../analyzers.md#internal) +queries this local database when evaluating components, so no external call is made at +analysis time—only during mirroring. + +Mirroring runs on a configurable schedule (daily by default) and on instance startup. +Progress and errors are reported via the `DATASOURCE_MIRRORING` +[notification group](../../concepts/architecture/design/notifications.md). + +## Mirrored Sources + +These sources are downloaded and stored locally. The internal analyzer queries them +without contacting any external service during vulnerability analysis. + +| Source | Identifier prefix | Primary use | +|:-------|:-----------------|:------------| +| [NVD](nvd.md) | `CVE-` | CPE-based matching for all component types | +| [GitHub Advisories](github-advisories.md) | `GHSA-` | PURL-based matching for open source packages | +| [OSV](osv.md) | varies by ecosystem | PURL-based matching for open source packages | + +## Other Sources + +| Source | Description | +|:-------|:------------| +| [Private Vulnerability Repository](private-vulnerability-repository.md) | Internally managed vulnerabilities for proprietary components or pre-disclosure research | +| [Repositories](repositories.md) | Package registry integrations used for outdated component detection | +| [Internal Components](internal-components.md) | Configuring components that should never be sent to external services | + +## Analyzers That Query External Services + +OSS Index, Snyk, Trivy, and VulnDB are *analyzers* that call external APIs at analysis +time. They are documented separately in the [Analyzers](../analyzers.md) reference. diff --git a/docs/reference/datasources/internal-components.md b/docs/reference/datasources/internal-components.md new file mode 100644 index 00000000..5eb3ff71 --- /dev/null +++ b/docs/reference/datasources/internal-components.md @@ -0,0 +1,48 @@ +# Internal Components + +Dependency-Track allows organisations to mark certain component namespaces and/or names +as *internal*. Components identified as internal are excluded from all external services: +they are never sent to external vulnerability analyzers (OSS Index, Snyk, Trivy, VulnDB) +and never queried against public package repositories. + +This is useful when your SBOMs include first-party libraries with coordinates that could +coincide with public packages, or when you simply do not want metadata about internal +packages to leave your network. + +## How Matching Works + +Internal component identification is configured in +**Administration → Internal Components** by specifying one or more namespace and/or name +patterns. + +Two matching modes are available: + +| Mode | Behaviour | +|:-----|:----------| +| OR (default) | A component is internal if its namespace *or* name matches any configured pattern. | +| AND | A component is internal if its namespace *and* name both match. | + +Patterns are matched against the component's PURL namespace and name fields. + +!!! note + By default, no components are identified as internal—all components are treated + as third-party and may be sent to configured external analyzers. + +## Effects of Being Marked Internal + +| Service | Behaviour for internal components | +|:--------|:----------------------------------| +| OSS Index | Not queried | +| Snyk | Not queried | +| Trivy | Not queried | +| VulnDB | Not queried | +| Public package repositories | Not queried for version currency checks | +| Internal analyzer | Still evaluated against the local vulnerability database | +| Private repositories | Still queried if configured | + +## Use with the Private Vulnerability Repository + +Internal components can still be matched against vulnerabilities defined in the +[private vulnerability repository](private-vulnerability-repository.md). This allows +organisations to track and triage vulnerabilities in their own codebases without +exposing component identifiers externally. diff --git a/docs/reference/datasources/nvd.md b/docs/reference/datasources/nvd.md new file mode 100644 index 00000000..839cfd40 --- /dev/null +++ b/docs/reference/datasources/nvd.md @@ -0,0 +1,51 @@ +# National Vulnerability Database (NVD) + +The [National Vulnerability Database](https://nvd.nist.gov/) (NVD) is the largest +publicly available source of vulnerability intelligence, maintained by NIST and building +on CVE identifiers from MITRE. It contains over 200,000 CVE records spanning from the +early nineties to the present day. + +!!! note + This product uses the NVD API but is not endorsed or certified by the NVD. + +## What It Provides + +The NVD mirror populates Dependency-Track's internal database with CVE records including +descriptions, CVSS scores, CWE classifications, and affected product configurations +expressed as CPE. The [internal analyzer](../analyzers.md#internal) uses this data +to match components with valid CPEs against known vulnerabilities. + +## Mirroring + +Dependency-Track mirrors the NVD via the NVD REST API. The mirror refreshes daily and +on instance startup. The initial mirror may take significantly longer than subsequent +incremental updates. + +The mirroring schedule is controlled by +[`dt.task.nist.mirror.cron`](../configuration/properties.md#dttasknistmirrorcron). + +## Configuration + +NVD mirroring is configured through the administration UI under +**Administration → Datasources → NVD**. + +| Setting | Description | +|:--------|:------------| +| Enabled | Whether NVD mirroring is active. Enabled by default. | +| NVD API Key | Optional but strongly recommended. Unauthenticated requests are rate-limited aggressively, which can cause the initial mirror to take hours or fail. | + +Obtain a free NVD API key at [nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key). + +!!! tip + Configuring an API key is especially important for new installations, where + the entire NVD dataset must be downloaded on the first mirror run. + +## CPE Matching + +NVD records describe affected products using CPE (Common Platform Enumeration). +Dependency-Track follows the NIST CPE name matching specification with adjustments +to reduce false positives: matches are rejected when the vendor comparison yields +*SUBSET* and the product comparison yields *SUPERSET*, or vice versa. + +Components without a valid CPE are not evaluated by the internal analyzer against +NVD data. Ensure your SBOMs include CPEs for non-open-source components. diff --git a/docs/reference/datasources/osv.md b/docs/reference/datasources/osv.md new file mode 100644 index 00000000..99ed8d26 --- /dev/null +++ b/docs/reference/datasources/osv.md @@ -0,0 +1,53 @@ +# OSV + +[OSV](https://osv.dev/) (Open Source Vulnerabilities) is a vulnerability database +focused on open source packages, maintained by Google. It aggregates advisories from +multiple upstream sources including GitHub Advisories, PyPA, RustSec, and many others, +providing a unified PURL-keyed dataset. + +## What It Provides + +OSV advisories are natively keyed by package ecosystem and version, making them +well-suited for PURL-based matching across a wide range of languages and package managers. + +OSV supports alias linking, so vulnerabilities tracked under different IDs (CVE, GHSA, +OSV-specific IDs) across databases are correlated automatically. + +## Supported Ecosystems + +OSV data can be selectively enabled per ecosystem. Available ecosystems include: +Go, npm, PyPI, RubyGems, crates.io (Rust), Maven, NuGet, Packagist (PHP), Hex (Erlang), +pub (Dart), Alpine, Debian, Ubuntu, Android, and others. + +!!! tip + For Debian, enable **Debian** rather than individual Debian version ecosystems. + The Debian ecosystem package is a superset of all individual versions. + +## Mirroring + +Dependency-Track mirrors OSV data from Google Cloud Storage (`gs://osv-vulnerabilities`). +No authentication token is required. The mirror refreshes daily and on instance startup. + +The mirroring schedule is controlled by +[`dt.task.osv.mirror.cron`](../configuration/properties.md#dttaskosvmirrorcron). + +## Configuration + +OSV mirroring is configured in the administration UI under +**Administration → Datasources → OSV**. + +| Setting | Description | +|:--------|:------------| +| Enabled | Whether OSV mirroring is active. | +| Ecosystems | The specific ecosystems to mirror. Only selected ecosystems are downloaded. | + +!!! warning + Disabling OSV removes ecosystem selections from the UI but preserves previously + mirrored vulnerability records in the database. Previously matched findings are + not automatically removed. + +## Alias Synchronisation + +OSV supports alias synchronisation with other vulnerability databases. This is +configured on the [internal analyzer](../analyzers.md#internal) rather than on +the OSV datasource directly. diff --git a/docs/reference/datasources/private-vulnerability-repository.md b/docs/reference/datasources/private-vulnerability-repository.md new file mode 100644 index 00000000..44e7a245 --- /dev/null +++ b/docs/reference/datasources/private-vulnerability-repository.md @@ -0,0 +1,68 @@ +# Private Vulnerability Repository + +The private vulnerability repository stores internally managed vulnerabilities. It behaves +identically to other vulnerability sources -- findings are raised, audit trails are maintained, +and notifications fire -- but the data is entirely user-managed. + +For use cases and step-by-step creation instructions, see +[Managing private vulnerabilities](../../guides/user/managing-private-vulnerabilities.md). + +## Vulnerability IDs + +Every vulnerability in the private repository requires a unique ID within the +`INTERNAL` source. By default, Dependency-Track generates IDs using the prefix `INT` +followed by three blocks of four alphanumeric characters (for example, `INT-td11-7hzm-qzot`). + +Any prefix meaningful to your organisation may be used (for example, `ACME-`, `INT-`, +`SEC-`). The only constraint is uniqueness within the `INTERNAL` source. + +## Severity and Risk Ratings + +Severity can be set explicitly or derived from a risk score: + +| Rating | Description | +|:-------|:------------| +| Explicit severity | Choose directly: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, or `INFO`. | +| CVSSv2 / CVSSv3 | Enter a CVSS vector; Dependency-Track calculates the base score and derives severity. | +| OWASP Risk Rating | Enter likelihood and impact factors; Dependency-Track calculates severity. | + +When multiple ratings are provided, CVSSv3 takes precedence over CVSSv2, and the rating +with the higher severity is preferred over OWASP Risk Rating. + +## Description Fields + +| Field | Purpose | +|:------|:--------| +| Title | Short summary shown in finding lists. | +| Description | High-level overview of the vulnerability and its risk. Supports Markdown. | +| Details | In-depth description, such as root cause analysis. Supports Markdown. | +| Recommendation | Remediation or mitigation instructions. Supports Markdown. | +| References | List of external links (changelogs, advisories, blog posts, etc.). | + +## Affected Components + +For a vulnerability to be matched against components, **Affected Components** must +be configured. Each entry specifies an identifier (PURL or CPE) and either an exact +version or a version range. + +**Version ranges** use lower and/or upper bounds: + +| Operator | Meaning | +|:---------|:--------| +| `>` | Greater than (exclusive lower bound) | +| `>=` | Greater than or equal (inclusive lower bound) | +| `<` | Less than (exclusive upper bound) | +| `<=` | Less than or equal (inclusive upper bound) | + +A range with only a lower bound matches all versions above it; a range with only an +upper bound matches all versions below it. + +!!! tip + Dependency-Track does not convert between PURL and CPE. Use the same identifier + type that your SBOM generator produces. Most modern generators emit PURLs. + +## Finding Behaviour + +Internal vulnerabilities are matched by the [internal analyzer](../analyzers.md#internal) +during regular vulnerability analysis. Findings appear identically to those from public +sources and support the same triage workflow (analysis states, suppression, VEX export). diff --git a/docs/reference/datasources/repositories.md b/docs/reference/datasources/repositories.md new file mode 100644 index 00000000..2e01b6f6 --- /dev/null +++ b/docs/reference/datasources/repositories.md @@ -0,0 +1,74 @@ +# Package Repositories + +Dependency-Track integrates with public and private package repositories to fetch +component metadata. This integration is used primarily for +outdated component detection: Dependency-Track +queries the registry for a component's latest available version and compares it to the +version in the SBOM. + +## Supported Ecosystems + +The following ecosystems are supported out of the box, each with a pre-configured +default repository: + +| Ecosystem | Default repository | +|:----------|:------------------| +| Cargo (Rust) | [crates.io](https://crates.io) | +| Composer (PHP) | [Packagist](https://packagist.org) | +| Gem (Ruby) | [RubyGems](https://rubygems.org) | +| GitHub (Actions) | [github.com](https://github.com) | +| Go Modules | [proxy.golang.org](https://proxy.golang.org) | +| Hex (Erlang/Elixir) | [Hex.pm](https://hex.pm) | +| Maven (Java) | [Maven Central](https://central.sonatype.com) | +| npm (Node.js) | [npmjs.com](https://www.npmjs.com) | +| NuGet (.NET) | [nuget.org](https://www.nuget.org) | +| PyPI (Python) | [pypi.org](https://pypi.org) | +| CPAN (Perl) | [CPAN](https://www.cpan.org) | + +Additional repositories can be configured for any ecosystem in +**Administration → Repositories**. + +## Configuration + +Repository settings are managed in **Administration → Repositories**. Each repository +entry has the following properties: + +| Property | Description | +|:---------|:------------| +| Enabled | Whether the repository is queried during analysis. Disabled repositories are skipped. | +| Internal | Whether this is an internal (private) registry. Internal repositories are used *only* for components marked as internal. Non-internal repositories are used only for non-internal components. | +| URL | The base URL of the repository. | +| Authentication | Optional credentials (see below). | + +## Authentication + +Three authentication methods are supported: + +| Method | Configuration | +|:-------|:-------------| +| None | No credentials required (default for public repositories). | +| Basic | Enter a username and password. | +| Bearer token | Leave the username blank; enter the token in the password field. | + +For GitHub, use your GitHub username and a [personal access token](https://github.com/settings/tokens) +with at least public read access. + +For private repositories such as Azure Artifacts or JFrog Artifactory, use the +appropriate service account credentials. + +## How Dependency-Track Uses Repositories + +Dependency-Track uses the Package URL (PURL) of each component to determine which +ecosystem it belongs to, then queries the matching repositories for the latest published +version. If the component's version is older than the latest, it is flagged as outdated. + +!!! note + Repository queries are used only for version currency checks. They are not part + of the vulnerability analysis pipeline. Vulnerability data comes from the + [internal analyzer](../analyzers.md) and the external analyzer integrations. + +## Internal Components and Repositories + +Components marked as [internal](internal-components.md) are only matched against +repositories that are also marked as internal. This prevents internal package +coordinates from being leaked to external registry APIs. diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md new file mode 100644 index 00000000..d65edab6 --- /dev/null +++ b/docs/reference/file-formats.md @@ -0,0 +1,63 @@ +# File Formats + +## CycloneDX + +Dependency-Track's primary file format is [CycloneDX](https://cyclonedx.org/), a +lightweight, security-focused Bill of Materials specification. CycloneDX is the only +format supported for **uploading** SBOMs to Dependency-Track. + +Supported CycloneDX serialisations: + +| Format | Content-Type | +|:-------|:-------------| +| JSON | `application/vnd.cyclonedx+json` | +| XML | `application/vnd.cyclonedx+xml` | + +All versions of the CycloneDX BOM specification are supported for upload. + +Dependency-Track also **generates** CycloneDX documents in several forms: + +| Document type | Description | +|:-------------|:------------| +| BOM | A full software bill of materials reflecting the current component inventory of a project. | +| VEX | A Vulnerability Exploitability Exchange document containing analysis decisions (states, justifications) for a project's findings. | +| VDR | A Vulnerability Disclosure Report containing full vulnerability data for a project's components. | + +## Finding Packaging Format (FPF) + +The Finding Packaging Format (FPF) is a Dependency-Track-native JSON format for +exporting findings. It is used primarily to integrate with platforms that cannot +consume the REST API directly. + +### Structure + +An FPF document contains four top-level fields: + +| Field | Description | +|:------|:------------| +| `version` | The FPF format version. | +| `meta` | Information about the Dependency-Track instance that generated the file. | +| `project` | Project metadata (name, version, UUID). | +| `findings` | Array of finding records, each linking a component to a vulnerability and including the current analysis state. | + +Each finding record includes the affected component's coordinates, the vulnerability +details (ID, source, severity, CVSS vectors, CWEs), the current analysis state and +justification, and a matrix identifier that uniquely identifies the (project, component, +vulnerability) triple. + +### API Endpoint + +```text +GET /api/v1/finding/project/{uuid}/export +``` + +Requires the `VIEW_VULNERABILITY` permission. + +### Version History + +| FPF Version | Dependency-Track Version | Changes | +|:------------|:------------------------|:--------| +| v1.0 | Initial | Baseline format. | +| v1.1 | v4.5 | Added `cwes` array to support multiple CWEs per vulnerability. | +| v1.2 | v4.8.0 | Removed `allBySource` and internal `id` fields from aliases. | +| v1.3 | v4.14.0 | Added optional CVSS vectors (`cvssV2Vector`, `cvssV3Vector`, `cvssV4Vector`) and OWASP Risk Rating vector fields. | diff --git a/docs/reference/images/analyzers/analyzer-config_internal.png b/docs/reference/images/analyzers/analyzer-config_internal.png new file mode 100644 index 00000000..ad201590 Binary files /dev/null and b/docs/reference/images/analyzers/analyzer-config_internal.png differ diff --git a/docs/reference/images/analyzers/analyzer-config_oss-index.png b/docs/reference/images/analyzers/analyzer-config_oss-index.png new file mode 100644 index 00000000..cbca6306 Binary files /dev/null and b/docs/reference/images/analyzers/analyzer-config_oss-index.png differ diff --git a/docs/reference/images/analyzers/analyzer-config_snyk.png b/docs/reference/images/analyzers/analyzer-config_snyk.png new file mode 100644 index 00000000..f6083bef Binary files /dev/null and b/docs/reference/images/analyzers/analyzer-config_snyk.png differ diff --git a/docs/reference/images/analyzers/analyzer-config_trivy.png b/docs/reference/images/analyzers/analyzer-config_trivy.png new file mode 100644 index 00000000..17e2ac2e Binary files /dev/null and b/docs/reference/images/analyzers/analyzer-config_trivy.png differ diff --git a/docs/reference/images/analyzers/analyzer-config_vulndb.png b/docs/reference/images/analyzers/analyzer-config_vulndb.png new file mode 100644 index 00000000..4c21dd5a Binary files /dev/null and b/docs/reference/images/analyzers/analyzer-config_vulndb.png differ diff --git a/docs/reference/index.md b/docs/reference/index.md index a44992e8..72869240 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,3 +1,68 @@ # Reference -Technical descriptions of the software's interfaces, configuration options, and internals. +Reference documentation describes Dependency-Track's technical interfaces, +configuration properties, and data schemas. It is designed to be consulted +rather than read from start to finish. + +For step-by-step instructions, see [Guides](../guides/index.md). +For background and explanations, see [Concepts](../concepts/index.md). + +## API + +- [REST API v1](api/v1.md) +- [REST API v2](api/v2.md) + +## Configuration + +- [Application](configuration/application.md) -- + general application settings and MicroProfile Config sources +- [Data Sources](configuration/datasources.md) -- + database connection and pool configuration +- [File Storage](configuration/file-storage.md) -- + local and S3-compatible storage providers +- [Database](configuration/database.md) -- + PostgreSQL requirements, extensions, and tuning parameters +- [All Properties](configuration/properties.md) -- + complete generated registry of all application properties + +## Notifications + +- [Publishers](notifications/publishers.md) -- + email, Jira, Kafka, Webhook, and other publisher options +- [Filter Expressions](notifications/filter-expressions.md) -- + CEL-based notification filtering + +## Datasources + +- [NVD](datasources/nvd.md) -- + National Vulnerability Database mirroring and CPE matching +- [GitHub Advisories](datasources/github-advisories.md) -- + GHSA mirroring via GitHub's GraphQL API +- [OSV](datasources/osv.md) -- + Open Source Vulnerabilities mirroring, selectable by ecosystem +- [Private Vulnerability Repository](datasources/private-vulnerability-repository.md) -- + internally managed vulnerabilities for proprietary components +- [Repositories](datasources/repositories.md) -- + package registries for outdated component detection +- [Internal Components](datasources/internal-components.md) -- + excluding first-party components from external analysis + +## Expressions and Schemas + +- [CEL Expressions](cel-expressions.md) -- + syntax reference for CEL used in policies and notifications +- [Vulnerability Analyzers](analyzers.md) +- [Vulnerability Policies](vulnerability-policies.md) +- [Notification Schema](schemas/notification.md) +- [Policy Schema](schemas/policy.md) + +## Access Control and Integrations + +- [Permissions](permissions.md) -- + users, teams, API keys, and the full permissions table +- [Badges](badges.md) -- + SVG badges for embedding vulnerability and policy metrics +- [File Formats](file-formats.md) -- + CycloneDX BOM/VEX/VDR and Finding Packaging Format (FPF) +- [Community Integrations](community-integrations.md) -- + third-party tools and libraries built on the Dependency-Track API diff --git a/docs/reference/notifications/.pages b/docs/reference/notifications/.pages new file mode 100644 index 00000000..a8b62f47 --- /dev/null +++ b/docs/reference/notifications/.pages @@ -0,0 +1,3 @@ +nav: + - Publishers: publishers.md + - Filter Expressions: filter-expressions.md diff --git a/docs/reference/notifications/filter-expressions.md b/docs/reference/notifications/filter-expressions.md new file mode 100644 index 00000000..a0c86200 --- /dev/null +++ b/docs/reference/notifications/filter-expressions.md @@ -0,0 +1,183 @@ +# Filter Expressions + +## Introduction + +Alerts can include a filter expression to control which notifications are dispatched +based on their content. Filter expressions are written in [CEL] (Common Expression Language), +the same language used for [policy compliance expressions](../../reference/cel-expressions.md). + +Without a filter expression, an alert matches all notifications that satisfy its scope, group, +level, and project or tag restrictions. A filter expression adds a further condition: the +notification is only dispatched when the expression evaluates to `true`. + +![Filter expression field in the alert editor](./images/filter-expression-editor.png) + +## Syntax + +Filter expressions use the same [CEL syntax](../../reference/cel-expressions.md#syntax) as +policy compliance expressions. CEL is not [Turing-complete] and does not support constructs +like `if` statements or loops. It compensates for this with [macros] like `all`, `exists`, +`exists_one`, `map`, and `filter`. + +Refer to the official [language definition] for a thorough description of the syntax. + +## Evaluation Context + +The context in which filter expressions are evaluated contains the following variables: + +| Variable | Type | Description | +|:------------|:-------------------------------------------------------------|:---------------------------------------------------------------------------------------| +| `level` | [`Level`](../../reference/schemas/notification.md#level) | The notification level, as an integer enum value. Use named constants (see below). | +| `scope` | [`Scope`](../../reference/schemas/notification.md#scope) | The notification scope, as an integer enum value. Use named constants (see below). | +| `group` | [`Group`](../../reference/schemas/notification.md#group) | The notification group, as an integer enum value. Use named constants (see below). | +| `title` | `string` | The notification title. | +| `content` | `string` | The notification content. | +| `timestamp` | [`google.protobuf.Timestamp`][protobuf-ts-docs] | The time at which the notification was created. | +| `subject` | dynamic | The notification subject, typed according to the notification group (see below). | + +### Enum Constants + +The `level`, `scope`, and `group` variables hold integer values. To compare them in a readable way, +use the named constants from the [notification schema](../../reference/schemas/notification.md#enums): + +```js +level == Level.LEVEL_INFORMATIONAL +``` + +```js +group == Group.GROUP_NEW_VULNERABILITY +``` + +```js +scope == Scope.SCOPE_PORTFOLIO +``` + +### Subject Types + +The `subject` variable holds the notification's subject, which varies depending on the notification +group. Refer to the [notification schema reference](../../reference/schemas/notification.md#subjects) +for full details of each subject type and its fields. + +| Group | Subject Type | +|:--------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------| +| `BOM_CONSUMED`, `BOM_PROCESSED` | [BomConsumedOrProcessedSubject](../../reference/schemas/notification.md#bomconsumedorprocessedsubject) | +| `BOM_PROCESSING_FAILED` | [BomProcessingFailedSubject](../../reference/schemas/notification.md#bomprocessingfailedsubject) | +| `BOM_VALIDATION_FAILED` | [BomValidationFailedSubject](../../reference/schemas/notification.md#bomvalidationfailedsubject) | +| `NEW_VULNERABILITY` | [NewVulnerabilitySubject](../../reference/schemas/notification.md#newvulnerabilitysubject) | +| `NEW_VULNERABLE_DEPENDENCY` | [NewVulnerableDependencySubject](../../reference/schemas/notification.md#newvulnerabledependencysubject) | +| `POLICY_VIOLATION` | [PolicyViolationSubject](../../reference/schemas/notification.md#policyviolationsubject) | +| `PROJECT_AUDIT_CHANGE` | [VulnerabilityAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../../reference/schemas/notification.md#policyviolationanalysisdecisionchangesubject) | +| `PROJECT_VULN_ANALYSIS_COMPLETE` | [ProjectVulnAnalysisCompleteSubject](../../reference/schemas/notification.md#projectvulnanalysiscompletesubject) | +| `VEX_CONSUMED`, `VEX_PROCESSED` | [VexConsumedOrProcessedSubject](../../reference/schemas/notification.md#vexconsumedorprocessedsubject) | +| `USER_CREATED`, `USER_DELETED` | [UserSubject](../../reference/schemas/notification.md#usersubject) | + +## Validation + +Filter expressions are validated when an alert is saved. If the expression contains syntax errors +or references types that do not exist, the save operation will fail and the errors will be reported +with their exact location (line and column). + +![Validation error for an invalid filter expression](./images/filter-expression-editor-error.png) + +The maximum length of a filter expression is 2048 characters. + +## Failure Behaviour + +If a filter expression fails to evaluate at dispatch time (for example due to accessing a field +that does not exist on the subject), the alert matches the notification regardless. +This "fail-open" strategy ensures that a broken expression causes over-notification rather than +silently suppressing notifications. Evaluation failures are logged as warnings. + +!!! warning + An alert with an expression that consistently fails will behave as though + it has no filter expression at all. Check the application logs for evaluation warnings + if an alert appears to match more broadly than expected. + +## Filtering Order + +When a notification is dispatched, Dependency-Track evaluates the following filters in order: + +1. **Scope, group, and level** matching (configured on the alert). +2. **Project and tag restrictions** (if the alert is limited to specific projects or tags). +3. **Filter expression** (if the alert has one). + +The filter expression is only evaluated when the notification has already passed the preceding +checks. This means that project and tag restrictions are always enforced, regardless of what the +expression contains. + +## Examples + +### Only critical and high severity vulnerabilities + +The following expression matches `NEW_VULNERABILITY` notifications where the vulnerability +severity is `CRITICAL` or `HIGH`: + +```js linenums="1" +subject.vulnerability.severity in ["CRITICAL", "HIGH"] +``` + +### Vulnerabilities with a CVSS v3 score above a threshold + +```js linenums="1" +subject.vulnerability.cvss_v3 >= 7.0 +``` + +### Notifications for projects matching a name prefix + +The following expression matches notifications whose subject contains a project with a name +starting with `acme-`: + +```js linenums="1" +subject.project.name.startsWith("acme-") +``` + +!!! tip + For simple project-based filtering, consider using project and tag restrictions on the + alert instead. Filter expressions are more useful for content-based conditions + that cannot be expressed through project or tag restrictions alone. + +### Vulnerabilities with a specific CWE + +The following expression matches `NEW_VULNERABILITY` notifications where the vulnerability +has CWE-79 (Cross-site Scripting) among its CWEs: + +```js linenums="1" +subject.vulnerability.cwes.exists(cwe, cwe.cwe_id == 79) +``` + +### Combining multiple conditions + +The following expression matches `NEW_VULNERABILITY` notifications for `CRITICAL` vulnerabilities +with a network attack vector in CVSSv3: + +```js linenums="1" +subject.vulnerability.severity == "CRITICAL" + && subject.vulnerability.cvss_v3_vector.matches(".*/AV:N/.*") +``` + +### Scheduled alerts: only when critical vulnerabilities were found + +For scheduled alerts that produce vulnerability summaries, the subject contains +an overview with vulnerability counts grouped by severity. The following expression matches +only when at least one `CRITICAL` vulnerability was found in the reporting period: + +```js linenums="1" +"CRITICAL" in subject.overview.new_vulnerabilities_count_by_severity +``` + +### Optional field checking + +CEL does not have a concept of `null`. Accessing a field that is not set returns its default +value (for example, `""` for strings, `0` for numbers), which can lead to misleading matches. +Use the `has()` macro to check for field presence before accessing it: + +```js linenums="1" +has(subject.vulnerability.cvss_v3_vector) + && subject.vulnerability.cvss_v3_vector.matches(".*/AV:N/.*") +``` + +[CEL]: https://cel.dev/ +[Turing-complete]: https://en.wikipedia.org/wiki/Turing_completeness +[language definition]: https://github.com/google/cel-spec/blob/v0.13.0/doc/langdef.md#language-definition +[macros]: https://github.com/google/cel-spec/blob/v0.13.0/doc/langdef.md#macros +[protobuf-ts-docs]: https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp diff --git a/docs/reference/notifications/images/email-publisher-alert-config.png b/docs/reference/notifications/images/email-publisher-alert-config.png new file mode 100644 index 00000000..1766f983 Binary files /dev/null and b/docs/reference/notifications/images/email-publisher-alert-config.png differ diff --git a/docs/reference/notifications/images/email-publisher-global-config.png b/docs/reference/notifications/images/email-publisher-global-config.png new file mode 100644 index 00000000..818a7a8b Binary files /dev/null and b/docs/reference/notifications/images/email-publisher-global-config.png differ diff --git a/docs/reference/notifications/images/filter-expression-editor-error.png b/docs/reference/notifications/images/filter-expression-editor-error.png new file mode 100644 index 00000000..1625e1e3 Binary files /dev/null and b/docs/reference/notifications/images/filter-expression-editor-error.png differ diff --git a/docs/reference/notifications/images/filter-expression-editor.png b/docs/reference/notifications/images/filter-expression-editor.png new file mode 100644 index 00000000..229c318a Binary files /dev/null and b/docs/reference/notifications/images/filter-expression-editor.png differ diff --git a/docs/reference/notifications/images/jira-publisher-alert-config.png b/docs/reference/notifications/images/jira-publisher-alert-config.png new file mode 100644 index 00000000..dfa96daf Binary files /dev/null and b/docs/reference/notifications/images/jira-publisher-alert-config.png differ diff --git a/docs/reference/notifications/images/jira-publisher-global-config.png b/docs/reference/notifications/images/jira-publisher-global-config.png new file mode 100644 index 00000000..4c54124c Binary files /dev/null and b/docs/reference/notifications/images/jira-publisher-global-config.png differ diff --git a/docs/reference/notifications/images/kafka-publisher-alert-config.png b/docs/reference/notifications/images/kafka-publisher-alert-config.png new file mode 100644 index 00000000..ecad8b13 Binary files /dev/null and b/docs/reference/notifications/images/kafka-publisher-alert-config.png differ diff --git a/docs/reference/notifications/images/kafka-publisher-global-config.png b/docs/reference/notifications/images/kafka-publisher-global-config.png new file mode 100644 index 00000000..dfeb67c5 Binary files /dev/null and b/docs/reference/notifications/images/kafka-publisher-global-config.png differ diff --git a/docs/reference/notifications/publishers.md b/docs/reference/notifications/publishers.md index c6046391..73a9ab95 100644 --- a/docs/reference/notifications/publishers.md +++ b/docs/reference/notifications/publishers.md @@ -1,4 +1,176 @@ -# Notification publishers +# Publishers -!!! warning "Placeholder" - This page has not been written yet. +## Console + +Publishes notifications by writing them to standard output. + +This publisher is intended for testing. It does not provide any configuration options. + +## Email + +Publishes notifications as emails. [SMTP] and [SMTPS] protocols are supported. + +### Global Config + +The global configuration defines how Dependency-Track connects to your email server. + +![Email publisher global config](images/email-publisher-global-config.png) + +### Alert Config {: #email-alert-config } + +The alert configuration defines the recipients of email notifications, +as well as an optional subject prefix. + +![Email publisher alert config](images/email-publisher-alert-config.png) + +In addition to listing recipient addresses explicitly, you can also specify +one or more teams as recipients. When teams are specified, emails will be sent +to all members of those teams. + +You can mix explicit recipient addresses and teams, but you must configure +*at least one* of the two. + +## Jira + +Publishes notifications by creating issues in an Atlassian Jira instance. + + +### Global Config {: #jira-global-config } + + +The global configuration defines how Dependency-Track connects to your Jira server. + +![Jira publisher global config](images/jira-publisher-global-config.png) + + +### Alert Config {: #jira-alert-config } + + +The alert configuration defines properties of the issues to create. + +![Jira publisher alert config](images/jira-publisher-alert-config.png) + +!!! note + Selecting teams as recipients has no effect for this publisher. + +## Kafka + +Publishes notifications by emitting records to an Apache Kafka cluster. + +### Global Config {: #kafka-global-config } + +The global configuration defines how Dependency-Track connects to your Kafka cluster. + +![Kafka publisher global config](images/kafka-publisher-global-config.png) + +!!! note "Configuring TLS" + When enabling TLS, you **must** provide the certificate of the certificate authority (CA) + that signed the certificate used by your Kafka brokers. It **must** be provided in + [PEM] format and **must not** be encrypted, that is, **not** password-protected. + +!!! note "Configuring mTLS" + When enabling [mutual TLS], you **must** provide a client certificate and key in [PEM] format. + Both **must not** be encrypted. The client key **must** be a [managed secret](../../guides/user/managing-secrets.md). + +!!! note "Default Producer Configs" + Dependency-Track applies the following [configs](https://kafka.apache.org/41/configuration/producer-configs/) + to the underlying Kafka producer by default: + + * [`compression.type`](https://kafka.apache.org/41/configuration/producer-configs/#producerconfigs_compression.type): `snappy` + * [`enable.idempotence`](https://kafka.apache.org/41/configuration/producer-configs/#producerconfigs_enable.idempotence): `true` + + +### Alert Config {: #kafka-alert-config } + + +The alert config defines the destination and format of Kafka records emitted by the publisher. + +![Kafka publisher alert config](images/kafka-publisher-alert-config.png) + +!!! note + Selecting teams as recipients has no effect for this publisher. + +!!! tip "Protobuf" + You are strongly encouraged to publish notifications in Protobuf format. + Dependency-Track ensures that changes to the Protobuf schema are backward-compatible, + which is crucial when notifications are stored in a durable log like Kafka. + +!!! warning "Templating" + The Kafka publisher does not ship with a default template, since it's meant to + be used with Protobuf. If you prefer a different payload format, you must configure + a custom template first. + +!!! tip "Record Keys" + If a notification's subject is a project, as is the case for groups like `BOM_CONSUMED`, + `NEW_VULNERABILITY` etc., then the Kafka record key will be the project's UUID. + If the notification's subject is *not* a project, the key will be `null`. + +## Mattermost + +Publishes notifications as Mattermost messages. + + +### Alert Config {: #mattermost-alert-config } + + +The alert config defines the destination of Mattermost messages. + +This should be the URL of an [incoming Webhook](https://docs.mattermost.com/integrations-guide/incoming-webhooks.html). + +!!! note + Selecting teams as recipients has no effect for this publisher. + +## Microsoft Teams + +Publishes notifications as Microsoft Teams messages. + +### Alert Config {: #teams-alert-config } + +The alert config defines the destination of Microsoft Teams messages. + +This should be the URL of an [incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). + +!!! note + Selecting teams as recipients has no effect for this publisher. + +## Slack + +Publishes notifications as Slack messages. + +### Alert Config {: #slack-alert-config } + +The alert config defines the destination of Microsoft Teams messages. + +This should be the URL of an [incoming Webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/). + +!!! note + Selecting teams as recipients has no effect for this publisher. + +## Webex + +Publishes notifications as Cisco Webex messages. + + +### Alert Config {: #webex-alert-config } + + +The alert config defines the destination of Microsoft Teams messages. + +This should be the URL of an [incoming Webhook](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054-23307-75252). + +!!! note + Selecting teams as recipients has no effect for this publisher. + +## Webhook + +Publishes notifications as Webhooks. + +### Alert Config {: #webhook-alert-config } + +!!! note + Selecting teams as recipients has no effect for this publisher. + +[PEM]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail +[SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol +[SMTPS]: https://en.wikipedia.org/wiki/SMTPS +[mutual TLS]: https://en.wikipedia.org/wiki/Mutual_authentication#mTLS diff --git a/docs/reference/permissions.md b/docs/reference/permissions.md index 209781b9..603120c0 100644 --- a/docs/reference/permissions.md +++ b/docs/reference/permissions.md @@ -1,4 +1,110 @@ # Permissions -!!! warning "Placeholder" - This page has not been written yet. +For background on how the access control model works (users, teams, ACLs), see +[Access control](../concepts/access-control.md). + +## Permissions + +Dependency-Track uses a two-level permission model. Coarse-grained permissions +(for example `PORTFOLIO_MANAGEMENT`) grant full access to a capability. Fine-grained +permissions (for example `PORTFOLIO_MANAGEMENT_CREATE`) allow restricting access to +specific operations. A coarse-grained permission implies all of its fine-grained +variants. + +### Portfolio + +| Permission | Description | +|:----------------------------------|:-----------------------------------------------------------------------| +| `BOM_UPLOAD` | Upload CycloneDX Software Bills of Materials. | +| `PROJECT_CREATION_UPLOAD` | Auto-create a project on BOM upload if it does not exist. | +| `VIEW_PORTFOLIO` | Read projects, components, licenses, the dependency graph, and metrics.| +| `PORTFOLIO_ACCESS_CONTROL_BYPASS` | Bypass portfolio access control, granting access to all projects. | +| `PORTFOLIO_MANAGEMENT` | Create, update, and delete projects and portfolio data. | +| `PORTFOLIO_MANAGEMENT_CREATE` | Create projects and portfolio data. | +| `PORTFOLIO_MANAGEMENT_READ` | Read portfolio data. | +| `PORTFOLIO_MANAGEMENT_UPDATE` | Update projects and portfolio data. | +| `PORTFOLIO_MANAGEMENT_DELETE` | Delete projects and portfolio data. | + +### Vulnerability analysis + +| Permission | Description | +|:----------------------------------|:---------------------------------------------------------------------------------| +| `VIEW_VULNERABILITY` | View vulnerabilities that affect projects. | +| `VULNERABILITY_ANALYSIS` | Make analysis decisions on vulnerabilities and manage VEX data. | +| `VULNERABILITY_ANALYSIS_CREATE` | Upload VEX documents to a project. | +| `VULNERABILITY_ANALYSIS_READ` | Read VEX documents for a project. | +| `VULNERABILITY_ANALYSIS_UPDATE` | Make analysis decisions on vulnerabilities and upload VEX documents. | + +### Vulnerability management + +| Permission | Description | +|:------------------------------------|:--------------------------------------------------------| +| `VULNERABILITY_MANAGEMENT` | Full management of internal vulnerabilities. | +| `VULNERABILITY_MANAGEMENT_CREATE` | Create internal vulnerabilities. | +| `VULNERABILITY_MANAGEMENT_READ` | Read internal vulnerabilities. | +| `VULNERABILITY_MANAGEMENT_UPDATE` | Update internal vulnerabilities and tags. | +| `VULNERABILITY_MANAGEMENT_DELETE` | Delete internal vulnerabilities. | + +### Policy management + +| Permission | Description | +|:------------------------------|:-----------------------------------------------------------------| +| `POLICY_MANAGEMENT` | Create, update, and delete policies, services, and license groups.| +| `POLICY_MANAGEMENT_CREATE` | Create policies. | +| `POLICY_MANAGEMENT_READ` | Read policies. | +| `POLICY_MANAGEMENT_UPDATE` | Update policies. | +| `POLICY_MANAGEMENT_DELETE` | Delete policies. | +| `POLICY_VIOLATION_ANALYSIS` | Make analysis decisions on policy violations. | +| `VIEW_POLICY_VIOLATION` | View policy violations across the portfolio. | + +### Access management + +| Permission | Description | +|:------------------------------|:--------------------------------------------------| +| `ACCESS_MANAGEMENT` | Manage users, teams, permissions, and API keys. | +| `ACCESS_MANAGEMENT_CREATE` | Create users, teams, and API keys. | +| `ACCESS_MANAGEMENT_READ` | Read users, teams, and API keys. | +| `ACCESS_MANAGEMENT_UPDATE` | Update users, teams, and API keys. | +| `ACCESS_MANAGEMENT_DELETE` | Delete users, teams, and API keys. | + +### System configuration + +| Permission | Description | +|:---------------------------------|:-------------------------------------------------------------------------------------| +| `SYSTEM_CONFIGURATION` | Full access to system configuration (notifications, repositories, email settings). | +| `SYSTEM_CONFIGURATION_CREATE` | Create system configuration entries. | +| `SYSTEM_CONFIGURATION_READ` | Read system configuration. | +| `SYSTEM_CONFIGURATION_UPDATE` | Update system configuration. | +| `SYSTEM_CONFIGURATION_DELETE` | Delete system configuration entries. | + +### Secret management + +| Permission | Description | +|:------------------------------|:----------------------------------| +| `SECRET_MANAGEMENT` | Full secret management access. | +| `SECRET_MANAGEMENT_CREATE` | Create secrets. | +| `SECRET_MANAGEMENT_UPDATE` | Update secrets. | +| `SECRET_MANAGEMENT_DELETE` | Delete secrets. | + +### Tags and badges + +| Permission | Description | +|:----------------------|:-----------------------------------------| +| `TAG_MANAGEMENT` | Update and delete tags. | +| `TAG_MANAGEMENT_DELETE`| Delete tags. | +| `VIEW_BADGES` | Retrieve SVG badge images for projects. | + +## Default teams + +Dependency-Track creates the following default teams on first startup: + +| Team | Purpose | +|:----------------|:----------------------------------------------------------------------------------------------------------------------------| +| Administrators | Full access. Used for initial setup and ongoing administration. Members receive all permissions. | +| Badge Viewers | Holds the `VIEW_BADGES` permission and a pre-created API key. Used for unauthenticated-style badge access via a shared key. | +| Portfolio Managers | Intended for users who manage projects and portfolios without needing administrative access. | +| Automation | Intended for CI/CD pipelines and automated tools. Typically holds `BOM_UPLOAD` and `PROJECT_CREATION_UPLOAD`. | + +!!! warning + Change the default API key on the **Badge Viewers** and **Automation** teams before + going to production. Default keys are predictable. Rotate them immediately. diff --git a/docs/reference/schemas/.pages b/docs/reference/schemas/.pages new file mode 100644 index 00000000..f82584aa --- /dev/null +++ b/docs/reference/schemas/.pages @@ -0,0 +1,3 @@ +nav: + - Notification Schema: notification.md + - Policy Schema: policy.md diff --git a/docs/reference/schemas/notification.md b/docs/reference/schemas/notification.md new file mode 100644 index 00000000..50f9e5f9 --- /dev/null +++ b/docs/reference/schemas/notification.md @@ -0,0 +1,1182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Notification + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `level` | [`Level`](#org-dependencytrack-notification-v1-Level) | | - | +| `scope` | [`Scope`](#org-dependencytrack-notification-v1-Scope) | | - | +| `group` | [`Group`](#org-dependencytrack-notification-v1-Group) | | - | +| `title` | `string` | | - | +| `content` | `string` | | - | +| `timestamp` | `google.protobuf.Timestamp` | | - | +| `subject` | `google.protobuf.Any` | | - | +| `id` | `string` | Unique identifier of the notification in UUIDv7 format. | - | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Subjects + + + + + + + + + + + +### BomConsumedOrProcessedSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `bom` | [`Bom`](#org-dependencytrack-notification-v1-Bom) | | - | +| `token` | `string` | | - | + + + + + + + + + +### BomProcessingFailedSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `bom` | [`Bom`](#org-dependencytrack-notification-v1-Bom) | | - | +| `cause` | `string` | | - | +| `token` | `string` | | - | + + + + + + + + + +### BomValidationFailedSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `bom` | [`Bom`](#org-dependencytrack-notification-v1-Bom) | | - | +| `errors` | `string[]` | | - | + + + + + + + + + + + +### ComponentVulnAnalysisCompleteSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `vulnerabilities` | [`Vulnerability[]`](#org-dependencytrack-notification-v1-Vulnerability) | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject + +Subject for GROUP_NEW_POLICY_VIOLATIONS_SUMMARY notifications. + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `overview` | [`NewPolicyViolationsSummarySubject.Overview`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-Overview) | | - | +| `project_summaries` | [`NewPolicyViolationsSummarySubject.ProjectSummaryEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-ProjectSummaryEntry) | | - | +| `violations_by_project` | [`NewPolicyViolationsSummarySubject.ProjectViolationsEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-ProjectViolationsEntry) | | - | +| `since` | `google.protobuf.Timestamp` | | - | + + + + + + + + + + + + + + + + + + + + + + + + + +### NewVulnerabilitiesSummarySubject + +Subject for GROUP_NEW_VULNERABILITIES_SUMMARY notifications. + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `overview` | [`NewVulnerabilitiesSummarySubject.Overview`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-Overview) | | - | +| `project_summaries` | [`NewVulnerabilitiesSummarySubject.ProjectSummaryEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-ProjectSummaryEntry) | | - | +| `findings_by_project` | [`NewVulnerabilitiesSummarySubject.ProjectFindingsEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-ProjectFindingsEntry) | | - | +| `since` | `google.protobuf.Timestamp` | | - | + + + + + + + + + + + + + + + + + + + + + + + + + +### NewVulnerabilitySubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `vulnerability` | [`Vulnerability`](#org-dependencytrack-notification-v1-Vulnerability) | | - | +| `affected_projects_reference` | [`BackReference`](#org-dependencytrack-notification-v1-BackReference) | | - | +| `vulnerability_analysis_level` | `string` | | - | +| `affected_projects` | [`Project[]`](#org-dependencytrack-notification-v1-Project) | List of projects affected by the vulnerability. DEPRECATED: This list only holds one item, and it is identical to the one in the project field. The field is kept for backward compatibility of JSON notifications, but consumers should not expect multiple projects here. Transmitting all affected projects in one notification is not feasible for large portfolios, see https://github.com/DependencyTrack/hyades/issues/467 for details. | - | +| `analysis_trigger` | [`AnalysisTrigger`](#org-dependencytrack-notification-v1-AnalysisTrigger) | The trigger of the analysis that identified the vulnerability. | - | + + + + + + + + + +### NewVulnerableDependencySubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `vulnerabilities` | [`Vulnerability[]`](#org-dependencytrack-notification-v1-Vulnerability) | | - | + + + + + + + + + + + + + + + + + + + +### PolicyViolationAnalysisDecisionChangeSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `policy_violation` | [`PolicyViolation`](#org-dependencytrack-notification-v1-PolicyViolation) | | - | +| `analysis` | [`PolicyViolationAnalysis`](#org-dependencytrack-notification-v1-PolicyViolationAnalysis) | | - | + + + + + + + + + +### PolicyViolationSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `policy_violation` | [`PolicyViolation`](#org-dependencytrack-notification-v1-PolicyViolation) | | - | + + + + + + + + + + + +### ProjectVulnAnalysisCompleteSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `findings` | [`ComponentVulnAnalysisCompleteSubject[]`](#org-dependencytrack-notification-v1-ComponentVulnAnalysisCompleteSubject) | | - | +| `status` | [`ProjectVulnAnalysisStatus`](#org-dependencytrack-notification-v1-ProjectVulnAnalysisStatus) | | - | +| `token` | `string` | | - | + + + + + + + + + +### UserSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `username` | `string` | | - | +| `email` | `string` | | - | + + + + + + + + + +### VexConsumedOrProcessedSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `vex` | `bytes` | | - | +| `format` | `string` | | - | +| `spec_version` | `string` | | - | + + + + + + + + + + + + + + + + + +### VulnerabilityAnalysisDecisionChangeSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `vulnerability` | [`Vulnerability`](#org-dependencytrack-notification-v1-Vulnerability) | | - | +| `analysis` | [`VulnerabilityAnalysis`](#org-dependencytrack-notification-v1-VulnerabilityAnalysis) | | - | + + + + + + + + + +### VulnerabilityRetractedSubject + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | The component for which the vulnerability was previously reported. | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | The project for which the vulnerability was previously reported. | - | +| `vulnerability` | [`Vulnerability`](#org-dependencytrack-notification-v1-Vulnerability) | The previously reported vulnerability. | - | + + + + + + + +## Messages + + + + + + + +### BackReference + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `api_uri` | `string` | URI to the API endpoint from which additional information can be fetched. | - | +| `frontend_uri` | `string` | URI to the frontend where additional information can be seen. | - | + + + + + + + + + +### Bom + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `content` | `string` | | - | +| `format` | `string` | | - | +| `spec_version` | `string` | | - | + + + + + + + + + + + + + + + +### Component + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `group` | `string` | | - | +| `name` | `string` | | - | +| `version` | `string` | | - | +| `purl` | `string` | | - | +| `md5` | `string` | | - | +| `sha1` | `string` | | - | +| `sha256` | `string` | | - | +| `sha512` | `string` | | - | + + + + + + + + + + + + + +### NewPolicyViolationsSummarySubject.Overview + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `affected_projects_count` | `int32` | | - | +| `affected_components_count` | `int32` | | - | +| `new_violations_count` | `int32` | | - | +| `new_violations_count_by_type` | [`NewPolicyViolationsSummarySubject.Overview.NewViolationsCountByTypeEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-Overview-NewViolationsCountByTypeEntry) | | - | +| `suppressed_new_violations_count` | `int32` | | - | +| `total_new_violations_count` | `int32` | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.Overview.NewViolationsCountByTypeEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.ProjectSummaryEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `new_violations_count_by_type` | [`NewPolicyViolationsSummarySubject.ProjectSummaryEntry.NewViolationsCountByTypeEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-ProjectSummaryEntry-NewViolationsCountByTypeEntry) | | - | +| `suppressed_new_violations_count_by_type` | [`NewPolicyViolationsSummarySubject.ProjectSummaryEntry.SuppressedNewViolationsCountByTypeEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-ProjectSummaryEntry-SuppressedNewViolationsCountByTypeEntry) | | - | +| `total_new_violations_count_by_type` | [`NewPolicyViolationsSummarySubject.ProjectSummaryEntry.TotalNewViolationsCountByTypeEntry[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-ProjectSummaryEntry-TotalNewViolationsCountByTypeEntry) | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.ProjectSummaryEntry.NewViolationsCountByTypeEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.ProjectSummaryEntry.SuppressedNewViolationsCountByTypeEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.ProjectSummaryEntry.TotalNewViolationsCountByTypeEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.ProjectViolationsEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `violations` | [`NewPolicyViolationsSummarySubject.Violation[]`](#org-dependencytrack-notification-v1-NewPolicyViolationsSummarySubject-Violation) | | - | + + + + + + + + + +### NewPolicyViolationsSummarySubject.Violation + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `policy_condition` | [`PolicyCondition`](#org-dependencytrack-notification-v1-PolicyCondition) | | - | +| `type` | `string` | | - | +| `timestamp` | `google.protobuf.Timestamp` | | - | +| `analysis_state` | `string` | | - | +| `suppressed` | `bool` | | - | + + + + + + + + + + + +### NewVulnerabilitiesSummarySubject.Finding + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `vulnerability` | [`Vulnerability`](#org-dependencytrack-notification-v1-Vulnerability) | | - | +| `analyzer_identity` | `string` | | - | +| `attributed_on` | `google.protobuf.Timestamp` | | - | +| `reference_url` | `string` | | - | +| `analysis_state` | `string` | | - | +| `suppressed` | `bool` | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.Overview + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `affected_projects_count` | `int32` | | - | +| `affected_components_count` | `int32` | | - | +| `new_vulnerabilities_count` | `int32` | | - | +| `new_vulnerabilities_count_by_severity` | [`NewVulnerabilitiesSummarySubject.Overview.NewVulnerabilitiesCountBySeverityEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-Overview-NewVulnerabilitiesCountBySeverityEntry) | | - | +| `suppressed_new_vulnerabilities_count` | `int32` | | - | +| `total_new_vulnerabilities_count` | `int32` | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.Overview.NewVulnerabilitiesCountBySeverityEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.ProjectFindingsEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `findings` | [`NewVulnerabilitiesSummarySubject.Finding[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-Finding) | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.ProjectSummaryEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `new_vulnerabilities_count_by_severity` | [`NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.NewVulnerabilitiesCountBySeverityEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-ProjectSummaryEntry-NewVulnerabilitiesCountBySeverityEntry) | | - | +| `suppressed_new_vulnerabilities_count_by_severity` | [`NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.SuppressedNewVulnerabilitiesCountBySeverityEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-ProjectSummaryEntry-SuppressedNewVulnerabilitiesCountBySeverityEntry) | | - | +| `total_new_vulnerabilities_count_by_severity` | [`NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.TotalNewVulnerabilitiesCountBySeverityEntry[]`](#org-dependencytrack-notification-v1-NewVulnerabilitiesSummarySubject-ProjectSummaryEntry-TotalNewVulnerabilitiesCountBySeverityEntry) | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.NewVulnerabilitiesCountBySeverityEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.SuppressedNewVulnerabilitiesCountBySeverityEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + +### NewVulnerabilitiesSummarySubject.ProjectSummaryEntry.TotalNewVulnerabilitiesCountBySeverityEntry + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `key` | `string` | | - | +| `value` | `int32` | | - | + + + + + + + + + + + + + + + +### Policy + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `name` | `string` | | - | +| `violation_state` | `string` | | - | + + + + + + + + + +### PolicyCondition + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `subject` | `string` | | - | +| `operator` | `string` | | - | +| `value` | `string` | | - | +| `policy` | [`Policy`](#org-dependencytrack-notification-v1-Policy) | | - | + + + + + + + + + +### PolicyViolation + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `type` | `string` | | - | +| `timestamp` | `google.protobuf.Timestamp` | | - | +| `condition` | [`PolicyCondition`](#org-dependencytrack-notification-v1-PolicyCondition) | | - | + + + + + + + + + +### PolicyViolationAnalysis + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `policy_violation` | [`PolicyViolation`](#org-dependencytrack-notification-v1-PolicyViolation) | | - | +| `state` | `string` | | - | +| `suppressed` | `bool` | | - | + + + + + + + + + + + + + +### Project + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `name` | `string` | | - | +| `version` | `string` | | - | +| `description` | `string` | | - | +| `purl` | `string` | | - | +| `tags` | `string[]` | | - | +| `is_active` | `bool` | | - | + + + + + + + + + + + + + + + +### Vulnerability + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `vuln_id` | `string` | | - | +| `source` | `string` | | - | +| `aliases` | [`Vulnerability.Alias[]`](#org-dependencytrack-notification-v1-Vulnerability-Alias) | | - | +| `title` | `string` | | - | +| `sub_title` | `string` | | - | +| `description` | `string` | | - | +| `recommendation` | `string` | | - | +| `cvss_v2` | `double` | | - | +| `cvss_v3` | `double` | | - | +| `owasp_rr_likelihood` | `double` | | - | +| `owasp_rr_technical_impact` | `double` | | - | +| `owasp_rr_business_impact` | `double` | | - | +| `severity` | `string` | | - | +| `cwes` | [`Vulnerability.Cwe[]`](#org-dependencytrack-notification-v1-Vulnerability-Cwe) | | - | +| `cvss_v2_vector` | `string` | | - | +| `cvss_v3_vector` | `string` | | - | +| `owasp_rr_vector` | `string` | | - | +| `cvss_v4` | `double` | | - | +| `cvss_v4_vector` | `string` | | - | + + + + + + + + + +### Vulnerability.Alias + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `id` | `string` | | - | +| `source` | `string` | | - | + + + + + + + + + +### Vulnerability.Cwe + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `cwe_id` | `int32` | | - | +| `name` | `string` | | - | + + + + + + + + + +### VulnerabilityAnalysis + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `component` | [`Component`](#org-dependencytrack-notification-v1-Component) | | - | +| `project` | [`Project`](#org-dependencytrack-notification-v1-Project) | | - | +| `vulnerability` | [`Vulnerability`](#org-dependencytrack-notification-v1-Vulnerability) | | - | +| `state` | `string` | | - | +| `suppressed` | `bool` | | - | + + + + + + + + + + + +## Enums + + + + + + +### AnalysisTrigger + + + +| Name | Description | +| :--- | :---------- | +| `ANALYSIS_TRIGGER_UNSPECIFIED` | No trigger specified. | +| `ANALYSIS_TRIGGER_BOM_UPLOAD` | The analysis was triggered by a BOM upload. | +| `ANALYSIS_TRIGGER_SCHEDULE` | The analysis was triggered by a schedule. | +| `ANALYSIS_TRIGGER_MANUAL` | The analysis was triggered manually. | + + + + + + +### Group + + + +| Name | Description | +| :--- | :---------- | +| `GROUP_UNSPECIFIED` | | +| `GROUP_CONFIGURATION` | | +| `GROUP_DATASOURCE_MIRRORING` | | +| `GROUP_REPOSITORY` | | +| `GROUP_INTEGRATION` | | +| `GROUP_FILE_SYSTEM` | | +| `GROUP_ANALYZER` | | +| `GROUP_NEW_VULNERABILITY` | | +| `GROUP_NEW_VULNERABLE_DEPENDENCY` | | +| `GROUP_PROJECT_AUDIT_CHANGE` | | +| `GROUP_BOM_CONSUMED` | | +| `GROUP_BOM_PROCESSED` | | +| `GROUP_VEX_CONSUMED` | | +| `GROUP_VEX_PROCESSED` | | +| `GROUP_POLICY_VIOLATION` | | +| `GROUP_PROJECT_CREATED` | | +| `GROUP_BOM_PROCESSING_FAILED` | | +| `GROUP_PROJECT_VULN_ANALYSIS_COMPLETE` | | +| `GROUP_USER_CREATED` | | +| `GROUP_USER_DELETED` | | +| `GROUP_BOM_VALIDATION_FAILED` | | +| `GROUP_VULNERABILITY_RETRACTED` | A previously identified vulnerability is no longer applicable, +e.g. due to upstream sources correcting their data. | +| `GROUP_NEW_VULNERABILITIES_SUMMARY` | Scheduled summary of new vulnerabilities across projects. | +| `GROUP_NEW_POLICY_VIOLATIONS_SUMMARY` | Scheduled summary of new policy violations across projects. | + + + + + + +### Level + + + +| Name | Description | +| :--- | :---------- | +| `LEVEL_UNSPECIFIED` | | +| `LEVEL_INFORMATIONAL` | | +| `LEVEL_WARNING` | | +| `LEVEL_ERROR` | | + + + + + + +### ProjectVulnAnalysisStatus + + + +| Name | Description | +| :--- | :---------- | +| `PROJECT_VULN_ANALYSIS_STATUS_UNSPECIFIED` | | +| `PROJECT_VULN_ANALYSIS_STATUS_FAILED` | | +| `PROJECT_VULN_ANALYSIS_STATUS_COMPLETED` | | + + + + + + +### Scope + + + +| Name | Description | +| :--- | :---------- | +| `SCOPE_UNSPECIFIED` | | +| `SCOPE_PORTFOLIO` | | +| `SCOPE_SYSTEM` | | + + + diff --git a/docs/reference/schemas/policy.md b/docs/reference/schemas/policy.md new file mode 100644 index 00000000..c4f86ba8 --- /dev/null +++ b/docs/reference/schemas/policy.md @@ -0,0 +1,235 @@ +## Messages + + + + + + +### Component + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | UUID of the component. | - | +| `group` | `string` | Group / namespace of the component. | - | +| `name` | `string` | Name of the component. | - | +| `version` | `string` | Version of the component. | - | +| `classifier` | `string` | Classifier / type of the component. May be any of: - APPLICATION - CONTAINER - DEVICE - FILE - FIRMWARE - FRAMEWORK - LIBRARY - OPERATING_SYSTEM | - | +| `cpe` | `string` | CPE of the component. https://csrc.nist.gov/projects/security-content-automation-protocol/specifications/cpe | - | +| `purl` | `string` | Package URL of the component. https://github.com/package-url/purl-spec | - | +| `swid_tag_id` | `string` | SWID tag ID of the component. https://csrc.nist.gov/projects/Software-Identification-SWID | - | +| `is_internal` | `bool` | Whether the component is internal to the organization. | - | +| `md5` | `string` | | - | +| `sha1` | `string` | | - | +| `sha256` | `string` | | - | +| `sha384` | `string` | | - | +| `sha512` | `string` | | - | +| `sha3_256` | `string` | | - | +| `sha3_384` | `string` | | - | +| `sha3_512` | `string` | | - | +| `blake2b_256` | `string` | | - | +| `blake2b_384` | `string` | | - | +| `blake2b_512` | `string` | | - | +| `blake3` | `string` | | - | +| `license_name` | `string` | | - | +| `license_expression` | `string` | | - | +| `resolved_license` | [`License`](#org-dependencytrack-policy-v1-License) | | - | +| `published_at` | `google.protobuf.Timestamp` | When the component current version last modified. | - | +| `latest_version` | `string` | | - | + + + + + + + +### License + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `id` | `string` | | - | +| `name` | `string` | | - | +| `groups` | [`License.Group[]`](#org-dependencytrack-policy-v1-License-Group) | | - | +| `is_osi_approved` | `bool` | | - | +| `is_fsf_libre` | `bool` | | - | +| `is_deprecated_id` | `bool` | | - | +| `is_custom` | `bool` | | - | + + + + + + + +### License.Group + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `name` | `string` | | - | + + + + + + + +### Project + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `group` | `string` | | - | +| `name` | `string` | | - | +| `version` | `string` | | - | +| `classifier` | `string` | | - | +| `is_active` | `bool` | | - | +| `tags` | `string[]` | | - | +| `properties` | [`Project.Property[]`](#org-dependencytrack-policy-v1-Project-Property) | | - | +| `cpe` | `string` | | - | +| `purl` | `string` | | - | +| `swid_tag_id` | `string` | | - | +| `last_bom_import` | `google.protobuf.Timestamp` | | - | +| `metadata` | [`Project.Metadata`](#org-dependencytrack-policy-v1-Project-Metadata) | | - | + + + + + + + +### Project.Metadata + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `tools` | [`Tools`](#org-dependencytrack-policy-v1-Tools) | | - | +| `bom_generated` | `google.protobuf.Timestamp` | | - | + + + + + + + +### Project.Property + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `group` | `string` | | - | +| `name` | `string` | | - | +| `value` | `string` | | - | +| `type` | `string` | | - | + + + + + + + +### Tools + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `components` | [`Component[]`](#org-dependencytrack-policy-v1-Component) | Components used as tools. | - | + + + + + + + +### VersionDistance + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `epoch` | `string` | | - | +| `major` | `string` | | - | +| `minor` | `string` | | - | +| `patch` | `string` | | - | + + + + + + + +### Vulnerability + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `uuid` | `string` | | - | +| `id` | `string` | | - | +| `source` | `string` | | - | +| `aliases` | [`Vulnerability.Alias[]`](#org-dependencytrack-policy-v1-Vulnerability-Alias) | | - | +| `cwes` | `int32[]` | | - | +| `created` | `google.protobuf.Timestamp` | | - | +| `published` | `google.protobuf.Timestamp` | | - | +| `updated` | `google.protobuf.Timestamp` | | - | +| `severity` | `string` | | - | +| `cvssv2_base_score` | `double` | | - | +| `cvssv2_impact_subscore` | `double` | | - | +| `cvssv2_exploitability_subscore` | `double` | | - | +| `cvssv2_vector` | `string` | | - | +| `cvssv3_base_score` | `double` | | - | +| `cvssv3_impact_subscore` | `double` | | - | +| `cvssv3_exploitability_subscore` | `double` | | - | +| `cvssv3_vector` | `string` | | - | +| `owasp_rr_likelihood_score` | `double` | | - | +| `owasp_rr_technical_impact_score` | `double` | | - | +| `owasp_rr_business_impact_score` | `double` | | - | +| `owasp_rr_vector` | `string` | | - | +| `epss_score` | `double` | | - | +| `epss_percentile` | `double` | | - | +| `cvssv4_score` | `double` | | - | +| `cvssv4_vector` | `string` | | - | + + + + + + + +### Vulnerability.Alias + + + + +| Field | Type | Description | +| :---- | :--- | :---------- | +| `id` | `string` | | - | +| `source` | `string` | | - | + + + + + + + + diff --git a/docs/reference/vulnerability-policies.md b/docs/reference/vulnerability-policies.md new file mode 100644 index 00000000..01ae82a6 --- /dev/null +++ b/docs/reference/vulnerability-policies.md @@ -0,0 +1,159 @@ +# Vulnerability Policies + +For background on what vulnerability policies are and how evaluation works, see +[Concepts: Vulnerability Policies](../concepts/vulnerability-policies.md). +For step-by-step procedures, see +[Managing Vulnerability Policies](../guides/user/managing-vulnerability-policies.md). + +## Policy Sources + +| Source | How it is managed | Editable | +|:-------|:-----------------------------------------------------|:---------| +| User | Created and edited directly in Dependency-Track | Yes | +| Bundle | Synchronised from a remote ZIP archive of YAML files | No | + +Policy names are globally unique across user-managed and bundle-managed policies. + +## Operation Modes + +| Mode | Behaviour | +|:---------|:-----------------------------------------------------------------------------------------------------| +| Apply | Apply the analysis and ratings to the finding. This is the default. | +| Log | Record that the policy matched, but do not modify the finding. Useful for validating a new policy. | +| Disabled | The policy is not evaluated at all. | + +## Condition Variables + +Conditions use the same [Common Expression Language](./cel-expressions.md) syntax, functions, and variables +as standard policy expressions, with one exception: A vulnerability policy is scoped to a +single vulnerability, exposed as the `vuln` variable, rather than a list of vulnerabilities. + +| Variable | Type | Description | +|:------------|:------------------------------------------------|:--------------------------------------------| +| `vuln` | [Vulnerability] | The vulnerability being evaluated | +| `component` | [Component] | The component the vulnerability applies to | +| `project` | [Project] | The project the component belongs to | +| `now` | [`google.protobuf.Timestamp`][protobuf-ts-docs] | The current time at the start of evaluation | + +Because `vuln` is a single object rather than a list, constructs like `vulns.exists(...)` from +standard policies become direct field accesses such as `vuln.id == "CVE-2022-41852"`. Everything +else works identically, including [`matches_range`](./cel-expressions.md#matches_range), +[`is_dependency_of`](./cel-expressions.md#is_dependency_of), `has()`, and the full CEL standard library. +Refer to the [expressions reference](./cel-expressions.md) for the complete function list. + +## Analysis Fields + +When a policy matches in *Apply* mode, the following analysis fields are applied to the finding: + +* **State** (required). One of `EXPLOITABLE`, `IN_TRIAGE`, `FALSE_POSITIVE`, `NOT_AFFECTED`, `RESOLVED`. +* **Justification**. Only applicable when the state is `NOT_AFFECTED`. Follows the CycloneDX VEX values + (for example `CODE_NOT_REACHABLE`, `PROTECTED_BY_MITIGATING_CONTROL`). +* **Vendor response**. The response communicated to consumers (`CAN_NOT_FIX`, `WILL_NOT_FIX`, `UPDATE`, + `ROLLBACK`, `WORKAROUND_AVAILABLE`). +* **Details**. Free-form text explaining the analysis. +* **Suppress**. Whether to suppress the finding. + +## Ratings + +Up to three ratings may be attached to a policy. Each rating specifies a method (`CVSSv2`, `CVSSv3`, +`CVSSv4`, `OWASP`), a severity, and optionally a score and vector. + +## Bundle Configuration + +| Property | Description | +|:---------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------| +| [`dt.vulnerability.policy.bundle.url`](./configuration/properties.md#dtvulnerabilitypolicybundleurl) | HTTP(S) URL of the bundle ZIP | +| [`dt.vulnerability.policy.bundle.auth.username`](./configuration/properties.md#dtvulnerabilitypolicybundleauthusername) | Basic-auth username | +| [`dt.vulnerability.policy.bundle.auth.password`](./configuration/properties.md#dtvulnerabilitypolicybundleauthpassword) | Basic-auth password | +| [`dt.vulnerability.policy.bundle.auth.bearer.token`](./configuration/properties.md#dtvulnerabilitypolicybundleauthbearertoken) | Bearer token, used when no basic-auth is configured | +| [`dt.task.vulnerability-policy-bundle-sync.cron`](./configuration/properties.md#dttaskvulnerability-policy-bundle-synccron) | Cron expression for the scheduled sync | + +## Bundle Layout + +A bundle is a plain ZIP archive of YAML files at the root. File names must end in `.yaml` or `.yml` and +must not start with `.` or `_`. Non-YAML files are ignored. + +```text +bundle.zip +├── cve-2022-41852.yaml +└── spring-cloud-suppressions.yaml +``` + +The following size limits apply: + +* The bundle ZIP must not exceed 10 MiB. +* It may contain at most 1000 entries. +* Each individual YAML file must not exceed 1 MiB. + +## Policy File Format + +Each YAML file contains a single policy. The schema is validated on every sync. If any policy in the bundle +fails to validate, the entire bundle is rejected and the database is left untouched. + +??? example "Example policy file: `cve-2022-41852.yaml`" + + ```yaml linenums="1" + apiVersion: v1.0 + type: Vulnerability Policy + name: Spring Cloud CVE-2022-41852 Suppression + description: |- + Suppresses occurrences of CVE-2022-41852 in commons-jxpath, + when commons-jxpath is introduced through Spring Cloud. + operationMode: APPLY + author: Jane Doe + condition: |- + vuln.id == "CVE-2022-41852" + && component.name == "commons-jxpath" + && component.is_dependency_of(v1.Component{ + group: "org.springframework.cloud", + version: "vers:maven/>3.1|<3.3" + }) + analysis: + state: NOT_AFFECTED + justification: CODE_NOT_REACHABLE + details: |- + It was determined that CVE-2022-41852 is not exploitable in Spring Cloud + components, because the vulnerable code is not used. + suppress: true + ``` + +| Field | Required | Description | +|:----------------|:---------|:-----------------------------------------------------------------------------| +| `apiVersion` | Yes | Schema version. Currently `v1.0`. | +| `type` | Yes | Must be the literal string `Vulnerability Policy`. | +| `name` | Yes | Globally unique policy name. | +| `description` | No | Short description, up to 512 characters. | +| `author` | No | Free-form author identifier. | +| `validFrom` | No | RFC 3339 timestamp. The policy is inactive before this instant. | +| `validUntil` | No | RFC 3339 timestamp. The policy is inactive after this instant. | +| `condition` | Yes | CEL expression. | +| `analysis` | Yes | Analysis to apply on match. See [Analysis Fields](#analysis-fields). | +| `ratings` | No | Up to 3 rating overrides. See [Ratings](#ratings). | +| `operationMode` | No | `APPLY` (default), `LOG`, or `DISABLED`. See [Operation Modes](#operation-modes). | +| `priority` | No | Integer between 0 and 100. Higher values are evaluated first. Defaults to 0. | + +## Sync Behaviour + +Each sync reconciles the bundle with the database: + +* Policies present in the bundle but absent from the database are *created*. +* Policies present in both are *updated* in place. +* Policies previously synced from the bundle but no longer present are *deleted*. Any analyses applied + by those policies are reset and an audit trail entry is recorded. +* User-managed policies are never touched, regardless of whether they appear in the bundle. + +A sync is aborted without any database changes when: + +* The bundle exceeds the size or entry limits. +* The ZIP is malformed, or the bundle file is not reachable. +* Any policy file fails schema validation or its CEL condition fails to compile. +* The bundle contains two policies with the same `name`. +* The bundle introduces a policy whose `name` already exists as a user-managed policy. + +The last failure reason is surfaced in the *Bundles* view so that operators can diagnose sync issues +without needing access to the server logs. + +[Component]: ./schemas/policy.md#component +[Project]: ./schemas/policy.md#project +[Vulnerability]: ./schemas/policy.md#vulnerability +[protobuf-ts-docs]: https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp