approvals_test.py 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  1. """``hermes approvals test`` — dry-run approval verdict for a command.
  2. Answers "what would the approval system do with this command?" WITHOUT running it, prompting anyone,
  3. or persisting anything. It composes the REAL runtime evaluators from ``tools.approval`` in the same
  4. order the runtime guard (``check_all_command_guards``) applies them:
  5. 1. container-skip gate (isolated backends bypass all guards), 2. hardline blocklist (never
  6. bypassable, fires before yolo/off), 3. sudo-stdin guard (unconditional), 4. user ``approvals.deny``
  7. rules (fire before yolo/off), 5. yolo / ``approvals.mode: off`` bypass, 6. permanent
  8. ``command_allowlist``, 7. dangerous-pattern detection (would prompt).
  9. """
  10. from __future__ import annotations
  11. import json
  12. EXIT_ALLOW = 0
  13. EXIT_USAGE = 1
  14. EXIT_ASK = 2
  15. EXIT_DENY = 3
  16. _VERDICT_EXIT = {
  17. "allow": EXIT_ALLOW, "ask-approval": EXIT_ASK, "hardline-deny": EXIT_DENY,
  18. "user-deny": EXIT_DENY,
  19. }
  20. def evaluate_command(command: str, env_type: str = "local") -> dict:
  21. """Return the dry-run verdict for *command* on *env_type*.
  22. Pure composition of the runtime evaluators — no execution, prompt or persistence. The dict
  23. carries ``verdict``, ``exit_code``, ``rule``, ``detail`` and ``normalized_variants`` (the
  24. de-obfuscated forms the detectors actually evaluated).
  25. """
  26. from tools import approval
  27. from tools import approval_context, approval_detection, approval_floors
  28. # Sync config-persisted "always" patterns so the allowlist check below sees what the runtime
  29. # would see (load is read-only).
  30. try:
  31. approval.load_permanent_allowlist()
  32. except Exception:
  33. pass
  34. variants = list(approval_detection._command_detection_variants(command))
  35. def result(verdict: str, rule=None, detail: str = "") -> dict:
  36. return {
  37. "command": command, "env_type": env_type, "verdict": verdict,
  38. "exit_code": _VERDICT_EXIT[verdict], "rule": rule, "detail": detail,
  39. "normalized_variants": variants,
  40. }
  41. # 1. Isolated container backends skip every guard except the operator's approvals.deny
  42. # (fires BEFORE the hardline floor at runtime).
  43. if approval._should_skip_container_guards(env_type):
  44. deny_pattern = approval_floors._match_user_deny_rule(command)
  45. if deny_pattern is not None:
  46. return result(
  47. "user-deny", rule=deny_pattern,
  48. detail="matches a user-defined approvals.deny rule in config.yaml "
  49. "(blocked even in an isolated container, under --yolo / mode=off)",
  50. )
  51. return result(
  52. "allow",
  53. detail=(f"env_type '{env_type}' is an isolated container backend; "
  54. "the runtime skips all command guards for it except approvals.deny"),
  55. )
  56. # 2. Hardline blocklist — never bypassable, even under yolo.
  57. is_hardline, hardline_desc = approval_detection.detect_hardline_command(command)
  58. if is_hardline:
  59. return result(
  60. "hardline-deny", rule=hardline_desc,
  61. detail="matches the hardline blocklist (never bypassable, "
  62. "blocked even under --yolo / approvals.mode=off)",
  63. )
  64. # 3. Sudo stdin guard — unconditional, like the hardline floor.
  65. is_sudo_guess, sudo_desc = approval_detection._check_sudo_stdin_guard(command)
  66. if is_sudo_guess:
  67. return result("hardline-deny", rule=sudo_desc, detail="sudo stdin guard (unconditional block)")
  68. # 4. User-defined approvals.deny rules — fire before yolo/off.
  69. deny_pattern = approval_floors._match_user_deny_rule(command)
  70. if deny_pattern is not None:
  71. return result(
  72. "user-deny", rule=deny_pattern,
  73. detail="matches a user-defined approvals.deny rule in "
  74. "config.yaml (blocked even under --yolo / mode=off)",
  75. )
  76. # 5. Yolo / approvals.mode=off bypass.
  77. if (approval._YOLO_MODE_FROZEN
  78. or approval.is_current_session_yolo_enabled()
  79. or approval_context._get_approval_mode() == "off"):
  80. return result(
  81. "allow",
  82. detail="approval bypass active (--yolo or approvals.mode: off); "
  83. "only hardline/deny rules would block",
  84. )
  85. # 6. Permanent command_allowlist.
  86. if approval_floors._command_matches_permanent_allowlist(command):
  87. return result("allow", detail="matches command_allowlist in config.yaml (permanently approved)")
  88. # 7. Dangerous-pattern detection → would prompt.
  89. is_dangerous, pattern_key, description = approval_detection.detect_dangerous_command(command)
  90. if is_dangerous:
  91. return result(
  92. "ask-approval", rule=description,
  93. detail="matches a dangerous-command pattern; the runtime would "
  94. f"raise an interactive approval prompt (pattern key: "
  95. f"{pattern_key!r})",
  96. )
  97. return result("allow", detail="no guard matched; would run without a prompt")
  98. def _render_text(verdict: dict) -> None:
  99. print(f"command : {verdict['command']}")
  100. print(f"env-type: {verdict['env_type']}")
  101. print(f"verdict : {verdict['verdict']} (exit {verdict['exit_code']})")
  102. if verdict["rule"]:
  103. print(f"rule : {verdict['rule']}")
  104. if verdict["detail"]:
  105. print(f"detail : {verdict['detail']}")
  106. print("normalized trace (variants the detectors evaluated):")
  107. for v in verdict["normalized_variants"]:
  108. print(f" - {v}")
  109. def approvals_test_command(args) -> int:
  110. """Handle ``hermes approvals test <command...>``. Returns the exit code."""
  111. words = list(getattr(args, "command_words", None) or [])
  112. # argparse REMAINDER keeps a leading "--" separator; it is not part of the command.
  113. if words and words[0] == "--":
  114. words = words[1:]
  115. if not words:
  116. print("usage: hermes approvals test [--env-type TYPE] [--json] -- <command...>")
  117. return EXIT_USAGE
  118. verdict = evaluate_command(" ".join(words), env_type=getattr(args, "env_type", None) or "local")
  119. if getattr(args, "json", False):
  120. print(json.dumps(verdict, indent=2))
  121. else:
  122. _render_text(verdict)
  123. return verdict["exit_code"]