Files

T

fn-registry agent 4b0fb61f02 chore: sync from fn-registry agent

2026-05-30 17:28:38 +02:00

6.7 KiB

Raw Permalink Blame History

name, lang, domain, description, icon, tags, version, uses_functions, uses_types, framework, entry_point, dir_path, repo_url, e2e_checks, service

name

lang

domain

description

icon

device_agent

Agente HTTP que corre en cada dispositivo del mesh WireGuard mesh (10.42.0.0/24). Escucha en la IP del mesh asignada al peer (10.42.0.10 en home-wsl, etc.) puerto 7474.

Endpoints

Metodo	Path	Descripcion
GET	`/health`	Liveness check, devuelve `{"ok":true,"device_id":"...","version":"..."}`
GET	`/capabilities`	Lista capabilities declaradas en el manifest local
POST	`/capability`	Despacha capability request. JSON envelope (ver flow 0009 spec issue 0134)

Flujo

agents_and_robots (VPS, 10.42.0.1)
  ↓ POST http://10.42.0.10:7474/capability
device_agent (este binario)
  ↓ validate manifest + nonce + (later) signature
  ↓ route capability → shell.exec | docker.* | fs.read | ...
  ↓ append audit hash-chain
  ↓ return JSON {ok, result, audit_hash}
agents_and_robots
  ↓ Matrix message back to room
Element user ve output

Manifest

~/.config/device_agent/manifest.yaml declara capabilities permitidas. POC inicial sin firma (issue 0134 introduce ed25519 sign). Formato:

device_id: home-wsl
operator: egutierrez
capabilities:
  - name: shell.exec
    binaries_allowed: [ls, cat, ps, df, git, echo]
    requires_approval: false
  - name: shell.exec.admin
    binaries_allowed: [systemctl, apt-get]
    requires_approval: true
  - name: shell.eval
    shell_mode: auto              # bash en linux/darwin, powershell.exe en windows
    blocklist: []                 # extension operador; hardcoded kill-list aplica siempre
    auto_approve:                 # regex pre-aprobados (override defaults si presente)
      - "^git\\s"
      - "^docker ps"
    max_output_bytes: 1048576     # 1MB
    timeout_seconds: 60
    requires_approval: false      # true => cmd no-auto se cola en local_files/approval_queue.jsonl
  - name: docker.container.list
    requires_approval: false
  - name: docker.container.logs
    requires_approval: false
  - name: docker.container.exec
    binaries_allowed: [ls, ps, cat]
    requires_approval: true

Capabilities soportadas

Capability	Estado	Que hace
`shell.exec`	v0.1.0	Ejecuta argv estructurado, whitelist binaries
`shell.eval`	v0.2.0	Evalua cmd shell-libre (`bash -c <cmd>` o `powershell.exe -Command <cmd>`). Hardcoded blocklist + auto_approve regex + approval queue + audit verbose con cmd cleartext
`docker.container.list`	stub	Lista contenedores via socket docker
`docker.container.logs`	stub	Logs de un contenedor
`docker.container.exec`	stub	exec en contenedor (whitelist)

shell.eval — detalle

shell.eval permite al agent LLM mandar comandos shell libres ("borra logs antiguos") en lugar de solo argv estructurado. Defensas:

Hardcoded blocklist no configurable: rm -rf /, dd if=, mkfs.*, curl|sh, shutdown, reboot, etc. Match case-insensitive. Cualquier match = rechazo, no aprobable.
Operator blocklist (capability.blocklist[]) extiende el hardcoded.
OS detect: bash -c en Linux/Mac, powershell.exe -NoProfile -NonInteractive -Command en Windows. Override via shell_mode o per-call shell arg.
auto_approve regex: lista (override-able) de patrones pre-aprobados (^git\s, ^docker ps, etc.). Match = ejecuta sin friccion.
Approval queue: si requires_approval: true y el cmd NO matchea auto_approve, se anade entry a local_files/approval_queue.jsonl {ts, request_id, cmd, cwd, capability, status: pending} y devuelve error approval_required. v0.2.0 es placeholder; 0144f pasa a Matrix reactions.
Output cap: max_output_bytes (default 1MB), timeout_seconds (default 60). Flag truncated:true cuando se aplica.
Audit verbose: nueva tabla audit_shell_eval(audit_id, cmd, cwd, shell, stdout_b64, stderr_b64) con cmd en CLARO (no hash) para forense. stdout/stderr > 4KB se comprimen gzip+base64 (prefijo gz:); cortos van con prefijo plain:.

Args en la HTTP envelope (POST /capability):

{
  "request_id": "...",
  "capability": "shell.eval",
  "args": ["{\"cmd\":\"git status\",\"cwd\":\"/repo\"}"]
}

O en formato posicional args: ["git status", "/repo", "bash"].

Audit

local_files/audit.db con tabla audit_log hash-chained. Cada request: {ts, request_id, capability, args_hash, exit_code, prev_hash, this_hash}.

Build

cd projects/element_agents/apps/device_agent
CGO_ENABLED=1 go build -o device_agent .
./device_agent --listen 10.42.0.10:7474 --manifest ~/.config/device_agent/manifest.yaml

Cross-compile a Windows (para aurgi-pc):

GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o device_agent.exe .

Estado

v0.1.0: POC sin firma de manifest. Solo shell.exec + docker.*. WIP.
v0.2.0 (issue 0140): firma ed25519, replay protection, approval flow.

Capability growth log

v0.1.0 (2026-05-24) — scaffold inicial POC para validar DoD gate Element→PC del flow 0009.
v0.2.0 (2026-05-24) — anade capability shell.eval (bash/powershell con hardcoded blocklist + regex auto_approve + approval queue + audit verbose con cmd cleartext). Nueva tabla audit_shell_eval. Manifest extendido con blocklist, auto_approve, shell_mode, max_output_bytes, timeout_seconds.

6.7 KiB Raw Permalink Blame History