Secure Architecture (SA)

Vendors Domain - HAIAMM v3.0

Practice Overview

Objective: Publish the reference architectures for safely consuming each AI vendor archetype, so teams integrating an AI vendor have a vetted "green path" that already implements the SR-Vendors requirements, and teams deviating from it do so knowingly and explicitly.

Description: SA-Vendors ships a small catalog of reference integration patterns, one per AI vendor archetype, showing how to place the data boundary, enforce identity, route traffic (and keep it routable), log activity, and contain agentic behavior. Each pattern is a block diagram plus a decision-log that ties the choices back to SR-Vendors requirements and TA-Vendors threats. Teams reach for the pattern first; deviations require design review.

Context: Without reference patterns, every team reinvents the integration. Some pipe prompts direct to a vendor API with no logging, some paste regulated data into consumer GenAI, some grant an AI agent platform credentials that exceed any human's permission set. At L1 SA-Vendors makes the safe path the easy path, not by blocking integrations but by publishing the shape of one that already satisfies the requirements.

Maturity Level 1

Objective: Publish reference architectures per AI vendor archetype, an anti-patterns catalog, and a deviation-review path; link each pattern to SR-Vendors requirements and TA-Vendors threats

At this level, architecture becomes prescriptive rather than advisory, reference patterns are named, versioned, and the first thing a team encounters when they land on an AI vendor approved by the intake gate.

Dependencies

• SR-Vendors L1 (required): patterns implement the base + archetype requirement packs; without the pack the patterns are stylistic choices.
• TA-Vendors L1 (required): threats drive the control placements.
• PC-Vendors L1 (required): patterns operationalize AUP and Data-Sharing policy constraints.
• Supports / unblocks: DR-Vendors L1 (design reviews use patterns as the baseline), IR-Vendors L1 (implementation reviews check pattern adherence), EH-Vendors L1 (hardening targets the pattern surfaces), ST-Vendors L1 (tests target the pattern's controls).

Desired Outcomes

• A team adopting a newly-approved AI vendor finds a documented reference pattern within one click of the inventory record.
• The pattern is concrete enough to implement (components, data flow, logging points, auth model) and explicit about what it does not cover.
• Known anti-patterns, the integrations that have produced real incidents in the industry, are named and prohibited, not rediscovered.
• Deviations from reference patterns are visible and reviewed, not accidental.
• Architecture choices carry explicit traceability to SR requirements and TA threats, any reviewer can ask "why is the proxy here?" and get an answer.

Activities

A) Publish reference architectures per AI vendor archetype

Ship one pattern per archetype, five at L1. Each pattern is short (≤2 pages), includes a labeled diagram, and covers the same structural elements so teams know what to expect.

Pattern skeleton (every archetype): - Scope, what the pattern covers and what it explicitly does not. - Data boundary, where org data meets vendor data; what crosses, what doesn't; DLP inspection points. - Identity & auth, SSO-backed access, service-principal model for API use, secret management, token lifecycle. - Traffic path, egress through monitored network, optional proxy (API-level inspection), region pinning for data residency. - Logging, what is logged where (vendor-side, org-side), retention, exportability; human-oversight and deployer-duty evidence trail. - Controls mapped to SR requirements, explicit row-by-row mapping; gaps acknowledged. - Threats mitigated, which TA archetype threats the pattern addresses and which remain residual.

Archetype-specific emphasis: - Consumer GenAI, enterprise tenant only; SSO enforced; content-filtering enabled; personal-account prohibition wired via IdP; DLP/browser controls on egress; admin-audit access. - AI-embedded SaaS, feature toggled on only after parent-DPA addendum; scoped to specific workspaces; admin audit of users and data types; vendor-side no-train setting verified and re-checked quarterly. - AI coding assistant, IDE-policy enforced (prohibited paths, prohibited languages/data markers); no-train path for regulated repositories; centralized license/SSO; telemetry scope documented. - AI API / foundation-model, a thin internal proxy between apps and the vendor API (prompt/response logging, PII scrubbing, rate-limit shaping, model-version pinning, kill-switch). This is the single most load-bearing pattern element for API use. - AI agent / automation platform, tool allowlist; per-tool scope; human-in-the-loop wrapper for destructive or external-communication actions; agent-session logging; indirect-prompt-injection defense (treat retrieved content as untrusted; provenance tags).

B) Publish the anti-patterns catalog

Name, describe, and prohibit the AI-vendor integrations that reliably cause incidents. L1 set (not exhaustive, but the ones every team must recognize): - "Copy-paste workflow", employees round-tripping regulated data into a consumer GenAI tab. - "Shadow API key", a single shared API key in a shared vault or repo, no attribution, no revocation plan. - "Unscoped agent", agent platform with unrestricted tool access or broad network/filesystem reach. - "Trust the embedded feature", AI feature inside approved SaaS turned on org-wide with no incremental review. - "Pull-without-label", retrieval-augmented generation consuming untrusted content (ticket bodies, email) with no provenance tagging or sanitization. - "Direct-to-vendor call", apps calling vendor APIs directly without the internal proxy, bypassing logging, PII scrubbing, and kill-switch.

Each anti-pattern gets: description, why it's dangerous, real-incident flavor, the reference pattern that replaces it.

C) Publish the deviation-review path and integrate patterns into the intake/inventory flow

Deviations from reference patterns are normal at the edges (a new use case, a constraint the pattern didn't anticipate). L1 handles them transparently: - Teams adopting an approved AI vendor land on the inventory record → see the recommended pattern → pick "using pattern" or "deviating." - Deviations require a short design review (DR-Vendors L1, lightweight) with a named architect reviewer and a documented rationale stored with the integration. - Repeat deviations in the same direction are a signal to update the pattern, not to keep approving exceptions.

Outcome Metrics (L1)

Process Metrics (leading)

• Pattern review cadence, quarterly refresh; change-log maintained.
• New-archetype lead time, new pattern published within 30 days of a first intake in a new category.
• Deviation-review SLA, ≤5 business days from deviation request to decision.

Effectiveness Metrics (business value)

• Integration lead time, time-to-production for a team adopting an approved AI vendor via the reference pattern (should decrease after patterns land).
• Avoided-incident stories, documented cases where the pattern (e.g., API proxy, DLP placement) blocked or contained a real exposure.
• Pattern reuse rate, % of new integrations using the pattern unchanged vs. deviating.

Success Criteria

• Five reference patterns published, each mapped to SR-Vendors requirements and TA-Vendors threats.
• Anti-patterns catalog published, linked from the AUP and the intake gate, referenced in EG-Vendors training.
• Deviation-review path operational with a named architect reviewer population.
• ≥85% of active AI vendor integrations classified as "on pattern" or "deviation with review."
• 100% of API/model archetype integrations with non-public data flowing through the internal API proxy.

Maturity Level 2

Objective: Extend reference patterns to multi-region, multi-tenant, and agent-platform complexity; publish an incident-informed anti-pattern catalog; encode patterns as IaC templates teams fork

At this level, architecture goes from "single-path reference" to "production-scale reference set." Multi-region data residency, multi-tenant isolation for parent-SaaS AI features, agent-platform tool-sandboxing are all covered. Anti-patterns evolve from IM incidents.

Dependencies

• SA-Vendors L1 (required): base reference patterns and anti-patterns catalog.
• SR-Vendors L2 (required): quantitative requirements drive pattern controls.
• IM-Vendors L1+ (required): incidents feed anti-pattern additions.

Desired Outcomes

• Teams integrating Critical/High AI vendors have a production-grade pattern to clone, not a napkin sketch.
• Anti-pattern catalog reflects real incidents, not theoretical harms.
• Pattern drift is detected (integrations using old patterns auto-flagged).
• IaC-encoded patterns reduce integration time and enforce baseline controls by default.

Activities

A) Extended reference patterns

• Multi-region AI-vendor integration pattern, residency enforcement, cross-region failover, GDPR transfer mechanism.
• Multi-tenant parent-SaaS AI-feature pattern, per-tenant key scope, per-tenant data scope, admin-governance integration.
• Agent-platform pattern, tool-sandboxing, HITL gates, session-isolation, indirect-prompt-injection defense in RAG-shaped agents.

B) Incident-driven anti-pattern catalog

• Every IM-Vendors incident classified to an anti-pattern; existing or new.
• Catalog refreshed monthly; teams see new anti-patterns before new features.

C) Pattern-as-IaC

• Reference patterns encoded as Terraform modules, Kubernetes manifests, Crossplane compositions, Pulumi stacks.
• Teams fork rather than handcraft; deviations flagged at plan time.

Outcome Metrics (L2)

Process Metrics (leading)

• Pattern refresh cadence, ≥1 change/quarter.
• Anti-pattern review cadence, monthly.
• IaC pipeline health monitored.

Effectiveness Metrics (business value)

• Integration time-to-production drops for teams adopting IaC patterns.
• Incident rate on IaC-encoded integrations lower than on hand-crafted ones.

Success Criteria

• 3/3 extended patterns published.
• ≥80% Critical/High integrations on IaC patterns.
• Anti-pattern catalog updated from ≥3 incidents in last 12 months.
• Pattern-drift detection covering 100% of IaC integrations.

Maturity Level 3

Objective: Contribute reference patterns to industry; implement zero-trust AI-vendor access; formally specify agent-tool-scope boundaries for Critical-tier agents

At this level, the patterns are open artifacts that industry adopts. Zero-trust for AI-vendor access (continuous verification, just-in-time tool scope) is the default. For Critical-tier agent deployments, tool-scope boundaries carry formal specifications.

Dependencies

• SA-Vendors L2 (required): extended patterns + IaC substrate.
• EH-Vendors L2 (required): hardening controls supply zero-trust enforcement points.

Desired Outcomes

• Patterns cited by industry (CNCF AI SIG, OpenSSF AI, CSA AI Safety Initiative).
• Zero-trust AI-vendor access is routine; static API keys retired.
• Critical-tier agent deployments carry formal tool-scope specifications that can be audited.

Activities

A) Contribute reference patterns externally

• Patterns published to CNCF AI SIG, OpenSSF AI, CSA, or sector-specific bodies.
• Maintained upstream; internal use aligns with external version.

B) Zero-trust AI-vendor access

• Continuous session verification for human access.
• Just-in-time tool scope for agents, scopes issued per session/per task.
• Device-trust integration, endpoint posture required for AI-vendor access.

C) Formal tool-scope specification

• Critical-tier agent integrations carry a formal tool-scope spec (parameter types, rate, data-class) enforced at runtime.
• Spec changes pass a DR-Vendors L3 review gate.

Outcome Metrics (L3)

Process Metrics (leading)

• External contribution pipeline ≥2 in-flight.
• Static-key retirement project on calendar.
• Formal-spec coverage tracked per Critical agent.

Effectiveness Metrics (business value)

• Reduced static-credential blast radius.
• Formal specs catch tool-scope mistakes pre-deploy.

Success Criteria

• ≥2 patterns externally adopted.
• ≥90% human sessions under zero-trust.
• ≥70% machine calls under JIT-scoped credentials.
• 100% Critical-tier agents with formal tool-scope specs.

Key Success Indicators

Level 1: - Five reference patterns published, one per archetype, each with a labeled diagram, scope, data boundary, identity model, traffic path, logging spec, and row-by-row SR-requirements and TA-threats mapping. - Anti-patterns catalog published and linked from the AI Acceptable Use Policy, the intake gate, and EG-Vendors training; teams can name the six L1 anti-patterns and cite the reference pattern that replaces each. - ≥85% of active AI vendor integrations classified as "on pattern" or "deviation with review"; no silent deviations in the integration inventory. - 100% of API/model-archetype integrations with non-public data flowing through the internal API proxy. - Deviation-review path operational: a named architect-reviewer population, ≤5 BD SLA, and a repeat-deviation signal that queues pattern updates.

Level 2: - 3/3 extended patterns published (multi-region residency, multi-tenant SaaS isolation, agent-platform tool-sandboxing), each encoded as a forkable IaC module. - ≥80% of Critical/High AI vendor integrations running on IaC-encoded patterns; plan-time deviation flagging operational. - Anti-pattern catalog updated from ≥3 real IM-Vendors incidents in the last 12 months; new anti-patterns visible to teams before they ship new features. - Pattern-drift detection covering 100% of IaC-encoded integrations; drift findings tracked to resolution.

Level 3: - ≥2 reference patterns externally cited or forked by industry bodies (CNCF AI SIG, OpenSSF AI, CSA, or sector equivalent). - ≥90% of AI-vendor human sessions under continuous zero-trust verification (IdP/CASB); ≥70% of machine calls under JIT-scoped credentials with static keys retired. - 100% of Critical-tier agent deployments carrying a formal tool-scope specification enforced at runtime; spec changes gated through DR-Vendors L3 review. - Quarterly pattern-evolution cadence driven by external (ISAC, MITRE ATLAS) and internal (IM, ML) signals with a traceable change log.

Common Pitfalls

Level 1: - ❌ Patterns are published but not linked from the intake record or inventory, teams skip them because they're hard to find, not because they disagree with them. - ❌ The internal API proxy pattern is described but not enforced, high-risk API/model integrations call vendor endpoints directly, bypassing logging and the kill-switch. - ❌ Anti-patterns remain theoretical; they are not tied to real incidents or to the reference pattern that replaces them, so developers don't recognize the hazard when they encounter it. - ❌ Deviations are approved individually but the repeat-deviation signal is never wired, SA patterns never update because nobody aggregates the pattern-update trigger. - ❌ Pattern controls are mapped to SR-requirements on paper but the mapping is never validated against an actual integration, the traceability is aspirational. - ❌ The "AI agent" archetype pattern omits indirect-prompt-injection defense (provenance tagging on retrieved content), leaving the most dangerous surface unaddressed at the cheapest moment to fix it.

Level 2: - ❌ IaC patterns are forked once and then hand-edited at each deployment, drift is immediate and the IaC substrate provides no actual baseline enforcement. - ❌ Extended patterns cover multi-region residency on paper but don't include the GDPR transfer-mechanism selection step, teams ship cross-region data flows without a legal basis. - ❌ Anti-pattern catalog grows from incidents but is never surfaced to teams at integration time, it sits in a doc that nobody reads until an incident repeats. - ❌ Pattern-drift detection fires on low-signal configuration noise; the team ignores it within a month because alert volume overwhelms bandwidth. - ❌ Agent-platform pattern includes HITL gates in the diagram but IaC module doesn't enforce them, the gate is optional in practice.

Level 3: - ❌ Externally contributed patterns diverge from internal practice, what's published reflects what the org once did, not what it currently does; external adoption erodes trust when discrepancies surface. - ❌ Zero-trust AI-vendor access is declared complete when SSO is enforced; JIT-scoped credentials for machine calls and device-trust integration for human access are deprioritized indefinitely. - ❌ Formal tool-scope specifications for Critical-tier agents are authored once and never updated as agent capabilities expand, the spec becomes a compliance artifact, not an enforcement artifact. - ❌ External contribution pipeline stalls at "in-draft", the program never completes the final publication step because internal legal or PR review creates indefinite delay.

Practice Maturity Questions

Level 1: 1. Are five reference patterns published, one per AI vendor archetype, each with a labeled diagram, data-boundary definition, identity and auth model, logging spec, and explicit row-by-row mapping to SR-Vendors requirements and TA-Vendors threats, accessible within one click of the integration inventory record? 2. Is the internal API proxy the mandatory traffic path for all API/model-archetype integrations handling non-public data, with 100% of such integrations verified against proxy routing configuration, not only declared in the pattern? 3. Is a repeat-deviation signal operational, such that three deviations in the same direction for the same archetype automatically queue a pattern-update review with SA ownership, and is the anti-patterns catalog linked from the AUP, the intake gate, and EG-Vendors training?

Level 2: 1. Are the three extended patterns (multi-region, multi-tenant, agent-platform) published as forkable IaC modules with plan-time deviation flagging, and are ≥80% of Critical/High AI vendor integrations running on IaC-encoded patterns as confirmed by the IaC and integration registry? 2. Has the anti-pattern catalog been updated from ≥3 real IM-Vendors incidents in the last 12 months, with new entries surfaced to teams at integration time rather than stored only in a reference document? 3. Is pattern-drift detection covering 100% of IaC-encoded integrations, with drift findings tracked to resolution and a change-log maintained for quarterly pattern refreshes?

Level 3: 1. Have ≥2 reference patterns been externally adopted (cited, forked, or incorporated) by recognized industry bodies, with documented evidence of adoption and internal practice aligned to the published version? 2. Are ≥90% of AI-vendor human sessions operating under continuous zero-trust verification and ≥70% of machine calls using JIT-scoped credentials, with static-key retirement tracked on a published calendar? 3. Do 100% of Critical-tier agent deployments carry a formal tool-scope specification (parameter types, rate, data-class) enforced at runtime, with spec changes gated through a DR-Vendors L3 review and a traceable change log?

Document Version: HAIAMM v3.0 Practice: Secure Architecture (SA) Domain: Vendors Last Updated: 2026-05-12 Author: Verifhai