From 01efcb777bfe8484a700c949e62acebfb0018e9a Mon Sep 17 00:00:00 2001 From: nscuro Date: Wed, 10 Jun 2026 18:11:58 +0200 Subject: [PATCH] Offer notification proto schema as download Makes it easier for users to find and integrate it. Signed-off-by: nscuro --- .github/workflows/update-proto-docs.yml | 5 +- .markdownlint-cli2.yaml | 5 +- .vale.ini | 4 +- Makefile | 10 +- .../architecture/design/notifications.md | 2 +- docs/concepts/changes-in-v5.md | 2 +- docs/concepts/notifications.md | 2 +- docs/reference/.pages | 1 - docs/reference/notifications/.pages | 1 + .../notifications/filter-expressions.md | 10 +- docs/reference/notifications/groups.md | 26 +- .../notifications/notification.proto | 360 ++++++++++++++++++ docs/reference/notifications/publishers.md | 1 + .../schema.md} | 4 + .../schema.md.tmpl} | 4 + docs/reference/notifications/templating.md | 4 +- docs/reference/policies/.pages | 1 + docs/reference/policies/component-policies.md | 2 +- .../policies/condition-expressions.md | 12 +- .../{schemas/policy.md => policies/schema.md} | 0 .../schema.md.tmpl} | 0 docs/reference/schemas/.pages | 3 - 22 files changed, 418 insertions(+), 41 deletions(-) create mode 100644 docs/reference/notifications/notification.proto rename docs/reference/{schemas/notification.md => notifications/schema.md} (98%) rename docs/reference/{schemas/notification.md.tmpl => notifications/schema.md.tmpl} (87%) rename docs/reference/{schemas/policy.md => policies/schema.md} (100%) rename docs/reference/{schemas/policy.md.tmpl => policies/schema.md.tmpl} (100%) delete mode 100644 docs/reference/schemas/.pages diff --git a/.github/workflows/update-proto-docs.yml b/.github/workflows/update-proto-docs.yml index 7b0256e2..d727b8ad 100644 --- a/.github/workflows/update-proto-docs.yml +++ b/.github/workflows/update-proto-docs.yml @@ -46,7 +46,10 @@ jobs: - name: Create Pull Request uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 with: - add-paths: "docs/reference/schemas/*.md" + add-paths: | + docs/reference/notifications/schema.md + docs/reference/notifications/notification.proto + docs/reference/policies/schema.md branch: update-proto-docs body: "Updates Protobuf documentation." commit-message: Update proto docs diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 160ba448..2af205c9 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -34,7 +34,10 @@ globs: ignores: - "docs/includes/**" - "docs/reference/configuration/properties.md" -- "docs/reference/schemas/**" +- "docs/reference/notifications/schema.md" +- "docs/reference/notifications/schema.md.tmpl" +- "docs/reference/policies/schema.md" +- "docs/reference/policies/schema.md.tmpl" - "existing-docs/**" - "site/**" - "node_modules/**" diff --git a/.vale.ini b/.vale.ini index 0e6a45d8..e342680a 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,9 @@ BasedOnStyles = Vale, Google, write-good, DependencyTrack # Ignore generated reference files. [docs/reference/configuration/properties.md] BasedOnStyles = -[docs/reference/schemas/*.md] +[docs/reference/notifications/schema.md] +BasedOnStyles = +[docs/reference/policies/schema.md] BasedOnStyles = # Tutorials use "we" voice and "will" to set expectations per Diataxis convention. diff --git a/Makefile b/Makefile index 131aecc2..032c25e0 100644 --- a/Makefile +++ b/Makefile @@ -97,15 +97,17 @@ generate-config-docs: generate-proto-docs: @docker run -i --rm -u "$$(id -u):$$(id -g)" \ - -v "$$(pwd)/docs/reference/schemas:/out" \ + -v "$$(pwd)/docs/reference/notifications:/out" \ -v "$$(pwd)/$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1:/protos" \ "$(PROTOC_GEN_DOC_IMAGE)" \ - --doc_opt=/out/notification.md.tmpl,notification.md + --doc_opt=/out/schema.md.tmpl,schema.md + @cp "$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1/notification.proto" \ + docs/reference/notifications/notification.proto @docker run -i --rm -u "$$(id -u):$$(id -g)" \ - -v "$$(pwd)/docs/reference/schemas:/out" \ + -v "$$(pwd)/docs/reference/policies:/out" \ -v "$$(pwd)/$(APISERVER_DIR)/proto/src/main/proto/org/dependencytrack/policy/v1:/protos" \ "$(PROTOC_GEN_DOC_IMAGE)" \ - --doc_opt=/out/policy.md.tmpl,policy.md + --doc_opt=/out/schema.md.tmpl,schema.md .PHONY: generate-proto-docs serve: diff --git a/docs/concepts/architecture/design/notifications.md b/docs/concepts/architecture/design/notifications.md index 6c9c9840..a2b7f27e 100644 --- a/docs/concepts/architecture/design/notifications.md +++ b/docs/concepts/architecture/design/notifications.md @@ -60,7 +60,7 @@ erDiagram The `ID` column uses [UUIDv7], which combines global uniqueness with sortability. The `PAYLOAD` column contains the serialized notification in [Protobuf] format. -The [notification schema reference](../../../reference/schemas/notification.md) describes the schema. +The [notification schema reference](../../../reference/notifications/schema.md) describes the schema. ### Preliminary filtering diff --git a/docs/concepts/changes-in-v5.md b/docs/concepts/changes-in-v5.md index b4483bb5..e1801d7c 100644 --- a/docs/concepts/changes-in-v5.md +++ b/docs/concepts/changes-in-v5.md @@ -150,7 +150,7 @@ remediation steps, lives in the [upgrade guides](../guides/upgrading/index.md). Headline items: * **Notification schema.** Subjects now use [Protobuf][Protobuf] (see the - [notification schema reference](../reference/schemas/notification.md)). + [notification schema reference](../reference/notifications/schema.md)). List fields gain a `List` suffix, enum-like values gain a type prefix (`INFORMATIONAL` → `LEVEL_INFORMATIONAL`, `SYSTEM` → `SCOPE_SYSTEM`, `NEW_VULNERABILITY` → `GROUP_NEW_VULNERABILITY`), and timestamps diff --git a/docs/concepts/notifications.md b/docs/concepts/notifications.md index 8113849e..24f59e8c 100644 --- a/docs/concepts/notifications.md +++ b/docs/concepts/notifications.md @@ -26,7 +26,7 @@ email to Webhook. Refer to [Publishers](../reference/notifications/publishers.md ## Templates Templates define how the platform's internal representation of notifications -(see [Notification schema](../reference/schemas/notification.md)) maps +(see [Notification schema](../reference/notifications/schema.md)) maps to the format that notification recipients expect. Each [publisher](#publishers) ships with a default template, and administrators diff --git a/docs/reference/.pages b/docs/reference/.pages index 0f731046..65922ffa 100644 --- a/docs/reference/.pages +++ b/docs/reference/.pages @@ -17,4 +17,3 @@ nav: - Badges: badges.md - File formats: file-formats.md - Community integrations: community-integrations.md - - Schemas: schemas diff --git a/docs/reference/notifications/.pages b/docs/reference/notifications/.pages index 81781fc9..9487bd78 100644 --- a/docs/reference/notifications/.pages +++ b/docs/reference/notifications/.pages @@ -3,3 +3,4 @@ nav: - Publishers: publishers.md - Templating: templating.md - Filter expressions: filter-expressions.md + - Proto schema: schema.md diff --git a/docs/reference/notifications/filter-expressions.md b/docs/reference/notifications/filter-expressions.md index 6023940c..0efa1ffb 100644 --- a/docs/reference/notifications/filter-expressions.md +++ b/docs/reference/notifications/filter-expressions.md @@ -30,9 +30,9 @@ The expression evaluation context 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). | +| `level` | [`Level`](schema.md#level) | The notification level, as an integer enum value. Use named constants (see below). | +| `scope` | [`Scope`](schema.md#scope) | The notification scope, as an integer enum value. Use named constants (see below). | +| `group` | [`Group`](schema.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 notification creation time. | @@ -41,7 +41,7 @@ The expression evaluation context contains the following variables: ### 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): +use the named constants from the [notification schema](schema.md#enums): ```js level == Level.LEVEL_INFORMATIONAL @@ -59,7 +59,7 @@ scope == Scope.SCOPE_PORTFOLIO The `subject` variable holds the notification's subject. Its type depends on the notification group; see [Subjects](groups.md#subjects) in the notification groups reference for the -group-to-subject mapping, and the [notification schema reference](../../reference/schemas/notification.md) +group-to-subject mapping, and the [notification schema reference](schema.md) for each subject's fields. ### Available functions diff --git a/docs/reference/notifications/groups.md b/docs/reference/notifications/groups.md index 0456d71d..e4f188df 100644 --- a/docs/reference/notifications/groups.md +++ b/docs/reference/notifications/groups.md @@ -7,7 +7,7 @@ trigger type: `Event` for ad-hoc notifications that the system emits in response to a system event, or `Schedule` for notifications that fire periodically on a cron schedule. -The [notification schema reference](../schemas/notification.md) describes the +The [notification schema reference](schema.md) describes the subject schema for each group. ## System scope @@ -176,19 +176,19 @@ Summarizes new policy violations found in a set of projects. ## Subjects The typed subject of a notification depends on its group. The -[notification schema reference](../schemas/notification.md) describes +[notification schema reference](schema.md) describes each subject schema. | Group | Subject type | |:--------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------| -| `BOM_CONSUMED`, `BOM_PROCESSED` | [BomConsumedOrProcessedSubject](../schemas/notification.md#bomconsumedorprocessedsubject) | -| `BOM_PROCESSING_FAILED` | [BomProcessingFailedSubject](../schemas/notification.md#bomprocessingfailedsubject) | -| `BOM_VALIDATION_FAILED` | [BomValidationFailedSubject](../schemas/notification.md#bomvalidationfailedsubject) | -| `NEW_VULNERABILITY` | [NewVulnerabilitySubject](../schemas/notification.md#newvulnerabilitysubject) | -| `NEW_VULNERABLE_DEPENDENCY` | [NewVulnerableDependencySubject](../schemas/notification.md#newvulnerabledependencysubject) | -| `POLICY_VIOLATION` | [PolicyViolationSubject](../schemas/notification.md#policyviolationsubject) | -| `PROJECT_AUDIT_CHANGE` | [VulnerabilityAnalysisDecisionChangeSubject](../schemas/notification.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](../schemas/notification.md#policyviolationanalysisdecisionchangesubject) | -| `VEX_CONSUMED`, `VEX_PROCESSED` | [VexConsumedOrProcessedSubject](../schemas/notification.md#vexconsumedorprocessedsubject) | -| `USER_CREATED`, `USER_DELETED` | [UserSubject](../schemas/notification.md#usersubject) | -| `NEW_VULNERABILITIES_SUMMARY` | [NewVulnerabilitiesSummarySubject](../schemas/notification.md#newvulnerabilitiessummarysubject) | -| `NEW_POLICY_VIOLATIONS_SUMMARY` | [NewPolicyViolationsSummarySubject](../schemas/notification.md#newpolicyviolationssummarysubject) | +| `BOM_CONSUMED`, `BOM_PROCESSED` | [BomConsumedOrProcessedSubject](schema.md#bomconsumedorprocessedsubject) | +| `BOM_PROCESSING_FAILED` | [BomProcessingFailedSubject](schema.md#bomprocessingfailedsubject) | +| `BOM_VALIDATION_FAILED` | [BomValidationFailedSubject](schema.md#bomvalidationfailedsubject) | +| `NEW_VULNERABILITY` | [NewVulnerabilitySubject](schema.md#newvulnerabilitysubject) | +| `NEW_VULNERABLE_DEPENDENCY` | [NewVulnerableDependencySubject](schema.md#newvulnerabledependencysubject) | +| `POLICY_VIOLATION` | [PolicyViolationSubject](schema.md#policyviolationsubject) | +| `PROJECT_AUDIT_CHANGE` | [VulnerabilityAnalysisDecisionChangeSubject](schema.md#vulnerabilityanalysisdecisionchangesubject) or [PolicyViolationAnalysisDecisionChangeSubject](schema.md#policyviolationanalysisdecisionchangesubject) | +| `VEX_CONSUMED`, `VEX_PROCESSED` | [VexConsumedOrProcessedSubject](schema.md#vexconsumedorprocessedsubject) | +| `USER_CREATED`, `USER_DELETED` | [UserSubject](schema.md#usersubject) | +| `NEW_VULNERABILITIES_SUMMARY` | [NewVulnerabilitiesSummarySubject](schema.md#newvulnerabilitiessummarysubject) | +| `NEW_POLICY_VIOLATIONS_SUMMARY` | [NewPolicyViolationsSummarySubject](schema.md#newpolicyviolationssummarysubject) | diff --git a/docs/reference/notifications/notification.proto b/docs/reference/notifications/notification.proto new file mode 100644 index 00000000..940a09fe --- /dev/null +++ b/docs/reference/notifications/notification.proto @@ -0,0 +1,360 @@ +syntax = "proto3"; + +package org.dependencytrack.notification.v1; + +import "google/protobuf/any.proto"; +import "google/protobuf/timestamp.proto"; + +option java_multiple_files = true; +option java_package = "org.dependencytrack.notification.proto.v1"; + +message Notification { + Level level = 1; + Scope scope = 2; + Group group = 3; + string title = 4; + string content = 5; + google.protobuf.Timestamp timestamp = 6; + google.protobuf.Any subject = 7; + + // Unique identifier of the notification in UUIDv7 format. + string id = 8; +} + +enum Level { + LEVEL_UNSPECIFIED = 0; + LEVEL_INFORMATIONAL = 1; + LEVEL_WARNING = 2; + LEVEL_ERROR = 3; +} + +enum Scope { + SCOPE_UNSPECIFIED = 0; + SCOPE_PORTFOLIO = 1; + SCOPE_SYSTEM = 2; +} + +enum Group { + GROUP_UNSPECIFIED = 0; + GROUP_CONFIGURATION = 1; + GROUP_DATASOURCE_MIRRORING = 2; + GROUP_REPOSITORY = 3; + GROUP_INTEGRATION = 4; + GROUP_FILE_SYSTEM = 6; + GROUP_ANALYZER = 7; + GROUP_NEW_VULNERABILITY = 8; + GROUP_NEW_VULNERABLE_DEPENDENCY = 9; + GROUP_PROJECT_AUDIT_CHANGE = 10; + GROUP_BOM_CONSUMED = 11; + GROUP_BOM_PROCESSED = 12; + GROUP_VEX_CONSUMED = 13; + GROUP_VEX_PROCESSED = 14; + GROUP_POLICY_VIOLATION = 15; + GROUP_PROJECT_CREATED = 16; + GROUP_BOM_PROCESSING_FAILED = 17; + GROUP_USER_CREATED = 19; + GROUP_USER_DELETED = 20; + GROUP_BOM_VALIDATION_FAILED = 21; + + // A previously identified vulnerability is no longer applicable, + // e.g. due to upstream sources correcting their data. + GROUP_VULNERABILITY_RETRACTED = 22; + + // Scheduled summary of new vulnerabilities across projects. + GROUP_NEW_VULNERABILITIES_SUMMARY = 23; + + // Scheduled summary of new policy violations across projects. + GROUP_NEW_POLICY_VIOLATIONS_SUMMARY = 24; + + // Indexing service has been removed as of + // https://github.com/DependencyTrack/hyades/issues/661 + reserved 5; + reserved "GROUP_INDEXING_SERVICE"; + + // PROJECT_VULN_ANALYSIS_COMPLETE notification removed. + reserved 18; + reserved "GROUP_PROJECT_VULN_ANALYSIS_COMPLETE"; +} + +message BackReference { + // URI to the API endpoint from which additional information can be fetched. + optional string api_uri = 1; + + // URI to the frontend where additional information can be seen. + optional string frontend_uri = 2; +} + +message BomConsumedOrProcessedSubject { + Project project = 1; + Bom bom = 2; + string token = 3; +} + +message BomProcessingFailedSubject { + Project project = 1; + Bom bom = 2; + string cause = 3; + string token = 4; +} + +message BomValidationFailedSubject { + Project project = 1; + Bom bom = 2; + repeated string errors = 3; +} + +message Bom { + string content = 1; + string format = 2; + string spec_version = 3; +} + +message NewVulnerabilitySubject { + Component component = 1; + Project project = 2; + Vulnerability vulnerability = 3; + BackReference affected_projects_reference = 4; + optional string vulnerability_analysis_level = 5 [deprecated = true]; + // 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. + repeated Project affected_projects = 6 [deprecated = true]; + + // The trigger of the analysis that identified the vulnerability. + AnalysisTrigger analysis_trigger = 7; +} + +message NewVulnerableDependencySubject { + Component component = 1; + Project project = 2; + repeated Vulnerability vulnerabilities = 3; +} + +message PolicyViolationSubject { + Component component = 1; + Project project = 2; + PolicyViolation policy_violation = 3; +} + +message VexConsumedOrProcessedSubject { + Project project = 1; + bytes vex = 2; + string format = 3; + string spec_version = 4; +} + +message VulnerabilityAnalysisDecisionChangeSubject { + Component component = 1; + Project project = 2; + Vulnerability vulnerability = 3; + VulnerabilityAnalysis analysis = 4; +} + +message PolicyViolationAnalysisDecisionChangeSubject { + Component component = 1; + Project project = 2; + PolicyViolation policy_violation = 3; + PolicyViolationAnalysis analysis = 4; +} + +message Component { + string uuid = 1; + optional string group = 2; + string name = 3; + string version = 4; + optional string purl = 5; + optional string md5 = 6; + optional string sha1 = 7; + optional string sha256 = 8; + optional string sha512 = 9; +} + +message Project { + string uuid = 1; + string name = 2; + optional string version = 3; + optional string description = 4; + optional string purl = 5; + repeated string tags = 6; + optional bool is_active = 7; +} + +message PolicyViolation { + string uuid = 1; + string type = 2; + google.protobuf.Timestamp timestamp = 3; + PolicyCondition condition = 4; +} + +message PolicyCondition { + string uuid = 1; + string subject = 2; + string operator = 3; + string value = 4; + Policy policy = 5; +} + +message Policy { + string uuid = 1; + string name = 2; + string violation_state = 3; +} + +message Vulnerability { + string uuid = 1; + string vuln_id = 2; + string source = 3; + repeated Alias aliases = 4; + optional string title = 5; + optional string sub_title = 6 [json_name = "subtitle"]; + optional string description = 7; + optional string recommendation = 8; + optional double cvss_v2 = 9 [json_name = "cvssv2"]; + optional double cvss_v3 = 10 [json_name = "cvssv3"]; + optional double owasp_rr_likelihood = 11 [json_name = "owaspRRLikelihood"]; + optional double owasp_rr_technical_impact = 12 [json_name = "owaspRRTechnicalImpact"]; + optional double owasp_rr_business_impact = 13 [json_name = "owaspRRBusinessImpact"]; + optional string severity = 14; + repeated Cwe cwes = 15; + optional string cvss_v2_vector = 16 [json_name = "cvssV2Vector"]; + optional string cvss_v3_vector = 17 [json_name = "cvssV3Vector"]; + optional string owasp_rr_vector = 18 [json_name = "owaspRRVector"]; + optional double cvss_v4 = 19 [json_name = "cvssv4"]; + optional string cvss_v4_vector = 20 [json_name = "cvssV4Vector"]; + + message Alias { + string id = 1 [json_name = "vulnId"]; + string source = 2; + } + + message Cwe { + int32 cwe_id = 1; + string name = 2; + } +} + +message UserSubject { + string username = 1; + optional string email = 2; +} + +message VulnerabilityAnalysis { + Component component = 1; + Project project = 2; + Vulnerability vulnerability = 3; + optional string state = 4; + optional bool suppressed = 5; +} + +message PolicyViolationAnalysis { + Component component = 1; + Project project = 2; + PolicyViolation policy_violation = 3; + optional string state = 4; + optional bool suppressed = 5; +} + +enum AnalysisTrigger { + // No trigger specified. + ANALYSIS_TRIGGER_UNSPECIFIED = 0; + + // The analysis was triggered by a BOM upload. + ANALYSIS_TRIGGER_BOM_UPLOAD = 1; + + // The analysis was triggered by a schedule. + ANALYSIS_TRIGGER_SCHEDULE = 2; + + // The analysis was triggered manually. + ANALYSIS_TRIGGER_MANUAL = 3; +} + +message VulnerabilityRetractedSubject { + // The component for which the vulnerability was previously reported. + Component component = 1; + + // The project for which the vulnerability was previously reported. + Project project = 2; + + // The previously reported vulnerability. + Vulnerability vulnerability = 3; +} + +// Subject for GROUP_NEW_VULNERABILITIES_SUMMARY notifications. +message NewVulnerabilitiesSummarySubject { + Overview overview = 1; + repeated ProjectSummaryEntry project_summaries = 2; + repeated ProjectFindingsEntry findings_by_project = 3; + google.protobuf.Timestamp since = 4; + + message Overview { + int32 affected_projects_count = 1; + int32 affected_components_count = 2; + int32 new_vulnerabilities_count = 3; + map new_vulnerabilities_count_by_severity = 4; + int32 suppressed_new_vulnerabilities_count = 5; + int32 total_new_vulnerabilities_count = 6; + } + + message ProjectSummaryEntry { + Project project = 1; + map new_vulnerabilities_count_by_severity = 2; + map suppressed_new_vulnerabilities_count_by_severity = 3; + map total_new_vulnerabilities_count_by_severity = 4; + } + + message ProjectFindingsEntry { + Project project = 1; + repeated Finding findings = 2; + } + + message Finding { + Component component = 1; + Vulnerability vulnerability = 2; + optional string analyzer_identity = 3; + google.protobuf.Timestamp attributed_on = 4; + optional string reference_url = 5; + optional string analysis_state = 6; + bool suppressed = 7; + } +} + +// Subject for GROUP_NEW_POLICY_VIOLATIONS_SUMMARY notifications. +message NewPolicyViolationsSummarySubject { + Overview overview = 1; + repeated ProjectSummaryEntry project_summaries = 2; + repeated ProjectViolationsEntry violations_by_project = 3; + google.protobuf.Timestamp since = 4; + + message Overview { + int32 affected_projects_count = 1; + int32 affected_components_count = 2; + int32 new_violations_count = 3; + map new_violations_count_by_type = 4; + int32 suppressed_new_violations_count = 5; + int32 total_new_violations_count = 6; + } + + message ProjectSummaryEntry { + Project project = 1; + map new_violations_count_by_type = 2; + map suppressed_new_violations_count_by_type = 3; + map total_new_violations_count_by_type = 4; + } + + message ProjectViolationsEntry { + Project project = 1; + repeated Violation violations = 2; + } + + message Violation { + string uuid = 1; + Component component = 2; + PolicyCondition policy_condition = 3; + string type = 4; + google.protobuf.Timestamp timestamp = 5; + optional string analysis_state = 6; + bool suppressed = 7; + } +} \ No newline at end of file diff --git a/docs/reference/notifications/publishers.md b/docs/reference/notifications/publishers.md index 2520f2bf..c412225b 100644 --- a/docs/reference/notifications/publishers.md +++ b/docs/reference/notifications/publishers.md @@ -108,6 +108,7 @@ The alert config defines the destination and format of Kafka records emitted by Publish notifications in Protobuf format whenever possible. Dependency-Track keeps changes to the Protobuf schema backward-compatible, which matters when a durable log like Kafka retains the notifications. + See the [Notification schema](schema.md) reference to download the `.proto` file and generate client code. !!! warning "Templating" The Kafka publisher ships without a default template, since it targets Protobuf. diff --git a/docs/reference/schemas/notification.md b/docs/reference/notifications/schema.md similarity index 98% rename from docs/reference/schemas/notification.md rename to docs/reference/notifications/schema.md index 6066d952..8cc6360c 100644 --- a/docs/reference/schemas/notification.md +++ b/docs/reference/notifications/schema.md @@ -1,3 +1,7 @@ +Dependency-Track represents notifications internally as Protobuf messages. Some publishers, such as [Kafka](publishers.md#kafka), can emit them directly in this format. Download the schema file below to [generate client code](https://protobuf.dev/getting-started/) in your language of choice. + +[Download notification.proto](notification.proto){ .md-button .md-button--primary download="notification.proto" } + diff --git a/docs/reference/schemas/notification.md.tmpl b/docs/reference/notifications/schema.md.tmpl similarity index 87% rename from docs/reference/schemas/notification.md.tmpl rename to docs/reference/notifications/schema.md.tmpl index 42e4ff5b..7ce0205d 100644 --- a/docs/reference/schemas/notification.md.tmpl +++ b/docs/reference/notifications/schema.md.tmpl @@ -1,3 +1,7 @@ +Dependency-Track represents notifications internally as Protobuf messages. Some publishers, such as [Kafka](publishers.md#kafka), can emit them directly in this format. Download the schema file below to [generate client code](https://protobuf.dev/getting-started/) in your language of choice. + +[Download notification.proto](notification.proto){ .md-button .md-button--primary download="notification.proto" } + {{ range .Files }} {{ range .Messages }} {{ if eq .LongName "Notification" }} diff --git a/docs/reference/notifications/templating.md b/docs/reference/notifications/templating.md index 9d53b48b..bb09435d 100644 --- a/docs/reference/notifications/templating.md +++ b/docs/reference/notifications/templating.md @@ -14,12 +14,12 @@ The following variables are available in every template. | `baseUrl` | string | Base URL of the Dependency-Track frontend, as configured by the operator. Empty string when unset. | | `timestampEpochSeconds` | long | Notification timestamp expressed as seconds since the Unix epoch. | | `timestamp` | string | Notification timestamp formatted as an [ISO 8601] local date-time (`uuuu-MM-dd'T'HH:mm:ss.SSSSSSSSS`). | -| `notification` | [`Notification`](../schemas/notification.md#notification) message | The full notification, with fields `level`, `scope`, `group`, `title`, `content`, `timestamp`, and `subject`. | +| `notification` | [`Notification`](schema.md#notification) message | The full notification, with fields `level`, `scope`, `group`, `title`, `content`, `timestamp`, and `subject`. | | `subject` | message | Typed subject of the notification, present only for groups that emit one. The concrete message type depends on the notification's `group`. | | `subjectJson` | string | JSON representation of `subject`, present only when the notification has a `subject`. | The shape of `subject` varies by notification group. Refer to the -[notification schema reference](../schemas/notification.md) for the +[notification schema reference](schema.md) for the message type emitted for each group. !!! note diff --git a/docs/reference/policies/.pages b/docs/reference/policies/.pages index bf2f7282..f47b8fdd 100644 --- a/docs/reference/policies/.pages +++ b/docs/reference/policies/.pages @@ -4,3 +4,4 @@ nav: - Component policies: component-policies.md - Vulnerability policies: vulnerability-policies.md - Condition expressions: condition-expressions.md + - Proto schema: schema.md diff --git a/docs/reference/policies/component-policies.md b/docs/reference/policies/component-policies.md index 24ab6891..fe9de70a 100644 --- a/docs/reference/policies/component-policies.md +++ b/docs/reference/policies/component-policies.md @@ -139,7 +139,7 @@ Matched against the severity of the component's vulnerabilities. - **Violation type:** Operational - **Operators:** `NUMERIC_*` -- **Value:** JSON [`VersionDistance`](../schemas/policy.md#versiondistance): +- **Value:** JSON [`VersionDistance`](schema.md#versiondistance): `{ "epoch": n, "major": n, "minor": n, "patch": n }`. ### `VULNERABILITY_ID` diff --git a/docs/reference/policies/condition-expressions.md b/docs/reference/policies/condition-expressions.md index 69ae7ec1..3e53302c 100644 --- a/docs/reference/policies/condition-expressions.md +++ b/docs/reference/policies/condition-expressions.md @@ -281,7 +281,7 @@ allow-lists, not as separate license and exception IDs. The license part uses ve ## Function reference -For type definitions, refer to the [schema reference](../schemas/policy.md). +For type definitions, refer to the [schema reference](schema.md). Beyond the [standard CEL library](../cel-expressions.md#standard-library), policy conditions have access to the following custom functions registered by Dependency-Track. @@ -579,13 +579,13 @@ component.version_distance(">=", v1.VersionDistance{major: 1}) ``` [CVSSv3]: https://www.first.org/cvss/v3.0/specification-document -[Component]: ../schemas/policy.md#component -[License]: ../schemas/policy.md#license +[Component]: schema.md#component +[License]: schema.md#license [Package URL]: https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst -[Project]: ../schemas/policy.md#project +[Project]: schema.md#project [RE2]: https://github.com/google/re2/wiki/Syntax [SPDX license expressions]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/ -[VersionDistance]: ../schemas/policy.md#versiondistance -[Vulnerability]: ../schemas/policy.md#vulnerability +[VersionDistance]: schema.md#versiondistance +[Vulnerability]: schema.md#vulnerability [protobuf-ts-docs]: https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp [vers]: https://github.com/package-url/vers-spec diff --git a/docs/reference/schemas/policy.md b/docs/reference/policies/schema.md similarity index 100% rename from docs/reference/schemas/policy.md rename to docs/reference/policies/schema.md diff --git a/docs/reference/schemas/policy.md.tmpl b/docs/reference/policies/schema.md.tmpl similarity index 100% rename from docs/reference/schemas/policy.md.tmpl rename to docs/reference/policies/schema.md.tmpl diff --git a/docs/reference/schemas/.pages b/docs/reference/schemas/.pages deleted file mode 100644 index 08287c77..00000000 --- a/docs/reference/schemas/.pages +++ /dev/null @@ -1,3 +0,0 @@ -nav: - - Notification schema: notification.md - - Policy schema: policy.md