approvals.py 3.8 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970
  1. """``hermes approvals`` subcommand parser."""
  2. from __future__ import annotations
  3. import argparse
  4. from typing import Callable
  5. from hermes_cli.subcommands._shared import add_json_flag
  6. def build_approvals_parser(subparsers, *, cmd_approvals: Callable) -> None:
  7. """Attach the ``approvals`` subcommand to ``subparsers``."""
  8. approvals_parser = subparsers.add_parser(
  9. "approvals", help="Approval-prompt tools (mine history into allowlist proposals)",
  10. description="Tools for the dangerous-command approval system. "
  11. "`hermes approvals suggest` mines past approval decisions from "
  12. "the session database and proposes command_allowlist entries so "
  13. "repeatedly-approved commands stop prompting.")
  14. approvals_subparsers = approvals_parser.add_subparsers(
  15. dest="approvals_command", metavar="<subcommand>")
  16. suggest_parser = approvals_subparsers.add_parser(
  17. "suggest", help="Propose command_allowlist entries from past approvals",
  18. description="Scan the session database for dangerous-classified commands "
  19. "that ran with user approval, rank the recurring patterns, and "
  20. "print a numbered allowlist proposal. Nothing is written unless "
  21. "--apply is given. Destructive classes (recursive delete, sudo, "
  22. "disk writes, credential edits, ...) are never proposed.")
  23. suggest_parser.add_argument(
  24. "--apply", dest="apply_indices", metavar="N[,M...]",
  25. help="Merge the numbered proposals (from a prior run) into "
  26. "command_allowlist in config.yaml")
  27. add_json_flag(suggest_parser, "Emit machine-readable JSON instead of human-readable text")
  28. suggest_parser.add_argument(
  29. "--days", type=int, default=90,
  30. help="How far back to scan session history (default: 90; 0 = all)")
  31. suggest_parser.add_argument(
  32. "--min-count", dest="min_count", type=int, default=2,
  33. help="Minimum approval count for a pattern to be proposed (default: 2)")
  34. suggest_parser.add_argument(
  35. "--limit", type=int, default=20, help="Maximum number of proposals to show (default: 20)")
  36. suggest_parser.add_argument(
  37. "--db", help="Path to an alternate session database (default: ~/.hermes/state.db)")
  38. suggest_parser.set_defaults(func=cmd_approvals)
  39. test_parser = approvals_subparsers.add_parser(
  40. "test", help="Dry-run the approval verdict for a command (never executes it)",
  41. description="Evaluate a command against the REAL runtime approval guards — "
  42. "hardline blocklist, user approvals.deny rules, dangerous-pattern "
  43. "detection, allowlist, yolo/off bypass — and print the verdict, "
  44. "the matching rule, and the normalized-command trace, without "
  45. "executing the command, prompting anyone, or persisting anything. "
  46. "Exit codes: 0 allow, 2 ask-approval, 3 deny (hardline or user "
  47. "deny rule). Tip: use `--` before the command so its own flags "
  48. "aren't parsed: hermes approvals test -- rm -rf ./build")
  49. test_parser.add_argument(
  50. "--env-type", dest="env_type", default="local",
  51. help="Terminal backend type to evaluate against (default: local; "
  52. "isolated container backends like docker skip the guards)")
  53. add_json_flag(test_parser, "Emit machine-readable JSON instead of human-readable text")
  54. test_parser.add_argument(
  55. "command_words",
  56. nargs=argparse.REMAINDER,
  57. metavar="command",
  58. # NOTE: dest must NOT be "command" — main.py's startup path reads
  59. # args.command as the top-level subcommand name ("approvals").
  60. help="The command to evaluate (prefix with -- to protect its flags)")
  61. test_parser.set_defaults(func=cmd_approvals)
  62. approvals_parser.set_defaults(func=cmd_approvals)