SPECTRA Tool Run

Panoramica

Pianificare una scansione ed eseguirla sono atti diversi, e il divario tra essi è dove si nasconde l’attività non autorizzata. SPECTRA chiude quel divario alle proprie condizioni: gli strumenti girano solo tramite un adapter deterministico che impone scope dell’engagement, Rules of Engagement e HARD BLOCK distruttivo a ogni invocazione. Non esiste “l’agente ha lanciato una shell con ciò che voleva” — il binario è fisso per strumento, non c’è shell e il target dev’essere in scope.

This skill is how an agent moves from a recommended command to an executed, evidence-producing result without leaving the authorized envelope. It wraps the Layer-3 tool adapter, which:

runs only allowlisted tools (the binary is never taken from input);
uses no shell (argv list, shell=False) — no injection surface;
scope-gates the target with the same scope-enforcer the workflows use;
RoE-gates the action (e.g. a DoS tool needs dos_testing_allowed);
enforces the destructive HARD BLOCK (ransomware/wipers/data-destroyers and obviously destructive shell constructs are refused outright);
defaults to a dry run mindset: preview the gated command before executing.

Execution defaults to the local host. Remote execution against a declared, in-scope, fingerprint-pinned host is handled by the exec-target capability and composed with this adapter.

Runtime deterministico (Layer 3)

List allowlisted tools and whether each binary is installed:

python3 {project-root}/_spectra/core/execution/tool-adapter.py list

Preview a gated command without executing anything (always do this first):

python3 {project-root}/_spectra/core/execution/tool-adapter.py run \
  --engagement "{engagement_yaml}" --tool nmap --target "{target}" --dry-run

Execute the gated command:

python3 {project-root}/_spectra/core/execution/tool-adapter.py run \
  --engagement "{engagement_yaml}" --tool nmap --target "{target}" -- -sV

Status values: planned (dry run), executed, blocked (failed scope/RoE/HARD BLOCK — see gate.errors), unavailable (binary not installed). Exit codes: 0 ok/planned, 1 blocked, 2 unavailable, 4 tool exited non-zero.

Contabilità delle esecuzioni

Ogni run viene registrato in un log append-only per engagement (run-log.jsonl, accanto a engagement.yaml) — inclusi i dry run e i tentativi bloccati, così l’engagement mantiene una traccia onesta dell’attività, separata dalla catena di evidenza. La registrazione è best-effort e non altera mai l’esito di una run; usa --no-log per saltarla.

Esamina il log delle attività:

python3 {project-root}/_spectra/core/execution/run-accounting.py status \
  --engagement "{engagement_yaml}" --limit 10

Il riepilogo riporta i totali per stato e per strumento, quante run sono state eseguite rispetto a quelle bloccate, il conteggio degli exit non-zero e le run più recenti. È la base deterministica di ciò che un operatore vede come storico delle esecuzioni dell’engagement.

Esecuzione remota: `--via exec-target`

Lo stesso comando gated può girare sull’host dichiarato dall’engagement, in scope e con fingerprint pinned, invece che in locale:

python3 {project-root}/_spectra/core/execution/tool-adapter.py run \
  --engagement "{engagement_yaml}" --tool nmap --target "{target}" --via exec-target -- -sV

L’ordine della fiducia è a strati e fail-closed: questo adapter applica il gating su tool, allowlist dei flag e scope del target per primo; solo allora il comando passa a spectra-exec-target, che aggiunge il controllo dell’host autorizzato, il pin del fingerprint SSH, il rifiuto del binario path-qualified e l’HARD BLOCK distruttivo. Nessuno dei due strati si fida dell’input dell’altro. Valori di stato remoti: executed_remote, fingerprint_mismatch o blocked (vedi remote.validation.errors); il dettaglio remoto è restituito in result["remote"]. Un --dry-run ha sempre la precedenza e non raggiunge mai l’host.

Fail-closed flag allowlist

Tool flags are allowlisted per tool, not denylisted: only explicitly vetted, read-only flags are permitted, and the target is validated as data (never a flag). This structurally refuses flags that would read or write arbitrary files (-oN, -iL, --resume), run code (nmap --script), or override the gated target with other hosts (nmap -iR). nuclei is intentionally not included — its templates can execute code, which flag-gating alone cannot make safe. Adding a tool or flag is a security decision made in tool-adapter.py’s ADAPTERS, not at call time.

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

Load config via spectra-init skill — store {user_name}, {communication_language}, {document_output_language}, {engagement_artifacts}, {evidence_artifacts}, and any other config vars.
Detect the active engagement — find an engagement.yaml with status: "active" under {engagement_artifacts}. If none, halt and recommend spectra-new-engagement.
Confirm the target and tool with the operator.
Dry-run first — run with --dry-run, show the exact argv and the gate result, and confirm before executing.
Execute — run for real; report status, exit code, and captured output.
Preserve evidence — register meaningful output with spectra-evidence-chain so findings derived from it can resolve to verified evidence (see spectra-attack-path).

Limite

This skill never runs a tool the adapter does not allowlist, never uses a shell, never targets anything outside engagement scope, and never executes a destructive construct — those are refused before execution, not after. Read-only recon is the default posture; anything louder is gated by the engagement noise budget and Rules of Engagement, and the operator decides within them.