Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Shell: Spouštění příkazů

Lekce 18 z 20 Vývojář
Na této stránce
  1. Shell: Spouštění příkazů
  2. Koncept a architektura
  3. Případ použití: Systémová diagnóza
  4. Zabezpečení provádění
  5. Implementace jako vlastní funkce
  6. Pracovní postupy automatizace
  7. Klíčové poznatky

Shell: Spouštění příkazů

Toto je nejmocnější nástroj v tomto kurzu a zároveň jediný, kde může chyba obrátit jeho sílu proti tobě. Ostatní nástroje pouze čtou, počítají nebo hledají; tento na stroji přímo jednají. Špatně formulovaná systémová diagnóza zůstane jen diagnózou; špatně formulovaný příkaz pro úklid smaže soubory.

Tato lekce pokrývá použití i bezpečnostní opatření společně, protože je nelze oddělit. Zlaté pravidlo zní: model nesmí nikdy spustit příkaz, který jsi předem výslovně neschválil.

Koncept a architektura

Rozdíl oproti Code Interpreter je zásadní a shrnuje se do jednoho slova: izolace. Code Interpreter běží v jednorázovém sandboxu izolovaném od sítě, kde je nejhorším scénářem špatný výpočet. Shell běží v prostředí, které konfiguruješ ty – potenciálně na tvém lokálním stroji, potenciálně na serveru – kde je nejhorším scénářem nevratná operace.

Tato svoboda je smyslem celého nástroje: bez ní by automatizované nasazování a údržba byly nemožné. Vyžaduje však, abys vědomě zvolil rozsah provádění. Vyhrazený kontejner s omezenými oprávněními je téměř vždy lepší volbou než přímý přístup k hostiteli.

from openai import OpenAI

client = OpenAI()

# The Shell tool is used via the Agents SDK
# because it requires a controlled execution environment
from agents import Agent, Runner

agent = Agent(
    name="devops-assistant",
    model="gpt-5.6-terra",
    instructions=(
        "You are a DevOps assistant. You execute system commands "
        "to diagnose and resolve infrastructure issues. "
        "Explain each command before executing it."
    ),
    tools=[{"type": "shell"}]
)

Případ použití: Systémová diagnóza

# The agent can execute diagnostic commands
agent = Agent(
    name="diagnostic",
    model="gpt-5.6-terra",
    instructions=(
        "Diagnose the system state by executing appropriate commands. "
        "Start with basic checks (disk, memory, CPU) "
        "then dig deeper based on symptoms."
    ),
    tools=[{"type": "shell"}]
)

# The agent will execute commands like:
# df -h          -> disk space
# free -m        -> memory
# top -bn1       -> CPU load
# systemctl status nginx  -> service status

Zabezpečení provádění

Společně fungují tři bezpečnostní opatření, přičemž žádné z nich není samo o sobě dostatečné. Základem je allowlist (seznam povolených): vyjmenuješ, co je povoleno, nikoliv co je zakázáno, protože blocklist (seznam zakázaných) vždy nějakou variantu přehlédne – a stačí jen jedna. Časový limit (timeout) zabrání tomu, aby zaseknutý příkaz zastavil systém. Omezený pracovní adresář limituje škody v případě, že legitimní příkaz ukazuje na špatné místo.

Čtvrté opatření není technické, ale stojí za všechna ostatní tři dohromady: vyžaduj lidské potvrzení pro jakoukoli destruktivní nebo nevratnou operaci. Model se může mýlit se stejnou jistotou, s jakou má pravdu.

# Pattern: wrapper function with validation
import subprocess
import shlex

ALLOWED_COMMANDS = {
    "diagnostic": ["df", "free", "top", "uptime", "ps", "netstat", "curl", "ping"],
    "deployment": ["git", "docker", "npm", "pip"],
    "files": ["ls", "cat", "head", "tail", "wc", "grep", "find"],
}

FORBIDDEN_COMMANDS = ["rm", "dd", "mkfs", "shutdown", "reboot", "kill", "passwd"]

def execute_secure_command(command: str, category: str = "diagnostic") -> dict:
    """Executes a command with security validation."""
    # Parse the command
    parts = shlex.split(command)
    executable = parts[0]

    # Check prohibitions
    if executable in FORBIDDEN_COMMANDS:
        return {
            "error": f"Forbidden command: {executable}",
            "reason": "This command is on the blocklist"
        }

    # Check permissions
    allowed = ALLOWED_COMMANDS.get(category, [])
    if executable not in allowed:
        return {
            "error": f"Command not allowed in category '{category}'",
            "allowed": allowed
        }

    # Execute with timeout
    try:
        result = subprocess.run(
            parts,
            capture_output=True,
            text=True,
            timeout=30,
            cwd="/tmp"  # Restricted working directory
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "return_code": result.returncode
        }
    except subprocess.TimeoutExpired:
        return {"error": "Timeout: command exceeded 30 seconds"}

Implementace jako vlastní funkce

Implementace tohoto řešení prostřednictvím volání funkcí (function calling) nabízí výhodu, kterou bys neměl považovat za záložní variantu: validace žije v tvém kódu. Ty rozhoduješ o allowlistu, logování a krocích potvrzení a vše můžeš auditovat. U nástroje s takovou mírou rizika je lepší udržet kontrolu nad kontrolním bodem, i když se stane dostupná nativní verze.

tools = [
    {
        "type": "function",
        "name": "execute_command",
        "description": (
            "Execute a shell command on the server. "
            "Allowed commands: system diagnostics (df, free, top, uptime, ps), "
            "file reading (ls, cat, head, tail, grep), "
            "network (curl, ping, netstat). "
            "Destructive commands are forbidden."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "The shell command to execute"
                },
                "directory": {
                    "type": "string",
                    "description": "Working directory (default: /tmp)"
                }
            },
            "required": ["command"],
            "additionalProperties": False
        },
        "strict": True
    }
]

import json

def handle_calls(response):
    results = []
    for item in response.output:
        if item.type == "function_call" and item.name == "execute_command":
            args = json.loads(item.arguments)
            result = execute_secure_command(
                args["command"],
                category="diagnostic"
            )
            results.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result)
            })
    return results

# Full loop
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Check disk space and available memory",
    tools=tools
)

results = handle_calls(response)
final_response = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + results,
    tools=tools
)
print(final_response.output_text)

Pracovní postupy automatizace

Automatizované nasazování

Nasazování je nejcennějším případem použití, pokud chápeš, co deleguješ. Model nevymýšlí postup: řetězí kroky, které jsi definoval, ověřuje dílčí výstupy a při jakékoli anomálii se zastaví. Je to pozorný operátor, nikoliv rozhodovatel.

tools_deploy = [
    {
        "type": "function",
        "name": "execute_deploy_step",
        "description": (
            "Execute a deployment step. "
            "Possible steps: git_pull, tests, build, deploy, rollback. "
            "Each step is validated before proceeding to the next."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "step": {
                    "type": "string",
                    "enum": ["git_pull", "tests", "build", "deploy", "rollback"]
                },
                "parameters": {
                    "type": "object",
                    "properties": {
                        "branch": {"type": "string"},
                        "environment": {"type": "string", "enum": ["staging", "production"]}
                    }
                }
            },
            "required": ["step"],
            "additionalProperties": False
        },
        "strict": True
    }
]

def execute_step(step: str, params: dict) -> dict:
    scripts = {
        "git_pull": "cd /app && git pull origin {branch}",
        "tests": "cd /app && npm test",
        "build": "cd /app && npm run build",
        "deploy": "cd /app && ./deploy.sh {environment}",
        "rollback": "cd /app && ./rollback.sh {environment}"
    }
    command = scripts[step].format(**params)
    return execute_secure_command(command, "deployment")

Monitorování a alerty

Monitorování obrací logiku zbytku této lekce: příkazy zde jsou pouze pro čtení, takže jsou neškodné, a hodnota spočívá v interpretaci. Model, který čte využití disku, zátěž a chybové logy, odhalí korelace, které izolovaný práh přehlédne – což z něj činí nejbezpečnější vstupní bod pro začátek práce s tímto nástrojem.

def check_system_health() -> dict:
    """Checks system health and returns a report."""
    checks = {}

    # Disk space
    r = execute_secure_command("df -h /", "diagnostic")
    checks["disk"] = r

    # Memory
    r = execute_secure_command("free -m", "diagnostic")
    checks["memory"] = r

    # Services
    for service in ["nginx", "postgresql", "redis"]:
        r = execute_secure_command(
            f"systemctl is-active {service}",
            "diagnostic"
        )
        checks[f"service_{service}"] = r

    return checks

# The AI analyzes the results and suggests actions
response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analyze this system health report and identify issues:\n"
          f"{json.dumps(check_system_health(), indent=2)}",
    tools=tools
)

Klíčové poznatky

  • Nástroj Shell propojuje model s tvou infrastrukturou
  • Implementuj allowlisty a blocklisty pro příkazy
  • Používej časové limity a omezené pracovní adresáře
  • Volání funkcí ti umožňuje implementovat Shell jako vlastní nástroj
  • Kombinuj Shell s dalšími nástroji pro kompletní pracovní postupy DevOps