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/start_analysis.py
View on GitHub#!/usr/bin/env python3
"""Collect one static Auto-RE result with preflight and bounded diagnostic logs."""
from __future__ import annotations
import argparse
import json
import os
from pathlib import Path
import shutil
import stat
import sys
from typing import Optional
# A managed Skill's inventory is immutable; importing helpers must not add .pyc.
sys.dont_write_bytecode = True
import run_next_action as actions
import skill_doctor as doctor
SKILL_ROOT = Path(__file__).resolve().parents[1]
LOG_TAIL_BYTES = 16 * 1024
# Each entry has a known JSON contract; this is not arbitrary CLI passthrough.
FIRST_COMMANDS = (
"report", "function", "inspect-go", "inspect-rust", "inspect-die",
"inspect-upx", "inspect-vmp", "pe-strings", "pe-resources",
)
def address(text: str) -> str:
try:
value = int(text, 16 if text.lower().startswith("0x") else 10)
except ValueError as error:
raise argparse.ArgumentTypeError("address must be decimal or hexadecimal") from error
if not 0 <= value < 1 << 64:
raise argparse.ArgumentTypeError("address must be an unsigned 64-bit integer")
return hex(value)
def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__, allow_abbrev=False)
parser.add_argument("input", type=Path)
parser.add_argument("--result-dir", type=Path, required=True,
help="new result directory with an existing parent, outside the input file parent directory "
"(including its descendants) and the installed Skill")
parser.add_argument("--cli", type=Path, help="trusted installed analyzer, never the input")
parser.add_argument("--command", choices=FIRST_COMMANDS,
help="one static query; default: function with a selector, otherwise report")
selector = parser.add_mutually_exclusive_group()
selector.add_argument("--addr", type=address)
selector.add_argument("--symbol")
parser.add_argument("--raw-shellcode", action="store_true")
parser.add_argument("--arch", choices=("x86", "x86-64", "x86_64", "aarch64"),
help="target architecture; x86-64 and x86_64 are equivalent")
parser.add_argument("--base-address", type=address)
parser.add_argument("--entry-address", type=address)
parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--timeout-seconds", type=actions.positive_seconds,
default=actions.DEFAULT_TIMEOUT_SECONDS,
help="analysis execution budget; increase for long static analyses (default: 900)")
args = parser.parse_args(argv)
selected = args.addr is not None or args.symbol is not None
args.command = args.command or ("function" if selected else "report")
if args.command == "function" and not selected:
parser.error("--command function requires --addr or --symbol")
if args.command != "function" and selected:
parser.error("--addr and --symbol are only supported by --command function")
if args.command == "pe-resources" and (
args.arch is not None or args.raw_shellcode
or args.base_address is not None or args.entry_address is not None
):
parser.error("pe-resources does not accept architecture or raw-input arguments")
if args.raw_shellcode and (args.arch is None or args.base_address is None):
parser.error("raw shellcode requires explicit --arch and --base-address")
if not args.raw_shellcode and (args.base_address is not None or args.entry_address is not None):
parser.error("--base-address and --entry-address require --raw-shellcode")
if args.symbol is not None and (not args.symbol.strip() or args.symbol.startswith("-")):
parser.error("--symbol must be non-empty and must not start with '-' (use --addr instead)")
return args
def within(path: Path, directory: Path) -> bool:
return path == directory or directory in path.parents
def preflight_paths(args: argparse.Namespace) -> tuple[Path, Path]:
target = args.input.expanduser().resolve(strict=True)
if not stat.S_ISREG(target.stat().st_mode):
raise actions.ActionError("input must be a regular file")
requested = args.result_dir.expanduser().absolute()
# Check before resolve: do not follow a dangling output symlink into creation.
actions._require_absent(requested, "result directory")
output = requested.parent.resolve(strict=True) / requested.name
actions._require_absent(output, "result directory")
if within(output, target.parent):
raise actions.ActionError(
"result directory must be outside the input file parent directory "
"to keep analysis output separate from samples: "
f"result_dir={output}; input_dir={target.parent}"
)
if within(output, SKILL_ROOT):
raise actions.ActionError("result directory must be outside the installed Skill")
return target, output
def prepare(args: argparse.Namespace, target: Path, output: Path) -> dict:
command = args.command
argv = [actions.TRUSTED_PROGRAM, command, str(target)]
if args.addr is not None:
argv += ["--addr", args.addr]
if args.symbol is not None:
argv += ["--symbol", args.symbol]
argv += ["--format", "json"]
if command != "function":
argv += ["--json-profile", "ai"]
if command == "report":
argv += ["--sections", "binary,summary,inspections,flow,functions,types", "--limit", "8"]
if args.raw_shellcode:
argv.append("--raw-shellcode")
for flag, value in (("--arch", args.arch), ("--base-address", args.base_address),
("--entry-address", args.entry_address)):
if value is not None:
argv += [flag, value]
argv += ["--output", str(output / "analysis.json")]
return {
"ok": True, "action_stage": f"initial.{command}",
"reason": "collect first static evidence for the supplied input and selector",
"expected_output": "one bounded Auto-RE JSON result",
"stop_condition": "initial result collected; agent must inspect evidence before continuing",
"command_owned_sink": False, "argv": argv,
}
def trusted_cli(args: argparse.Namespace, target: Path) -> Path:
candidate = args.cli if args.cli is not None else shutil.which(actions.TRUSTED_PROGRAM)
if candidate is None:
raise actions.ActionError("auto-re-cli is not available on PATH")
executable = Path(candidate).expanduser().resolve(strict=True)
if not executable.is_file():
raise actions.ActionError("trusted CLI must be a regular file")
# This must precede doctor/--version, which executes the trusted analyzer.
if os.path.samefile(executable, target):
raise actions.ActionError("input must never be used as the CLI, including aliases")
return executable
def run(args: argparse.Namespace) -> tuple[int, dict]:
target, output = preflight_paths(args)
prepared = prepare(args, target, output)
actions.validate_prepared_argv(prepared["argv"], command_owned_sink=False)
# Known receipt fields are admitted before doctor can probe the trusted CLI.
budget = actions.receipt_budget_plan(prepared, output / "receipts/initial.json.logs",
log_tail_bytes=LOG_TAIL_BYTES, timeout_seconds=args.timeout_seconds)
if args.dry_run:
return 0, dict(prepared, readiness_checked=False, analysis_executed=False,
investigation_complete=False, result_dir=str(output),
result_validation="not_attempted", receipt_budget=budget)
executable = trusted_cli(args, target)
readiness = doctor.diagnose(SKILL_ROOT, executable=executable)
if not readiness["ok"]:
raise actions.ActionError("Skill preflight failed: " + "; ".join(readiness["warnings"]))
# No replacement or automatic recursive cleanup: existing user paths survive.
output.mkdir(mode=0o700)
receipts = output / "receipts"
receipts.mkdir(mode=0o700)
code, summary = actions.execute_prepared_with_receipt(
prepared, executable, receipts / "initial.json", log_tail_bytes=LOG_TAIL_BYTES,
timeout_seconds=args.timeout_seconds,
)
result_path = output / "analysis.json"
summary.update(readiness_checked=True, analysis_executed=True,
investigation_complete=False, result_path=str(result_path),
result_validation="not_attempted",
warnings=readiness["warnings"],
next_step="Read result JSON; inspect warnings, completion and next_actions before choosing one relevant follow-up.")
if code != 0:
summary.update(
failure_phase="execution",
next_step="Inspect the execution receipt and bounded logs before changing the query or budget; partial results are not validated evidence.",
)
return code, summary
try:
if not stat.S_ISREG(result_path.lstat().st_mode):
raise actions.ActionError("analysis JSON must be a direct regular file")
result = actions.load_json_object(result_path)
wrapper = actions.validate_result_contract(result, command=args.command)
expected = "wrapper:function" if args.command == "function" else "profile:ai"
if wrapper != expected:
raise actions.ActionError(f"{args.command} expected {expected}, received {wrapper}")
except (actions.ActionError, OSError, RuntimeError, ValueError) as error:
# The receipt describes the process; this failure belongs to the launcher.
# Keep its paths/status rather than losing them in main's preflight error.
summary.update(
ok=False, exit_code=1, result_validation="failed",
failure_phase="result_validation",
error="result JSON validation failed: " + str(error)[:512],
next_step="Inspect the retained receipt, bounded logs and result path; correct the output/contract problem before retrying into a new result directory. Do not treat the invalid result as evidence.",
)
return 1, summary
summary.update(result_wrapper=wrapper, result_validation="passed")
return code, summary
def main() -> int:
try:
code, result = run(parse_args())
# Keep post-execution validation errors on stderr for existing callers.
stream = sys.stderr if result.get("failure_phase") == "result_validation" else sys.stdout
json.dump(result, stream, sort_keys=True)
stream.write("\n")
# Preserve normal error codes; map POSIX signal termination to shell form.
return code if code >= 0 else 128 - code
except (actions.ActionError, doctor.DoctorError, OSError, RuntimeError, ValueError) as error:
json.dump({"ok": False, "error": str(error), "investigation_complete": False},
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 |