If you discover a security vulnerability in featherflow, 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:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We aim to respond to security reports within 48 hours.

CRITICAL: Never commit API keys to version control.

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

# ❌ Bad: Hardcoding keys in code or committing them

Recommendations:

• Store API keys in ~/.featherflow/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

IMPORTANT: Always configure allowFrom lists for production use.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789", "987654321"]
    }
  }
}

Security Notes:

• Empty allowFrom list will ALLOW ALL users (open by default for personal use)
• Get your Telegram user ID from @userinfobot
• Review access logs regularly for unauthorized access attempts

The exec tool can execute shell commands. While dangerous command patterns are blocked, you should:

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

Blocked patterns:

• 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

File operations have path traversal protection, but:

• ✅ Run featherflow 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

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

Channel adapters:

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

Critical: Keep dependencies updated!

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

# Update to latest secure versions
pip install --upgrade featherflow-ai

Important Notes:

• Keep litellm 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 featherflow and its dependencies

For production use:

1. Isolate the Environment

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

2. Use a Dedicated User

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

3. Set Proper Permissions

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

4. Enable Logging

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

5. Use Rate Limiting

   • Configure rate limits on your API providers
   • Monitor usage for anomalies
   • Set spending limits on LLM APIs

6. Regular Updates

   # Check for updates weekly
   pip install --upgrade featherflow-ai

Development:

• Use separate API keys
• Test with non-sensitive data
• Enable verbose logging
• Use a test Telegram bot

Production:

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

• 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 ~/.featherflow directory
• API keys are in plain text - use OS keyring for production

If you suspect a security breach:

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

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

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

✅ Input Validation

• Path traversal protection on file operations
• Dangerous command pattern detection
• 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)
• Output truncation (10KB limit)
• 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 featherflow (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 Tool Isolation

• Per-server allowedTools and deniedTools config fields to restrict which MCP tools the agent can invoke

⚠️ 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. Limited Audit Trail - Security events are logged via loguru but there is no structured SIEM integration

Before deploying featherflow:

• Container runs as unprivileged user featherflow (UID 1000) — automatic when using Docker
• Memory / session files written with 0600 permissions — automatic
• 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

Last Updated: 2026-02-24

For the latest security updates and announcements, check:

• GitHub Security Advisories: https://github.com/lichman0405/featherflow/security/advisories
• Release Notes: https://github.com/lichman0405/featherflow/releases

See LICENSE file for details.