Modelo de Seguridad — Architect CLI

Documentación exhaustiva de las capas de seguridad, modelo de amenazas, superficie de ataque y recomendaciones de hardening.

Modelo de amenazas

Architect da control al LLM sobre herramientas reales del sistema: lectura/escritura de archivos, ejecución de comandos y conexión a servidores remotos (MCP). Esto implica riesgos concretos que el sistema mitiga con múltiples capas defensivas.

Actores de amenaza

Actor	Vector	Mitigación principal
LLM adversarial / hallucination	El modelo intenta leer `/etc/passwd`, ejecutar `rm -rf /`, o escapar del workspace	Path traversal prevention + blocklist + workspace sandboxing
Prompt injection (indirecta)	Un archivo del workspace contiene instrucciones que manipulan al LLM	Confinamiento al workspace + confirmación de operaciones sensibles
Servidor MCP malicioso	El servidor MCP retorna datos que contienen prompt injection	Sanitización de args en logs + aislamiento de tool results
Usuario con config insegura	`--mode yolo` + `--allow-commands` sin restricciones	Blocklist hard (no bypassable) + `allowed_only` mode + defaults seguros

Superficie de ataque

                    ┌──────────────┐
                    │     LLM      │  ← Prompt injection (indirecta)
                    └──────┬───────┘
                           │ tool calls
                    ┌──────▼───────┐
                    │ ExecutionEngine│  ← Validación + confirmación
                    └──────┬───────┘
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────▼───────┐ ┌─────▼──────┐ ┌──────▼───────┐
    │  Filesystem  │ │ run_command │ │     MCP      │
    │  Tools       │ │  (shell)   │ │   (HTTP)     │
    └──────────────┘ └────────────┘ └──────────────┘
           │               │               │
    validate_path()   4 capas seguridad  Bearer token
    workspace jail    blocklist+classify  session ID

Capa 1 — Confinamiento del workspace (Path Traversal Prevention)

Archivo: src/architect/execution/validators.py

Toda operación de filesystem pasa obligatoriamente por validate_path(). Es la barrera más crítica del sistema.

Mecanismo

def validate_path(path: str, workspace_root: Path) -> Path:
    workspace_resolved = workspace_root.resolve()
    full_path = (workspace_root / path).resolve()  # resolve() elimina ../ y symlinks

    if not full_path.is_relative_to(workspace_resolved):
        raise PathTraversalError(...)

    return full_path

Qué previene

Intento	Resultado
`../../etc/passwd`	`PathTraversalError` — `.resolve()` colapsa los `..` y detecta que escapa
`/etc/shadow` (path absoluto)	`PathTraversalError` — al concatenar con workspace, resolve detecta escape
`src/../../.env`	`PathTraversalError` — resolve normaliza y detecta salida
Symlink a `/root`	`PathTraversalError` — `.resolve()` sigue el symlink real

Garantías

Path.resolve() resuelve symlinks, . y .. al path real del filesystem
is_relative_to() verifica que el path resuelto comience con el workspace resuelto
Incluye fallback de comparación de strings para Python < 3.9
Cada tool de filesystem (read_file, write_file, edit_file, delete_file, list_files, apply_patch, search_code, grep, find_files) llama a validate_path() antes de cualquier operación

Errores retornados al LLM (nunca excepciones al caller)

Cuando PathTraversalError ocurre, la tool retorna:

ToolResult(success=False, output="", error="Error de seguridad: Path '../../etc/passwd' escapa del workspace.")

El LLM recibe el error como resultado del tool call y puede razonar sobre él. El loop nunca se rompe por un error de seguridad.

Capa 2 — Seguridad de ejecución de comandos (4 capas)

Archivo: src/architect/tools/commands.py

run_command es la tool más peligrosa del sistema. Implementa 4 capas de seguridad independientes.

Capa 2.1 — Blocklist hard (regex)

Patrones que nunca se ejecutan, independientemente del modo de confirmación o configuración del usuario:

BLOCKED_PATTERNS = [
    r"\brm\s+-rf\s+/",          # rm -rf /
    r"\brm\s+-rf\s+~",          # rm -rf ~
    r"\bsudo\b",                 # escalada de privilegios
    r"\bsu\b",                   # cambio de usuario
    r"\bchmod\s+777\b",          # permisos inseguros
    r"\bcurl\b.*\|\s*(ba)?sh",   # curl | bash
    r"\bwget\b.*\|\s*(ba)?sh",   # wget | bash
    r"\bdd\b.*\bof=/dev/",       # escritura a dispositivos
    r">\s*/dev/sd",              # redirección a discos
    r"\bmkfs\b",                 # formateo de discos
    r"\b:()\s*\{\s*:\|:&\s*\};?:", # fork bomb
    r"\bpkill\s+-9\s+-f\b",     # kill masivo por nombre
    r"\bkillall\s+-9\b",        # kill masivo
]

Matching con re.search() y flag re.IGNORECASE
Son aditivos: la config puede añadir blocked_patterns extra, pero nunca quitar los built-in
Si coincide, retorna ToolResult(success=False) inmediatamente — el LLM recibe el rechazo

Capa 2.2 — Clasificación dinámica

Cada comando se clasifica en 3 categorías:

Categoría	Criterio	Ejemplos
`safe`	Match de prefijo con `SAFE_COMMANDS` (28 comandos)	`ls`, `cat`, `git status`, `grep`, `pip list`, `kubectl get`
`dev`	Match de prefijo con `DEV_PREFIXES` (30+ prefijos)	`pytest`, `mypy`, `ruff`, `cargo test`, `npm test`, `make`
`dangerous`	Todo lo demás	`python script.py`, `bash deploy.sh`, `docker run`

La clasificación determina si se pide confirmación según el modo:

Clasificación	`yolo`	`confirm-sensitive`	`confirm-all`
`safe`	No	No	Si
`dev`	No	Si	Si
`dangerous`	Si	Si	Si

Incluso en modo yolo, los comandos dangerous requieren confirmación. La única forma de saltarse confirmación para dangerous es que no haya TTY (headless), lo cual lanza NoTTYError.

Capa 2.3 — Timeouts y truncado de output

subprocess.run(
    command,
    shell=True,
    timeout=effective_timeout,  # default 30s, configurable hasta 600s
    capture_output=True,
    stdin=subprocess.DEVNULL,   # headless: nunca espera input
)

stdin=subprocess.DEVNULL: previene que un comando interactivo bloquee el agente
Timeout: configurable via commands.default_timeout (1-600s)
Truncado de output: max_output_lines (default 200) — preserva inicio y final del output, evita saturar el context window del LLM

Capa 2.4 — Directory sandboxing

def _resolve_cwd(self, cwd: str | None) -> Path:
    if cwd is None:
        return self.workspace_root
    return validate_path(cwd, self.workspace_root)  # Reutiliza validate_path()

El directorio de trabajo del proceso siempre está dentro del workspace. Si el LLM intenta ejecutar un comando con cwd: "../../", validate_path() lo bloquea.

Modo `allowed_only`

Configuración extra para entornos restrictivos:

commands:
  allowed_only: true  # Solo safe + dev; dangerous = rechazado sin confirmación

Con allowed_only: true, los comandos dangerous se rechazan directamente en execute(), sin llegar a pedir confirmación. Útil en CI/CD donde no hay TTY.

Desactivación completa

commands:
  enabled: false  # La tool run_command no se registra

O via CLI: --no-commands. En este caso, la tool ni siquiera está disponible para el LLM.

Capa 3 — Políticas de confirmación

Archivo: src/architect/execution/policies.py

Modos

Modo	Comportamiento	Uso recomendado
`confirm-all`	Confirma cada tool call	Producción, primera vez
`confirm-sensitive`	Solo confirma tools con `sensitive=True`	Default, desarrollo normal
`yolo`	Sin confirmación (excepto `dangerous` commands)	Tareas de confianza, CI

Tools sensibles (built-in)

Tool	`sensitive`	Motivo
`read_file`	`false`	Solo lectura
`list_files`	`false`	Solo lectura
`write_file`	`true`	Modifica archivos
`edit_file`	`true`	Modifica archivos
`apply_patch`	`true`	Modifica archivos
`delete_file`	`true`	Elimina archivos
`run_command`	`true`	Ejecución arbitraria (clasificación dinámica)
`search_code`	`false`	Solo lectura
`grep`	`false`	Solo lectura
`find_files`	`false`	Solo lectura

Protección headless (CI/CD)

if not sys.stdin.isatty():
    raise NoTTYError(
        "Se requiere confirmación para ejecutar '{tool_name}' "
        "pero no hay TTY disponible (entorno headless/CI). "
        "Soluciones: 1) Usa --mode yolo, 2) Usa --dry-run, "
        "3) Cambia la configuración del agente a confirm_mode: yolo"
    )

Si una tool requiere confirmación pero no hay TTY (CI, Docker, cron), el sistema falla de forma segura con NoTTYError en lugar de ejecutar sin confirmación.

Capa 4 — Delete protection

Archivo: src/architect/config/schema.py — WorkspaceConfig

workspace:
  allow_delete: false  # Default

delete_file está desactivada por defecto. Requiere configuración explícita allow_delete: true para funcionar. Incluso con --mode yolo, si allow_delete es false, la tool retorna error.

Capa 5 — Seguridad del ExecutionEngine

Archivo: src/architect/execution/engine.py

El ExecutionEngine es el punto de paso obligatorio para toda ejecución de tools. Aplica un pipeline de 7 pasos:

Tool call → Buscar en registry → Validar args (Pydantic) → Política de confirmación
         → Ejecutar (o dry-run) → Log resultado → Retornar ToolResult

Invariantes

Nunca lanza excepciones al caller — siempre retorna ToolResult. Triple try-catch:
- Catch de cada paso individual (registry, validación, confirmación, ejecución)
- Catch de último recurso en execute_tool_call()
- Las tools internamente también capturan sus propias excepciones
Sanitización de argumentos para logs — _sanitize_args_for_log() trunca valores > 200 chars:
```
sanitized[key] = value[:200] + f"... ({len(value)} chars total)"
```
Esto previene que contenido sensible (API keys en archivos, tokens) aparezca completo en logs.
Dry-run — --dry-run simula la ejecución sin efectos reales. El engine retorna ToolResult con [DRY-RUN] sin ejecutar la tool.

Capa 6 — Seguridad de API keys y tokens

LLM API keys

Archivo: src/architect/llm/adapter.py

api_key = os.environ.get(self.config.api_key_env)  # Lee de env var
os.environ["LITELLM_API_KEY"] = api_key              # Configura para LiteLLM

Las API keys nunca se almacenan en config files — solo se referencian via api_key_env
Si la env var no existe, el adapter logea warning pero no falla inmediatamente
Los logs no incluyen el valor de la API key, solo el nombre de la env var: env_var=self.config.api_key_env
LiteLLM maneja internamente la key; architect no la propaga a herramientas ni outputs

Tokens MCP

Archivo: src/architect/mcp/client.py

def _resolve_token(self) -> str | None:
    if self.config.token:
        return self.config.token        # 1. Token directo
    if self.config.token_env:
        return os.environ.get(self.config.token_env)  # 2. Env var
    return None

Soporte para token directo en config o via env var (recomendado: env var)
El token se envía como Authorization: Bearer {token} en headers HTTP
Logs de inicialización usan has_token=self.token is not None (boolean, no el valor)
El session ID del servidor se logea truncado: session_id[:12] + "..."
_sanitize_args() trunca valores > 100 chars en logs de tool calls

Capa 7 — Seguridad del agent loop

Safety nets

Archivo: src/architect/core/loop.py

El loop while True tiene 5 safety nets que previenen ejecución infinita:

Safety net	Mecanismo	Default
`max_steps`	Contador de iteraciones	50 (build), 20 (plan/review), 15 (resume)
`budget`	`CostTracker` + `BudgetExceededError`	Sin límite (configurable)
`timeout`	`StepTimeout` (SIGALRM por step)	Configurable
`context_full`	`ContextManager.is_critically_full()`	80k tokens default
`shutdown`	`GracefulShutdown` (SIGINT/SIGTERM)	Siempre activo

Graceful shutdown

Archivo: src/architect/core/shutdown.py

SIGINT (Ctrl+C) #1  →  Marca should_stop = True, loop termina al acabar el step actual
SIGINT (Ctrl+C) #2  →  sys.exit(130) inmediato
SIGTERM             →  Igual que primer SIGINT (para Docker/K8s)

No corta a mitad de una operación de archivo
Permite _graceful_close(): una última llamada al LLM sin tools para generar resumen
Exit code 130 (estándar POSIX: 128 + SIGINT)

Step timeout

Archivo: src/architect/core/timeout.py

with StepTimeout(seconds=60):
    response = llm.completion(messages)
    result = engine.execute_tool_call(...)

Usa signal.SIGALRM en Linux/macOS
En Windows: no-op (degrada gracefully)
Lanza StepTimeoutError que el loop captura y registra como StopReason

Capa 8 — Seguridad de la configuración

Validación estricta con Pydantic v2

Archivo: src/architect/config/schema.py

Todos los modelos de configuración usan model_config = {"extra": "forbid"}. Esto significa que:

Cualquier campo desconocido en el YAML es un error de validación
No se pueden inyectar opciones no documentadas
Los tipos son estrictamente validados (Literal, int con ge/le, etc.)

Defaults seguros

Configuración	Default	Razón
`workspace.allow_delete`	`false`	Prevenir borrado accidental
`commands.allowed_only`	`false`	Permite dangerous con confirmación
`confirm_mode`	`"confirm-sensitive"`	Equilibrio seguridad/usabilidad
`llm_cache.enabled`	`false`	Cache solo para desarrollo
`evaluation.mode`	`"off"`	No consumir tokens extra
`commands.default_timeout`	`30`	Prevenir procesos colgados
`commands.max_output_lines`	`200`	Prevenir context flooding
`llm.retries`	`2`	Solo errores transitorios

Precedencia de configuración

CLI flags  >  variables de entorno  >  config.yaml  >  defaults Pydantic

Los CLI flags siempre ganan. El usuario en terminal tiene la última palabra.

Capa 9 — Validación de argumentos (Pydantic)

Cada tool define un args_model (Pydantic BaseModel) que valida los argumentos antes de la ejecución:

class RunCommandArgs(BaseModel):
    command: str
    cwd: str | None = None
    timeout: int = 30
    env: dict[str, str] | None = None

Los argumentos del LLM se validan antes de ejecutar la tool
Si la validación falla, se retorna ToolResult(success=False, error="Argumentos inválidos: ...")
El LLM recibe el error y puede corregir su siguiente llamada

Capa 10 — Post-edit hooks (seguridad de código generado)

Archivo: src/architect/core/hooks.py

Los hooks verifican automáticamente el código que el agente escribe:

hooks:
  post_edit:
    - name: lint
      command: "ruff check {file} --fix"
      file_patterns: ["*.py"]
      timeout: 15

Seguridad de los hooks

Timeout por hook: default 15s, configurable (1-300s) — previene procesos colgados
stdin=subprocess.DEVNULL: los hooks no pueden pedir input interactivo
cwd=workspace_root: hooks ejecutan dentro del workspace
Output truncado: máximo 1000 chars para no saturar el contexto
Nunca rompen el loop: errores en hooks se logean y retornan None, el agente continúa
Variable de entorno: ARCHITECT_EDITED_FILE se inyecta al hook
Solo edit tools: se ejecutan exclusivamente para edit_file, write_file, apply_patch

Capa 11 — Logging y sanitización

3 pipelines de logging

Pipeline	Destino	Contenido
Human	stderr	Eventos del agente con iconos (solo en terminal)
Console	stderr	Logs técnicos (structlog)
JSON file	archivo	Logs completos en JSON-lines (auditoria)

Sanitización en logs

ExecutionEngine._sanitize_args_for_log(): trunca valores > 200 chars
MCPClient._sanitize_args(): trunca valores > 100 chars
Session IDs: truncados a 12 chars en logs
API keys: solo se logea el nombre de la env var, nunca el valor
stdout reservado exclusivamente para resultado final y JSON — logs a stderr

Capa 12 — Seguridad de agentes (registry)

Archivo: src/architect/agents/registry.py

Cada agente tiene restricciones de tools definidas en su configuración:

Agente	Tools permitidas	`confirm_mode`	`max_steps`
`build`	Todas	`confirm-sensitive`	50
`plan`	Solo lectura	`yolo`	20
`review`	Solo lectura	`yolo`	20
`resume`	Solo lectura	`yolo`	15

plan, review y resume usan modo yolo porque no tienen tools de escritura — no hay nada que confirmar
build es el único agente con tools de escritura y ejecución, y usa confirm-sensitive por defecto
allowed_tools en el registry define exactamente qué tools puede usar cada agente
Un agente plan no puede llamar a write_file aunque el LLM lo intente — el engine retorna ToolNotFoundError

Capa 13 — Seguridad MCP (Model Context Protocol)