Flocks Docs

English

Simplified Chinese

English

Simplified Chinese

Appearance

3.7 Security Policies & Access Control

This document explains Flocks security control capabilities across product design, runtime execution, external interaction, deployment, and operations. It helps explain to customers how Flocks reduces its own exposure surface, constrains Agent behavior, audits activity, and isolates data. This document is based on the current product code and default configuration. Enterprise-edition capabilities depend on the actually licensed version.

3.7.1 Security Design Goals

Flocks is an agent-powered SecOps platform. It can connect to large models, call tools, execute commands, integrate security devices/APIs, run Workflows, and connect to IM channels. Therefore, the security design is not just about single sign-on. It provides layered controls around these goals:

  • Reduce exposure surface: Flocks listens locally by default. Remote access must be explicitly enabled, and network access should be controlled through firewalls, Nginx, or reverse proxies.
  • Trusted identity: browsers use account login and secure cookies. Programmatic clients must carry API Token. localhost is not treated as a trust boundary.
  • Minimize capabilities: Agents gain capabilities through tool allowlists. Tools can be registered, enabled, disabled, and uninstalled. API/device tools are also constrained by service switches.
  • Approve execution: sensitive operations such as command execution, file writes, and external-directory access enter a permission approval flow, with one-time, session-level, or permanent allow/deny options.
  • Isolate runtime: supports Docker deployment and can also run Agent/Workflow execution inside a Docker sandbox, limiting network, filesystem, process, and resource usage.
  • Isolate data: in multi-account mode, sessions are isolated by owner, and private sessions are visible only to their owner by default.
  • Audit process: the enterprise edition can register audit sinks for querying key events such as login, sessions, and Workflows.

3.7.2 Flocks Interaction With the Outside World

HTTP and WebUI Access

The Flocks WebUI and API are served from the same address and port. By default, they bind to 127.0.0.1:5173, avoiding direct exposure to the entire network after installation. Remote access must be explicitly configured through startup parameters:

bash
flocks start --host <host_ip>

Recommended deployment modes:

  • Single-machine/personal use: keep the default 127.0.0.1 and allow only local browser access.
  • LAN or server deployment: bind only to a specific internal IP and restrict source IPs with the host firewall.
  • Enterprise production deployment: expose the unified service entry through Nginx/gateway, forwarding both the WebUI and /api endpoint.

Browsers send API requests to the /api endpoint on the same host and port by default, avoiding direct access to a separate backend origin. CORS configuration does not automatically allow all origins just because the service is bound to 0.0.0.0; remote deployment must explicitly configure allowed origins.

Authentication Paths and Public Entries

After enabling the local account system, Flocks protects all HTTP APIs by default and only allows necessary public paths, such as:

  • WebUI onboarding page, login page, and initial administrator page;
  • Static assets;
  • Health checks;
  • Webhook paths explicitly designed for external platforms.

These webhooks need independent signature, Token, source, or replay validation.

Programmatic Client Access

TUI, SDKs, scripts, and automation clients must carry API Token. Token supports two request headers:

text
Authorization: Bearer <token>
X-Flocks-API-Token: <token>

API Token is stored in the local secret store with secret id server_api_token. This design avoids the risk of "trust any request from 127.0.0.1 by default", especially for reverse proxies, desktop clients, scripts, and local multi-process scenarios.

Network Control Strategy

Flocks outbound network access mainly includes:

  • Large-model services: access configured large-model gateways or enterprise-specified LLM domains.
  • Dependency installation: installation or upgrade may access dependency sources such as uv/PyPI, npm registry, GitHub/GHCR, and Chrome for Testing. Domestic installation scripts support mirror sources.
  • Enterprise licensing and upgrades: enterprise-edition licensing, upgrades, and component downloads require access to enterprise authorization or portal services such as passport.threatbook.cn and portalflocks.threatbook.cn; exact domains depend on the delivered version configuration.
  • Security capability integration: access the corresponding APIs for intelligence services, security devices, IM platforms, MCP services, and other capabilities enabled by the customer.

Production environments can build egress allowlists based on the actually enabled capabilities. If customers want to minimize network access, use a policy that allows only the LLM gateway, enterprise licensing/upgrade domains, and enabled security API/device domains.

IM, Webhooks, and Workflow Triggers

Flocks supports triggering sessions or Workflows through IM, email integrations, webhooks, syslog, Kafka, scheduled tasks, and other methods. Related security controls include:

  • Inbound IM messages have deduplication to avoid repeated execution from repeated delivery.
  • IM channels support allowlists to restrict users, groups, or rooms allowed to initiate requests.
  • Email integrations should configure sender allowlists and use a dedicated mailbox with an app-specific password to avoid arbitrary emails triggering Agents.
  • Feishu groups can configure groupPolicy, group ID allowlist, in-group user allowlist, and whether @bot is required.
  • Slack channels should configure user ID / channel ID allowlists and prefer app_mention, direct messages, or replies as triggers, avoiding all ordinary channel messages triggering Agents.
  • Telegram webhook validates X-Telegram-Bot-Api-Secret-Token.
  • Feishu webhook supports signature validation, verification token, timestamp validation, and replay-key deduplication.
  • Workflow webhook triggers support api_key and hmac authentication. HMAC calculates SHA256 from the request body and secret, then compares in constant time.

External Media and SSRF Controls

Some IM channels involve external media download. For WeChat-related capabilities, for example, the code applies a CDN host allowlist to media URLs, allowing only known WeChat CDN domains and restricting URL schemes to http/https to reduce SSRF risk.

3.7.3 Flocks Runtime Execution Controls

Agent Capability Model

Flocks Agents do not naturally have all system capabilities. They obtain external capabilities through tools. Agent configuration supports explicit tools allowlists:

  • Main Agent Rex handles overall orchestration and task decomposition.
  • Sub-agents can be designed to have only a specific tool set.
  • Agents without explicitly declared tools do not inherit all tools by default.
  • When delegate_task creates a sub-agent session, session permission rules are applied on top.
  • Sub-agents are forbidden from nested delegation by default, preventing permission spread and uncontrollable task chains.

Therefore, different Agents can be designed for different business scenarios, such as read-only analysis Agents, Agents that can only query device APIs, or Agents that can execute host emergency commands but require approval.

Tool Registration and Enable/Disable Controls

Flocks external capabilities are mainly carried by the tool system. Tools have these metadata and control points:

  • Tool source: built-in tools, plugin tools, MCP tools, API tools, device tools, and more.
  • Tool state: enabled, disabled, default enabled state, and user-customized state.
  • Tool ownership: API/device tools are associated with specific providers/services.
  • Tool management: supports registration, refresh, enable, disable, reset, update, and delete.

API/device tools are also controlled by service-level switches:

  • When a service is disabled, associated tools cannot actually be enabled even if they have tool-level enable configuration.
  • Tools can be disabled globally or per device instance.
  • When integrating security devices, you can choose to integrate only query APIs and not integrate APIs that execute, block, isolate, delete, or perform other actions.

Tool management interfaces are administrative operations and require administrator permission.

Tool Call Context Validation

Flocks adds extra constraints for "calling tools directly through HTTP". For built-in local tools or permission-sensitive tools, direct HTTP calls must bind to a real session_id and messageID, ensuring tool execution still occurs inside a session context and enters the permission approval flow.

Without session context, HTTP tool context cannot automatically approve permissions. This design prevents callers from bypassing Agent sessions and approval mechanisms to trigger local tools directly.

Sensitive Operation Approval

Flocks has a built-in permission approval mechanism for sensitive actions such as command execution, file writing, and external-directory access. Approval replies support:

  • allow: allow this time;
  • deny: deny this time;
  • allow_session: allow for the current session;
  • always: always allow;
  • never: always deny.

Approval requests persist pending/reply state, and the frontend or client can respond to approvals. Approval rules can come from session permissions, Agent permissions, or user actions.

Note: the system has an automatic approval switch, FLOCKS_AUTO_APPROVE=true, suitable for local development or controlled automation. It is not recommended for production or customer delivery environments.

Bash/Command Execution Controls

The Bash tool is high risk, and Flocks applies multiple layers of control:

  • Requests bash permission approval before execution.
  • Requests additional external_directory permission when the working directory is outside the current project.
  • Supports timeout control so commands do not run forever by default.
  • Supports abort and process-tree cleanup.
  • Limits output lines and bytes to avoid oversized output overwhelming the system or polluting context.
  • In sandbox mode, bash executes in a Docker container by default.
  • To elevate from sandbox execution to host execution, explicitly enable sandbox.elevated.enabled and add bash to the allowed elevated tools list.

For host emergency Agents, command-execution tools can be set to require approval so every host command executes only after user confirmation.

File and Path Security

Flocks provides basic protections for path handling and plugin script execution:

  • Sandbox path resolution blocks path escapes such as ...
  • Symlinks are checked to avoid escaping the sandbox root through symbolic links.
  • File read/write tools can enter permission approval.
  • YAML script tools can only load scripts under user or project .flocks/plugins directories, and cannot point arbitrarily to system paths for execution.
  • When importing custom-page zip files, hidden paths, file count, single-file size, and total size are limited.

Workflow Execution Controls

Workflows can be triggered manually, on a schedule, by webhook, syslog, Kafka, and other methods. Related controls include:

  • Triggers can be enabled/disabled.
  • Webhook triggers support API Key/HMAC.
  • Triggers support concurrency policies such as allow concurrent, forbid overlap, queue, drop old tasks, or drop new tasks.
  • Workflow execution records store status, input, output, logs, duration, trigger source, and other information for tracking and auditing.
  • Workflow Python execution can use sandbox runtime to reduce impact on the host.

3.7.4 Deployment Controls

Default Local Deployment

Default deployment is suitable for local use on a PC or single server:

  • Flocks unified service defaults to 127.0.0.1:5173;
  • WebUI uses /, and API requests go through /api;
  • Browser access is local;
  • Service ports are not exposed externally.

This is the default mode with minimum exposure.

Remote Access Deployment

For remote access, combine it with network-layer controls:

  • Bind only to an internal IP or specified IP and avoid unnecessary 0.0.0.0.
  • Use the host firewall to restrict access sources.
  • Use Nginx/gateway for TLS termination, access control, logging, and rate limiting.
  • The reverse proxy should forward X-Forwarded-Proto: https so the server can correctly set secure cookies.
  • Browser-side access should route API requests through /api, avoiding cross-origin access and direct backend connections.

Docker Deployment

Flocks supports Docker deployment, which is suitable when customers are concerned about affecting the PC or server host environment:

  • The service runs inside a container, with relatively isolated dependencies and runtime environment.
  • The container runs as a non-root user.
  • The user data directory can be mounted to the host through a volume.
  • Ports must be explicitly mapped with -p before they can be accessed from the host.

Docker deployment isolates the overall product runtime environment. Flocks also supports finer-grained Agent/Workflow sandboxing to isolate specific execution tasks.

Agent/Workflow Sandbox

Sandbox can control the impact of Agent or Workflow execution on the host. Default safety items include:

  • Docker container runtime;
  • network=none, no network by default;
  • Read-only root filesystem;
  • tmpfs for /tmp, /var/tmp, /run, and similar paths;
  • cap-drop=ALL;
  • no-new-privileges;
  • Configurable process count, memory, CPU, and ulimit;
  • Configurable seccomp/AppArmor;
  • Workspace access levels of none, ro, and rw;
  • Container isolation by session, agent, or shared dimensions.

These controls apply to scenarios such as executing untrusted scripts, running Workflow nodes, or letting sub-agents perform exploratory tasks.

Network Egress Control Recommendations

Customers can narrow egress according to the "minimum necessary" principle:

  • During runtime, allow only the configured large-model gateway or enterprise LLM domain.
  • Allow only business integration domains for enabled security devices/APIs, IM platforms, MCP services, and similar systems.
  • For enterprise licensing and upgrades, allow enterprise portal, passport, and upgrade package download domains.
  • During installation/upgrade windows, temporarily allow dependency sources such as GitHub/GHCR, PyPI/uv, and npm registry. These egress paths can be closed during production runtime.
  • Keep network=none for sandboxes that do not need public-network access.

3.7.5 Identity, Accounts, and Data Isolation

Local Account System

Flocks supports a local account system:

  • Initial deployment creates a single admin.
  • Supports admin/member roles.
  • Administrators can view user lists, reset passwords, and force users to change passwords.
  • Minimum password length is 8 characters, with salted scrypt hashing.
  • Temporary passwords have an expiration period.
  • Changing or resetting a password revokes existing sessions.

Session Ownership

Session data is isolated by owner:

  • Owners can read and write their own sessions.
  • Members cannot read other users' private sessions by default.
  • Admins also cannot read or delete other users' private sessions by default.
  • Explicitly shared sessions can be accessed read-only by shared users.
  • Ownerless historical sessions or ownerless sessions generated by backend/IM can be managed by admins and support ownership backfill.

Agents, Skills, and Shared Resources

Agents, Skills, plugins, and tools are platform capability resources and are usually shared. Session content and execution records are isolated by user. In enterprise delivery, customers can further define which resources are centrally maintained by administrators and which resources users may customize according to organizational management requirements.

3.7.6 Secrets and Credential Management

Flocks uses SecretManager to manage local secrets, including:

  • Large-model API Keys;
  • External API service keys;
  • MCP server keys;
  • server API token;
  • workflow trigger secrets;
  • Device credentials and more.

The default storage location is ~/.flocks/config/.secret.json. File permissions are set to 600, readable and writable only by the current system user. Tool YAML supports {secret:secret_id} placeholders, which are resolved from the secret store at runtime to avoid writing secrets directly into tool definitions.

Note: the current default implementation provides local-file minimum-permission protection and display masking. It is not encrypted storage by default. If customers have higher requirements, enterprise-edition or delivery integrations can connect to operating system keychains, KMS, Vault, or other enterprise secrets management systems.

3.7.7 Auditability and Traceability

The Flocks code provides an audit facade. The enterprise edition can register a real audit sink, write key events to storage, and provide queries. Auditable events include but are not limited to:

  • Successful/failed login;
  • User and password management operations;
  • Session creation, deletion, ownership, and related events;
  • Tool permission requests and responses;
  • Workflow execution records, trigger sources, execution status, and output summaries;
  • Enterprise licensing, upgrade requests, and license synchronization.

The OSS default audit sink is no-op. Full audit capability can be enabled after enterprise-edition authorization.

3.7.8 Plugin, Tool, and External Capability Integration Controls

Flocks supports extension through plugins, MCP, API YAML tools, device tools, and more. Recommended security controls:

  • Install plugins only from trusted sources.
  • Enable/disable API/device tools centrally by provider/service.
  • Disable or do not integrate device APIs with execution capabilities by default.
  • For tools that write, delete, isolate, block, or otherwise affect production environments, configure approval or allow only specific Agents to use them.
  • Keep path constraints for YAML script tools. Scripts should be located under .flocks/plugins.
  • Keep admin permission for plugin import and custom-page import.

3.7.9 Recommended Customer-side Control Strategy

For customers with higher security requirements, use this combination:

  1. Deployment layer

    • Do not expose to the public Internet by default;
    • Expose the unified service entry through Nginx/TLS/firewall;
    • Do not expose internal backend ports directly;
    • Configure explicit CORS origins.

  2. Account layer

    • Enable local accounts;
    • Keep administrator accounts separately managed;
    • Rotate API Token regularly;
    • Reset passwords and revoke sessions when employees leave or roles change.

  3. Execution layer

    • Disable automatic approval in production;
    • Require approval by default for bash, file writes, external directories, and host commands;
    • Place high-risk Agents in sandbox;
    • Enforce per-command approval for host emergency Agents.

  4. Tool layer

    • Enable only necessary tools;
    • Manage intelligence query tools separately from response/execution tools;
    • Prefer read-only query capability when integrating security device APIs;
    • Disable high-risk APIs per device instance or authorize them only to dedicated Agents.

  5. Network layer

    • During runtime, allow only domains required for LLM, licensing, upgrades, and enabled integrations;
    • Keep sandboxes offline by default;
    • Use temporary windows or internal mirrors for installation/upgrade dependency access.

  6. Audit layer

    • Enable the audit sink in the enterprise edition;
    • Regularly export and inspect login, tool execution, and Workflow execution records;
    • Keep traceable records for high-risk tool approvals.

3.7.10 Summary

Flocks security controls are not a single switch. They are composed of deployment exposure surface, account authentication, session isolation, Agent tool allowlists, tool enable/disable controls, permission approval, sandbox isolation, secret management, and audit tracing. Customers can choose control combinations of different strengths based on usage scenarios: secure local default use, server reverse-proxy deployment, Docker-isolated deployment, or enterprise-edition multi-account audit with strict network egress control.

Built with VitePress

Copyright © Flocks