Secure architecture and development of AI applications

An AI application forms an end-to-end path: user or system input, application logic, API, RAG sources, agent tools, external recipients, and telemetry. AI-SDLC1 registers where the subject's identity and privileges are established, where data becomes untrusted, where model output turns into action, and where the request crosses the boundary to leave the controlled zone.

The application must be divided into at least the following logical contours:

Contour	Purpose	Minimum security outcome
Ingress	Receiving user and external requests	Untrusted input is validated, limited in terms of size and frequency, and separated from the application's internal components
Identity	Authentication and authorization of users, services, and agents	All subjects have a verifiable identity; access is granted based on the principle of least privilege
Application	Business logic orchestration; assembly of prompts, RAG context, and tool calls	User input, system instructions, retrieved content, and tool results are processed as separate untrusted sources
Model	Interacting with an LLM or another AI model	Only the minimum required data is provided to the model; secrets, credentials, and uncontrolled system instructions are not included into the prompt
Data/RAG	Data ingestion, storage, indexing, and retrieval	RAG content has provenance, class labels, and access metadata; search returns only data permitted for the specific subject
Egress	Accessing external LLMs, APIs, plugins, and tools	Outbound connections are allowed only to approved recipients; data transfer is controlled, minimized, and logged
Logging/Monitoring	Audit, attack detection and incident investigation	Events allow to reconstruct the request chain, application decisions, data accesses, model and tool calls without logging excessive secrets or personal data

The presented scheme is a logical model for analysis, not a required physical topology: one component can implement several contours; and one contour can be comprised of several services. For each contour, the following must be defined: owner, allowed data streams, access mechanisms, audit events, and response procedures. A given AI system's architecture may lack any particular branch (e.g., no external calls or agent tools).

Architecture and changesArchitecture and changes

Architecture and risks are documented prior to releaseArchitecture and risks are documented prior to release

Requirement ID: AI-SDLC1

Requirement

Prior to the first production release and after any major update, the system’s owner must document all components, trust boundaries, data, subjects, model calls, tools, external connections, and the potential impact of errors or malicious behavior. This description must map each major risk to a specific boundary, measure, or check method.

For each mapping, you must state the source subject and resource, target resource or API, data class, protocol, authentication method, network path, event source, and owner.

Make sure to explicitly define these checkpoints: pre_model before calling a model, retrieval during data retrieval; pre_action before applying the tool, post_model after the model responds, and pre_egress before a request leaves the secure zone.

Implementation

An update is considered major if it introduces a new model or provider, data type, RAG source, tool, external recipient, public endpoint, role, or code execution method. The organization must define a procedure to review these updates and assign employees responsible for the approval. This requirement applies to every production system and every major update. The system-wide N/A result is not allowed. Before any work begins, you must agree on the conditions for revising the description and the approving party.

Manual check

1. Map the documented architecture to your deployed resources, routes, and accounts.
2. Select one allowed and one blocked data flow for each boundary.

You are compliant if all the production components are documented, and every boundary has a defined owner and a measure to check. An unmapped component or data flow means failure. You must either update your description and applicable requirements to include such an asset, or remove it from the production environment. After that, repeat the allowed and blocked flow checks.

Artifact

• Architecture description.
• Data flow diagram.
• Mapping to actual resources.
• Test results.
• Documented approval.

Input, context, and outputInput, context, and output

Untrusted input is verified prior to model ingestionUntrusted input is verified prior to model ingestion

Requirement ID: AI-APP-WAF1

Requirement

The application must verify the type, size, encoding, structure, required fields, as well as validity of user and machine input before including the data into the model request or performing any other action. For each field and object type, the allowed values or an explicit rejection rule must be defined. The text, file, URL, search result, and external service's response remain untrusted whether or not they have passed the network perimeter.

Implementation

For public HTTP(S) entry points, Yandex API Gateway and Yandex Smart Web Security can limit requests at the levels of HTTP, WAF rules, bot activity, and frequency. This does not replace application-level validation of the prompt's semantic content.

The connection between API Gateway and an Smart Web Security profile is set by a documented OpenAPI extension; for profile capabilities, see Security profiles.

For additional moderation of requests and responses, you can use guardrails. However, this feature is in Preview and does not replace authorization, schema validation, or personal data processing. For more information, see this guardrail description.

For Serverless Containers, Cloud Functions, and Kubernetes without Smart Web Security, the same validator resides in the Ingress or application intermediate layer; security groups and network policies do not analyze the prompt and request body. The N/A result is acceptable only for the Smart Web Security branch, provided there is no HTTP(S) entry point, and does not cancel application-level input data validation. Semantic moderation of content pertains to AI-CONTENT1.

For a route with an Smart Web Security profile, both profile connection details and access log are saved.

Check

1. Send a valid request, a request with a missing or extra field, violated schema, exceeded limit, and content that should be rejected by the approved rule.
2. Check that each time the rejection occurs before the model call or another risky action, has a specific code or reason, and the log contains no secrets or excessive original content.

A valid request must get a correlation ID. Each rejection must be additionally confirmed by the absence of a subsequent model call or tool call event in the log or trace.

Artifact

• Rejection records.
• OpenAPI specification configuration and hash.
• Smart Web Security profile ID.
• Test requests and their results.
• Subsequent call absence confirmation.

Guardrails have defined categories and fault-tolerant behaviorGuardrails have defined categories and fault-tolerant behavior

Requirement ID: AI-CONTENT1

Scope

This requirement applies if an approved product, corporate, contractual, or legal policy prohibits individual content categories or if the architecture declares guardrails to be the protective measure. The N/A result is acceptable for a specific route only if the approved content policy does not require guardrails for that route.

Requirement

The owner must document the rule version subject to verification: input and output content categories, covered interfaces, action for each category, and behavior if the moderator commits an error or is unavailable. Actions may include blocking, restricting the response, forwarding for a manual review, or another approved reaction. An undefined moderator error must not quietly turn into a permission where the policy requires blocking.

Implementation

In AI Studio, guardrails can only be used within the published Preview function. A rule, dictionary, or classifier and theirs version are configuration objects; edits can be made by a subject with the documented ai.guardrails.editor role.

When blocked, the response has the incomplete status with content_filter for reason; however, these indicators do not replace application-level error handling. Guardrails do not decide whether data is legally admissible and do not replace the schema, IAM, personal data protection, document-level authorization, or agent action verification. For more information, see this guardrail description.

One guardrail is attached to a model instance; a custom guardrail overrides the system one, thus changing the effective category coverage. Management is effected via the management console (AI Studio → Management → Security → Guardrails); the software management interfaces are not documented, so an exported versioned configuration and manual evidence are required. Guardrails are not a WAF.

Check

1. For each approved category, perform allow test and deny test on each covered path. The request and response are checked separately. Request blocking is confirmed by not calling the model; and response blocking, by not displaying the result.
2. Separately simulate the moderator committing an error or being unavailable.
3. Record the rule version, observed action (incomplete status with content_filter as reason), Yandex Audit Trails management event pertaining to guardrail setup, and application record; a separate guardrail trigger event in Audit Trails is not documented and, if necessary, gets recorded as a blind spot.

A bypass via an uncovered interface or allowing where rejection is required means failure to comply. In the event of a false negative, change the category, threshold, or dictionary, wait for it to apply, and repeat the documented set of tests.

Artifact

• Rule version and exported configuration.
• Model instance and guardrail IDs.
• Blocking test.
• Management event or application record.

Model output is verified prior to rendering and executionModel output is verified prior to rendering and execution

Requirement ID: AI-CONTENT2

Requirement

The application must treat the model's output as untrusted data. Before displaying it as active content, forming a request, writing to storage, or executing a command, the application must validate the format, schema, permissible values, target object, and the calling subject's privileges.

If the model generates SQL, shell command, URL, file name, template, API call, or tool arguments, the application must use a separate deterministic validator and a list of allowed operations. Successful generation of text by the model is not an authorization for an action.

The response gets parsed into a typed object: unknown and missing fields are rejected, and values are escaped according to the target context rules (HTML, SQL, shell, or file name).

For a system that outputs only inert text, execution-related branches may not apply but a safe render is still mandatory. Output validation is implemented by the application: the native output schema validation mechanism in Yandex Cloud is not certified.

Check

Submit a synthetic response with an extra or privileged field, prohibited object, control sequence, HTML or script markup, invalid JSON, fragment of an SQL or shell command, and an unknown action. The requirement is met if the application rejects each such response prior to execution and logs the reason without recording sensitive data. None of the tests should result in a call for the target system, which should be confirmed by the absence of the corresponding event in the log or trace.

Artifact

• Model test responses.
• Rejection records.
• Validator code.
• Schema hash and policy version.
• Confirmation that there is no call for the target system.

System guidelines and policies must only be modified via a trusted pathSystem guidelines and policies must only be modified via a trusted path

Requirement ID: AI-CORE5

Requirement

System instructions, prompt templates, tool policies, routing rules, security configurations, and other trusted settings must be stored separately from user content, have an owner, object ID, and version, and must be modified only through an approved change process. If such a configuration exists, the N/A result is not allowed.

For the object, the reading and writing entities, revision history, and active version are recorded. A deployment record links the artifact hash of the instructions to a model or application version.

The application must not replace them with data from RAG, a tool response, or message from another agent. The runtime environment accepts a trusted set only from an approved release path.

Secrets should not be included in the system prompt. If the configuration is stored in Yandex Object Storage or another cloud resource, the access control, encryption, and versioning mechanisms documented for that resource apply; Object Storage versioning may be used as part of the revision history but does not replace the approval procedure. No native registry for prompts and policies is claimed for Yandex Cloud; cloud-based tools ensure secure storage and deployment, while trusted instruction management handles the application release process.

Manual check

1. Compare the active version of the configuration with the approved version and the subjects authorized to read and modify it.
2. Then, try to change the goal or policy via custom input and the RAG document.

This change must not be included in the trusted configuration. If the change has made its way into the active configuration, stop the release or agent operation, revert to the last approved set, rotate any exposed secrets, and rerun the original negative test.

Artifact

• Active configuration version.
• Release notes.
• Spoofing test result.
• Instruction artifact hash.
• Deployment event.
• Current version log.

External or retrieved context gains no implicit trustExternal or retrieved context gains no implicit trust

Requirement ID: AI-APP-INJECT1

Requirement

RAG chunks, web pages, files, emails, tool results, and other external data must be provided to the model as payload, not as trusted system instructions. For each chunk, the accessible source ID and the result of applied policy are saved.

The application must separate data from control instructions, process the retrieval or validation error in a fail-safe manner, and limit the consequences if an external context attempts to change the objective, disclose a secret, or initiate an action.

Labeling is assigned during the upload: immutable source and document IDs, owner, trust level or data class, and version. External content cannot select a tool, action, or recipient.

AI Search does the uploading, chunking, vectorization, and searching for documents. The application must separate the found data from control instructions, and limit their impact. For the service capabilities, see this AI Search guide.

Check

Put into a test source a document with a known ID and an instruction to change a system policy or call a tool.

The requirement is met if the instruction is treated as data, changes no privileges, and does not lead to an action without a separate verification, and the trace links the result to the source and policy decision. The system may quote or paraphrase such content, but there must be no tool events or target system events.

Upon failure, quarantine the document or index version, disable the affected search source, fix the policy or parser, rebuild the index, and repeat the test.

Artifact

• Test document with instructions.
• Policy decision trace.
• Search result IDs.
• Quarantine or reindexing record.

External connections and public perimeterExternal connections and public perimeter

External model API calls are routed through a managed boundaryExternal model API calls are routed through a managed boundary

Requirement ID: AI-NET3

Requirement

If the AI system calls a model API outside Yandex Cloud, the owner must define the allowed endpoints, types of transmitted data, service account or another workload identity, secret storage location, route, timeouts, and logging. The application must exclude any unapproved recipient and must not transmit data lacking the required authorization. The list of recipients and transmitted data categories must be reviewed whenever the provider, model, processing region, contract, data schema, or network path changes.

The provider key must be stored within a dedicated storage in compliance with AI-SECRET1; however, its scope, expiration, and revocation must be verified in the provider system. The IAM policy does not create a private network path to an external provider; such a path may only be claimed when documented officially by the provider.

The Yandex Virtual Private Cloud route table and NAT gateway define the network path, but they do not by themselves filter the domain name, recipient, or request content. For the documented properties of the routes and next hop, see the VPC routing description. Where recipient restrictions are required, the organization must implement them through an appropriate proxy, firewall, or application and verify the actual TLS endpoint.

Check

1. Make one allowed call and one call to a non-whitelisted test endpoint.
2. Check the route, DNS/TLS destination, absence of the secret in the log, and the correlation between the application record and the external request.

Whether the data may be transmitted is verified separately according to Compliance and processing of personal and regulated data. The denied call must not appear in the provider’s log; any credentials exposed during the check must be rotated and must not be reinstated.

Artifact

• Proxy and firewall configuration.
• Allowed and denied call record.
• Secret ID.
• Call correlation log.

Public HTTP(S) perimeter has an explicit protection schemePublic HTTP(S) perimeter has an explicit protection scheme

Requirement ID: AI-NET7

Requirement

For each public endpoint, the owner must record the domain, route, authentication method, rate limit, maximum request size, logging policy, and internal backend connection. Direct backend access must not bypass the checks established for the public path.

Implementation

API Gateway supports authorization via documented extensions, including JWT authorizer, and Smart Web Security integration. Do not assign a non-existent generic invocation role to API Gateway: the authorization method depends on the OpenAPI specification and backend integration. Smart Web Security logs events within its documented log model. A list of allowed requests does not substitute for a complete application log.

The Smart Web Security rate limits protect the relevant HTTP route but do not apply to model token costs or content semantics. The N/A result is allowed for a closed internal system without a public route, but partner endpoints must comply.

Check

1. Compare your published OpenAPI specification, domain, and backend to make sure they match.
2. Test a request without credentials, request with invalid credentials, request exceeding the limit, and a direct request to the backend.

Access must match the specified schema, and there must be no way to bypass the perimeter. Match gateway or Smart Web Security logs and target system logs using the unified correlation ID. Run this test from both from a public and private source. A prohibition and disabled public access indicate a safe disaster state.

Artifact

• OpenAPI specification.
• Unauthenticated requests.
• Backend bypass test.
• Specification and Smart Web Security profile IDs.
• Bindings.
• HTTP test results.