Security

Security policies, vulnerability reporting, and best practices for PraisonAI

Harden an Agent by enabling security defaults before it runs — injection defense, audit logging, and sandboxed execution.

from praisonaiagents import Agent
from praisonai.security import enable_security

enable_security()  # Injection defense + audit logging
agent = Agent(instructions="Help users safely")
agent.start("Summarise this document")

Security

PraisonAI takes security seriously. This page outlines our security policies, how to report vulnerabilities, and best practices for secure deployment.

Supported Versions

Latest (>= 2.0.0)

Actively maintained with security patches

Legacy (< 2.0.0)

Please upgrade to the latest version

Reporting Security Vulnerabilities

If you discover a security vulnerability, please report it responsibly to help protect the community.

GitHub Security Advisories is the preferred reporting method for fastest response.

1. Open Draft Advisory

   Navigate to github.com/MervinPraison/PraisonAI/security/advisories/new

2. Describe the Issue

   Include detailed reproduction steps and impact assessment

3. Allow Time for Fix

   Allow time for maintainers to address the issue before public disclosure

What to Include

Vulnerability Description

Clear explanation of the security issue and affected components

Reproduction Steps

Step-by-step instructions to reproduce the vulnerability

Affected Versions

Which versions of PraisonAI are impacted

Impact Assessment

Severity rating and potential consequences

Suggested Fix

Optional: Your recommendation for fixing the issue

Security Advisories

View all published security advisories:

View Advisories

Browse all published security advisories on GitHub

Report New Issue

Create a new draft security advisory

Recent Security Hardening (PR #2062)

Breaking API change: enable_injection_defense() now returns Dict[str, str] with keys "before_tool" and "before_agent" — not a single string hook ID.

# Before (PR #2062)
hook_id = enable_injection_defense()
remove_hook("before_tool", hook_id)

# After (PR #2062)
hook_ids = enable_injection_defense()
remove_hook("before_tool", hook_ids["before_tool"])
remove_hook("before_agent", hook_ids["before_agent"])

Also in PR #2062:

• execute_command blocks DANGEROUS_COMMANDS by default (allow_dangerous=False)
• search_replace and append_to_file enforce protected paths
• Audit log is thread-safe with get_audit_log().close() lifecycle API
• AgentOps init deduplicated — use is_agentops_available() instead of eager AGENTOPS_AVAILABLE in observability/hooks

Recent Security Hardening (PraisonAI #3087)

Commit d1d0272 (fixes #3087) closes a workspace-escape bug in the code-editing tools.

What changed:

• apply_diff, search_replace, and append_to_file in praisonai.code.tools previously gated their workspace-confinement check behind if workspace: and silently skipped it when no workspace was passed.
• All three now default the workspace to os.getcwd() when unset, and always enforce is_path_within_directory(...) — matching the behaviour write_file / read_file already had.

Who is affected: Anyone using praisonai.code tools (code_apply_diff, code_search_replace, code_write_file, or the low-level append_to_file) without calling set_workspace(...). Absolute paths outside cwd are now rejected with "Path '<path>' is outside the workspace".

Action required: Either call set_workspace("/intended/root") before invoking the tools, or ensure the process cwd is the intended workspace root. No action needed if you were already calling set_workspace(...).

Any workflow that never called set_workspace() and passed an absolute path outside cwd to code_apply_diff / code_search_replace / append_to_file will now fail. Set the workspace at the intended root instead.

See Code Editing → Workspace Security and Protected Paths.

Recent Security Hardening (4.6.34)

PraisonAI 4.6.34 (released May 3, 2026) introduced three critical security fixes that change default behavior:

Security Vulnerabilities Fixed

GHSA-9mqq-jqxf-grvw

Critical: Path traversal in MCP rules

GHSA-6rmh-7xcm-cpxj

High: Unauthenticated API by default

GHSA-3643-7v76-5cj2

Medium: SQL identifier injection

Breaking Changes

If you’re upgrading from 4.6.33 or earlier, your setup may break. See the migration guide below.

What changed:

1. API servers now require authentication by default - anonymous requests return 401
2. API servers bind to 127.0.0.1 by default instead of 0.0.0.0
3. MCP rules tools reject unsafe file paths - names like "../../etc/passwd" now fail
4. Knowledge backends validate identifiers - collection names must be [A-Za-z0-9_]+

Recent Security Hardening (next release — Security Batch 10)

PraisonAI’s upcoming release includes 10 security advisories worth of hardening fixes from PR #1684. Several changes are user-facing and breaking.

Security Vulnerabilities Fixed

GHSA-4mr5-g6f9-cfrh

Critical: execute_code sandbox escapes

GHSA-5c6w-wwfq-7qqm

High: spider_tools loopback bypass

GHSA-9cr9-25q5-8prj

High: MCP CLI tools path traversal

GHSA-86qc-r5v2-v6x6

High: Call server unauthenticated

GHSA-hvhp-v2gc-268q

Medium: write_file workspace escape

GHSA-5cxw-77wg-jrf3

Medium: @url: mentions SSRF

GHSA-xwq8-frcg-77q8

Low: Cross-workspace IDOR

GHSA-c2m8-4gcg-v22g

Low: Platform RBAC bypass

GHSA-xp85-6wwf-r67c

Low: CI branch injection

GHSA-3qg8-5g3r-79v5

Low: Platform default JWT secret

Breaking Changes

Four breaking changes require configuration updates before upgrading:

1. praisonai call now requires CALL_SERVER_TOKEN (or explicit opt-out) — server fails with 503 if unconfigured
2. MCP workflow_show / workflow_validate / deploy_validate no longer accept absolute or outside-cwd paths — place files in project root
3. Platform member/workspace mutation endpoints now enforce admin / owner roles — grant appropriate roles to existing clients
4. Platform refuses to issue JWTs when running with the default secret outside PLATFORM_ENV=dev — set PLATFORM_JWT_SECRET in production

Call server bind hardening (PR #2085, fixes #1602): praisonai call now binds to 127.0.0.1 by default and exposes a --host flag for explicit override. Previously bound to 0.0.0.0 unconditionally while printing a misleading http://localhost:{port} log line. If --host 0.0.0.0 is used without --public, a WARNING is printed at startup. Related advisory: GHSA-86qc-r5v2-v6x6.

Migration for API Server Users

For step-by-step migration instructions, see API Server Authentication.

Recent Security Hardening (Batch 2)

PraisonAI Security Batch 2 (merged May 19, 2026) introduces six additional critical security fixes with behavioral changes:

Security Vulnerabilities Fixed

GHSA-943m-6wx2-rc2j

High: Platform cross-workspace project access

GHSA-5jx9-w35f-vp65

High: Platform cross-workspace label access

GHSA-4x6r-9v57-3gqw

Medium: Platform cross-workspace dependencies

GHSA-27p4-pjqv-whgj

Medium: Platform cross-workspace activity logs

GHSA-6xj3-927j-6pqw

Medium: Deploy HTML sanitization missing

GHSA-vg22-4gmj-prxw

Low: Tool eval() RCE in examples

Breaking / Behavioral Changes

If you’re using platform APIs or custom tool examples, your setup may require updates.

What changed:

1. Cross-workspace IDs on platform routes now return 404 instead of leaking data - affects project, label, dependency, and issue-activity routes
2. Generated api.py from praisonai deploy now requires the bleach package at runtime for HTML sanitization
3. Custom tool eval examples switched from eval to AST allow-list - if you copied the old _safe_eval snippet, adopt the new pattern (see Safe Tool Eval)
4. WorkspaceService.delete now also removes Member rows in the same transaction - no caller action needed but SDK consumers relying on orphaned memberships should re-check fixtures

Hardened Examples

The unsafe eval(expr, {"__builtins__": {}}) pattern in examples has been replaced with an AST-based allow-list that only permits basic arithmetic operations. See the new Safe Math Eval in Custom Tools guide for the secure implementation pattern.

Recent Security Hardening (PR #1870)

PR #1870 adds filesystem-boundary enforcement to the local sandbox backends.

What changed

• DockerSandbox.write_file / read_file / list_files and SubprocessSandbox.write_file / read_file / list_files now reject any path that resolves outside the sandbox’s temp_dir.
• Rejected operations return False (write), None (read), or [] (list) and log Path traversal attempt blocked: <path>.
• Helper: praisonai.sandbox._compat.safe_sandbox_path().

Who is affected

Anyone using sandbox=True, sandbox=SandboxConfig.docker(...), or sandbox=SandboxConfig.subprocess(...) and exposing execute_python_code / execute_shell_command tools to an LLM.

Action required

None — the protection is on by default. If an agent had previously relied on writing to host paths via ../, it will now fail and should be reconfigured to write inside the sandbox root.

How It Works

Every input passes through injection defense before the Agent acts, and every tool call is recorded in the audit log.

Hook inputs are always scanned as external. The injection defense treats every string reaching the before_llm_call hook (system prompt, user prompt, prompt list) as untrusted, regardless of any _source attribute on the payload. Trust cannot be re-declared inside the hook payload — a compromised tool wrapper or mis-wired middleware cannot silently disable scanning by setting data._source = "internal".

Best Practices

Webhook Verification

Bot adapters that accept inbound webhooks verify HMAC signatures fail-closed by default — missing secrets or invalid signatures return HTTP 401. Set PRAISONAI_INSECURE_WEBHOOKS=true only for local development. See Webhook Verification.

API Key Management

Never hardcode API keys in your source code. Use environment variables instead.

import os
from praisonaiagents import Agent

agent = Agent(
    api_key=os.environ.get("OPENAI_API_KEY"),
    # ... other config
)

Sandboxed Execution

Always use sandbox mode when enabling code execution in agents.

from praisonaiagents import Agent
from praisonaiagents.agent.config import ExecutionConfig

agent = Agent(
    execution=ExecutionConfig(
        code_execution=True,
        code_mode="safe"  # Sandboxed execution
    )
)

Input Validation

Validate and sanitize user inputs before passing to agents.

from praisonaiagents.security import scan_text

result = scan_text(user_input)
if result.threat_level.value >= 3:  # HIGH or CRITICAL
    raise ValueError("Potentially malicious input detected")

How to Secure Your Agents

Secure Agent Configuration

1. Enable Security Modules

   Always enable security features before creating agents:

   from praisonai.security import enable_security
   enable_security()  # Enables injection defense + audit logging
   
2. Set Workspace Boundaries

   Define clear workspace boundaries to prevent path traversal:

   from praisonai.code import set_workspace
   set_workspace("/safe/project/directory")  # Agents cannot escape this
   
3. Use ExecutionConfig for Code

   When agents need to execute code, always use safe mode:

   from praisonaiagents.agent.config import ExecutionConfig
   
   execution = ExecutionConfig(
       code_execution=True,
       code_mode="safe",  # Sandboxed, not "unsafe"
       timeout=30  # Limit execution time
   )
   

   When using Code Mode Tool Bridge, require_approval is honoured on every tool call from within the script — a single approval does not silently unlock later calls. The feature is opt-in via code_tools=True and requires an explicit code_tools_allow list:

   execution = ExecutionConfig(
       code_execution=True,
       code_tools=True,
       code_tools_allow=["fetch", "extract_price"],  # Only these tools are callable
   )
   
4. Configure Rate Limiting

   Prevent abuse with rate limiting:

   from praisonaiagents.agent.config import ExecutionConfig
   from praisonaiagents.config import RateLimiter
   
   rate_limiter = RateLimiter(
       max_calls=100,
       per_seconds=60
   )
   execution = ExecutionConfig(rate_limiter=rate_limiter)
   
5. Add Verification Hooks

   For autonomous agents, add verification hooks:

   from praisonaiagents.agent.autonomy import AutonomyConfig
   
   autonomy = AutonomyConfig(
       verification_hooks=[my_custom_validator],
       max_iterations=10  # Prevent infinite loops
   )
   

Security Checklist

Pre-Deployment Checklist

• Security modules enabled (enable_security())
• Workspace boundaries set
• API keys in environment variables (not hardcoded)
• Code execution in “safe” mode (if enabled)
• Rate limiting configured
• Protected paths reviewed
• Input validation enabled

Runtime Security Checklist

• Audit logging active
• Injection defense scanning all inputs
• Path traversal protection enabled
• Tool execution timeout set
• Memory limits configured
• Error handling doesn’t leak sensitive info

Production Hardening

• Network egress restricted
• Container sandboxing enabled
• Secrets management (Vault/AWS Secrets/etc.)
• Log aggregation configured
• Monitoring and alerting active
• Regular dependency updates
• Security scanning in CI/CD

FileMemory user_id sanitisation

FileMemory(user_id=...) strips whitespace, rejects path-traversal characters, and uses the sanitised value for both the in-memory user_id and the on-disk user_path. Empty or whitespace-only inputs fall back to "default". Fix landed in PR #1980 — earlier releases used the raw input for the path, so user_id=" alice " could write to a different directory than mem.user_id reported.

Secure Implementation Guide

Pattern 1: Secure Multi-Agent Workflow

This pattern shows how to configure multiple agents securely with proper isolation and monitoring.

from praisonaiagents import Agent, AgentTeam
from praisonaiagents.agent.config import ExecutionConfig
from praisonaiagents import MemoryConfig
from praisonai.security import enable_security, enable_injection_defense

# Step 1: Enable security globally
enable_security()

# Step 2: Create secure execution config
secure_execution = ExecutionConfig(
    code_execution=True,
    code_mode="safe",
    timeout=30,
    rate_limiter=RateLimiter(max_calls=50, per_seconds=60)
)

# Step 3: Configure memory with auto-save
secure_memory = MemoryConfig(
    auto_save="session_name",  # Persist securely
    history=True  # Track for audit
)

# Step 4: Create agents with security config
researcher = Agent(
    name="researcher",
    instructions="Research topics safely",
    execution=secure_execution,
    memory=secure_memory,
    tools=["search_web"]  # Whitelist allowed tools
)

writer = Agent(
    name="writer",
    instructions="Write content based on research",
    execution=secure_execution,
    memory=secure_memory
)

# Step 5: Create team with handoff security
team = AgentTeam(
    agents=[researcher, writer],
    handoffs={"researcher": [writer]},  # Explicit handoff allowed
    process="sequential"  # Controlled flow
)

team.start("Research and write about AI safety")

Pattern 2: Secure Bot Deployment

from praisonai import AgentOS
from praisonai.bots import BotConfig
from praisonai.security import enable_security

# Enable security before any bot operations
enable_security()

# Configure bot with security defaults
config = BotConfig(
    auto_approve_tools=False,  # Require approval for tool calls
    allowed_tools=["search_web", "schedule_add"],  # Bot-level whitelist (runtime)
    max_messages_per_minute=30,  # Rate limiting
    session_timeout=3600  # 1 hour session limit
)

# Note: BotConfig.allowed_tools provides per-bot runtime filtering
# For global environment-level tool whitelisting, use ALLOWED_TOOLS env var
# See: /features/allowed-tools for comprehensive collision prevention

# Deploy with platform-specific security
botos = AgentOS.from_config("botos.yaml")
botos.run()

Pattern 3: Secure Autonomous Agent

Autonomous agents require extra security measures. Always use verification hooks and iteration limits.

from praisonaiagents import Agent
from praisonaiagents.agent.autonomy import AutonomyConfig, AutonomyLevel
from praisonaiagents.agent.config import ExecutionConfig

# Strict execution limits
execution = ExecutionConfig(
    code_execution=True,
    code_mode="safe",
    timeout=10  # Short timeout for autonomous actions
)

# Autonomy with guardrails
autonomy = AutonomyConfig(
    level=AutonomyLevel.SUGGEST,  # Start conservative
    auto_escalate=False,  # Manual approval for escalation
    max_iterations=5,  # Prevent runaway loops
    verification_hooks=[
        lambda action: validate_action_safe(action),
        lambda action: check_resource_limits(action)
    ]
)

agent = Agent(
    name="autonomous_assistant",
    instructions="Help users autonomously within strict bounds",
    execution=execution,
    autonomy=autonomy,
    tools=["read_file", "write_file"]  # Limited toolset
)

# Run with explicit user approval loop
agent.run_autonomous(
    prompt="Organize my project files",
    require_approval=True  # Each action needs approval
)

Pattern 4: Secure MCP Server Integration

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

# Whitelist only specific MCP servers
allowed_mcp_servers = [
    MCP(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem"],
        env={"ALLOWED_PATHS": "/safe/data"}  # Restrict server access
    )
]

agent = Agent(
    name="mcp_agent",
    instructions="Use filesystem tools safely",
    tools=allowed_mcp_servers,
    execution=ExecutionConfig(
        code_execution=False  # Disable code exec when using MCP
    )
)

Security Hardening by Environment

Development

Enable All Logging

Set LOGLEVEL=debug for security event visibility

Use Test API Keys

Separate keys with limited quotas for dev

import os
os.environ["LOGLEVEL"] = "debug"
from praisonai.security import enable_security
enable_security()

Staging

Audit Mode

Enable full audit logging without blocking

Test Protection

Verify all security controls work

from praisonai.security import enable_audit_log
enable_audit_log()

Production

Block Mode

Enable blocking for all threat levels

Minimal Logs

Reduce verbose logging, keep audit trail

from praisonai.security import enable_security
from praisonaiagents.security import InjectionDefense

# Production: block on medium+ threats
defense = InjectionDefense(blocking_threshold="MEDIUM")
enable_security(defense)

CVE Policy

PraisonAI follows responsible disclosure practices with a structured workflow:

This process typically takes 1-3 business days from report to CVE assignment.

Security Features

Path Traversal Protection

Prevents agents from accessing files outside the designated workspace

Injection Defense

Scans for prompt injection attempts before processing

Protected Paths

Blocks modification of sensitive system files and directories

Audit Logging

Thread-safe JSONL audit log for tool calls

Optional Security Modules

from praisonai.security import enable_security, enable_injection_defense

# Enable all security features
enable_security()

# Or enable specific features
enable_injection_defense()

Secrets in Deployment

PraisonAI never passes secrets via command line arguments, which prevents exposure in process lists, shell history, and CI logs.

Secure Cloud Deployment

When deploying to cloud platforms, PraisonAI automatically handles secrets securely:

from praisonai.deploy import Deploy, DeployConfig, DeployType, CloudProvider

config = DeployConfig(
    type=DeployType.CLOUD,
    cloud=CloudConfig(
        provider=CloudProvider.GCP,
        # Secrets are handled via secure temp files, not argv
        env_vars={
            "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY"),
            "DATABASE_URL": os.getenv("DATABASE_URL")
        }
    )
)

deploy = Deploy(config, "agents.yaml")
result = deploy.deploy()  # Uses --env-vars-file with chmod 0600

The deployment process:

1. Creates temp YAML via tempfile.mkstemp() with mode 0600 (owner read/write only)
2. Writes secrets to temp file instead of command line
3. Passes via --env-vars-file to gcloud command
4. Removes temp file in finally block, even if deployment fails

Reference: See GCP Deploy Documentation for implementation details.

Secret handling for gateway credentials

Gateway channel credentials — token, app_token, and verify_token — support a first-class { source, id } reference so tokens never live in YAML or a process-wide env var.

• Zero secrets in YAML, zero in the process env. { source: file, id: /run/secrets/token } reads a mounted Docker / Kubernetes secret; { source: exec, id: "vault read ..." } runs a secret-manager CLI. Neither is inherited by child processes.
• Automatic log redaction. Every resolved secret is registered so it is scrubbed from logs and tracebacks — tokens never leak into errors.
• Availability probe never prints values. praisonai gateway doctor reports each field as available / configured-but-unavailable / configured / missing without revealing the value, so operators can validate wiring before start-up.

Secret References

Load gateway credentials from files, env vars, or secret managers — never plaintext

Gateway Edge Protections (PR #2623)

Internet-exposed praisonai serve gateway deployments now have two default-on guards that require no configuration:

• PreauthConnectionBudget — caps concurrent unauthenticated WebSocket connections per source IP (preauth_max_connections_per_ip=32). Connections that exceed the cap are closed before auth runs with WebSocket close code 4029. Loopback is always exempt.
• UnauthorizedFloodGuard — closes a connection that sends too many unauthorized frames on a single session (max_unauthorized_frames=10), using close code 4028. Distinct from the existing 4008 handshake rate-limit code so clients can handle each case correctly.
• AuthRateLimiter overflow fail-closed — when the per-IP key map is saturated, new IPs are rejected rather than admitted (which would evict existing lockouts). Existing lockouts are preserved even under a fresh-IP flood.

Gateway Edge Protections

Full operator guide: defaults, YAML/Python tuning, close code reference, and when to change limits

Recent Security Hardening (PR #2850)

PR #2850 (fixes #2843) upgrades .gateway_secret handling in praisonai_bot.gateway.pairing from warn-only to remediate-or-fail-closed. The file signs pairing codes, so world-readable permissions previously allowed forged codes; the old behaviour surfaced the risk but loaded the file anyway.

Permissions are now re-checked and remediated on every PairingStore(...) construction, not only at creation:

• POSIX: an existing file with any mode other than 0o600 is chmod-ed to 0o600 on load. A failing chmod raises OSError instead of falling back to secret regeneration — preserving the HMAC signing key so outstanding pairing codes stay valid.
• Windows: best-effort ACL lockdown via icacls /inheritance:r /grant:r "<user>":F, with icacls resolved from %SystemRoot%\System32 rather than PATH to avoid a hijacked binary. This path is best-effort and never raises.
• The prior per-init WARNING ("Gateway secret file … has insecure permissions …") is removed; POSIX success logs at INFO, and Windows logs at DEBUG only.

See Bot Pairing → Secret Management.

Recent Security Hardening

Recent security improvements include:

Gateway Auth Token Unification (PR #1744):

• Config token now exports to GATEWAY_AUTH_TOKEN env var at startup
• Ensures all auth paths (HTTP, magic-link, WebSocket) use the same secret
• Config wins over environment variable to prevent stale token issues

Sandbox Resource Cleanup (PR #1744):

• SSH: Fixed temp file cleanup in finally block and remote process timeout handling
• Docker: Container naming and proper kill on timeout to enforce resource limits
• Prevents resource leaks that could lead to DoS conditions

Cloud Deploy Secret Handling (PR #1744):

• Uses secure temp YAML file with chmod 0600 instead of argv secrets
• Prevents secret exposure in ps, shell history, and CI logs
• Automatic cleanup even on deployment failures

Concurrency & Async Safety

PraisonAI includes several security hardening measures for concurrent and asynchronous execution:

Chat-History Integrity

Chat history mutations are now lock-protected to prevent lost updates and corrupt rollback in multi-agent and async scenarios:

# Safe concurrent access to chat history
agent.chat_history = new_messages  # Uses locked setter
response = agent.chat("Hello")     # Thread-safe appending

Fail-Closed Approvals

Console-backend approvals now raise PermissionError in async contexts instead of silently bypassing security checks:

# Configure non-console backend for async compatibility
from praisonaiagents.approval import get_approval_registry, WebhookBackend

get_approval_registry().set_backend(
    WebhookBackend(url="https://your-approval-service.com/approve")
)

See the Approval guide for more async-compatible backends.

Visible Failures

Previously silent failures now log at WARN level with stack traces for improved security visibility:

• Streaming callback errors (praisonaiagents.streaming.events)
• Session-gateway linkage failures (praisonaiagents.agent.execution_mixin)
• Learning-nudge generation failures (praisonaiagents.agent.tool_execution)

Monitor these log channels for potential security incidents or system anomalies.

Resources

GitHub Repository

Source code, issue tracking, and contribution guidelines

Documentation

Comprehensive guides, API reference, and tutorials

Website

Product overview, features, and enterprise solutions

Security Advisories

View and report security issues

Acknowledgments

We thank the security researchers who have responsibly disclosed vulnerabilities. Credits are listed in individual security advisories on GitHub.

Thank you to all security researchers who help make PraisonAI safer for everyone.

Related

Protected Paths

Block modification of sensitive files and directories.

Audit Logging

Thread-safe JSONL audit log for tool calls.