Skip to main content
Glama
nh4ttruong

secobserve-mcp

by nh4ttruong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Generate SecObserve VEX Document

secobserve_vex_document

Generate CSAF, OpenVEX, or CycloneDX VEX documents from assessed vulnerability observations. Revise existing documents by passing the base ID to update version.

Instructions

Generate a CSAF, OpenVEX or CycloneDX VEX document from assessed observations, or revise one.

The document's content comes from the assessments already recorded: statuses like "Not affected" plus their VEX justification. Assess first, generate second. Passing document_base_id revises that document and bumps its version instead of creating a new one. The generated file is written to the server's export directory.

Args: format (str): "csaf", "openvex" or "cyclonedx". document_id_prefix (Optional[str]): Required to create, and to identify a document to update. document_base_id (Optional[str]): Present only when updating. product_id (Optional[int]) and/or vulnerability_names (Optional[List[str]]): the scope when creating; at least one is required. branch_ids (Optional[List[int]]): Restrict to these branches. fields (Optional[dict]): Format-specific metadata (CSAF: title, publisher_name, publisher_category, publisher_namespace, tracking_status, tlp_label; OpenVEX: id_namespace, author, role; CycloneDX: author, manufacturer). filename (Optional[str]): Base filename for the written document.

Returns: str: A line giving the absolute path and byte size of the document written to the export directory.

Examples: - Use when: "publish an OpenVEX for product 12" -> format="openvex", document_id_prefix="acme-vex", product_id=12, fields={"id_namespace": "https://acme.example", "author": "Acme Security"} - Use when: "a CSAF advisory for CVE-2024-3094 across our products" -> format="csaf", vulnerability_names=["CVE-2024-3094"], fields={...} - Use when: reissuing after new assessments -> pass document_base_id. - Don't use when: importing someone else's VEX (use secobserve_upload_file, kind="vex").

Error Handling: 400 names the missing format-specific field; read the exact set with secobserve_describe_resource on the matching vex_* resource. A document with no qualifying assessments is generated but empty of statements.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fieldsNoFormat-specific fields. CSAF create needs title, publisher_name, publisher_category, publisher_namespace, tracking_status, tlp_label; OpenVEX needs id_namespace and author; CycloneDX takes author and manufacturer. Read the exact set with secobserve_describe_resource on the matching vex_* resource, or from /api/oa3/swagger-ui.
formatYesVEX document format to generate.
filenameNoBase filename for the generated document. No directory separators.
branch_idsNoRestrict to these branches of the product.
product_idNoCover one product. Give product_id or vulnerability_names (or both) when creating.
document_base_idNoThe generated base id. Required only when updating an existing document.
document_id_prefixNoPrefix of the document id. Required when creating, and to identify the document when updating.
vulnerability_namesNoCover these vulnerabilities across products, e.g. ['CVE-2024-3094'].

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.3.0
    • removedInput schema / $defs
      Removed value: -{
-  "VexDocumentInput": {
-    "additionalProperties": false,
-    "description": "Input model for generating or revising a VEX document.",
-    "properties": {
-      "branch_ids": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "integer"
-            },
-            "maxItems": 20,
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Restrict to these branches of the product.",
-        "title": "Branch Ids"
-      },
-      "document_base_id": {
-        "anyOf": [
-          {
-            "maxLength": 200,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "The generated base id. Required only when updating an existing document.",
-        "title": "Document Base Id"
-      },
-      "document_id_prefix": {
-        "anyOf": [
-          {
-            "maxLength": 200,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Prefix of the document id. Required when creating, and to identify the document when updating.",
-        "title": "Document Id Prefix"
-      },
-      "fields": {
-        "anyOf": [
-          {
-            "additionalProperties": true,
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Format-specific fields. CSAF create needs title, publisher_name, publisher_category, publisher_namespace, tracking_status, tlp_label; OpenVEX needs id_namespace and author; CycloneDX takes author and manufacturer. Read the exact set with secobserve_describe_resource on the matching vex_* resource, or from /api/oa3/swagger-ui.",
-        "title": "Fields"
-      },
-      "filename": {
-        "anyOf": [
-          {
-            "maxLength": 120,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Base filename for the generated document. No directory separators.",
-        "title": "Filename"
-      },
-      "format": {
-        "description": "VEX document format to generate.",
-        "enum": [
-          "csaf",
-          "openvex",
-          "cyclonedx"
-        ],
-        "title": "Format",
-        "type": "string"
-      },
-      "product_id": {
-        "anyOf": [
-          {
-            "minimum": 1,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Cover one product. Give product_id or vulnerability_names (or both) when creating.",
-        "title": "Product Id"
-      },
-      "vulnerability_names": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "maxItems": 20,
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Cover these vulnerabilities across products, e.g. ['CVE-2024-3094'].",
-        "title": "Vulnerability Names"
-      }
-    },
-    "required": [
-      "format"
-    ],
-    "title": "VexDocumentInput",
-    "type": "object"
-  }
-}
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / branch_ids
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "maxItems": 20,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Restrict to these branches of the product.",
+  "title": "Branch Ids"
+}
    • addedInput schema / properties / document_base_id
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 200,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The generated base id. Required only when updating an existing document.",
+  "title": "Document Base Id"
+}
    • addedInput schema / properties / document_id_prefix
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 200,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Prefix of the document id. Required when creating, and to identify the document when updating.",
+  "title": "Document Id Prefix"
+}
    • addedInput schema / properties / fields
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Format-specific fields. CSAF create needs title, publisher_name, publisher_category, publisher_namespace, tracking_status, tlp_label; OpenVEX needs id_namespace and author; CycloneDX takes author and manufacturer. Read the exact set with secobserve_describe_resource on the matching vex_* resource, or from /api/oa3/swagger-ui.",
+  "title": "Fields"
+}
    • addedInput schema / properties / filename
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 120,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Base filename for the generated document. No directory separators.",
+  "title": "Filename"
+}
    • addedInput schema / properties / format
      Added value: +{
+  "description": "VEX document format to generate.",
+  "enum": [
+    "csaf",
+    "openvex",
+    "cyclonedx"
+  ],
+  "title": "Format",
+  "type": "string"
+}
    • removedInput schema / properties / params
      Removed value: -{
-  "$ref": "#/$defs/VexDocumentInput"
-}
    • addedInput schema / properties / product_id
      Added value: +{
+  "anyOf": [
+    {
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Cover one product. Give product_id or vulnerability_names (or both) when creating.",
+  "title": "Product Id"
+}
    • addedInput schema / properties / vulnerability_names
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 20,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Cover these vulnerabilities across products, e.g. ['CVE-2024-3094'].",
+  "title": "Vulnerability Names"
+}
    • changedInput schema / required
      Previous value: -[
-  "params"
-]New value: +[
+  "format"
+]
  2. First observedv0.1.2

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses that the file is written to the server's export directory, that passing document_base_id bumps the version, and that a document with no qualifying assessments is still generated but empty. It also describes 400 error behavior, which helps an agent recover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer, but the tool has eight parameters and three formats; it is organized into summary, Args, Examples, and Error Handling. Each section carries necessary information and the primary purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, file-writing tool with 8 parameters and multiple formats, it covers input constraints, update semantics, output (absolute path and byte size), empty-document behavior, and error remediation. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description still adds workflow meaning: document_id_prefix is required to create and identify updates, document_base_id is only for updates, and at least one of product_id/vulnerability_names is needed. It also enumerates the exact format-specific fields, going slightly beyond the schema's generic field description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific verbs ('generate or revise') and exact resource ('CSAF, OpenVEX or CycloneDX VEX document') and explains the data source (already-recorded assessments). It distinguishes this generation tool from the sibling import path, so an agent can identify it without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the workflow dependency ('Assess first, generate second') and gives concrete use-when examples for creation and reissuing. It explicitly says not to use it for importing someone else's VEX and names the alternative (secobserve_upload_file, kind='vex').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools