AstrBot Agent Sandbox Security Measures Against Malicious Hosts

AstrBot's Agent Sandbox employs a defense-in-depth architecture that combines local command filtering, filesystem path confinement, and remote container isolation with token authentication to prevent malicious hosts from executing harmful operations.

AstrBot is an open-source multi-platform chatbot framework developed by AstrBotDevs. Its Agent Sandbox provides isolated execution environments for agent-requested code and shell commands, implementing robust AstrBot Agent Sandbox security measures against malicious hosts through layered protections that restrict both command execution and filesystem access.

Local Sandbox Protections (LocalBooter)

The default LocalBooter in astrbot/core/computer/booters/local.py implements two critical safety layers for host-level protection: command filtering and path confinement. These measures ensure that even if an agent generates malicious instructions, the local execution environment remains contained.

Command Filtering with Blocked Patterns

The _is_safe_command() function validates all shell commands against a static denylist _BLOCKED_COMMAND_PATTERNS. This list includes dangerous operations like recursive deletion (rm -rf), disk formatting (mkfs), system shutdown commands, and fork bombs.

# astrbot/core/computer/booters/local.py

_BLOCKED_COMMAND_PATTERNS = [
    " rm -rf ",
    " rm -fr ",
    " rm -r ",
    " mkfs",
    " dd if=",
    " shutdown",
    " reboot",
    " poweroff",
    " halt",
    " sudo ",
    ":(){:|:&};:",
    " kill -9 ",
    " killall ",
]

def _is_safe_command(command: str) -> bool:
    cmd = f" {command.strip().lower()} "
    return not any(pat in cmd for pat in _BLOCKED_COMMAND_PATTERNS)

Any attempt to execute a blocked command raises PermissionError in LocalShellComponent.exec, preventing destructive operations before they reach the operating system.

Filesystem Path Confinement

The _ensure_safe_path() function restricts all file operations to three trusted roots: astrbot_root, astrbot_data_path, and astrbot_temp_path. This prevents agents from accessing sensitive system files or other user data outside the AstrBot environment.

# astrbot/core/computer/booters/local.py

def _ensure_safe_path(path: str) -> str:
    abs_path = os.path.abspath(path)
    allowed_roots = [
        os.path.abspath(get_astrbot_root()),
        os.path.abspath(get_astrbot_data_path()),
        os.path.abspath(get_astrbot_temp_path()),
    ]
    if not any(abs_path.startswith(root) for root in allowed_roots):
        raise PermissionError("Path is outside the allowed computer roots.")
    return abs_path

All filesystem operations—including create_file, read_file, write_file, delete_file, and list_dir—invoke this helper, ensuring that paths like /etc/passwd or system directories are inaccessible to agent processes.

Remote Sandbox Isolation (ShipyardBooter)

For high-risk environments or untrusted agent code, ShipyardBooter in astrbot/core/computer/booters/shipyard.py provides hardware-level isolation via the Shipyard/Shipyard-Neo platform. This remote sandbox architecture ensures that malicious code runs in ephemeral containers completely separated from the host machine.

Token-Based Authentication

The ShipyardClient requires bearer token authentication for all API interactions. The ShipyardBooter initializes the client with an access_token from the configuration, ensuring only the authenticated AstrBot instance can spawn and control sandbox containers.

# astrbot/core/computer/booters/shipyard.py

class ShipyardBooter(ComputerBooter):
    def __init__(self, endpoint_url: str, access_token: str, ttl: int = 3600,
                 session_num: int = 10) -> None:
        self._sandbox_client = ShipyardClient(
            endpoint_url=endpoint_url, access_token=access_token
        )
        ...

This token-based approach prevents unauthorized entities from accessing the remote sandbox API, even if the endpoint URL is discovered.

Health Check Validation

Before reusing any remote container, the available() method performs proactive health checks via get_ship(). If the container reports status != 1 or returns no data, it is marked unhealthy and discarded, preventing persistence of compromised environments.

# astrbot/core/computer/booters/shipyard.py

async def available(self) -> bool:
    try:
        ship_id = self._ship.id
        data = await self._sandbox_client.get_ship(ship_id)
        if not data:
            logger.info("[Computer] Shipyard sandbox health check: id=%s, healthy=False (no data)", ship_id)
            return False
        health = bool(data.get("status", 0) == 1)
        logger.info("[Computer] Shipyard sandbox health check: id=%s, healthy=%s", ship_id, health)
        return health
    except Exception as e:
        logger.error(f"Error checking Shipyard sandbox availability: {e}")
        return False

This validation ensures that each agent session runs in a verified clean environment, eliminating the risk of cross-contamination from previous malicious executions.

Configuration Audit and Validation

The dashboard route in astrbot/dashboard/routes/config.py implements _compare_and_log_sandbox_changes() to audit all configuration modifications. When users modify sandbox settings, the system logs the specific changes with old and new values, creating an immutable record of security-critical configuration drift.

# astrbot/dashboard/routes/config.py

def _compare_and_log_sandbox_changes(old_ps, new_ps):
    old_sandbox = old_ps.get("sandbox", {})
    new_sandbox = new_ps.get("sandbox", {})
    ...
    logger.info("[Computer] Config changed: sandbox.%s %s -> %s", key, old_val, new_val)

Only configurations passing validation (requiring valid endpoint_url and access_token for remote mode) activate the Agent Sandbox, preventing accidental exposure of insecure sandbox settings.

Summary

• Command Filtering: Static denylist blocks dangerous shell patterns including rm -rf, mkfs, and fork bombs via _is_safe_command() in local.py.
• Path Confinement: Filesystem operations restricted to AstrBot directories via _ensure_safe_path(), preventing access to system files like /etc/passwd.
• Remote Isolation: Shipyard containers provide hardware-level separation with token-authenticated API access via ShipyardBooter.
• Health Monitoring: Proactive container validation via available() prevents reuse of compromised remote environments.
• Audit Logging: Configuration changes tracked via _compare_and_log_sandbox_changes() ensure accountability for security settings.

Frequently Asked Questions

What shell commands are blocked by AstrBot's local sandbox?

The local sandbox blocks commands containing dangerous patterns defined in _BLOCKED_COMMAND_PATTERNS within astrbot/core/computer/booters/local.py. Blocked patterns include recursive deletion commands (rm -rf, rm -fr), disk formatting (mkfs), direct disk writes (dd if=), system shutdowns (shutdown, reboot, poweroff), privilege escalation (sudo), fork bombs (:(){:|:&};:), and process termination utilities (kill -9, killall). The _is_safe_command() function converts commands to lowercase and checks for these substrings, raising PermissionError if any match is found.

How does AstrBot prevent agents from escaping the sandbox directory?

AstrBot enforces filesystem isolation through the _ensure_safe_path() function in astrbot/core/computer/booters/local.py. This function resolves all paths to absolute form and verifies they start with one of three trusted roots: astrbot_root, astrbot_data_path, or astrbot_temp_path. If a requested path falls outside these directories—such as system paths like /etc/passwd or /root/—the function raises PermissionError with the message "Path is outside the allowed computer roots." All file operations including create_file, read_file, write_file, and delete_file invoke this validation helper.

What authentication protects the remote Shipyard sandbox?

The remote Shipyard sandbox uses bearer token authentication implemented in astrbot/core/computer/booters/shipyard.py. The ShipyardBooter class initializes a ShipyardClient with an access_token parameter sourced from the AstrBot configuration. This token must be included in all API requests to the remote sandbox endpoint. The authentication ensures that even if the endpoint URL is exposed, unauthorized entities cannot spawn containers or execute code within the AstrBot sandbox environment. Configuration validation requires both endpoint_url and access_token before enabling remote sandbox mode.

How does AstrBot verify remote sandbox containers are secure before reuse?

AstrBot implements proactive health checking through the available() method in astrbot/core/computer/booters/shipyard.py. Before reusing an existing container for agent execution, this method queries the remote ship via get_ship() and validates that the returned data contains status == 1. If the container reports any other status, returns no data, or raises an exception, the method returns False and the ShipyardBooter discards the unhealthy container. This prevents the reuse of potentially compromised or corrupted environments, ensuring each agent session runs in a verified clean state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}