Shell: Executarea comenzilor
Pe această pagină
Shell: Executarea comenzilor
Acesta este cel mai puternic instrument din acest curs și singurul în care o greșeală poate întoarce puterea sa împotriva dumneavoastră. Alte instrumente citesc, calculează sau caută; acesta acționează asupra unei mașini. Un diagnostic de sistem formulat greșit rămâne doar un diagnostic; o comandă de curățare formulată greșit șterge fișiere.
Această lecție acoperă utilizarea și măsurile de siguranță împreună, deoarece ele nu pot fi separate. Regula de aur: modelul nu trebuie niciodată să execute o comandă pe care nu ați autorizat-o explicit în prealabil.
Concept și Arhitectură
Diferența față de Code Interpreter este critică și se rezumă la un singur cuvânt: izolare. Code Interpreter rulează într-un sandbox eliminabil, izolat de rețea, unde scenariul cel mai defavorabil este un calcul eronat. Shell rulează într-un mediu configurat de dumneavoastră – potențial mașina locală, potențial un server – unde scenariul cel mai defavorabil este o operațiune ireversibilă.
Această libertate este scopul: fără ea, implementarea și mentenanța automatizate sunt imposibile. Totuși, aceasta necesită să alegeți conștient domeniul de execuție. Un container dedicat cu privilegii limitate este aproape întotdeauna alegerea corectă în detrimentul accesului direct la gazdă.
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"}]
)
Caz de utilizare: Diagnosticul sistemului
# 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
Securizarea execuției
Trei măsuri de siguranță funcționează împreună, iar niciuna nu este suficientă de una singură. Lista de permisiuni (allowlist) este fundamentul: enumerați ce este permis, nu ce este interzis, deoarece o listă de blocare (blocklist) ratează întotdeauna o variantă – și este nevoie doar de una singură. Un timeout previne blocarea sistemului de către o comandă blocată. Un director de lucru restricționat limitează daunele dacă o comandă legitimă indică o locație greșită.
O a patra măsură, non-tehnică, dar care valorează cât celelalte trei la un loc: cereți confirmarea umană pentru orice operațiune distructivă sau ireversibilă. Un model face greșeli cu aceeași încredere cu care are dreptate.
# 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"}
Implementarea ca funcție personalizată
Implementarea acestui mecanism dumneavoastră înșivă prin apelarea de funcții (function calling) oferă un avantaj pe care nu ar trebui să-l considerați o soluție de rezervă: validarea reside în codul dumneavoastră. Dumneavoastră decideți lista de permisiuni, jurnalizarea (logging) și pașii de confirmare, iar puteți audita totul. Pentru un instrument cu acest nivel de risc, menținerea controlului asupra punctului de verificare este preferabilă, chiar și atunci când o versiune nativă devine disponibilă.
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)
Fluxuri de lucru automate
Implementare automată (Deployment)
Implementarea este cel mai valoros caz de utilizare, cu condiția să înțelegeți ce delegați. Modelul nu inventează procedura: el înlănțuie pași pe care i-ați definit, verifică rezultatele intermediare și se oprește la orice anomalie. Este un operator atent, nu un factor de decizie.
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")
Monitorizare și alerte
Monitorizarea inversează logica restului acestei lecții: comenzile de aici sunt doar pentru citire, deci sunt inofensive, iar valoarea constă în interpretare. Un model care citește spațiul pe disc, sarcina procesorului și jurnalele de erori observă corelații pe care un prag izolat le ratează – făcând din aceasta cea mai sigură poartă de intrare pentru a începe cu acest instrument.
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
)
Puncte cheie
- Instrumentul Shell conectează modelul la infrastructura dumneavoastră
- Implementați liste de permisiuni (allowlists) și liste de blocare (blocklists) pentru comenzi
- Utilizați timeout-uri și directoare de lucru restricționate
- Apelarea de funcții (Function calling) vă permite să implementați Shell ca un instrument personalizat
- Combinați Shell cu alte instrumente pentru fluxuri de lucru DevOps complete