Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Shell: Uitvoeren van commando's

Les 18 van 20 Ontwikkelaar
Op deze pagina
  1. Shell: Uitvoeren van commando’s
  2. Concept en architectuur
  3. Use case: Systeemdiagnose
  4. Uitvoering beveiligen
  5. Implementeren als aangepaste functie
  6. Automatiseringsworkflows
  7. Belangrijkste punten

Shell: Uitvoeren van commando’s

Dit is het krachtigste instrument in deze cursus, en het enige waarbij een fout zijn kracht tegen u kan keren. Andere tools lezen, berekenen of zoeken; deze handelt op een machine. Een slecht geformuleerde systeemdiagnose blijft slechts een diagnose; een slecht geformuleerd opruimcommando verwijdert bestanden.

Deze les behandelt gebruik en beveiliging samen, omdat ze niet gescheiden kunnen worden. De gouden regel: het model mag nooit een commando uitvoeren dat u niet vooraf expliciet hebt goedgekeurd.

Concept en architectuur

Het verschil met Code Interpreter is cruciaal, en het komt neer op één woord: isolatie. Code Interpreter draait in een wegwerpbare, van het netwerk geïsoleerde sandbox waar het worstcasescenario een verkeerde berekening is. Shell draait in een omgeving die u configureert—potentieel uw lokale machine, potentieel een server—waar het worstcasescenario een onomkeerbare bewerking is.

Deze vrijheid is het doel: zonder dit zijn geautomatiseerde implementatie en onderhoud onmogelijk. Het vereist echter dat u bewust de uitvoeringsscope kiest. Een toegewijde container met beperkte rechten is bijna altijd de juiste keuze boven directe hosttoegang.

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"}]
)

Use case: Systeemdiagnose

# 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

Uitvoering beveiligen

Drie beveiligingsmaatregelen werken samen, en geen enkele is op zichzelf voldoende. De allowlist is de basis: u somt op wat is toegestaan in plaats van wat verboden is, omdat een blocklist altijd een variant mist—en er is maar één nodig. Een timeout voorkomt dat een vastgelopen commando het systeem ophangt. Een beperkte werkmap beperkt de schade als een legitiem commando naar de verkeerde locatie wijst.

Een vierde maatregel, niet-technisch maar even waardevol als de andere drie samen: vereis menselijke bevestiging voor elke destructieve of onomkeerbare bewerking. Een model maakt fouten met evenveel zelfvertrouwen als wanneer het gelijk heeft.

# 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"}

Implementeren als aangepaste functie

Het zelf implementeren hiervan via function calling biedt een voordeel dat u niet als noodoplossing moet zien: validatie leeft in uw code. U bepaalt de allowlist, de logging en de bevestigingsstappen, en u kunt alles auditen. Voor een tool met dit risiconiveau is het behouden van controle over het controlepunt te verkiezen, zelfs wanneer een native versie beschikbaar komt.

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)

Automatiseringsworkflows

Geautomatiseerde implementatie

Implementatie is de meest waardevolle use case, mits u begrijpt wat u delegeert. Het model verzint de procedure niet: het koppelt stappen die u hebt gedefinieerd aan elkaar, verifieert tussenresultaten en stopt bij elke afwijking. Het is een attente operator, geen besluitvormer.

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")

Monitoring en waarschuwingen

Monitoring draait de logica van de rest van deze les om: de commando’s hier zijn read-only, dus onschadelijk, en de waarde ligt in de interpretatie. Een model dat schijfruimte, belasting en foutenlogs leest, spot correlaties die een geïsoleerde drempelwaarde mist—waarmee dit het veiligste startpunt is om met deze tool aan de slag te gaan.

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
)

Belangrijkste punten

  • De Shell-tool verbindt het model met uw infrastructuur
  • Implementeer allowlists en blocklists voor commando’s
  • Gebruik timeouts en beperkte werkmappen
  • Met function calling kunt u Shell als een aangepaste tool implementeren
  • Combineer Shell met andere tools voor complete DevOps-workflows