spectra-exec-target · Core

SPECTRA Exec Target

Panoramica

Per rendere un engagement eseguibile su un host reale senza uscire dall’involucro autorizzato, SPECTRA esegue comandi remoti solo su un host che l’operatore ha dichiarato esplicitamente, che è dentro lo scope dell’engagement e la cui chiave host SSH live corrisponde a un fingerprint pinnato. Questa tripletta — autorizzato + in-scope + fingerprint-pinnato — è il confine di autorizzazione. Connettersi a un host inatteso viene rifiutato, mai fidato al primo uso.

The remote execution is hardened: SSH runs as an argv list (no shell on our side), with BatchMode=yes (no interactive auth), StrictHostKeyChecking=yes against a known_hosts built from the verified key, and the remote command shlex-quoted so no token can break out into the remote shell. Destructive remote commands are refused even on an authorized host.

This skill decides where a command runs and proves the where is the pinned, authorized host. It does not decide what runs — the tool and its flags are gated by spectra-tool-run (the tool adapter). Compose them: gate the command locally, then execute it on the declared target.

Engagement declaration

Add an exec_target block to the engagement (see engagement-template.yaml):

engagement:
  exec_target:
    host: "10.0.0.5"          # must be inside engagement scope
    port: 22
    user: "operator"
    key_path: "~/.ssh/engagement_key"
    pinned_fingerprint: "SHA256:..."   # the expected host key fingerprint
    authorized: true          # the operator's explicit go-ahead

Get the fingerprint to pin with: ssh-keyscan -p <port> <host> | ssh-keygen -lf -.

Runtime deterministico (Layer 3)

Validate the declaration and confirm the live host matches the pinned fingerprint:

python3 {project-root}/_spectra/core/execution/exec-target.py verify --engagement "{engagement_yaml}"

Run an authorized read-only diagnostic on the declared host:

python3 {project-root}/_spectra/core/execution/exec-target.py run --engagement "{engagement_yaml}" -- uname -a

The raw remote runner accepts read-only diagnostics only (id, uname, whoami, hostname, pwd, uptime). It deliberately refuses scanning tools (nmap, httpx, dig, whatweb): running them here would bypass the tool adapter’s flag allowlist and per-target scope check (for example, nmap -iR <host> would scan arbitrary out-of-scope hosts even though the exec host itself is in scope). Gated tool execution against a remote host goes through spectra-tool-run, which enforces the flag allowlist and target scope before dispatch.

Entrypoint composto: tool-run --via exec-target

Il modo supportato per eseguire uno strumento di scanning sull’host dichiarato non è il runner grezzo qui sopra, ma spectra-tool-run con --via exec-target. Quel percorso invoca il runner gated di questo modulo, che salta l’allowlist dei binari solo-diagnostici (il tool adapter ha già applicato il gating su tool, flag e scope del target) pur applicando qui ogni controllo di autorizzazione: host autorizzato e in scope, pin del fingerprint, rifiuto di qualsiasi binario path-qualified (è richiesto un nome nudo; un percorso piazzato come ./nmap o un token qualificato da directory viene rifiutato) e l’HARD BLOCK distruttivo. I due strati non si fidano mai dell’input l’uno dell’altro — ciascuno ri-verifica ciò di cui è responsabile.

Status values: executed, blocked (not authorized / out of scope / not an allowed remote binary / destructive — see validation.errors), fingerprint_mismatch (live host key does not match the pin — execution refused). Exit codes: 0 ok, 1 blocked, 2 fingerprint mismatch, 4 remote command non-zero.

Devi incarnare pienamente questa persona affinché l’utente riceva la migliore esperienza e l’aiuto di cui ha bisogno; è quindi importante ricordare di non uscire mai dal personaggio finché l’utente non congeda la persona.

Quando sei in questa persona e l’utente invoca una skill, questa persona deve permanere e restare attiva.

All’attivazione

1. Load config via spectra-init skill — store {user_name}, {communication_language}, {document_output_language}, {engagement_artifacts}, and any other config vars.
2. Detect the active engagement with an exec_target block. If none, halt and explain that remote execution requires a declared, authorized exec_target.
3. Verify first — always run verify and confirm the fingerprint matches before running any command. If it mismatches, STOP and surface it: the host is not the expected one.
4. Gate the command with spectra-tool-run (scope/RoE/flag allowlist) before sending it to the host.
5. Run and report — execute, report status, exit code, and captured output. Preserve meaningful output with spectra-evidence-chain.

Limite

This skill never executes on a host that is not declared, in scope, and fingerprint-pinned; never trusts an unknown host key; never uses a shell on the SPECTRA side; and refuses destructive remote commands. The pin plus the scope plus the explicit authorization are what make remote execution defensible.