Security

Reporting a Vulnerability

If you discover a security vulnerability in miqi, please report it by:

1. DO NOT open a public GitHub issue
2. Create a private security advisory on GitHub or contact the repository maintainers (xubinrencs@gmail.com)
3. Include:
4. Description of the vulnerability
5. Steps to reproduce
6. Potential impact
7. Suggested fix (if any)

We aim to respond to security reports within 48 hours.

Security Best Practices

1. API Key Management

CRITICAL: Never commit API keys to version control.

# ✅ Good: Store in config file with restricted permissions
chmod 600 ~/.miqi/config.json

# ❌ Bad: Hardcoding keys in code or committing them

Recommendations: - Store API keys in ~/.miqi/config.json with file permissions set to 0600 - Consider using environment variables for sensitive keys - Use OS keyring/credential manager for production deployments - Rotate API keys regularly - Use separate API keys for development and production

2. Channel Access Control

IMPORTANT: Always configure allowFrom lists for production use.

{
  "channels": {
      "feishu": {
      "enabled": true,
         "appId": "cli_...",
         "appSecret": "...",
         "allowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

Security Notes: - Empty allowFrom list will ALLOW ALL users (open by default for personal use) - Prefer explicit user/chat allowlists before exposing the gateway to any real users - Review access logs regularly for unauthorized access attempts

3. Shell Command Execution

The exec tool can execute shell commands. Today it uses a static deny-list safety guard, optional workspace restriction, and credential-environment stripping for spawned subprocesses. The separate helper in miqi/agent/command_approval.py exists in the repository, but it is not yet wired into the packaged CLI/gateway shell path.

You should still:

• ✅ Review all tool usage in agent logs
• ✅ Understand what commands the agent is running
• ✅ Use a dedicated user account with limited privileges
• ✅ Never run miqi as root
• ❌ Don't disable security checks
• ❌ Don't run on systems with sensitive data without careful review

Blocked patterns include: - rm -rf / - Root filesystem deletion - Fork bombs - Filesystem formatting (mkfs.*) - Raw disk writes - sudo — privilege escalation - eval — dynamic code evaluation - source / . — script sourcing - Backtick substitution `cmd` — command injection via legacy syntax - $() substitution inside quoted strings — shell command injection - Pipe-to-shell (| bash, | sh, | zsh, etc.) — piped execution of untrusted input - curl/wget piped to python/python3 — remote code execution via download - Other destructive operations

4. File System Access

File operations have path traversal protection, but:

• ✅ Run miqi with a dedicated user account
• ✅ Use filesystem permissions to protect sensitive directories
• ✅ Regularly audit file operations in logs
• ❌ Don't give unrestricted access to sensitive files

5. Network Security

API Calls: - All external API calls use HTTPS by default - Timeouts are configured to prevent hanging requests - Consider using a firewall to restrict outbound connections if needed

MCP subprocesses: - Stdio MCP servers inherit the MiQi process environment when tools.mcpServers.<name>.env is omitted - Treat stdio MCP servers as trusted local code, or explicitly provide a minimal env mapping - HTTP MCP servers can use headers for explicit auth instead of inheriting process credentials

Channel adapters: - Use HTTPS webhook endpoints only - Validate platform signatures/tokens for incoming callbacks - Restrict source IP ranges when your platform supports it

6. Dependency Security

Critical: Keep dependencies updated!

# Check for vulnerable dependencies
pip install pip-audit
pip-audit

# Update to latest secure versions
pip install --upgrade miqi

Important Notes: - Keep openai and anthropic SDKs updated to the latest version for security fixes - We've updated ws to >=8.17.1 to fix DoS vulnerability - Run pip-audit regularly - Subscribe to security advisories for miqi and its dependencies

7. Production Deployment

For production use:

1. Isolate the Environment

   # Run in a container or VM
   docker run --rm -it python:3.11
   pip install miqi
   

2. Use a Dedicated User

   sudo useradd -m -s /bin/bash miqi
   sudo -u miqi miqi gateway
   

3. Set Proper Permissions

   chmod 700 ~/.miqi
   chmod 600 ~/.miqi/config.json
   

4. Enable Logging

   # Configure log monitoring
   tail -f ~/.miqi/logs/miqi.log
   

5. Use Rate Limiting

6. Configure rate limits on your API providers
7. Monitor usage for anomalies

8. Set spending limits on LLM APIs

9. Regular Updates

   # Check for updates weekly
   pip install --upgrade miqi
   

8. Development vs Production

Development: - Use separate API keys - Test with non-sensitive data - Enable verbose logging - Use a test Feishu app or isolated staging workspace

Production: - Use dedicated API keys with spending limits - Restrict file system access - Enable audit logging - Regular security reviews - Monitor for unusual activity

9. Data Privacy

• Logs may contain sensitive information - secure log files appropriately
• LLM providers see your prompts - review their privacy policies
• Chat history is stored locally - protect the ~/.miqi directory
• API keys are in plain text - use OS keyring for production

10. Incident Response

If you suspect a security breach:

1. Immediately revoke compromised API keys
2. Review logs for unauthorized access

   grep "Access denied" ~/.miqi/logs/miqi.log
   

3. Check for unexpected file modifications
4. Rotate all credentials
5. Update to latest version
6. Report the incident to maintainers

Security Features

Built-in Security Controls

✅ Input Validation - Path traversal protection on file operations - Dangerous command deny-list for exec - Input length limits on HTTP requests

✅ Authentication - Allow-list based access control - Failed authentication attempt logging - Open by default (configure allowFrom for production use)

✅ Resource Protection - Command execution timeouts (60s default) - exec output truncation (10KB limit) - Live prompt tool-result truncation (agents.defaults.maxToolResultChars, default 16000) - Per-tool timeout override support (for example MCP toolTimeout) - HTTP request timeouts (10–30s) - SSRF protection — web tool blocks requests to private/link-local/loopback IP ranges (10.x, 172.16/12, 192.168.x, 127.x, 169.254.x, IPv6 equivalents)

✅ Secure Communication - HTTPS for all external API calls - TLS for Telegram API - TLS/Webhook verification for Feishu API calls

✅ Container Hardening - Container runs as unprivileged user miqi (UID 1000) — not root - Gateway port bound to 127.0.0.1 by default in Docker Compose - Volume mount uses user home directory, not /root

✅ MCP Runtime Controls - Per-server toolTimeout and progressIntervalSeconds - Optional lazy gateway mode to avoid sending large MCP tool lists on every model call - Explicit env and headers fields per MCP server

Known Limitations

⚠️ Current Security Limitations:

1. No Rate Limiting - Users can send unlimited messages (add your own if needed)
2. Plain Text Config - API keys stored in plain text (use keyring for production)
3. No Session Management - No automatic session expiry
4. Command Filtering - Dangerous patterns are blocked (see list above), but a determined attacker with arbitrary command execution can still cause damage — always run with a dedicated low-privilege account
5. MCP Environment Inheritance - Stdio MCP servers inherit the parent process environment unless you explicitly provide tools.mcpServers.<name>.env
6. Limited Audit Trail - Security events are logged via loguru but there is no structured SIEM integration

Security Checklist

Before deploying miqi:

• [x] Container runs as unprivileged user miqi (UID 1000) — automatic when using Docker
• [x] Memory / session files written with 0600 permissions — automatic
• [x] SSRF protection — web tool blocks requests to private/link-local IP ranges — automatic
• [ ] API keys stored securely (not in code)
• [ ] Config file permissions set to 0600
• [ ] allowFrom lists configured for all channels
• [ ] Running as non-root user (bare-metal deploys)
• [ ] File system permissions properly restricted
• [ ] Dependencies updated to latest secure versions
• [ ] Logs monitored for security events
• [ ] Rate limits configured on API providers
• [ ] Backup and disaster recovery plan in place
• [ ] Security review of custom skills/tools

Updates

Last Updated: 2026-04-11

For the latest security updates and announcements, see:

• GitHub Security Advisories
• Releases