timwhitez/AutoRE-CLI / skills/auto-re
auto-re
VerifiedAnalyze a supplied executable, DLL, binary or object to explain what it does, investigate suspicious behavior, decompile a function, or inspect strings and references. Use for requests such as 'what does this executable do?' or '这个程序是干什么的', even without naming Auto-RE. Static ELF/PE/Mach-O and explicitly identified raw shellcode only; never run target bytes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| VERSION | other | 7 B |
| agents/openai.yaml | config | 615 B |
| evals/trigger_cases.json | config | 5.5 KB |
| references/command-routing.md | markdown | 9.7 KB |
| references/compact-ai-view.md | markdown | 3.1 KB |
| references/evidence-contract.md | markdown | 24.1 KB |
| references/investigation-workflows.md | markdown | 14.6 KB |
| references/platform-invocation.md | markdown | 1.5 KB |
| references/safety-and-claims.md | markdown | 3.1 KB |
| scripts/compact_result.py | script | 5.5 KB |
| scripts/process_control.py | script | 17.8 KB |
| scripts/read_result.py | script | 15.1 KB |
| scripts/run_next_action.pyexecutable | script | 74.2 KB |
| scripts/skill_doctor.pyexecutable | script | 12.9 KB |
| scripts/start_analysis.py | script | 10.8 KB |
| scripts/verify_bundle.pyexecutable | script | 28.9 KB |
scripts/run_next_action.py
View on GitHub#!/usr/bin/env python3
"""Validate and run one emitted Auto-RE static next action."""
from __future__ import annotations
import argparse
import hashlib
import importlib.util
import json
import math
import os
import pathlib
import re
import shutil
import stat
import subprocess # retained test seam; lifecycle is owned by process_control
import sys
import time
from datetime import datetime, timezone
from typing import Any, BinaryIO, NamedTuple, Optional
# Import only the helper shipped beside this script, not a module from CWD/PATH.
# Managed Skill inventories must not acquire import-time bytecode files.
sys.dont_write_bytecode = True
_PROCESS_SPEC = importlib.util.spec_from_file_location(
"auto_re_process_control", pathlib.Path(__file__).with_name("process_control.py")
)
assert _PROCESS_SPEC is not None and _PROCESS_SPEC.loader is not None
process_control = importlib.util.module_from_spec(_PROCESS_SPEC)
_PROCESS_SPEC.loader.exec_module(process_control)
DEFAULT_TIMEOUT_SECONDS = process_control.DEFAULT_TIMEOUT_SECONDS
TRUSTED_PROGRAM = "auto-re-cli"
SUPPORTED_SCHEMA_VERSIONS = frozenset({"0.1.0"})
SUPPORTED_PROFILES = frozenset({"ai"})
SUPPORTED_MANIFEST_KINDS = frozenset({"context_bundle", "agent_spill_manifest"})
# Audited CLI contract, not an execution authorization list. Keep the release
# fixture and source Clap drift test in sync when auditing another version.
IDENTITY_CONTRACT_VERSION = "0.1.14"
IDENTITY_GLOBAL_VALUE_OPTIONS = ["--output", "--diagnostic-format"]
IDENTITY_COMMAND_CONTRACT = {
"aarch64-refs": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--address --arch --base-address --entry-address --format --function --function-addr "
"--instruction-limit --json-profile --limit --max-functions --max-input-bytes "
"--max-instructions-per-function --offset --output --spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"analyze": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --max-functions --max-input-bytes "
"--max-instructions-per-function --output --spill-dir --style --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"archive": {"classification": "archive_replay", "aliases": []},
"batch": {"classification": "batch", "aliases": []},
"batch-diff": {"classification": "batch", "aliases": []},
"batch-replay": {"classification": "batch", "aliases": []},
"bench": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --iterations --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --style --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"call-graph": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --depth --edge-limit --entry-address --format "
"--json-profile --max-functions --max-input-bytes --max-instructions-per-function "
"--node-limit --output --spill-dir --symbol --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"compare-functions": {"classification": "multi_input", "aliases": []},
"data-xrefs": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--address --address-end --arch --base-address --direction --entry-address --format "
"--function --function-addr --global --json-profile --limit --max-functions "
"--max-input-bytes --max-instructions-per-function --offset --output --provenance-limit "
"--spill-dir --string --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"decompile": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --function-offset --json-profile "
"--limit --max-functions --max-input-bytes --max-instructions-per-function "
"--max-output-lines --output --spill-dir --style --diagnostic-format --result-contract --function-page-start-cap"
).split(),
"switch_options": "--flat --include-noise --raw-shellcode --split-output".split(),
},
"describe": {"classification": "metadata_no_input", "aliases": []},
"diff": {"classification": "archive_replay", "aliases": []},
"dump-cfg": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --entry-address --format --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --symbol --diagnostic-format --result-contract"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"dump-il": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --entry-address --format --level --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir "
"--statement-address --statement-contains --statement-limit --statement-offset --symbol --diagnostic-format --result-contract --register-provenance"
).split(),
"switch_options": "--flat --raw-shellcode".split(),
},
"dump-llvm": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --entry-address --max-functions --max-input-bytes "
"--max-instructions-per-function --output --spill-dir --symbol --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"extract-embedded": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--format --max-input-bytes --max-input-span --max-output-bytes --max-ratio "
"--offset --output --spill-dir --diagnostic-format"
).split(),
"switch_options": "".split(),
},
"fold-pair-bytes": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": "--output --spill-dir --diagnostic-format".split(),
"switch_options": "".split(),
},
"function": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --entry-address --format --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --style "
"--symbol --diagnostic-format --result-contract"
).split(),
"switch_options": "--flat --raw-shellcode".split(),
},
"function-bounds": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": "--addr --format --max-input-bytes --output --spill-dir --diagnostic-format".split(),
"switch_options": "".split(),
},
"help": {"classification": "metadata_no_input", "aliases": []},
"inspect-die": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --json-profile --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-embedded": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--format --max-findings --max-input-bytes --offset --output --scan-bytes "
"--spill-dir --diagnostic-format"
).split(),
"switch_options": "".split(),
},
"inspect-flow": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --depth --entry-address --format --max-functions "
"--max-input-bytes --max-instructions-per-function --node-limit --output "
"--per-node-limit --spill-dir --symbol --diagnostic-format --result-contract"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-go": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --function-offset --json-profile "
"--limit --max-functions --max-input-bytes --max-instructions-per-function --output "
"--spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-passes": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --entry-address --format --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --symbol --diagnostic-format --result-contract"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-rust": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --function-offset --json-profile "
"--limit --max-functions --max-input-bytes --max-instructions-per-function --output "
"--spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-types": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --max-functions --max-input-bytes "
"--max-instructions-per-function --output --scalar-evidence-limit "
"--scalar-evidence-offset --spill-dir --variable-function-limit "
"--variable-function-offset --variable-hint-limit --variable-hint-offset --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-upx": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --json-profile --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"inspect-vmp": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --entry-address --format --json-profile --max-functions "
"--max-input-bytes --max-instructions-per-function --output --spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"pe-resources": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--decoded-characters --format --json-profile --limit --max-input-bytes --offset "
"--output --reference-provenance --resource-depth --resource-entries "
"--resource-payload-bytes --scan-bytes --spill-dir --diagnostic-format"
).split(),
"switch_options": "".split(),
},
"pe-strings": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --decoded-characters --entry-address --format --json-profile "
"--limit --max-functions --max-input-bytes --max-instructions-per-function --offset "
"--output --reference-provenance --resource-depth --resource-entries "
"--resource-payload-bytes --scan-bytes --spill-dir --diagnostic-format"
).split(),
"switch_options": "--raw-shellcode".split(),
},
"recover-bytes": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --max-functions --max-input-bytes --max-instructions-per-function --output "
"--spill-dir --diagnostic-format"
).split(),
"switch_options": "".split(),
},
"replay": {"classification": "archive_replay", "aliases": []},
"report": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--arch --base-address --bundle-dir --entry-address --flow-depth --flow-node-limit "
"--flow-per-node-limit --format --function-offset --json-profile --limit "
"--max-functions --max-input-bytes --max-instructions-per-function --max-output-lines "
"--output --sections --spill-dir --style --diagnostic-format --result-contract --function-page-start-cap"
).split(),
"switch_options": "--flat --include-noise --raw-shellcode --split-output".split(),
},
"slice-function": {
"classification": "single_input", "aliases": [], "input_position": 1,
"value_options": (
"--addr --arch --base-address --contains-call --contains-string --entry-address "
"--format --max-functions --max-input-bytes --max-instructions-per-function --output "
"--slice-index --slice-size --slice-start --spill-dir --style --symbol --diagnostic-format --result-contract"
).split(),
"switch_options": "--raw-shellcode".split(),
},
}
FORBIDDEN_FLAGS = {"--execute"}
COMMAND_OWNED_SINK_FLAGS = {"--bundle-dir", "--spill-dir"}
CONTROL_READ_CHUNK_BYTES = 64 * 1024
LOG_TAIL_BYTES = 1024 * 1024
RECEIPT_MAX_BYTES = 256 * 1024
PROGRAM_VERSION_MAX_BYTES = 4096
PROGRAM_VERSION_PATTERN = re.compile(r"^auto-re-cli [0-9]+\.[0-9]+\.[0-9]+$")
class ControlJsonPolicy(NamedTuple):
kind: str
max_encoded_bytes: int
max_depth: int
max_values: int
max_container_entries: int
max_string_bytes: int
ACTION_RESULT_POLICY = ControlJsonPolicy(
"action_result",
64 * 1024 * 1024,
64,
2_000_000,
500_000,
16 * 1024 * 1024,
)
RECEIPT_POLICY = ControlJsonPolicy("prior_receipt", RECEIPT_MAX_BYTES, 16, 10000, 1000, 65536)
RECEIPT_UINT_MAX = (1 << 64) - 1
IDENTITY_INPUT_MAX_BYTES = 512 * 1024 * 1024
IDENTITY_REASONS = frozenset({"unsupported_command", "unsupported_shape", "input_nonregular",
"input_too_large", "input_unstable", "input_unreadable", "available",
"input_unstable_after_execution"})
CONTINUATION_CHECKS = frozenset({"not_requested", "not_evaluated_unavailable_identity",
"changed_analysis", "increased_timeout_after_timeout"})
class ActionError(ValueError):
pass
CapturedStream = process_control.CapturedStream
def _control_file_too_large(policy: ControlJsonPolicy, observed: int) -> ActionError:
return ActionError(
"control_file_too_large: "
f"kind={policy.kind} limit={policy.max_encoded_bytes} "
f"observed_at_least={observed}"
)
def _control_file_structure_limit(
policy: ControlJsonPolicy,
dimension: str,
limit: int,
observed: int,
) -> ActionError:
return ActionError(
"control_file_structure_limit: "
f"kind={policy.kind} dimension={dimension} limit={limit} "
f"observed_at_least={observed}"
)
def _read_bounded_control_bytes(
handle: BinaryIO,
policy: ControlJsonPolicy,
) -> bytes:
data = bytearray()
limit_plus_one = policy.max_encoded_bytes + 1
while len(data) < limit_plus_one:
remaining = limit_plus_one - len(data)
chunk = handle.read(min(CONTROL_READ_CHUNK_BYTES, remaining))
if not chunk:
break
data.extend(chunk)
if len(data) > policy.max_encoded_bytes:
raise _control_file_too_large(policy, len(data))
return bytes(data)
def _utf8_length(value: str) -> int:
if any(0xD800 <= code <= 0xDFFF for code in map(ord, value)):
raise ActionError("invalid_result_boundary: unpaired JSON surrogate")
return sum(
1 if code <= 0x7F else 2 if code <= 0x7FF else 3 if code <= 0xFFFF else 4
for code in map(ord, value)
)
def _validate_json_shape(value: Any, policy: ControlJsonPolicy) -> None:
stack: list[tuple[Any, int]] = [(value, 1)]
value_count = 0
while stack:
current, depth = stack.pop()
if depth > policy.max_depth:
raise _control_file_structure_limit(
policy, "depth", policy.max_depth, depth
)
value_count += 1
if value_count > policy.max_values:
raise _control_file_structure_limit(
policy, "values", policy.max_values, value_count
)
if isinstance(current, str):
length = _utf8_length(current)
if length > policy.max_string_bytes:
raise _control_file_structure_limit(
policy, "string_bytes", policy.max_string_bytes, length
)
elif isinstance(current, float) and not math.isfinite(current):
raise ActionError("invalid_result_boundary: non-finite JSON number")
elif isinstance(current, list):
if len(current) > policy.max_container_entries:
raise _control_file_structure_limit(
policy,
"container_entries",
policy.max_container_entries,
len(current),
)
stack.extend((child, depth + 1) for child in reversed(current))
elif isinstance(current, dict):
if len(current) > policy.max_container_entries:
raise _control_file_structure_limit(
policy,
"container_entries",
policy.max_container_entries,
len(current),
)
for key, child in current.items():
if not isinstance(key, str):
raise ActionError(f"control_file_structure_limit: kind={policy.kind} object keys must be strings")
key_length = _utf8_length(key)
if key_length > policy.max_string_bytes:
raise _control_file_structure_limit(
policy,
"string_bytes",
policy.max_string_bytes,
key_length,
)
stack.append((child, depth + 1))
def _unique_json_members(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
value: dict[str, Any] = {}
for key, child in pairs:
if key in value:
raise ActionError("invalid_result_boundary: duplicate JSON member")
value[key] = child
return value
def load_json_object(
path: pathlib.Path,
*,
policy: ControlJsonPolicy = ACTION_RESULT_POLICY,
) -> dict[str, Any]:
try:
fd = os.open(path, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0))
try:
opened = os.fstat(fd)
if not stat.S_ISREG(opened.st_mode):
raise ActionError("invalid_result_boundary: control JSON must be a regular file")
if opened.st_size > policy.max_encoded_bytes:
raise _control_file_too_large(policy, opened.st_size)
with os.fdopen(fd, "rb", closefd=False) as handle:
data = _read_bounded_control_bytes(handle, policy)
finally:
os.close(fd)
try:
value = json.loads(data.decode("utf-8"), object_pairs_hook=_unique_json_members)
except RecursionError as error:
raise _control_file_structure_limit(policy, "depth", policy.max_depth, policy.max_depth + 1) from error
except ActionError:
raise
except ValueError as error:
raise ActionError(f"invalid_result_boundary: cannot read result JSON: {str(error)[:512]}") from error
except ActionError:
raise
except (OSError, UnicodeDecodeError, json.JSONDecodeError, RecursionError) as error:
raise ActionError(f"invalid_result_boundary: cannot read result JSON: {error}") from error
_validate_json_shape(value, policy)
if not isinstance(value, dict):
raise ActionError("invalid_result_boundary: result JSON root must be an object")
return value
def _matches_shape(result: dict[str, Any], shape: dict[str, type]) -> bool:
return all(isinstance(result.get(field), expected) for field, expected in shape.items())
# Admission freezes root DTO fields, not nested evidence semantics. Unknown
# evidence stays passive; only reviewed controls can select actions/authority.
_FUNCTION_META = {"go_compiler_function": dict, "rust_symbol_name_hint": str,
"rust_source_context": dict, "slice_budget": dict, "next_actions": list}
_IDENTITY = {"display_name": str, "function": dict}
_NULL_OBJECT = (dict, type(None))
_NULL_ARRAY = (list, type(None))
_RESULT_FIELDS = {
"function_detail": ({**_IDENTITY, "static_byte_evidence": dict},
{**_FUNCTION_META, "inferred_role": dict}),
"function_cfg": ({**_IDENTITY, "basic_blocks": list}, _FUNCTION_META),
"function_slice": ({**_IDENTITY, "slice_size": int, "slice": dict,
"semantic_summary": dict, "block_summaries": list, "instructions": list,
"mlil": list, "hlil_flat": list, "pseudo_function_flat": str, "pseudo_flat": str},
{**{k: v for k, v in _FUNCTION_META.items() if k != "slice_budget"},
"inferred_role": dict, "warnings": list}),
"function_flow_graph": ({"root": dict, "summary": dict, "nodes": list,
"edges": list, "warnings": list}, {"next_actions": list}),
"function_il": ({**_IDENTITY, "level": str}, {**_FUNCTION_META, "inferred_role": dict}),
"function_passes": ({**_IDENTITY, "hlil_passes": list, "render_passes": list}, _FUNCTION_META),
"decompile_ai": ({"flat": bool, "binary": dict, "inspections": dict,
"summary": dict, "recovered_types": list, "functions": list}, {"next_actions": list}),
"report_ai": ({"sections": list, "binary": _NULL_OBJECT, "inspections": _NULL_OBJECT,
"summary": _NULL_OBJECT, "flow": _NULL_OBJECT, "recovered_types": _NULL_ARRAY,
"functions": _NULL_ARRAY, "protection_playbook_count": int, "protection_playbooks": list},
{"global_string_samples": list, "current_findings": list, "next_actions": list}),
"inspect-go": ({"binary": dict, "language": dict, "go": _NULL_OBJECT,
"warnings": list}, {"next_actions": list}),
"inspect-rust": ({"binary": dict, "language": dict, "rust": _NULL_OBJECT,
"warnings": list}, {"next_actions": list}),
"inspect-die": ({"file": dict, "fingerprint": dict, "language": dict,
"protections": list, "normalizations": list, "summary": dict,
"flow_root": _NULL_OBJECT, "recovered_types": list, "interesting_functions": list,
"warnings": list}, {"package": dict, "global_string_samples": list, "next_actions": list}),
"upx": ({"inspection": _NULL_OBJECT, "next_actions": list, "warnings": list}, {}),
"vm_protect": ({"inspection": _NULL_OBJECT, "next_actions": list, "warnings": list}, {}),
"pe_resources": ({"input": dict, "budget": dict, "summary": dict, "records": list,
"stop_reasons": list, "next_actions": list, "warnings": list}, {}),
"pe_strings": ({"input": dict, "budget": dict, "summary": dict, "records": list,
"stop_reasons": list, "next_actions": list, "warnings": list}, {}),
"call_graph": ({"root": dict, "budget": dict, "summary": dict, "nodes": list,
"edges": list}, {"stop_reasons": list, "next_actions": list, "warnings": list}),
"data_xrefs": ({"direction": str, "selector": dict, "budget": dict, "summary": dict,
"records": list, "stop_reasons": list, "next_actions": list, "warnings": list}, {}),
"context_bundle": ({"files": list}, {"next_actions": list}),
"agent_spill_manifest": ({"files": list}, {"next_actions": list}),
}
_IL_PAGING = {"statement_limit": int, "statement_contains": str, "statement_address": int,
"statement_contains_search_offset": int, "statement_address_search_offset": int,
"next_statement_offset": int, "next_statement_contains_offset": int}
_IL_FIELDS = {
"llil": ({"instructions": list}, {}), "mlil": ({"instructions": list}, {}),
"hlil": ({"flat": bool, "statements": list}, {}),
"custom": ({"summary": dict, "semantic_ast": dict, "statement_offset": int,
"statements_truncated": bool, "statements": list}, _IL_PAGING),
}
_RESULT_COMMANDS = {
"function_detail": "function", "function_cfg": "dump-cfg",
"function_slice": "slice-function", "function_flow_graph": "inspect-flow",
"function_il": "dump-il", "function_passes": "inspect-passes",
"decompile_ai": "decompile", "report_ai": "report",
"upx": "inspect-upx", "vm_protect": "inspect-vmp",
"pe_resources": "pe-resources", "pe_strings": "pe-strings",
"call_graph": "call-graph", "data_xrefs": "data-xrefs",
}
_RESULT_LABELS = {"function_detail": "wrapper:function", "function_cfg": "wrapper:cfg",
"function_slice": "wrapper:slice_function", "function_flow_graph": "wrapper:flow_graph",
"function_il": "wrapper:function", "function_passes": "wrapper:function",
"call_graph": "wrapper:call_graph", "data_xrefs": "wrapper:data_xrefs"}
_SELECTED_KINDS = frozenset(_RESULT_COMMANDS) - {
"upx", "vm_protect", "pe_resources", "pe_strings", "call_graph", "data_xrefs"}
_LEGACY_SIGNATURES = {
family: set(_RESULT_FIELDS[family][0])
for family in _SELECTED_KINDS | {"inspect-go", "inspect-rust", "inspect-die"}
}
_IL_SUBSHAPE_FIELDS = set().union(
*(set(required) | set(optional) for required, optional in _IL_FIELDS.values()))
def _validate_result_actions(result: dict[str, Any], family: str) -> None:
if "next_actions" not in result:
return
actions = result["next_actions"]
if family == "data_xrefs":
try:
_data_xref_actions(actions)
except ActionError as error:
raise ActionError("invalid_result_boundary: " + str(error)) from error
return
if family in {"pe_resources", "pe_strings"}:
actions = _pe_actions(actions, family)
stages = set()
for row in actions:
if (not isinstance(row, dict)
or any(not isinstance(row.get(field), str) or not row[field].strip()
for field in ("stage", "reason", "expected_output", "stop_condition"))
or not isinstance(row.get("argv"), list)
or any(not isinstance(arg, str) for arg in row["argv"])):
raise ActionError("invalid_result_boundary: invalid next action stage or controls")
if row["stage"] in stages:
raise ActionError("invalid_result_boundary: duplicate next action stage")
stages.add(row["stage"])
def _pe_actions(actions: list[Any], family: str) -> list[dict[str, Any]]:
normalized = []
for row in actions:
if isinstance(row, dict) and "stage" not in row:
argv = row.get("argv")
if (row.get("reason") != "record_limit" or not isinstance(argv, list)
or not argv or argv[0] != _RESULT_COMMANDS[family]):
raise ActionError("invalid_result_boundary: invalid PE legacy action")
row = {**row, "stage": family + ".page"}
normalized.append(row)
return normalized
def validate_result_contract(result: dict[str, Any], *, command: str | None = None) -> str:
schema_version = result.get("schema_version")
if not isinstance(schema_version, str) or schema_version not in SUPPORTED_SCHEMA_VERSIONS:
raise ActionError(f"unsupported_result_version: unsupported result schema_version {repr(schema_version)[:128]}")
explicit = "kind" in result
if explicit:
kind = result["kind"]
if not isinstance(kind, str) or kind not in _SELECTED_KINDS | {
"call_graph", "data_xrefs", "upx", "vm_protect", "pe_resources", "pe_strings",
*SUPPORTED_MANIFEST_KINDS}:
raise ActionError(f"unsupported_result_kind: {repr(kind)[:128]}")
family = kind
else:
candidates = [family for family, fields in _LEGACY_SIGNATURES.items()
if fields <= result.keys()]
if len(candidates) > 1:
raise ActionError("ambiguous_legacy_result: conflicting family discriminators")
if not candidates:
raise ActionError("invalid_result_fields: result is not a supported Auto-RE wrapper")
family = candidates[0]
manifest = family in SUPPORTED_MANIFEST_KINDS
if manifest and {"verified_root", "cleanup_token", "consumption_contract"} <= result.keys():
raise ActionError("invalid_result_boundary: verifier operational output is not a result manifest")
if (manifest and result.get("owner") != "auto-re-cli") or (not manifest and "owner" in result):
raise ActionError("invalid_result_boundary: invalid result owner")
expected_profile = ({"ai", "full"} if family in {"call_graph", "data_xrefs"} else
{"ai"} if family in {"decompile_ai", "report_ai", "inspect-go", "inspect-rust",
"inspect-die", "upx", "vm_protect", "pe_resources", "pe_strings", "context_bundle"}
else None)
profile = result.get("profile")
if ((expected_profile is None and "profile" in result) or
(expected_profile is not None and (not isinstance(profile, str) or profile not in expected_profile))):
raise ActionError(f"invalid_result_profile: invalid {family}.profile: {repr(profile)[:128]}")
required, optional = _RESULT_FIELDS[family]
if family == "function_il":
level = result.get("level")
if not isinstance(level, str) or level not in _IL_FIELDS:
raise ActionError("invalid_result_fields: unsupported IL level")
il_required, il_optional = _IL_FIELDS[level]
required = {**required, **il_required}
optional = {**optional, **il_optional}
conflicts = set()
if family != "function_il" and "level" in result:
conflicts.add("level")
if family not in {"report_ai", "context_bundle"} and "sections" in result:
conflicts.add("sections")
function_root = _IDENTITY.keys() <= required.keys()
if function_root:
for foreign, fields in (("function_cfg", {"basic_blocks"}),
("function_slice", {"slice", "slice_size"}),
("function_passes", {"hlil_passes", "render_passes"})):
if family != foreign:
conflicts |= fields & result.keys()
conflicts |= {"root", "nodes", "edges"} & result.keys()
elif "function" in result:
conflicts.add("function")
if family == "inspect-die" and "binary" in result:
conflicts.add("binary")
if family == "report_ai" and "flat" in result:
conflicts.add("flat")
if family == "function_il":
conflicts |= (_IL_SUBSHAPE_FIELDS & result.keys()) - (set(il_required) | set(il_optional))
for foreign, fields in _LEGACY_SIGNATURES.items():
# Explicit call_graph shares the frozen flow shape.
if foreign == family or (family == "call_graph" and foreign == "function_flow_graph"):
continue
if fields <= result.keys():
conflicts |= fields
if conflicts:
reason = "invalid_result_fields" if explicit else "ambiguous_legacy_result"
raise ActionError(f"{reason}: foreign family fields: {', '.join(sorted(conflicts))}")
for field, expected in {**required, **optional}.items():
if field not in result and field in optional:
continue
value = result.get(field)
if field not in result or not isinstance(value, expected) or (expected is int and type(value) is not int):
raise ActionError(f"invalid_result_fields: invalid {family}.{field}")
if expected is int:
minimum = 1 if field in {"slice_size", "statement_limit"} else 0
if value < minimum or (field == "statement_address" and value > 2**64 - 1):
raise ActionError(f"invalid_result_fields: invalid {family}.{field}")
if family == "report_ai":
sections = result["sections"]
if (any(not isinstance(section, str) or section not in {
"binary", "inspections", "summary", "types", "flow", "functions"} for section in sections)
or len(set(sections)) != len(sections)):
raise ActionError("invalid_result_fields: invalid report sections")
if family == "data_xrefs":
direction = result.get("direction")
if not isinstance(direction, str) or direction not in {"code_to_data", "data_to_code"}:
raise ActionError("invalid_result_fields: invalid data_xrefs.direction")
selector = result.get("selector")
if not isinstance(selector, dict) or not isinstance(selector.get("kind"), str):
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
selector_kind = selector["kind"]
if selector_kind == "all":
if "value" in selector:
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
elif selector_kind in {"function", "string_exact", "global_exact"}:
if not isinstance(selector.get("value"), str):
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
elif selector_kind in {"function_address", "data_address"}:
if type(selector.get("value")) is not int or not 0 <= selector["value"] <= 2**64 - 1:
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
elif selector_kind == "data_address_range":
value = selector.get("value")
if (not isinstance(value, dict) or type(value.get("start")) is not int
or type(value.get("end")) is not int
or not 0 <= value["start"] < value["end"] <= 2**64 - 1):
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
else:
raise ActionError("invalid_result_fields: invalid data_xrefs.selector")
if (not _matches_shape(result, {"budget": dict, "summary": dict,
"records": list, "stop_reasons": list,
"next_actions": list, "warnings": list})
or any(not isinstance(row, dict) for row in result["records"])
or any(not isinstance(row, dict) for row in result["stop_reasons"])
or any(not isinstance(warning, str) for warning in result["warnings"])):
raise ActionError("invalid_result_fields: invalid data_xrefs wrapper")
_validate_result_actions(result, family)
if command is not None and command != _RESULT_COMMANDS.get(family, family):
raise ActionError(f"result_command_mismatch: {command} received {family}")
return (f"manifest:{family}" if manifest else _RESULT_LABELS.get(family, "profile:ai"))
def _data_xref_actions(actions: list[Any]) -> list[dict[str, Any]]:
legacy = {"record_limit": ("data_xrefs.page", "data-xrefs"),
"provenance_limit": ("data_xrefs.provenance", "slice-function")}
normalized = []
stages = set()
for action in actions:
if (not isinstance(action, dict)
or not isinstance(action.get("reason"), str)
or not action["reason"].strip()
or not isinstance(action.get("argv"), list)
or len(action["argv"]) < 2
or any(not isinstance(item, str) for item in action["argv"])
or any(not isinstance(action.get(field), str) or not action[field].strip()
for field in ("expected_output", "stop_condition"))):
raise ActionError("invalid data_xrefs next action")
if "stage" in action:
stage = action["stage"]
if not isinstance(stage, str) or not stage.strip():
raise ActionError("invalid data_xrefs next action stage")
source = "explicit"
else:
pair = legacy.get(action["reason"])
if pair is None or action["argv"][1] != pair[1]:
raise ActionError("cannot derive data_xrefs legacy action stage")
stage, _command = pair
source = "legacy_reason"
if stage in stages:
raise ActionError("duplicate data_xrefs next action stage")
stages.add(stage)
normalized.append({**action, "stage": stage, "_stage_source": source})
return normalized
def utc_now() -> str:
return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
def sha256_file(path: pathlib.Path) -> str:
digest = hashlib.sha256()
try:
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
except OSError as error:
raise ActionError(f"cannot hash trusted program: {error}") from error
return digest.hexdigest()
def _identity_argv_shape(argv: list[str]) -> tuple[int | None, set[int], str]:
"""Locate the sole positional and parsed sinks using the pinned arity table."""
index = 1
sinks: set[int] = set()
while index < len(argv) and argv[index].startswith("-"):
flag, equals, _value = argv[index].partition("=")
if flag not in IDENTITY_GLOBAL_VALUE_OPTIONS:
return None, sinks, "unsupported_shape"
if flag == "--output":
sinks.add(index)
if not equals:
index += 1
if index >= len(argv) or argv[index].startswith("-"):
return None, sinks, "unsupported_shape"
if flag == "--output":
sinks.add(index)
index += 1
if index >= len(argv):
return None, sinks, "unsupported_command"
contract = IDENTITY_COMMAND_CONTRACT.get(argv[index])
if contract is None or contract["classification"] != "single_input":
return None, sinks, "unsupported_command"
index += 1
input_index = None
positional_only = False
while index < len(argv):
argument = argv[index]
if argument == "--" and not positional_only:
positional_only = True
elif argument.startswith("-") and not positional_only:
flag, equals, _value = argument.partition("=")
if flag in contract["value_options"]:
if flag in COMMAND_OWNED_SINK_FLAGS | {"--output"}:
sinks.add(index)
if not equals:
sinks.add(index + 1)
if not equals:
index += 1
if index >= len(argv) or argv[index].startswith("-"):
return None, sinks, "unsupported_shape"
elif flag not in contract["switch_options"] or equals:
return None, sinks, "unsupported_shape"
elif input_index is None:
input_index = index
else:
return None, sinks, "unsupported_shape"
index += 1
return input_index, sinks, "available" if input_index is not None else "unsupported_shape"
def _request_identity_with_reason(argv: list[str], program_sha256: str,
program_version: str = "auto-re-cli " + IDENTITY_CONTRACT_VERSION) -> tuple[dict[str, Any] | None, str]:
"""Identify an audited single-input request without its output destinations."""
if program_version != "auto-re-cli " + IDENTITY_CONTRACT_VERSION:
return None, "unsupported_command"
input_index, _sinks, reason = _identity_argv_shape(argv)
if input_index is None:
return None, reason
try:
fd = os.open(argv[input_index], os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0))
try:
before = os.fstat(fd)
except OSError:
os.close(fd)
raise
if not stat.S_ISREG(before.st_mode):
os.close(fd)
return None, "input_nonregular"
with os.fdopen(fd, "rb") as handle:
if before.st_size > IDENTITY_INPUT_MAX_BYTES:
return None, "input_too_large"
digest = hashlib.sha256()
observed = 0
for chunk in iter(lambda: handle.read(CONTROL_READ_CHUNK_BYTES), b""):
observed += len(chunk)
if observed > before.st_size:
return None, "input_unstable"
digest.update(chunk)
after = os.fstat(handle.fileno())
if observed != before.st_size or (before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns):
return None, "input_unstable"
except OSError:
return None, "input_unreadable"
return _make_request_identity(argv, program_sha256, digest.hexdigest(), before.st_size), "available"
def _make_request_identity(argv: list[str], program_sha256: str,
input_sha256: str, input_bytes: int) -> dict[str, Any]:
"""Share the exact duplicated argv projection with side-effect-free admission."""
input_index, sinks, reason = _identity_argv_shape(argv)
if input_index is None:
raise ActionError("cannot project request identity: " + reason)
arguments = ["<input-sha256>=" + input_sha256 if index == input_index else argument
for index, argument in enumerate(argv) if index > 0 and index not in sinks]
identity = {"input_sha256": input_sha256, "input_bytes": input_bytes,
"program_sha256": program_sha256, "analysis_argv": arguments}
identity["sha256"] = hashlib.sha256(json.dumps(identity, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
return identity
def request_identity(argv: list[str], program_sha256: str,
program_version: str = "auto-re-cli " + IDENTITY_CONTRACT_VERSION) -> dict[str, Any] | None:
return _request_identity_with_reason(argv, program_sha256, program_version)[0]
def validate_prior_receipt(prior: dict[str, Any]) -> dict[str, Any]:
if (type(prior.get("schema_version")) is not int or prior["schema_version"] != 1
or prior.get("owner") != "auto-re-skill"
or prior.get("kind") != "auto_re_action_execution_receipt"):
raise ActionError("invalid prior receipt identity")
identity = prior.get("request_identity")
if identity is not None:
if not isinstance(identity, dict) or set(identity) != {
"input_sha256", "input_bytes", "program_sha256", "analysis_argv", "sha256"
}:
raise ActionError("invalid prior request_identity")
digest_fields = ("input_sha256", "program_sha256", "sha256")
if any(not isinstance(identity.get(field), str) or
re.fullmatch(r"[0-9a-f]{64}", identity[field]) is None
for field in digest_fields):
raise ActionError("invalid prior request_identity hash")
if (type(identity.get("input_bytes")) is not int or identity["input_bytes"] < 0
or not isinstance(identity.get("analysis_argv"), list)
or not identity["analysis_argv"]
or any(not isinstance(item, str) for item in identity["analysis_argv"])):
raise ActionError("invalid prior request_identity fields")
payload = {field: identity[field] for field in
("input_sha256", "input_bytes", "program_sha256", "analysis_argv")}
expected = hashlib.sha256(json.dumps(payload, sort_keys=True,
separators=(",", ":")).encode()).hexdigest()
if identity["sha256"] != expected:
raise ActionError("invalid prior request_identity digest")
if "execution_status" in prior and (not isinstance(prior["execution_status"], str)
or not prior["execution_status"]):
raise ActionError("invalid prior execution_status")
if "timeout_seconds" in prior:
try:
process_control.validate_seconds(prior["timeout_seconds"])
except process_control.ProcessError as error:
raise ActionError("invalid prior timeout_seconds") from error
if "leader_reaped" in prior and not isinstance(prior["leader_reaped"], bool):
raise ActionError("invalid prior leader_reaped")
return prior
def assess_continuation(prior: dict[str, Any] | None, identity: dict[str, Any] | None,
timeout_seconds: float) -> str:
if prior is None:
return "not_requested"
prior_identity = prior.get("request_identity")
if prior_identity is None or identity is None:
return "not_evaluated_unavailable_identity"
if prior_identity != identity:
return "changed_analysis"
if prior.get("execution_status") == "timed_out":
if prior.get("leader_reaped") is not True:
raise ActionError("unresolved_prior_process: timed out leader was not confirmed reaped")
previous_timeout = prior.get("timeout_seconds")
if previous_timeout is not None and timeout_seconds > previous_timeout:
return "increased_timeout_after_timeout"
if "execution_status" not in prior or "timeout_seconds" not in prior:
raise ActionError("no_progress: prior receipt lacks status or timeout needed for a safe exception")
raise ActionError("no_progress: identical input, tool, selector and budget; inspect the prior result instead of renaming and repeating it")
def receipt_log_dir(receipt_path: pathlib.Path) -> pathlib.Path:
requested = receipt_path.expanduser().absolute()
return requested.parent / f"{requested.name}.logs"
def _require_absent(path: pathlib.Path, label: str) -> None:
try:
path.lstat()
except FileNotFoundError:
return
except OSError as error:
raise ActionError(f"cannot inspect {label}: {error}") from error
raise ActionError(f"{label} already exists: {path}")
def prepare_receipt_paths(receipt_path: pathlib.Path) -> tuple[pathlib.Path, pathlib.Path]:
requested = receipt_path.expanduser().absolute()
try:
parent = requested.parent.resolve(strict=True)
except OSError as error:
raise ActionError(f"receipt output parent is unavailable: {error}") from error
receipt = parent / requested.name
logs = parent / f"{requested.name}.logs"
_require_absent(receipt, "receipt output")
_require_absent(logs, "log directory")
return receipt, logs
def _write_private_bytes(path: pathlib.Path, data: bytes, label: str) -> None:
created: Optional[os.stat_result] = None
def private_opener(name: str, flags: int) -> int:
return os.open(name, flags, 0o600)
try:
with open(path, "xb", opener=private_opener) as output:
created = os.fstat(output.fileno())
output.write(data)
output.flush()
os.fsync(output.fileno())
if hasattr(os, "fchmod"):
os.fchmod(output.fileno(), 0o400)
if not os.path.samestat(created, path.lstat()):
raise OSError("output object changed during write")
if not hasattr(os, "fchmod"):
path.chmod(0o400)
except OSError as error:
cleanup_error = None
# A failed exclusive open never grants ownership of the destination.
# Also preserve any replacement object observed after a later failure.
if created is not None:
try:
if os.path.samestat(created, path.lstat()):
path.unlink()
except FileNotFoundError:
pass
except OSError as failure:
cleanup_error = failure
detail = f"cannot write {label}: {error}"
if cleanup_error is not None:
detail += f"; cannot remove incomplete owned output: {cleanup_error}"
raise ActionError(detail) from error
def _encode_receipt(value: dict[str, Any]) -> bytes:
_validate_json_shape(value, RECEIPT_POLICY)
validate_prior_receipt(value)
encoded = (json.dumps(value, indent=2, sort_keys=True) + "\n").encode("utf-8")
if len(encoded) > RECEIPT_MAX_BYTES:
raise ActionError(
"execution receipt exceeds limit: "
f"limit={RECEIPT_MAX_BYTES} observed={len(encoded)}"
)
return encoded
def _write_receipt(path: pathlib.Path, value: dict[str, Any]) -> None:
_write_private_bytes(path, _encode_receipt(value), "execution receipt")
def probe_program_version(executable: pathlib.Path) -> str:
try:
combined = process_control.probe_output(executable, max_bytes=PROGRAM_VERSION_MAX_BYTES)
except process_control.ProcessError as error:
raise ActionError(f"cannot probe trusted program version: {error}") from error
try:
output = combined.decode("utf-8").strip()
except UnicodeDecodeError as error:
raise ActionError("trusted program version output is not UTF-8") from error
if not output:
raise ActionError("trusted program version output is empty")
if PROGRAM_VERSION_PATTERN.fullmatch(output) is None:
raise ActionError(f"unexpected trusted program version output: {output!r}")
return output
def _stream_receipt(
path: pathlib.Path,
captured: CapturedStream,
tail_limit: int,
) -> dict[str, Any]:
return {
"path": str(path),
"retention": "tail",
"tail_limit_bytes": tail_limit,
"bytes_total": captured.bytes_total,
"bytes_retained": len(captured.tail),
"sha256": captured.sha256,
"retained_sha256": hashlib.sha256(captured.tail).hexdigest(),
"truncated": captured.bytes_total > len(captured.tail),
"capture_complete": captured.complete,
"digest_scope": "complete_stream" if captured.complete else "observed_prefix",
}
def _sink_record(prepared: dict[str, Any]) -> dict[str, Any]:
argv = prepared["argv"]
if prepared["command_owned_sink"]:
flags = [
argument
for argument in argv
if any(
argument == flag or argument.startswith(f"{flag}=")
for flag in COMMAND_OWNED_SINK_FLAGS
)
]
return {"ownership": "command", "arguments": flags}
output_index = len(argv) - 2
if output_index >= 0 and argv[output_index] == "--output":
return {"ownership": "caller", "path": argv[output_index + 1]}
return {"ownership": "unresolved"}
def _receipt_value(prepared, executable, program_version, program_sha256, identity,
identity_reason, continuation_check, log_dir, captured, started_at,
ended_at, duration_ms, log_tail_bytes, timeout_seconds):
stdout_path = log_dir / "stdout.tail.log"
stderr_path = log_dir / "stderr.tail.log"
argv = [str(executable), *prepared["argv"][1:]]
exit_code = execution_exit_code(captured)
value = {
"schema_version": 1,
"owner": "auto-re-skill",
"kind": "auto_re_action_execution_receipt",
"action_stage": prepared["action_stage"],
"reason": prepared["reason"],
"expected_output": prepared["expected_output"],
"stop_condition": prepared["stop_condition"],
"program": {
"path": str(executable),
"version_output": program_version,
"sha256": program_sha256,
},
"argv": argv,
"request_identity": identity,
"request_identity_unavailable_reason": identity_reason,
"continuation_check": continuation_check,
"sink": _sink_record(prepared),
"started_at": started_at,
"ended_at": ended_at,
"duration_ms": duration_ms,
"exit_code": exit_code,
"process_exit_code": captured.returncode,
"execution_status": captured.status,
"timeout_seconds": timeout_seconds,
"leader_reaped": captured.leader_reaped,
"diagnostics": list(captured.diagnostics),
"stdout": _stream_receipt(
stdout_path, captured.stdout, log_tail_bytes
),
"stderr": _stream_receipt(
stderr_path, captured.stderr, log_tail_bytes
),
"evidence_boundary": "operational_diagnostics_not_target_analysis_evidence",
}
if "action_stage_source" in prepared:
value["action_stage_source"] = prepared["action_stage_source"]
_validate_generated_receipt_fields(value)
return value
def _validate_generated_receipt_fields(value: dict[str, Any]) -> None:
"""Explicit generator ceilings; invariant failure never clips evidence."""
def integer(number, low, high, field):
if type(number) is not int or not low <= number <= high:
raise ActionError(f"receipt dynamic invariant: {field} outside {low}..{high}")
integer(value["duration_ms"], 0, RECEIPT_UINT_MAX, "duration_ms")
integer(value["exit_code"], -RECEIPT_UINT_MAX, RECEIPT_UINT_MAX + 128, "exit_code")
if value["process_exit_code"] is not None:
integer(value["process_exit_code"], -RECEIPT_UINT_MAX, RECEIPT_UINT_MAX, "process_exit_code")
if value["execution_status"] not in process_control.PROCESS_STATUSES:
raise ActionError("receipt dynamic invariant: unsupported execution_status")
if value["continuation_check"] not in CONTINUATION_CHECKS:
raise ActionError("receipt dynamic invariant: unsupported continuation_check")
if (value["request_identity_unavailable_reason"] is not None
and value["request_identity_unavailable_reason"] not in IDENTITY_REASONS):
raise ActionError("receipt dynamic invariant: unsupported identity reason")
for field in ("started_at", "ended_at"):
if not isinstance(value[field], str) or len(value[field]) > 27 or not value[field].isascii():
raise ActionError(f"receipt dynamic invariant: invalid {field}")
diagnostics = value["diagnostics"]
if len(diagnostics) > process_control.DIAGNOSTIC_MAX_ENTRIES:
raise ActionError("receipt dynamic invariant: too many diagnostics")
for diagnostic in diagnostics:
if diagnostic == "pipe_drain_timeout":
continue
if not isinstance(diagnostic, str) or not any(
diagnostic.startswith(prefix)
and len(diagnostic) - len(prefix) <= process_control.DIAGNOSTIC_EXCEPTION_CHARACTERS
for prefix in process_control.DIAGNOSTIC_PREFIXES
):
raise ActionError("receipt dynamic invariant: invalid diagnostic")
for name in ("stdout", "stderr"):
stream = value[name]
integer(stream["bytes_total"], 0, RECEIPT_UINT_MAX, f"{name}.bytes_total")
integer(stream["bytes_retained"], 0, stream["tail_limit_bytes"], f"{name}.bytes_retained")
if stream["bytes_retained"] > stream["bytes_total"]:
raise ActionError("receipt dynamic invariant: retained bytes exceed observed bytes")
def receipt_budget_plan(prepared: dict[str, Any], log_dir: pathlib.Path, *,
executable: str = "", program_version: str | None = None,
program_sha256: str = "f" * 64,
identity: dict[str, Any] | None = None,
continuation_check: str | None = None,
log_tail_bytes: int = LOG_TAIL_BYTES,
timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS) -> dict[str, Any]:
"""Encode the common schema with maxima derived from bounded generators.
The known pass reserves a possible identity without reading the target.
The resolved pass also covers an identity disappearing after execution.
False is the largest boolean encoding; None is smaller than reserved strings,
signed return code and identity object. Hash lengths and argv projection are
exact. UTF-16 surrogate pairs cost at most twelve JSON bytes per character.
"""
try:
timeout_seconds = process_control.validate_seconds(timeout_seconds)
except process_control.ProcessError as error:
raise ActionError(str(error)) from error
for field in ("action_stage", "reason", "expected_output", "stop_condition"):
if not isinstance(prepared.get(field), str) or not prepared[field].strip():
raise ActionError(f"prepared action is missing {field}")
if "action_stage_source" in prepared and not isinstance(prepared["action_stage_source"], str):
raise ActionError("prepared action_stage_source must be a string")
if type(log_tail_bytes) is not int or not 0 <= log_tail_bytes <= LOG_TAIL_BYTES:
raise ActionError(f"log tail byte limit must be an integer between 0 and {LOG_TAIL_BYTES}")
argv = prepared["argv"]
if identity is None and _identity_argv_shape(argv)[0] is not None:
identity = _make_request_identity(argv, program_sha256, "f" * 64, IDENTITY_INPUT_MAX_BYTES)
if program_version is None:
program_version = "auto-re-cli " + "9" * (PROGRAM_VERSION_MAX_BYTES - 16) + ".9.9"
if len(program_version.encode("utf-8")) > PROGRAM_VERSION_MAX_BYTES or PROGRAM_VERSION_PATTERN.fullmatch(program_version) is None:
raise ActionError("receipt dynamic invariant: invalid version output")
if continuation_check is None:
continuation_check = max(CONTINUATION_CHECKS, key=len)
diagnostic = max(process_control.DIAGNOSTIC_PREFIXES, key=len) + "\U0001f600" * process_control.DIAGNOSTIC_EXCEPTION_CHARACTERS
stream = CapturedStream(b"", RECEIPT_UINT_MAX, "f" * 64, False)
captured = process_control.ProcessResult(-RECEIPT_UINT_MAX,
max(process_control.PROCESS_STATUSES, key=len), stream, stream,
(diagnostic,) * process_control.DIAGNOSTIC_MAX_ENTRIES, False)
value = _receipt_value(prepared, executable, program_version, program_sha256,
identity, max(IDENTITY_REASONS, key=len), continuation_check, log_dir,
captured, "9999-12-31T23:59:59.999999Z", "9999-12-31T23:59:59.999999Z",
RECEIPT_UINT_MAX, log_tail_bytes, timeout_seconds)
for name in ("stdout", "stderr"):
value[name]["bytes_retained"] = log_tail_bytes
value[name]["truncated"] = False
# The longest status and the longest mapped exit do not occur together;
# reserving each field's maximum covers all admitted status/exit pairs.
value["exit_code"] = RECEIPT_UINT_MAX + 128
encoded = _encode_receipt(value)
return {"encoded_upper_bound": len(encoded), "encoded_limit": RECEIPT_MAX_BYTES,
"program_and_identity_checked": bool(executable)}
def _command_sink_values(argv: list[str]) -> list[pathlib.Path]:
sinks: list[pathlib.Path] = []
for index, argument in enumerate(argv):
for flag in COMMAND_OWNED_SINK_FLAGS:
if argument == flag:
if index + 1 >= len(argv) or argv[index + 1].startswith("--"):
raise ActionError(f"{flag} requires an output directory")
value = argv[index + 1]
elif argument.startswith(f"{flag}="):
value = argument.split("=", 1)[1]
else:
continue
if not value:
raise ActionError(f"{flag} requires an output directory")
# argv is passed with shell=False: a literal ~ is not expanded.
sinks.append(pathlib.Path(value).resolve())
if not sinks:
raise ActionError("command-owned action is missing an output directory")
return sinks
def validate_receipt_sink_separation(
prepared: dict[str, Any],
receipt: pathlib.Path,
log_dir: pathlib.Path,
) -> None:
def overlaps(left: pathlib.Path, right: pathlib.Path) -> bool:
return left == right or left in right.parents or right in left.parents
try:
receipt = receipt.expanduser().resolve()
log_dir = log_dir.expanduser().resolve()
argv = prepared["argv"]
if prepared["command_owned_sink"]:
for sink in _command_sink_values(argv):
if overlaps(receipt, sink) or overlaps(log_dir, sink):
raise ActionError(
"receipt or log path overlaps a command-owned action sink"
)
return
output = pathlib.Path(argv[-1]).resolve()
if overlaps(receipt, output) or overlaps(log_dir, output):
raise ActionError("receipt or log path aliases action output")
except ActionError:
raise
except (OSError, RuntimeError, ValueError) as error:
raise ActionError(f"cannot resolve receipt/action sink paths: {error}") from error
def prepare_action_receipt_paths(
prepared: dict[str, Any], receipt_path: pathlib.Path, *,
log_tail_bytes: int = LOG_TAIL_BYTES,
timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
) -> tuple[pathlib.Path, pathlib.Path]:
"""Apply the same side-effect-free receipt preflight to preview and execution."""
validate_prepared_argv(
prepared.get("argv"),
command_owned_sink=prepared.get("command_owned_sink") is True,
)
receipt, logs = prepare_receipt_paths(receipt_path)
validate_receipt_sink_separation(prepared, receipt, logs)
receipt_budget_plan(prepared, logs, log_tail_bytes=log_tail_bytes,
timeout_seconds=timeout_seconds)
return receipt, logs
def execute_prepared_with_receipt(
prepared: dict[str, Any],
executable: pathlib.Path,
receipt_path: pathlib.Path,
*,
log_tail_bytes: int = LOG_TAIL_BYTES,
timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
prior_receipt: pathlib.Path | None = None,
) -> tuple[int, dict[str, Any]]:
if (
not isinstance(log_tail_bytes, int)
or isinstance(log_tail_bytes, bool)
or not 0 <= log_tail_bytes <= LOG_TAIL_BYTES
):
raise ActionError(
f"log tail byte limit must be an integer between 0 and {LOG_TAIL_BYTES}"
)
try:
timeout_seconds = process_control.validate_seconds(timeout_seconds)
except process_control.ProcessError as error:
raise ActionError(str(error)) from error
receipt, log_dir = prepare_action_receipt_paths(prepared, receipt_path,
log_tail_bytes=log_tail_bytes, timeout_seconds=timeout_seconds)
try:
resolved_executable = executable.expanduser().resolve(strict=True)
except OSError as error:
raise ActionError(f"cannot resolve trusted program: {error}") from error
if not resolved_executable.is_file():
raise ActionError("trusted program must be a regular file")
program_version = probe_program_version(resolved_executable)
program_sha256 = sha256_file(resolved_executable)
identity, identity_reason = _request_identity_with_reason(prepared["argv"], program_sha256, program_version)
prior = None
if prior_receipt is not None:
prior = validate_prior_receipt(load_json_object(
prior_receipt, policy=RECEIPT_POLICY))
continuation_check = assess_continuation(prior, identity, timeout_seconds)
receipt_budget_plan(prepared, log_dir, executable=str(resolved_executable),
program_version=program_version, program_sha256=program_sha256,
identity=identity, continuation_check=continuation_check,
log_tail_bytes=log_tail_bytes, timeout_seconds=timeout_seconds)
try:
log_dir.mkdir(mode=0o700)
except OSError as error:
raise ActionError(f"cannot create log directory: {error}") from error
stdout_path = log_dir / "stdout.tail.log"
stderr_path = log_dir / "stderr.tail.log"
argv = [str(resolved_executable), *prepared["argv"][1:]]
started_at = utc_now()
started_monotonic = time.monotonic()
try:
captured = process_control.run_process(
argv, timeout_seconds=timeout_seconds, tail_bytes=log_tail_bytes,
)
except process_control.ProcessError as error:
shutil.rmtree(log_dir, ignore_errors=True)
raise ActionError(str(error)) from error
results = {"stdout": captured.stdout, "stderr": captured.stderr}
exit_code = execution_exit_code(captured)
ended_at = utc_now()
duration_ms = round((time.monotonic() - started_monotonic) * 1000)
final_identity, final_reason = _request_identity_with_reason(prepared["argv"], program_sha256, program_version)
if final_identity != identity:
identity_reason = "input_unstable_after_execution"
elif identity is None:
identity_reason = final_reason
try:
_write_private_bytes(stdout_path, results["stdout"].tail, "stdout tail log")
_write_private_bytes(stderr_path, results["stderr"].tail, "stderr tail log")
receipt_value = _receipt_value(
prepared, resolved_executable, program_version, program_sha256,
identity if final_identity == identity else None,
None if final_identity == identity and identity is not None else identity_reason,
continuation_check, log_dir, captured, started_at, ended_at, duration_ms,
log_tail_bytes, timeout_seconds,
)
_write_receipt(receipt, receipt_value)
except BaseException:
shutil.rmtree(log_dir, ignore_errors=True)
raise
summary = {
"ok": exit_code == 0,
"owner": "auto-re-skill",
"kind": "auto_re_action_execution_summary",
"receipt_path": str(receipt),
"exit_code": exit_code,
"process_exit_code": captured.returncode,
"execution_status": captured.status,
"continuation_check": continuation_check,
"request_identity_unavailable_reason": receipt_value["request_identity_unavailable_reason"],
"diagnostics": list(captured.diagnostics),
"stdout_truncated": receipt_value["stdout"]["truncated"],
"stderr_truncated": receipt_value["stderr"]["truncated"],
}
return exit_code, summary
def select_action(result: dict[str, Any], action_stage: str) -> dict[str, Any]:
actions = result.get("next_actions")
if not isinstance(actions, list):
raise ActionError("result next_actions must be an array")
matches = [
action
for action in actions
if isinstance(action, dict) and action.get("stage") == action_stage
]
if len(matches) != 1:
raise ActionError(
"action stage must select exactly one next action: "
f"{action_stage!r}"
)
action = matches[0]
for field in ("reason", "expected_output", "stop_condition"):
if not isinstance(action.get(field), str) or not action[field].strip():
raise ActionError(f"selected action is missing {field}")
return action
def validate_argv(value: Any) -> list[str]:
if not isinstance(value, list) or not value:
raise ActionError("selected action argv must be a non-empty array")
if any(
not isinstance(argument, str) or not argument or "\0" in argument
for argument in value
):
raise ActionError("selected action argv must contain non-empty strings")
argv = list(value)
if argv[0] != TRUSTED_PROGRAM:
raise ActionError("selected action must use the trusted auto-re-cli program")
for flag in FORBIDDEN_FLAGS:
if any(argument == flag or argument.startswith(f"{flag}=") for argument in argv):
raise ActionError(f"forbidden action flag: {flag}")
if any(
argument == "--output" or argument.startswith("--output=")
for argument in argv
):
raise ActionError("emitted next action must not inherit --output")
return argv
def validate_prepared_argv(value: Any, *, command_owned_sink: bool) -> list[str]:
if not isinstance(value, list) or not value:
raise ActionError("prepared action argv must be a non-empty array")
if any(
not isinstance(argument, str) or not argument or "\0" in argument
for argument in value
):
raise ActionError("prepared action argv must contain non-empty strings")
argv = list(value)
if argv[0] != TRUSTED_PROGRAM:
raise ActionError("prepared action must use the trusted auto-re-cli program")
for flag in FORBIDDEN_FLAGS:
if any(argument == flag or argument.startswith(f"{flag}=") for argument in argv):
raise ActionError(f"forbidden action flag: {flag}")
output_positions = [
index
for index, argument in enumerate(argv)
if argument == "--output" or argument.startswith("--output=")
]
has_command_sink = any(
argument == flag or argument.startswith(f"{flag}=")
for argument in argv
for flag in COMMAND_OWNED_SINK_FLAGS
)
if command_owned_sink:
if not has_command_sink or output_positions:
raise ActionError("prepared command-owned action has an invalid sink")
try:
_command_sink_values(argv)
except (OSError, RuntimeError) as error:
raise ActionError(f"cannot resolve action output directories: {error}") from error
elif (
has_command_sink
or len(output_positions) != 1
or output_positions[0] != len(argv) - 2
or argv[output_positions[0]] != "--output"
):
raise ActionError("prepared caller-owned action must end with one --output path")
return argv
def prepare_action(
result_path: pathlib.Path,
action_stage: str,
output: Optional[pathlib.Path],
) -> dict[str, Any]:
result_path = result_path.expanduser().resolve()
result = load_json_object(result_path)
result_wrapper = validate_result_contract(result)
if result_wrapper == "wrapper:data_xrefs":
result = {**result, "next_actions": _data_xref_actions(result["next_actions"])}
elif result.get("kind") in {"pe_resources", "pe_strings"}:
result = {**result, "next_actions": _pe_actions(result["next_actions"], result["kind"])}
action = select_action(result, action_stage)
argv = validate_argv(action.get("argv"))
command_owned_sink = any(
argument == flag or argument.startswith(f"{flag}=")
for argument in argv
for flag in COMMAND_OWNED_SINK_FLAGS
)
if command_owned_sink:
if output is not None:
raise ActionError(
"selected action already owns its output sink; omit --output"
)
else:
if output is None:
raise ActionError("selected action requires a new explicit --output path")
output = output.expanduser().resolve()
if output == result_path:
raise ActionError("selected action output must not overwrite its parent result")
if not output.parent.is_dir():
raise ActionError(
f"selected action output parent does not exist: {output.parent}"
)
argv.extend(["--output", str(output)])
validate_prepared_argv(argv, command_owned_sink=command_owned_sink)
prepared = {
"ok": True,
"schema_version": result["schema_version"],
"result_wrapper": result_wrapper,
"action_stage": action_stage,
"reason": action["reason"],
"expected_output": action["expected_output"],
"stop_condition": action["stop_condition"],
"command_owned_sink": command_owned_sink,
"argv": argv,
}
if "_stage_source" in action:
prepared["action_stage_source"] = action["_stage_source"]
return prepared
def execution_exit_code(result) -> int:
if result.status == "timed_out":
return 124
if result.status == "cancelled":
return 130
if result.status != "completed" or result.returncode is None:
return 125
return result.returncode if result.returncode >= 0 else 128 - result.returncode
def positive_seconds(text: str) -> float:
try:
return process_control.validate_seconds(float(text))
except ValueError as error:
raise argparse.ArgumentTypeError(str(error)) from error
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Validate and run one exact static next_actions[] command."
)
parser.add_argument("result", type=pathlib.Path)
parser.add_argument("--action-stage", required=True)
parser.add_argument("--output", type=pathlib.Path)
parser.add_argument("--receipt", type=pathlib.Path)
parser.add_argument("--prior-receipt", type=pathlib.Path, help="stop before repeating an identical recorded request")
parser.add_argument("--timeout-seconds", type=positive_seconds, default=DEFAULT_TIMEOUT_SECONDS,
help="analysis execution budget; increase for long static analyses (default: 900)")
parser.add_argument("--dry-run", action="store_true")
return parser.parse_args()
def main() -> int:
args = parse_args()
try:
if args.prior_receipt is not None and args.receipt is None:
raise ActionError("--prior-receipt requires --receipt")
prepared = prepare_action(args.result, args.action_stage, args.output)
if args.dry_run:
if args.prior_receipt is not None:
prepared["continuation_check"] = "not_evaluated_dry_run"
if args.receipt is not None:
receipt, logs = prepare_action_receipt_paths(prepared, args.receipt,
timeout_seconds=args.timeout_seconds)
prepared["planned_receipt"] = str(receipt)
prepared["planned_log_dir"] = str(logs)
prepared["receipt_budget"] = receipt_budget_plan(
prepared, logs, timeout_seconds=args.timeout_seconds)
json.dump(prepared, sys.stdout, indent=2, sort_keys=True)
sys.stdout.write("\n")
return 0
executable = shutil.which(TRUSTED_PROGRAM)
if executable is None:
raise ActionError("auto-re-cli is not available on PATH")
if args.receipt is not None:
exit_code, summary = execute_prepared_with_receipt(
prepared,
pathlib.Path(executable),
args.receipt,
timeout_seconds=args.timeout_seconds,
prior_receipt=args.prior_receipt,
)
json.dump(summary, sys.stdout, indent=2, sort_keys=True)
sys.stdout.write("\n")
return exit_code
argv = [executable, *prepared["argv"][1:]]
try:
completed = process_control.run_process(
argv, timeout_seconds=args.timeout_seconds, capture=False,
)
except process_control.ProcessError as error:
raise ActionError(str(error)) from error
if completed.status != "completed":
json.dump({"ok": False, "error": completed.status,
"diagnostics": list(completed.diagnostics)}, sys.stderr, sort_keys=True)
sys.stderr.write("\n")
return execution_exit_code(completed)
except (ActionError, OSError) as error:
json.dump({"ok": False, "error": str(error)}, sys.stderr, sort_keys=True)
sys.stderr.write("\n")
return 1
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |