Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Shell: Käskude täitmine

Õppetund 18 / 20 Arendajatele
Sellel lehel
  1. Shell: Käskude täitmine
  2. Kontseptsioon ja arhitektuur
  3. Kasutusjuhtum: Süsteemidiagnoos
  4. Täitmise turvamine
  5. Rakendamine kohandatud funktsioonina
  6. Automatiseerimise töövoogud
  7. Peamised punktid

Shell: Käskude täitmine

See on selle kursuse võimsaim tööriist ja ainus, kus viga võib pöörata selle jõu sinu vastu. Teised tööriistad loevad, arvutavad või otsivad; see tegutseb masinal. Halvasti sõnastatud süsteemidiagnoos jääb lihtsalt diagnoosiks; halvasti sõnastatud puhastuskäsk kustutab faile.

Selles õppetükis käsitletakse kasutamist ja kaitsemeetmeid koos, sest neid ei saa lahutada. Kuldreegel: mudel ei tohi kunagi käivitada käsku, mida sa pole eelnevalt selgesõnaliselt heaks kiitnud.

Kontseptsioon ja arhitektuur

Erinevus Code Interpreterist on kriitiline ja taandub ühele sõnale: isolatsioon. Code Interpreter töötab ühekordses, võrgust isoleeritud liivakastis, kus halvim stsenaarium on vale arvutus. Shell töötab keskkonnas, mille sina konfigureerid – olgu see siis sinu kohalik masin või server –, kus halvim stsenaarium on pöördumatu operatsioon.

See vabadus ongi mõte: ilma selleta on automatiseeritud juurutamine ja hooldus võimatu. See nõuab siiski, et valiksid teadlikult täitmise ulatuse. Piiratud õigustega spetsiaalne konteiner on peaaegu alati õige valik võrreldes otsese hostile juurdepääsuga.

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

Kasutusjuhtum: Süsteemidiagnoos

# 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

Täitmise turvamine

Kolm kaitsemehhanismi töötavad koos ja ükski neist ei ole üksi piisav. Lubatud nimekiri (allowlist) on alus: loetled üles, mis on lubatud, mitte mis on keelatud, sest keelatud nimekiri jätab alati mõne variandi vahele – ja piisab vaid ühest. Ajalimiit takistab kinni jäänud käsul süsteemi blokeerimast. Piiratud töökataloog piirab kahju, kui legitiimne käsk viitab valesse asukohta.

Neljas kaitsemeede, mis pole tehniline, kuid kaalub üles ülejäänud kolm kokku: nõua inimkinnitust iga destruktiivse või pöördumatu operatsiooni jaoks. Mudel teeb vigu sama enesekindlalt, kui ta on õiges.

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

Rakendamine kohandatud funktsioonina

Selle ise funktsioonikutse kaudu rakendamine pakub eelist, mida ei tohiks pidada varuplahenduseks: valideerimine elab sinu koodis. Sina otsustad lubatud nimekirja, logimise ja kinnitussammud ning saad kõike auditeerida. Sellise riskitasemega tööriista puhul on kontrollpunkti enda käes hoidmine eelistatav isegi siis, kui saadaval on nativ-versioon.

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)

Automatiseerimise töövoogud

Automatiseeritud juurutamine

Juurutamine on kõige väärtuslikum kasutusjuhtum, eeldusel et mõistad, mida delegeerid. Mudel ei leiuta protseduuri välja: ta aheldab kokku sinu defineeritud sammud, kontrollib vahepealseid väljundeid ja peatub iga anomaalia korral. See on tähelepanelik operaator, mitte otsustaja.

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

Jälgimine ja hoiatused

Jälgimine pöörab selle õppetüki ülejäänud osa loogika tagurpidi: siinsed käsud on ainult lugemiseks, seega on need kahjutud, ja väärtus peitub tõlgendamises. Mudel, mis loeb kettaruumi, koormust ja vealogisid, märkab korrelatsioone, mida isoleeritud lävend ei märka – muutes selle ohutuimaks sisenemispunktiks selle tööriista kasutamise alustamisel.

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
)

Peamised punktid

  • Shelli tööriist ühendab mudeli sinu taristuga
  • Rakenda käskude jaoks lubatud ja keelatud nimekirjad
  • Kasuta ajalimiite ja piiratud töökatalooge
  • Funktsioonikutse võimaldab rakendada Shelli kohandatud tööriistana
  • Kombineeri Shell teiste tööriistadega terviklike DevOpsi töövoogude jaoks