Vendor Management

The vendor command group manages vendor entities and their evidence documents. Vendors represent external providers (CSPs, SaaS, managed services) or internal teams whose controls your system inherits.

List Vendors

pretorin vendor list
pretorin vendor list --search aws --risk-tier critical --assessment-status submitted

vendor list follows the paginated public API and fetches all matching vendors by default. Filters include --search, --type, --risk-tier, --owner-user-id, --assessment-status, --lifecycle-status, --sort-by, and --sort-dir.

Inactive vendors are hidden by default. Pass --include-inactive to show them, or filter to a single lifecycle state with --lifecycle-status onboarding|active|inactive:

pretorin vendor list --include-inactive
pretorin vendor list --lifecycle-status inactive

When present, the table also surfaces Lifecycle, Expired Doc, and Expiring Doc columns so you can spot vendors with lapsed or soon-to-expire evidence.

Lifecycle

Transition a vendor between lifecycle states (onboarding, active, inactive). A non-empty --reason (max 500 characters) is required and recorded on the audit trail:

pretorin vendor lifecycle <vendor_id> inactive --reason "Contract ended 2026-06-30"
pretorin vendor lifecycle <vendor_id> active --reason "Renewed and re-onboarded"

This endpoint requires the server-side vendor.pii scope (or an admin token). The CLI just sends the existing Bearer token; the platform returns 403 if it is not authorized. Inactive vendors cannot have assessments launched against them — reactivate the vendor first with pretorin vendor lifecycle <id> active --reason ....

Create a Vendor

pretorin vendor create "AWS" --type csp --description "Primary cloud provider" \
  --authorization-level "FedRAMP High P-ATO" \
  --inherent-risk high

Vendor Types

Vendor Risk Bands

inherent_risk and residual risk_tier use the shared risk-band vocabulary: low, moderate, high, critical.

medium is accepted as a deprecated input alias for moderate during the platform migration window. CLI create/update commands normalize it to moderate and print a warning in human-readable output.

Get Vendor Details

pretorin vendor get <vendor_id>

Update a Vendor

pretorin vendor update <vendor_id> --name "AWS GovCloud" --authorization-level "FedRAMP High"
pretorin vendor update <vendor_id> --inherent-risk critical --owner-user-id <user_id>

Delete a Vendor

pretorin vendor delete <vendor_id>
pretorin vendor delete <vendor_id> --force  # skip confirmation

Vendor History

pretorin vendor history <vendor_id>
pretorin vendor history <vendor_id> --limit 25

TPRM Reporting Dashboard

Show an organization-wide third-party-risk posture summary — posture counts, residual-tier and provider-type breakdowns, the 5×5 residual likelihood×impact heatmap, and forward-looking document and contract expiry lists:

pretorin vendor dashboard
pretorin vendor dashboard --horizon-days 30
pretorin --json vendor dashboard

--horizon-days (1–365, default 90) sets the look-ahead window for the “expiring soon” figures and the expiry lists. --json is a global option (it comes before the subcommand: pretorin --json vendor dashboard) and emits the raw VendorTprmSummary body for scripting and agents.

The dashboard is organization-wide, so it requires an org-scoped token with the vendor.pii or admin scope. A system-scoped token is rejected with a clear, actionable error (and in --json mode the platform entitlement envelope is preserved for automation callers).

Upload Vendor Documents

Upload SOC 2 reports, Customer Responsibility Matrices (CRMs), FedRAMP packages, or other vendor evidence:

pretorin vendor upload-doc <vendor_id> ./aws-soc2-report.pdf \
  --name "AWS SOC 2 Type II" \
  --description "Annual SOC 2 report covering 2025" \
  --attestation-type third_party_attestation \
  --expires-at 2027-01-31 \
  --refresh-cadence-days 90

--expires-at (ISO-8601 date) and --refresh-cadence-days (1–365) drive the platform’s document expiry and refresh reminders. Both are optional.

Attestation Types

List Vendor Documents

pretorin vendor list-docs <vendor_id>

The table includes Expires (the document’s expires_at date) and Expired (the platform-computed is_expired flag) so you can identify lapsed evidence.

Vendor Contacts

Manage the people associated with a vendor. All contact commands require the server-side vendor.pii scope (or an admin token); the platform returns 403 if the token is not authorized.

pretorin vendor contact list <vendor_id>
pretorin vendor contact add <vendor_id> --name "Jane Doe" \
  --email jane@vendor.example --title "Security Lead" --phone "+1-555-0100" \
  --is-primary --notes "Primary security contact"
pretorin vendor contact update <vendor_id> <contact_id> --title "CISO"
pretorin vendor contact delete <vendor_id> <contact_id>          # confirmation prompt
pretorin vendor contact delete <vendor_id> <contact_id> --force  # skip confirmation

--name is required on add. Optional fields are --email, --title, --phone, --is-primary/--no-is-primary, and --notes. Setting --is-primary auto-demotes the previous primary contact server-side; if a concurrent write races to set a second primary, the platform returns HTTP 409 and the CLI prints the platform message.

Vendor Contracts

Track contracts, SLAs, DPAs, and order forms for a vendor. All contract commands require the server-side vendor.pii scope (or an admin token).

pretorin vendor contract list <vendor_id>
pretorin vendor contract add <vendor_id> --name "MSA 2026" --contract-type contract \
  --start-date 2026-01-01 --end-date 2027-01-01 --renewal-date 2026-11-01 \
  --auto-renew --notice-period-days 30
pretorin vendor contract update <vendor_id> <contract_id> --renewal-date 2026-12-01
pretorin vendor contract delete <vendor_id> <contract_id>          # confirmation prompt
pretorin vendor contract delete <vendor_id> <contract_id> --force  # skip confirmation

--name and --contract-type are required on add. --contract-type must be one of contract, sla, dpa, or order_form. Other optional fields: --start-date, --end-date, --renewal-date, --auto-renew/--no-auto-renew, --notice-period-days, --terminated-at, --document-evidence-item-id, and --notes. There are no financial fields.

The list/detail output renders the server-derived Status (active/expired/terminated) and Expired (is_expired) columns. These are read-only — there is no flag to set them.

Vendor Systems

Attach a vendor to the systems it serves and manage those mappings. This is the system-of-record for SR-5 / SA-9 vendor↔system relationships.

pretorin vendor systems list <vendor_id>
pretorin vendor systems attach <vendor_id> --system-id sys-1 --system-id sys-2
pretorin vendor systems detach <vendor_id> <system_id>          # confirmation prompt
pretorin vendor systems detach <vendor_id> <system_id> --force  # skip confirmation

attach requires at least one --system-id; repeat the flag to attach several systems in one call.

Residual Acceptance

Sign authorizing-official acceptance of a vendor’s residual risk for a single attached system. The (vendor, system) pair is idempotent server-side.

pretorin vendor residual-acceptance sign <vendor_id> --system-id sys-1 \
  --note "Accepted per AO review 2026-07"

Signing is gated on the organization’s evidence attestation-envelope capability and attestation process mode. When signing is disabled the platform returns HTTP 503 and the command prints an actionable message rather than a raw error.

Assessment Templates

Vendor assessment templates are shared across the public API, CLI, MCP, and platform UI. Seed templates are read-only; org-scoped custom or imported templates can be deleted.

pretorin vendor template list
pretorin vendor template get <template_id>
pretorin vendor template delete <template_id> --force

Import SIG-Lite or CAIQ-Lite workbooks in two steps. The default is a dry-run preview; pass --apply and --acknowledge-license-rights to persist the template.

pretorin vendor template import ./sig-lite.xlsx --source-format sig_lite
pretorin vendor template import ./sig-lite.xlsx --source-format sig_lite \
  --apply --acknowledge-license-rights

--source-format accepts sig_lite or caiq_lite.

Vendor Assessments

Launch, fill, submit, score, and review assessments against a vendor:

pretorin vendor assessment launch <vendor_id> --template-id <template_id>
pretorin vendor assessment list <vendor_id>
pretorin vendor assessment get <vendor_id> <assessment_id>

Save responses from JSON. The payload can be a list of answer objects or an object with an answers list:

pretorin vendor assessment save-responses <vendor_id> <assessment_id> \
  --answers-file ./answers.json
pretorin vendor assessment submit <vendor_id> <assessment_id>
pretorin vendor assessment score <vendor_id> <assessment_id>

Each answer includes question_ref plus optional answer, comment, and evidence_item_id.

[
  {
    "question_ref": "q-1",
    "answer": true,
    "comment": "Confirmed in the vendor SOC 2 report.",
    "evidence_item_id": "ev-123"
  }
]

Finalize the assessment with the NIST 800-30 five-point residual likelihood/impact scale: very_low, low, moderate, high, very_high. If AI advisory scoring was unavailable, pass --acknowledge-no-ai-review.

pretorin vendor assessment review <vendor_id> <assessment_id> \
  --residual-likelihood low \
  --residual-impact moderate \
  --acknowledge-no-ai-review

Assessment Portal Lifecycle

Send an assessment to vendor recipients through the external portal, rotate and resend its link, or revoke active access for all recipients:

pretorin vendor assessment send <vendor_id> <assessment_id> \
  --recipient-email security@vendor.example \
  --recipient-email compliance@vendor.example \
  --expires-in-days 30 \
  --message "Please complete this assessment."
pretorin vendor assessment resend <vendor_id> <assessment_id> \
  --recipient-email security@vendor.example
pretorin vendor assessment revoke <vendor_id> <assessment_id> \
  --reason "Assessment no longer required"

send and resend require 1–20 --recipient-email values and accept an --expires-in-days value from 1–365. Human output displays the portal URL, token prefix, expiry, and delivery counts. Use --json for the complete platform response, including the standard entitlement envelope when the organization has not enabled the vendor-portal capability.

Related: Control Inheritance

Once vendors are created and documents uploaded, use the MCP tools or platform to set control responsibility edges:

• set_control_responsibility — Mark controls as inherited/shared
• generate_inheritance_narrative — AI-draft inheritance narratives from vendor docs
• get_stale_edges / sync_stale_edges — Monitor and sync inheritance