Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Shell: Eżekuzzjoni tal-Kmandi

Lezzjoni 18 / 20 Zviluppatur
F'din il-paġna
  1. Shell: Eżekuzzjoni tal-Kmandi
  2. Kunċett u Arkitettura
  3. Każ ta’ Użu: Dijanjosi tas-Sistema
  4. Sigurtà tal-Eżekuzzjoni
  5. Implimentazzjoni bħala Funzjoni Customizzata
  6. Flussi ta’ Ħidma ta’ Awtomazzjoni
  7. Punti Ewlenin

Shell: Eżekuzzjoni tal-Kmandi

Din hija l-aktar għodda qawwija f’dan il-kors, u l-unika waħda fejn żball jista’ jdawwar il-qawwa tagħha kontra tiegħek. Għodod oħra jaqraw, jikkalkulaw, jew ifittxu; din taġixxi fuq magna. Dijanjosi tas-sistema mfassla ħażin tibqa’ sempliċiment dijanjosi; kmand ta’ tindifa mfassal ħażin iħassar fajls.

Din il-lezzjoni tkopri l-użu u l-miżuri ta’ sigurtà flimkien għax ma jistgħux jiġu separati. Ir-regola tad-deheb: il-mudell qatt m’għandu jeżegwixxi kmand li ma awtorizzajtx espliċitament minn qabel.

Kunċett u Arkitettura

Id-differenza mill-Code Interpreter hija kritika, u tinżel f’kelma waħda: iżolament. Il-Code Interpreter jaħdem f’sandbox li tista’ tintrema u iżolata min-netwerk fejn l-agħar xenarju possibbli huwa kalkolu żbaljat. Is-Shell taħdem f’ambjent li inti tikkonfigura—potenzjalment il-magna lokali tiegħek, potenzjalment server—fejn l-agħar xenarju possibbli huwa operazzjoni irreversibbli.

Din il-libertà hija l-għan: mingħajrha, id-distribuzzjoni u l-manutenzjoni awtomatizzata huma impossibbli. Madankollu, dan jeħtieġ li int tagħżel b’mod konxju l-ambitu tal-eżekuzzjoni. Kontenitur iddedikat b’privileġġi limitati huwa kważi dejjem l-għażla t-tajba meta mqabbel ma’ aċċess dirett għall-host.

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

Każ ta’ Użu: Dijanjosi tas-Sistema

# 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

Sigurtà tal-Eżekuzzjoni

Tliet miżuri ta’ sigurtà jaħdmu flimkien, u l-ebda waħda mhix biżżejjed waħedha. L-allowlist hija l-fondazzjoni: intielenka dak li huwa permess minflok dak li huwa pprojbit, għax lista ta’ blokok (blocklist) dejjem titlef varjant—u biżżejjed wieħed biss. Timeout jipprevjeni kmand imblukkat milli jwaqqaf is-sistema. Direttorju tax-xogħol ristrett jillimita l-ħsara jekk kmand leġittimu jipponta lejn il-post żbaljat.

Ir-raba’ miżura, mhux teknika iżda tiswi daqs it-tlieta l-oħra flimkien: itlob konferma umana għal kwalunkwe operazzjoni distruttiva jew irreversibbli. Mudell jagħmel żbalji bl-istess kunfidenza meta jkollu raġun.

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

Implimentazzjoni bħala Funzjoni Customizzata

L-implimentazzjoni ta’ dan int stess permezz tas-sejħa tal-funzjonijiet (function calling) toffri vantaġġ li m’għandekx tqisu bħala pjan ta’ riżerva: il-validazzjoni tgħix fil-kodiċi tiegħek. Inti tiddeċiedi l-allowlist, il-logging, u l-passi ta’ konferma, u tista’ tawditja kollox. Għal għodda b’dan il-livell ta’ riskju, li żżomm il-kontroll tal-punt ta’ kontroll huwa preferibbli, anke meta ssir disponibbli verżjoni nattiva.

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)

Flussi ta’ Ħidma ta’ Awtomazzjoni

Distribuzzjoni Awtomatizzata

Id-distribuzzjoni (deployment) hija l-aktar każ ta’ użu prezzjuż, sakemm tifhem x’inhu qed tiddelega. Il-mudell ma jinventax il-proċedura: iħabbat flimkien passi li ddefinixxejt int, jivverifika outputs intermedjarji, u jieqaf fuq kwalunkwe anomaliija. Huwa operatur attenti, mhux dawk li jieħdu d-deċiżjonijiet.

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

Monitoraġġ u Allerti

Il-monitoraġġ jibdel il-loġika tal-bqija ta’ din il-lezzjoni: il-kmandi hawnhekk huma biss għall-qari, allura huma innocwi, u l-valur jinsab fl-interpretazzjoni. Mudell li jaqra l-ispazju tad-diska, it-tagħbija, u l-logs tal-iżbalji jinduna b’korrelazzjonijiet li limitu iżolat jitlifhom—u dan jagħmilha l-aktar punt ta’ dħul sikur biex tibda tuża din l-għodda.

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
)

Punti Ewlenin

  • L-għodda Shell tgħaqqad il-mudell mal-infrastruttura tiegħek
  • Implimenta allowlists u blocklists għall-kmandi
  • Uża timeouts u direttorji tax-xogħol ristretti
  • Is-sejħa tal-funzjonijiet (function calling) tippermettilek timplimenta s-Shell bħala għodda customizzata
  • Għaqqad is-Shell ma’ għodod oħra għal flussi ta’ ħidma DevOps sħaħ