Item Definition

Item Definition is a canvas for laying out the assets in scope for a threat model, wiring up how they interact, and seeing VSEC’s confidence in each asset at a glance — a definition can scope a feature and its components, a single component, or a whole vehicle.

Open it from the sidebar under Tools → Design → Item Definition.

Item Definitions List

The landing page lists your existing item definitions as cards. Each card is titled after its item — the asset the definition is about — and shows a component-count chip (e.g. “3 components”) and when it was last updated. Click a card to open its canvas.

Use the Crosshair button above the list to scope it to one or more assets: the button reads All assets when nothing is selected, the asset’s name when one is selected, or “N assets” beyond that, with a filter chip showing the active scope. Scoped, the list shows only the item definitions those assets take part in. This is the same asset-scope control Risk Manager uses.

Creating an Item Definition

Click New item definition to open a dialog headed What are you analyzing? Pick the item the definition is about — either an Existing asset or a New asset (name it and choose a type; this creates a real asset in Asset Manager). An item must be chosen before Create is enabled. The asset you pick becomes the item boundary: its components go inside, everything else is the operational environment.

An optional Label sits under More options. A definition is named after its item, so a label is only needed to tell two definitions of the same item apart (e.g. “Concept phase”, “MY26”). What the item does isn’t asked here — it’s the definition’s own Item Function, written by generating from documents or by editing it directly. Click Create to open the new canvas with your item as its boundary.

On the definition’s own page, the title shows the item as a clickable chip, and the page header carries Edit item definition, Generate canvas from documents, Add asset to canvas, Import existing TARA, and Run TARA buttons (the last reads Re-run TARA once a run exists). The Edit item definition dialog changes the item or label at any time.

Deleting an item definition (via the trash icon on its card) only removes that canvas layout — the assets and the relations drawn between them stay in Asset Manager untouched.

Item Function and Assumptions

Below the title, the definition’s page carries the two texts ISO/SAE 21434 §9.3 asks for about the item itself:

• Item Function — what the item does, “the vehicle functionality that is realized by the item” (ISO/SAE 21434 §9.3 [RQ-09-01] b). This is the definition’s own field: what the item does for this scope, so a component-level definition and a feature-level definition of the same asset can describe different behaviour. Click Describe (or Edit once it’s set) to write it yourself — two to four functional sentences — or let a document generation write the first draft, which you can then edit. Until it’s described, the panel reads Not described yet — generate the item definition from documents, or write it yourself., and the item’s readiness shows the reason “Describe what the item does — the vehicle function it implements”.
• Assumptions — what the analysis takes for granted (ISO/SAE 21434 §9.3 [RQ-09-02]). Click Add assumption to record a free-text assumption; each can stand alone or be about a specific member asset (shown with that asset’s name in bold). Remove one with the ✕ next to it. When there are none, the panel reads None recorded. Assumptions never hold back readiness. An operational-environment node’s readiness panel also nudges you when nothing is recorded about it (No assumptions recorded), with a Record assumption box that files the assumption against that node.

The Canvas

The canvas is a node-and-wire diagram built on a drag-and-drop graph editor. Each node is an asset; each wire is a relation between two assets (see Wires below).

Adding Assets

Click Add asset to canvas in the page header (or Add components on the canvas when the item has none yet) to open the Add assets to the item definition dialog, which has three tabs:

• Existing assets — multi-select assets already in Asset Manager (grouped by type; archived assets and assets already on the canvas are excluded).
• New asset — give it a name and pick a type. This creates a real asset in Asset Manager, not a canvas-only placeholder.
• Generate from documents — have VSEC draw the item definition from your own documents (see Generating from Documents below). Only shown when an intelligence provider is configured for the workspace.

Everything added lands inside the item, as one of its components. To treat something as operational environment instead, drag its node outside the perimeter or use the node’s right-click menu (see Item Boundary) — the canvas is the boundary, so placement is something you do on it, not a question the dialog asks.

Generating from Documents

Open the Generate from documents tab, or click Generate canvas from documents in the page header (also offered from an empty canvas):

Upload the documents you already have — Excel TARAs, system-of-interest docs, architecture PDFs — and VSEC draws the item definition from them. You review every type, asset, and relation before anything lands.

Click Choose documents to attach one or more files, then fill in a Root asset name (the top of the item definition, e.g. the vehicle or system), a Root asset type, and optional Guidance to steer the read (e.g. “Focus on the ECUs on the backup-alarm CAN bus; ignore the wiring appendix.”). Click Generate.

VSEC reads the documents in the background — a toast confirms you’ll get a notification when it’s ready, and the header button shows Generating… (disabled) until then. Only one generation can be in flight per item definition at a time. When it’s ready, VSEC sends a notification titled “Item definition ready to review” and the header button switches to Review generation. Opening the item definition also surfaces a finished review automatically, even if you don’t click the notification.

The review is a dialog with up to four steps — New types, Assets, Relations, and Subassets (New types only appears if the documents describe something that doesn’t map onto any of your existing asset types; Subassets only appears when the documents surfaced any, and only when reviewing on an item-definition canvas):

• New types — each candidate type defaults to off, with its assets mapped onto an existing type of your choosing instead; switch it on to create the type for real and pick an existing type to nest it under.
• Assets — every asset the documents named, each with an Include toggle and an editable name. An asset that fuzzily matches one you already have is flagged as reusing that existing asset (with an override to create a new one instead), so applying updates it rather than creating a duplicate.
• Relations — the connections the documents describe, each with the document’s own explanation (editable), an Include toggle, and a protocol label; a relation that would cross the item boundary is flagged External interface.
• Subassets — what the documents suggest an attacker could go after, each anchored to an asset or to a relation between two assets, shown with its C/I/A chips, an editable What could be attacked? name, and an Include toggle (see Subassets).

The first step opens with a one-line summary of what the proposal contains (assets, relations, subassets, new types), plus an Item function chip — the drafted function statement, editable right here — and, when the documents reach beyond the item in scope, an amber Check scope warning (hover to read it) telling you to toggle off anything out of scope on the Assets step.

Click Apply to canvas to create or update the included assets, place them on the canvas, draw the included relations, and record the included subassets — nothing is created before this point. Discard abandons the proposal without creating anything; the uploaded documents themselves stay attached to the item definition either way.

Node Right-Click Menu

Right-clicking a node opens a menu with:

• Add context — jot down what you know about the asset without leaving the canvas (see Context and Open Questions)
• Request context — ask the person who knows (see below)
• Open asset — jump to the asset’s detail page
• Add subasset (“The data, code, or secrets it holds”) — identify what an attacker could go after on this asset (see Subassets)
• Move inside the item / Move outside the item — move the node across the item boundary, between being a component of the item and being operational environment it interfaces with. Only shown when the canvas has an item boundary.
• Make this the item — make this asset the item, so the rest of the canvas becomes its components. Only shown for a node that isn’t already the item.
• Remove from canvas — removes the node from this diagram only; the asset and its relations are untouched elsewhere

Moving and Removing Nodes

Drag a node to reposition it; the new position saves automatically. Archived assets still appear on the canvas, rendered dimmed rather than hidden.

Wires

Draw a wire by dragging from one node to another. A Connect assets dialog asks how the two assets connect: a Protocol (choose from common automotive buses — CAN, Ethernet, LIN, and so on — or type your own, or leave it blank if unknown), which the canvas colors and can filter by, and the Signals the connection carries — one row per signal or message, each with a name (e.g. “Status”) and an optional description. Click Add signal for another row, then Connect.

A wire is not canvas decoration — it creates a relation between the two assets that is shared, global data: the same relation shows up as a Related Assets entry on both assets’ detail pages (see Asset Details → Related Assets), and on any other item-definition canvas that includes both assets. If the two assets are already related, VSEC shows an error instead of creating a duplicate.

Click an existing wire to edit its protocol and signals (Edit connection) or Delete connection. Deleting asks for confirmation, since it removes the relation everywhere in VSEC, not just from the current diagram. Right-clicking a relation instead opens a menu with Edit connection (“Protocol and the signals it carries”) and Add subasset (see Subassets).

Subassets

Beyond laying out assets and how they relate, you can break each one down into its subassets — what an attacker could go after — the ISO/SAE 21434 §15.3 asset-identification step. A subasset is a named thing (for example Firmware, stored keys, or a Lamp request signal) together with which of Confidentiality, Integrity, and Availability must be protected about it. (VSEC’s API and ISO/SAE 21434 call these cybersecurity properties; on the canvas they’re called subassets, since the thing an attacker is after sits inside an asset.)

These subassets are scoped to the item definition: the same asset can carry different subassets in different item definitions, and identifying them here never changes the asset itself in Asset Manager — the C/I/A verdict lives on the item definition, not on the asset.

Adding a subasset

Right-click a node and choose Add subasset (“The data, code, or secrets it holds”), or right-click a relation and choose Add subasset (“What must be protected on this connection”). Either opens the Subassets dialog for that asset or relation.

Under What could be attacked?, name the subasset, add optional Notes, then tick What must be protected about it?:

• Confidentiality — must stay private; an attacker must not be able to read it.
• Integrity — must stay correct; an attacker must not be able to change it.
• Availability — must stay working; an attacker must not be able to take it down.

Click Add to record it. The dialog lists everything already identified on that asset or relation, each editable or removable, and Done closes it. A subasset attaches to exactly one thing — a single asset or a single relation — and is removed automatically if that asset or relation is removed from the canvas.

On the canvas

An asset that carries subassets shows a chip per subasset, labelled with the subasset name and its protected letters joined by a dot (for example Firmware C·I). A relation that carries subassets appends them to its label after a 🔐, with the letters in parentheses (for example 🔐 Lamp request (I,A)). Hovering a chip spells out what must stay private, correct, or working.

Tables Below the Canvas

The canvas stays deliberately uncluttered, so the scannable, shareable views of everything on it live underneath it as two tabs — each with a count, shown once the canvas has assets:

• Subassets (the default tab) — every subasset in the definition in one place: the subasset name, what it sits On (the asset or the connection), what it Must protect (its C/I/A), and any Notes. This is the “what is an attacker after?” scan the canvas chips can’t give you all at once.
• Connections — every connection as a row: From, To, Protocol, and the Signals it carries (each signal’s name, with its description after a dash).

Clicking a row on either tab opens the same dialog the canvas does for that item — the Subassets dialog for a subasset’s anchor, or Edit connection for a connection.

Readiness (Confidence)

Every node shows a colored dot — VSEC’s deterministic assessment of how well it understands that asset, recomputed live as context changes:

While an analysis is running, the dot is replaced by a spinner. Click a node to open the readiness panel, which shows:

• Why this color — the specific reasons behind the current state (e.g. “Context added since the last analysis”, “2 open questions block confidence”)
• VSEC still needs to know — the open questions VSEC has generated for this asset, each tagged Blocking, Advisory, or Nice to have. Only Blocking (high-confidence) questions prevent the asset from reaching green. Click the dismiss icon next to a question to mark it answered or not applicable — dismissed questions no longer hold back confidence, and the dismissal is remembered across future re-analysis.
• Add context, Request context from someone, and Open asset buttons — the same actions available from the node’s right-click menu.

If no intelligence provider is configured for the workspace, the canvas shows a banner explaining that VSEC can’t analyze assets or generate open questions until one is set up under Integrations.

Item Boundary

The item you chose when creating the definition is its boundary. VSEC renders that asset as an item boundary (ISO/SAE 21434 §9.3) instead of drawing it as its own node — a labeled perimeter box enclosing its components:

• The item’s components render inside the perimeter.
• Everything else on the canvas renders outside it, as the item’s operational environment.
• A wire with one endpoint inside and one outside crosses the perimeter, drawn dashed to set it apart — VSEC treats it as an external interface, the attack surface ISO 21434 cares about (the External interface label itself appears when reviewing a document generation’s Relations step; on the canvas the crossing is shown only by the dashed styling).

The perimeter is a resizable frame: drag its handles to say where the item boundary runs. Until you resize it, VSEC keeps it fitted around the components inside; once you drag it, the frame stays where you put it and VSEC stops auto-fitting it. A node whose center sits inside the frame counts as a component; one whose center sits outside is operational environment — so resizing the frame can pull assets in or push them out, and VSEC tells you how many moved.

The perimeter’s colored dot reflects the item’s overall readiness rather than just the item asset’s own:

• 🔴 Red — nothing inside the item has context yet.
• 🟡 Yellow — the item has no components inside it yet, some assets still need context, or the external interfaces haven’t been identified yet (no wire crosses the perimeter, and the item’s own connections aren’t confirmed).
• 🟢 Green — the boundary and every inside component are green, and the external interfaces are identified.

Item definitions created before this behavior existed may have no item set. For those, VSEC falls back to inferring the boundary: if the canvas has exactly one asset of type Feature with other assets linked beneath it (as parent/child Links in Asset Manager), that Feature becomes the boundary; a canvas with zero or more than one Feature member — or a Feature with nothing linked beneath it — renders flat, with every node showing only its own per-asset readiness. You can give such a definition an item at any time from Edit.

Context and Open Questions

Add context opens a text box to jot down anything you know about the asset — what it does, what it talks to, what data it handles, how it updates. It feeds the same AI curation pipeline as the asset’s own Context tab, and VSEC re-analyzes automatically afterward.

Request context sends an email with a secure, one-time link to someone outside the workspace — no VSEC account required. If VSEC has already generated open questions for the asset, the message is pre-filled with them (editable); otherwise, a Generate questions button lets you trigger an analysis first. The recipient’s answer lands on the asset automatically and VSEC re-analyzes on its own.

From item definition to TARA

Once the item is defined, a Damage scenarios panel below the canvas lets you agree the impact half of the analysis (ISO/SAE 21434 §15.4) before running it, and the header’s Run TARA button generates the threat model. Both are covered under Threat Modeling.

Permissions

Item Definition uses the same underlying asset permissions as Asset Manager — creating or editing a canvas, adding/removing nodes, drawing or deleting wires, and adding or editing subassets all require the same permission as creating or updating assets. The Item Definition sidebar entry sits under Design, so it’s also subject to the Design permission block being enabled for your workspace.