devguard

Vendors

Add the suppliers you depend on, rate them, record the approval decision and where they process data, and see which supplier needs attention next.

The Vendors module keeps one record per supplier. The record shows who owns the relationship and how risky the supplier is, before and after your measures. It also shows whether the supplier was approved and by whom, where it processes data, and which controls it carries for you. The overview tells you when an assessment falls due or a contract runs out. When an auditor asks how you manage a supplier, show that supplier's page. The approved-supplier list is one filtered export.

These are the tasks, in the order the work usually runs:

  1. Add a vendor, or import a list.
  2. Rate its risk before and after treatment.
  3. Record the approval decision, and export the approved-supplier list for the auditor.
  4. Record where it processes data and file its documents.
  5. Set the shared responsibility for the controls it carries.
  6. Assess it, on a schedule or by sending a questionnaire the supplier answers over a link.
  7. Review the register periodically, and read the overview to see what is open.

Integrators go straight to the API.

An assessment looks at one supplier at a time. A review goes through the whole register in one campaign and records every decision. Auditors usually ask for both. Questionnaire templates and the risk matrix have their own pages.

What Needs Doing on the overview: Slack is blocked but still active and its assessment is overdue, Datadog has no approval decision, Mailgun's contract is expiring, and each row names the vendor, its owner and its level.
Each row is one open finding. Select a row to open the vendor.

Add a vendor

  1. Open Vendors and choose Add vendor.
  2. Enter the Name. devguard makes the vendor's slug from it. The slug is the identifier in the app's address; API paths use the vendor's id instead.
  3. Choose the Owner, the business role responsible for the relationship.
  4. Set the Category (what the supplier provides), the Relationship (its data-protection role: processor, sub-processor, controller or other) and the Status (Active, unless you are recording a past relationship).
  5. Fill in what you know of the optional sections: Contact, Approval, Privacy, Lifecycle, Assessment and Relations. You can complete each one later with Edit on the vendor's page.
  6. Save. devguard gives the vendor an ID such as V-008 and opens its page.
The five required fields, each marked with an asterisk, filled in for Hetzner Online: name, owner, category, relationship and status.
Five fields are required. Everything else can wait.

Import vendors from a spreadsheet

  1. On the vendor list, open the toolbar menu and download the template. Its columns are the vendor's fields under their API names. Only organizationId is left out.
  2. Fill one row per vendor. Reference columns take names, not ids: ownerId takes the role's name, locationId the location's name, labels the label names. Choice columns take the label from the form (Cloud) or the value (CLOUD). Dates take 31.12.2027 or 2027-12-31. Separate list items with ; or ,. You may leave slug empty; devguard makes it from the name.
  3. Choose Import and pick the file. Each row becomes one vendor. The result dialog counts the imported rows. For each refused value it names the row and the field, for example a role name that was not found or that matches more than one role.
vendors.csv
name,ownerId,category,relationship,contractExpiry
Hetzner Online,Head of IT,Cloud,Processor,31.12.2027
Bexio,Head of Finance,SaaS,Processor,30.06.2027

Rate a vendor's risk

  1. Open the vendor, choose Edit and go to Assessment.
  2. Set Inherent probability and Inherent impact: the exposure with no treatment, on the scales of your risk settings.
  3. Choose a Treatment strategy (mitigate, accept, avoid or transfer). Link the Treatment actions that reduce the exposure. They are the same records your risks use.
  4. Set Residual probability and Residual impact: the exposure once every linked action is implemented. Neither may be higher than its inherent value, or the form refuses the save.

The vendor's page then shows three ratings in its Risk Assessment card. The third one, the current rating, is explained below.

The Risk Assessment card: current risk 8, Medium, with treatment progress 1 of 2, inherent 15 and residual 3.
One of two treatment actions is implemented, so the current rating sits halfway between inherent and residual.

Record the approval decision

  1. Open the vendor, choose Edit and go to Approval.
  2. Choose the Approval status: Approved, Approved with conditions or Blocked. For a conditional or blocked decision, write the conditions or the reason in the Approval note. The save is refused without one.
  3. Save. The decision appears as a chip in the vendor's header. Hover over it to see who decided, when, and the note.

Approval is a recorded decision, not a gate: nothing stops a blocked vendor from being used. The overview lists two cases so that they are seen: a blocked vendor that is still active, and an active vendor with no decision.

Export the approved-supplier list

  1. On the vendor list, add the Approval status filter and select Approved.
  2. Open the menu at the end of the toolbar and export the filtered list.

The file is named approved-suppliers. It has one row per vendor: name, category, status, approval status, approval note, who decided and when. Any other approval filter gives the same columns in a file named vendor-approvals. Export all ignores the filters and writes the plain vendors list.

An auditor usually asks for three more files:

Record where data is processed

  1. Open the vendor, choose Edit and go to Privacy.
  2. Add every country in Countries where data is processed, including those of the vendor's own sub-processors.
  3. Choose the Transfer mechanism that covers transfers to countries without an adequacy decision: adequacy decision, standard contractual clauses, binding corporate rules, derogation, other appropriate safeguards, or not applicable (no transfer).
  4. If the vendor's SOC report mentions subservice organizations, set the Subservice organization method (SOC reports) to Carve-out or Inclusive.

The Federal Council decides adequacy for the Swiss FADP, and the EU Commission for the GDPR. Check each country against the list that applies to you. devguard does not judge adequacy, but it shows the gap in two places:

  • The header shows Countries set, no transfer mechanism when a country other than Switzerland is set without a mechanism (or with Not applicable).
  • The overview lists a processor or sub-processor with countries and no mechanism under Transfer safeguard missing.

File a vendor's documents

  1. Open the vendor's Evidence tab and choose Upload Evidence.
  2. Pick the Type: SOC 2, ISO 27001, Penetration Test, DPA, AOC, Business associate agreement (HIPAA) or Other.
  3. Enter a Title, the Issued at date and the Valid until date. For a SOC report, use the end of the reporting period.
  4. Add the file (up to 200 MB) and choose Upload.

Each document is an evidence record linked to the vendor. It starts without an owner or approver. Each row on the tab shows whether the document is valid and for how many more days. The DPA chip in the vendor's header reads DPA in place, DPA missing or DPA expired, based on the DPA documents on file.

A document with a Valid until date appears on Deadlines once that date is less than 90 days away. It stays there after it lapses. A newer document of the same type for the same vendor clears it; a document of type Other never clears another. Documents of inactive, offboarded or archived vendors raise no deadline. An expiring document also brings the vendor's next automatic reassessment forward.

Set the shared responsibility for a control

A SOC report states what the vendor does. The Shared Responsibility tab states what is left to you, control by control. In an audit, the two can be read side by side.

  1. Link the control to the vendor: edit the vendor and add it under Relations → Controls, or open the control and use Link a vendor on its Links tab.
  2. On the vendor's Shared Responsibility tab, choose for each control who is responsible: Vendor, Shared or Our organization.
  3. For a shared control, describe your part in What our organization does for this control. A shared row without a note is flagged Shared, but no note on what we do.
  4. Choose Export CSV to hand the table to an auditor.
Stripe's controls: A.5.19 is Shared, with the organization's part written in the right-hand column; A.8.24 is carried by the vendor, so its note stays empty.
Shared rows need a note on what your organization does.

The line under the tab heading names the subservice organization method. It also lists the SOC reports and attestations on file with their Valid until dates. On the control's Links tab, each linked vendor shows its responsibility as a badge. The CSV has one row per control with its identifier, name, responsibility and note. Every row repeats the vendor, the method, the source documents and the export date.

Review the register

A vendor review takes the whole register through one campaign. Each vendor in scope is approved or rejected. A rejection raises a finding in the findings register. Vendor reviews explains the whole campaign.

Datadog has no approval decision, so the reviewer rejects it. The rejection becomes finding OBS-007.
Review VAR-005 after the rejection: the banner lists findings OBS-006 for Slack and OBS-007 for Datadog, and Datadog's item shows Rejected with its reason.
The new finding is listed at the top of the review, next to the one raised earlier.

Read the overview

Vendors → Overview answers one question: what does the register need next? It covers every vendor that is neither archived nor offboarded.

Vendor Posture and Vendor Lifecycle: the levels as a bar, the three tiles, and one bar per step of the work with its count.
The tiles count what needs attention. The bars show how far the register has come on each step.

Vendor Posture counts the vendors and shows their current levels as a bar, with tiles for vendors that are Not acceptable, Not rated, and Contracts expiring within 60 days.

Vendor Lifecycle shows how far the register has come on each step of the work:

  • Vendors rated.
  • Treatment decided, counted among vendors whose inherent level is not acceptable.
  • Approval decided: approved or approved with conditions.
  • Assessed: at least one completed assessment.
  • Assessment up to date: the latest completed assessment is not past its next review.
  • Reviewed within the interval: approved in a vendor review within the review interval of your risk settings.

What Needs Doing lists the open findings, grouped by kind in the order below. Within a kind, the highest level comes first. Each row opens the vendor.

FindingThe condition behind it
Not yet ratedNo likelihood and impact rating.
Not acceptable, no treatment decidedThe current level is not acceptable and no treatment strategy is set.
Blocked but still activeThe approval is Blocked while the status is Active.
No approval decisionThe vendor is active and has no approval status.
Never assessedNo completed assessment.
Assessment overdueThe newest completed assessment is past its next review date.
Contract expiringThe contract ends within 60 days, or already has.
Transfer safeguard missingA processor or sub-processor has countries set and no transfer mechanism.
Review dueNot approved in a vendor review within the review interval, and older than that interval.

How devguard computes a vendor's state

How the current rating moves

A vendor carries two ratings you set, inherent and residual, and one that devguard computes. The current rating starts at inherent. It moves toward residual by the share of linked treatment actions marked Implemented:

  • none implemented: current equals inherent;
  • all implemented: current equals residual;
  • no treatment actions: current stays at inherent.

The list, the overview and the matrix show the current rating. Its level (by default low, medium, high or critical) comes from the matrix in your risk settings. So does the answer to whether that level is acceptable.

How the approval decision is kept

The decision is credited to the member who saves it, also when the change comes through a personal API key. The stamp (who and when) changes only when the status changes. If you edit the note under an existing decision, the original decider and date stay, and the vendor's History tab records the edit. Setting the status back to not evaluated clears the stamp.

Status, archiving and deletion

The Status describes the relationship. Active means in use. Inactive means paused or lapsed. Offboarded means ended and kept for the history. Offboarded vendors leave the overview, and their documents raise no deadlines. The daily reassessment check looks at every vendor whose status is Active. When you stop using a vendor, set it to Inactive or Offboarded; archiving alone is not enough.

Archiving, from the row menu on the list, is separate from the status. An archived vendor leaves the list, the overview, the matrix and new reviews. The Archived toggle on the list shows archived vendors. Restore brings one back, unless the organization is at its plan limit for vendors. An archived vendor keeps its slug, so a new vendor with that slug is refused. Delete removes the vendor with its assessments and links.

Where vendors appear elsewhere

  • Controls linked under Relations count toward control coverage and, with risks and assets, appear under Related Data on the vendor's page.
  • Risks are linked through the API's riskLinks field; the form does not offer them.
  • Incidents link to vendors from the incident's side.
  • A process set to This process is about: A vendor shows its submissions under Process Runs once an admin picks the vendor with Pick a vendor.
  • Tasks on the vendor's Tasks tab also appear in Tasks and, with a deadline, on the Roadmap.
  • Documents on the vendor's Evidence tab are evidence records linked to the vendor.
  • The Trust Center lists vendors you choose under Subprocessors. It shows a vendor's description only when you turn on Show description.

Reference

Vendor fields

FieldValues and notes
NameRequired.
SlugUnique per organization. Derived from the name in the app; required when creating through the API.
OwnerRequired. A business role.
CategoryCloud, SaaS, Infrastructure, Processor, Hardware, Professional services, Other. Default Other.
RelationshipProcessor, Sub-processor, Controller, Other. Default Processor.
StatusActive, Inactive, Offboarded. Default Active.
DescriptionFree text.
LabelsAny number, from Collections → Labels. Shared with risks and assets.
WebsiteAn address starting with https://. If you enter only the domain, such as acme.com, devguard adds https://.
Contact name, Contact emailFree text.
LocationA location from Collections.
Approval statusNot evaluated, Approved, Approved with conditions, Blocked.
Approval noteUp to 2000 characters. Required for a conditional or blocked status.
Countries where data is processedISO 3166-1 alpha-2 codes, up to 300.
Transfer mechanismAdequacy decision, Standard contractual clauses, Binding corporate rules, Derogation, Other appropriate safeguards, Not applicable (no transfer).
Subservice organization methodCarve-out, Inclusive.
Contract expiryA date.
Reassessment frequencyA schedule from Collections → Schedules.
Inherent and residual probability and impactPositions on the scales of your risk settings. Residual never above inherent.
Treatment strategyUnknown, Mitigate, Accept, Avoid, Transfer.
Treatment actions, Controls, AssetsAny number of links.

Derived values

ValueHow it is computed
Level and tierThe level of the current rating in the risk matrix; the tier (high, medium, low) is derived from the level for filters and reports.
Assessment statusRead from the vendor's latest assessment (the overview's findings read the newest completed one instead, so the two differ while an assessment is reopened). Never assessed with no completed assessment; In progress when the latest assessment was reopened to draft; Assessed when its next review date lies ahead or is unset; Overdue when it has passed.

The vendor list

The list searches by name or ID. It filters by Owner, Category, Status, Relationship, Approval status, Current risk (the tier), Current level, Labels, Overdue, Contract expiry and Last updated. Overdue means the latest completed assessment is past its next review date. Select rows for a bulk delete or a selection export. The toolbar menu offers Import, the CSV template, and Export all or an export of the filtered list.

Reports

  • Vendors, under Reports: the register, or one risk tier of it, as a PDF. It lists each vendor's inherent, residual and current ratings and its assessment status. The report on the whole register also counts the overdue reassessments. Its address is /reports/vendors/?report=<tier>-vendors, where the tier is all, high, medium or low.
  • Vendor Reviews: the record of one review, also from Generate Report on the review.

Permissions

Owners and admins manage vendors; members and auditors read them. A personal API key acts with its owner's role. An organization token acts as the service role, which manages vendors like an admin. An approval saved through a personal key is credited to the key's owner. Vendors, assessments and reviews count against the organization's plan. The list shows a banner when the limit is near, and the API names the error at the limit.

API

The API reference lists every endpoint. This section adds what it cannot say. There is no CLI command for vendors. Scripts call https://app.devguard.ch/api with Authorization: Bearer <key>. The key is a personal API key (dvg_…) or an organization token (dvgo_…). A create or restore at the plan limit answers 403 with the message LIMIT_REACHED:vendors (or vendorAssessments, vendorReviews). That message tells it apart from a permission 403.

  • GET /vendors/ and POST /vendors/; GET, PATCH and DELETE /vendors/{id}/. A GET by id returns the vendor with its owner, links and latest assessment.
  • POST /vendors/{id}/archive/ and POST /vendors/{id}/restore/.
  • GET /vendors/overview/?organizationId=...: the overview as data, over every vendor that is neither archived nor offboarded.

A create requires slug, name, ownerId and organizationId, with links as arrays of ids. Role ids for ownerId come from GET /business-roles/. Ratings are 1-based positions on the scales of the organization's risk criteria. A value outside the scale is refused; without ratings, the vendor is unrated. Processing countries are stored as upper-case ISO 3166-1 alpha-2 codes.

curl -X POST "https://app.devguard.ch/api/vendors/" \
  -H "Authorization: Bearer dvg_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "<organization-id>",
    "name": "Hetzner Online", "slug": "hetzner-online",
    "ownerId": "<role-id>", "category": "CLOUD"}'

A PATCH must carry the slug, name, owner and all four ratings. null clears a rating, so send the stored values (from GET /vendors/{id}/) of any rating you do not mean to change. Other fields you leave out are kept. A link array, when sent, replaces those links. This example sets the status to Inactive and repeats every other required value:

curl -X PATCH "https://app.devguard.ch/api/vendors/<vendor-id>/" \
  -H "Authorization: Bearer dvg_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"slug": "hetzner-online", "name": "Hetzner Online",
    "ownerId": "<role-id>", "status": "INACTIVE",
    "inherentProbability": 3, "inherentImpact": 4,
    "residualProbability": 2, "residualImpact": 3}'

GET /vendors/ takes these query parameters, among others:

  • organizationId, page, and limit (5 to 100, default 100; outside that range 400);
  • filterByName: a name or an ID such as V-008;
  • filters: the list filters, as JSON;
  • sort: as JSON, for example [{"id":"name","desc":false}].

filterByArchived=active means not archived; it does not mean status Active. Ask for the status through filters. The answer is { "items": [...], "total": 42, "page": 1, "limit": 20 }, where total counts every match. A page past the last one answers 400 when the query matches at least one vendor. When nothing matches, any page answers 200 with empty items.

F='{"status":{"type":"in","values":["ACTIVE"]}}'
curl -G "https://app.devguard.ch/api/vendors/" \
  -H "Authorization: Bearer dvg_your_token_here" \
  -d "organizationId=<organization-id>" \
  -d page=1 -d limit=20 -d filterByName=hetzner \
  --data-urlencode "filters=$F"
Overview fieldMeaning
total, unrated, notAcceptable, contractsExpiringCounts, as on the tiles.
byLevelVendors per current level, indexed from the lowest level of your risk settings.
findings[]One entry per vendor and gap: kind (UNRATED, NO_TREATMENT_DECISION, BLOCKED_BUT_ACTIVE, APPROVAL_MISSING, NO_ASSESSMENT, ASSESSMENT_OVERDUE, CONTRACT_EXPIRING, TRANSFER_MECHANISM_MISSING, REVIEW_DUE), the vendor (with a 0-based level) and since: the missed review date, the contract expiry or the last approved review, null for the other kinds.
process[]The lifecycle bars in order, each { step, done, total }: rated, treatment, approved, assessed, assessmentCurrent, reviewed.

How is this guide?

On this page