fn-registry agent
167 lines
6.7 KiB
Markdown
167 lines
6.7 KiB
Markdown
---
|
|
name: device_agent
|
|
lang: go
|
|
domain: tools
|
|
description: "Agente HTTP por dispositivo del mesh WireGuard. Recibe capability requests del Matrix bot agents_and_robots (via mesh 10.42.0.0/24), valida contra manifest YAML, ejecuta con sandbox (shell whitelist o docker exec whitelist), devuelve resultado con audit hash-chained."
|
|
icon:
|
|
phosphor: "robot"
|
|
accent: "#06b6d4"
|
|
tags: [agents, device-agent, mesh, wireguard, matrix, http, service, security]
|
|
version: 0.2.0
|
|
uses_functions:
|
|
- shell_exec_whitelist_go_infra
|
|
- docker_container_list_go_infra
|
|
- docker_container_exec_go_infra
|
|
- docker_container_logs_go_infra
|
|
- http_logger_middleware_go_infra
|
|
- logger_new_go_infra
|
|
uses_types: []
|
|
framework: "stdlib-http"
|
|
entry_point: "main.go"
|
|
dir_path: "projects/element_agents/apps/device_agent"
|
|
repo_url: "https://gitea.organic-machine.com/dataforge/device_agent"
|
|
e2e_checks:
|
|
- id: build
|
|
cmd: "cd /home/lucas/fn_registry/projects/element_agents/apps/device_agent && CGO_ENABLED=1 go build -o device_agent ."
|
|
timeout_s: 60
|
|
- id: self_test
|
|
cmd: "/home/lucas/fn_registry/projects/element_agents/apps/device_agent/device_agent --self-test"
|
|
timeout_s: 10
|
|
- id: unit_tests
|
|
cmd: "cd /home/lucas/fn_registry/projects/element_agents/apps/device_agent && CGO_ENABLED=1 go test -count=1 ./..."
|
|
timeout_s: 60
|
|
service:
|
|
port: 7474
|
|
health_endpoint: /health
|
|
health_timeout_s: 3
|
|
systemd_unit: device_agent.service
|
|
systemd_scope: user
|
|
restart_policy: always
|
|
runtime: systemd-user
|
|
pc_targets:
|
|
- home-wsl
|
|
- aurgi-pc
|
|
is_local_only: false
|
|
---
|
|
|
|
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
1. **Hardcoded blocklist** no configurable: `rm -rf /`, `dd if=`, `mkfs.*`, `curl|sh`, `shutdown`, `reboot`, etc. Match case-insensitive. Cualquier match = rechazo, no aprobable.
|
|
2. **Operator blocklist** (`capability.blocklist[]`) extiende el hardcoded.
|
|
3. **OS detect**: `bash -c` en Linux/Mac, `powershell.exe -NoProfile -NonInteractive -Command` en Windows. Override via `shell_mode` o per-call `shell` arg.
|
|
4. **auto_approve regex**: lista (override-able) de patrones pre-aprobados (`^git\s`, `^docker ps`, etc.). Match = ejecuta sin friccion.
|
|
5. **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.
|
|
6. **Output cap**: `max_output_bytes` (default 1MB), `timeout_seconds` (default 60). Flag `truncated:true` cuando se aplica.
|
|
7. **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`):
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`.
|