LlamaIndex Security Guide: Hardening Loaders, Query Engines, Agents and LlamaParse

LlamaIndex is a library that runs inside your application, so the security of a LlamaIndex RAG pipeline or agent is decided by the controls you build around it: what data it loads, which credentials its tools hold, what a generated query is allowed to touch and who can reach the hosted LlamaParse project behind it. The project's own security policy states the boundary clearly: the library is meant for a trusted execution environment, and input validation, authentication, authorisation and prompt injection defences belong to the hosting application. This guide turns that shared responsibility into concrete settings for data loaders, query engines including text-to-SQL, agent tools and MCP, telemetry, and the LlamaParse (formerly LlamaCloud) platform. It is written for engineers and security reviewers taking LlamaIndex applications into production. General RAG threats are covered in the RAG Security Guide; this page stays specific to LlamaIndex.

This is an independent guide from NHI Mgmt Group, based on LlamaIndex's public documentation as of November 2026. It is not sponsored or reviewed by LlamaIndex. Product features change, so confirm settings against LlamaIndex's current documentation.

Key takeaways

• Read the threat model first. The LlamaIndex security policy places user input validation, web-layer controls, URL and file path handling and prompt injection mitigation with the application that embeds the library.
• Give text-to-SQL a read-only identity. The docs advise restricted roles, read-only databases and sandboxing; combine that with include_tables on SQLDatabase so the engine sees only the tables it needs.
• Bind sensitive tool arguments in code. FunctionTool accepts partial_params, so values such as the current user or tenant are fixed by your code rather than chosen by the model.
• Enforce retrieval permissions with metadata filters. Tag nodes with tenant or group metadata at ingestion and apply MetadataFilters on every retriever, so the LLM never sees documents the user may not read.
• Treat LlamaParse keys as user and project credentials. Keys are scoped to the creating user and project; use separate keys per environment, store them in a secrets manager and revoke promptly.

How identity and access work in LlamaIndex

The open source framework has no users, roles or sessions of its own. Every access decision is made by one of three parties, and each needs its own controls.

The security policy lists issues the project treats as application-layer, including server-side request forgery from attacker-controlled URLs passed to loaders, path traversal from untrusted file paths, prompt injection and denial of service from unbounded input. In practice this means the application must validate any URL, file path or document a user supplies before it reaches a reader such as SimpleDirectoryReader, and must cap input sizes. Report suspected vulnerabilities in the library itself through the repository's security advisory process described in that policy, and apply LlamaIndex package updates promptly.

Data leaving your environment

The LlamaIndex privacy page notes that tutorials use hosted model and embedding APIs by default, so documents and queries leave your machine, and that LlamaIndex itself does not store your data but sends requests to whichever providers you configure. It describes a fully local stack (a local LLM runtime, HuggingFaceEmbedding, SentenceTransformerRerank and a self-hosted or in-memory vector store) and intermediate options: use a cloud where you already have a data protection agreement, self-host the embedding and reranking steps, and scrub PII before indexing with the beta PIINodePostprocessor. Decide this per data classification before ingestion, because embeddings and stored nodes carry the content with them.

Admin roles and privileged access

LlamaParse organisations and projects

LlamaParse organises access as organisations that contain projects, and projects that contain resources such as indexes, data sources and data sinks. On the managed service the organisations page states that every member of an organisation has the same level of access to its projects and resources, admins add and remove members from the Members tab under Manage Organization, and invited users do not receive an email. Two practical consequences follow:

• Use organisations as the access boundary. Put production indexes in an organisation whose membership is limited to the people who operate production, and keep experiments elsewhere.
• Review membership on a schedule. Remove leavers from the Members tab and revoke their API keys, since keys belong to individual users.

The enterprise access page states that the managed service supports single sign-on through SAML and OIDC, that bring-your-own-cloud on Azure supports Microsoft Entra ID through OIDC, that role-based access control covers organisation and project access, and that SSO is configured by contacting LlamaIndex support.

Self-hosted roles

For self-hosted LlamaParse, the user roles page defines three roles, with scope set per member through project_ids (null for the whole organisation, or a list of project IDs):

Member management uses PUT /api/v1/organizations/{ORG_ID}/users and requires an organisation admin's API key; look up role IDs by name with GET /api/v1/organizations/{ORG_ID}/roles because they are generated per deployment. Keep that admin key in a secrets manager and out of CI logs.

Privileged code paths in the framework

In the library, privilege sits with whoever defines tools, system prompts and agent handoffs. In AgentWorkflow, each agent's can_handoff_to list limits which agents it may pass control to; set it explicitly so a low-trust agent cannot hand work to one that holds write tools. Agents stop after max_iterations (default 20 in the current core source); set a value that fits the task and a workflow timeout.

Integrations, API tokens and service accounts

LlamaParse API keys and regions

The API key page states that keys are created from the API Key page, shown only once, scoped to the creating user and to the project they were created in, and revocable, with revocation eventually consistent within about a minute. It recommends never hardcoding keys, storing them in environment variables or a key management service, rotating periodically and using separate keys for development and production. The client reads LLAMA_CLOUD_API_KEY.

LlamaParse runs in two regions: North America (https://api.cloud.llamaindex.ai, AWS us-east-1) and Europe (https://api.cloud.eu.llamaindex.ai, AWS eu-central-1). The client selects a region through its base URL, for example LlamaCloud(api_key=..., base_url="https://api.cloud.eu.llamaindex.ai"), and tokens issued in one region are rejected by the other. Set the base URL in configuration, not code defaults, so an EU workload cannot silently send documents to the North America endpoint.

Data handling on LlamaParse

The data privacy page states that customer data is not used for model training by default (organisation administrators can opt in to a data-sharing programme), that customer files are encrypted at rest with AES-256 and in transit with TLS 1.2 or higher, and that subprocessor and security documentation is in the LlamaIndex Trust Center. Confirm the data-sharing setting stays off unless your organisation has chosen otherwise.

Agent tools and MCP

• Bound parameters: create tools with FunctionTool.from_defaults(fn, partial_params={...}) so identifiers such as user ID or tenant come from your session, not the model. This is the main defence against a prompt-injected agent querying another user's records.
• Human approval: for dangerous actions, have the tool emit an InputRequiredEvent and wait for a HumanResponseEvent using ctx.wait_for_event, as the human in the loop guide shows. See the Human-in-the-Loop for AI Agents Guide.
• MCP: llama-index-tools-mcp provides BasicMCPClient (SSE, streamable HTTP or a local process) and McpToolSpec, which accepts an allowed_tools list and partial_params. Load only the tools the agent needs, connect only to trusted servers, and run local-process servers with the least privilege possible. See the MCP Security Guide.
• Provider keys: one key per application and environment, with spend limits at the provider, read from a secrets manager at start-up.

Securing loaders, retrieval and query engines

Most LlamaIndex risk sits in what flows into the prompt. Map each component to its control:

For text-to-SQL, the LlamaIndex structured data guide warns that executing arbitrary SQL is a security risk and recommends restricted roles, read-only databases and sandboxing. SQLDatabase accepts include_tables or ignore_tables to limit the schema the model sees, and sample_rows_in_table_info controls whether sample rows, which may be sensitive, go into the prompt. Set it to zero for regulated tables. For permission-aware retrieval patterns, see the Permission-Aware RAG Guide.

Decision guidance: one index per tenant is simplest to reason about and suits a few large tenants; a shared index with mandatory metadata filters scales to many small tenants but depends on every code path applying the filter, so wrap retrieval in one function that always adds it. For regulated data, prefer the fully local stack the privacy page describes, or a cloud provider under an existing data protection agreement.

Logging and detection

Observability in LlamaIndex runs through the instrumentation module (from v0.10.20), with dispatchers, events and spans; the legacy CallbackManager is still used by some integrations. The OpenTelemetry integration traces events from LLMs, agents and RAG components and can export to any OpenTelemetry backend with a custom span exporter. Custom handlers subclass BaseEventHandler, which lets you send security events to your SIEM without third-party services. Traces contain prompts, retrieved chunks and outputs, so treat the trace store as sensitive data with its own access control and retention. See OpenTelemetry GenAI Semantic Conventions for Security Teams.

Alert on:

• Tool calls with arguments outside expected ranges, and any write tool called without a matching human response event.
• Generated SQL containing statements other than SELECT, or touching tables outside the allowlist (log the SQL before execution).
• Retrieval queries returning nodes whose tenant metadata differs from the caller's.
• Agents reaching max_iterations or the workflow timeout repeatedly.
• LlamaParse key creation, membership changes and calls from unexpected networks, from your gateway or egress logs.

Metrics: share of tools with bound sensitive parameters; share of retrievers that pass through the filtered retrieval wrapper (target 100 percent); text-to-SQL engines on read-only roles (target 100 percent); LlamaParse keys older than your rotation period (target zero); and organisation members reviewed in the last quarter.

Hardening baseline

1. Inventory every reader, index, query engine, agent, tool, MCP server and hosted service, with the credential each uses.
2. Classify data and choose hosted, partly local or fully local processing per class before ingesting anything.
3. Harden ingestion: allowlist sources, validate URLs and paths in the application, add tenant and provenance metadata to every node.
4. Enforce retrieval permissions through a single wrapper that applies MetadataFilters; test with a second tenant's account that it returns nothing.
5. Constrain query engines and tools: read-only SQL roles, include_tables, partial_params, allowed_tools, can_handoff_to and human approval events for writes.
6. Secure LlamaParse: separate organisations for production, SSO where available, ViewerV2 for read-only self-hosted members, per-environment keys in a secrets manager, explicit region base URL.
7. Instrument with the OpenTelemetry integration or a custom handler, protect the trace store and build the alerts above.
8. Test with injected instructions in documents and tool outputs before each release; roll back by redeploying the previous index version and application build, which is why indexes should be versioned.

Common misconfigurations

• Library exposed as the web layer: a thin HTTP handler passes user-supplied URLs and file paths straight to readers, when the security policy places that validation with the application.
• Text-to-SQL on an owner account: the engine connects with the application's read-write database user and sees every table, including sample rows in the prompt.
• Filters applied in some code paths only: the chat endpoint filters by tenant but a summarisation job or agent tool calls the retriever directly.
• Model-chosen identifiers: a tool takes user_id as a model argument instead of a bound partial_params value.
• Shared personal LlamaParse keys: one developer's key used in production, so a departure or rotation breaks the service and actions cannot be attributed.
• Region left at default: an EU workload calls the North America base URL because the client was created without base_url.

Practitioner checklist

• Validate URLs, file paths and input sizes in the application before any reader runs.
• Choose hosted or local model, embedding and reranking per data class, and scrub PII where needed.
• Tag every node with tenant and provenance metadata and enforce MetadataFilters through one wrapper.
• Run text-to-SQL on a read-only role with include_tables and no sample rows for sensitive tables.
• Bind user and tenant identifiers with partial_params; require a human response event for writes.
• Limit MCP tools with allowed_tools and set can_handoff_to, max_iterations and timeouts.
• Use per-environment LlamaParse keys in a secrets manager, rotate them and set the region base URL explicitly.
• Restrict production LlamaParse organisations, use SSO and ViewerV2 where available, and review members quarterly.
• Export instrumentation to your monitoring stack and protect traces as sensitive data.

Standards and references

• LlamaIndex: Security Policy
• LlamaIndex: Privacy and Security
• LlamaIndex: A Guide to LlamaIndex and Structured Data
• LlamaIndex: Human in the loop
• LlamaParse: API Key
• LlamaParse: User Roles
• LlamaParse: Data Privacy and Security
• OWASP: Top 10 for LLM Applications 2025

Related NHI Mgmt Group resources: Securing Agent Frameworks Guide, RAG Security Guide, Permission-Aware RAG Guide, Prompt Injection Guide.