agentsguard 0.2.0__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

agentguard/approval_engine.py

@@ -0,0 +1,194 @@
+import os
+from datetime import datetime
+
+from . import guards, presets, risk_engine, telegram_bot
+from .audit import log_event, now_iso
+from .config import load_config
+from .storage import add_approval, add_instruction, list_approvals
+
+DEFAULT_TIMEOUT = 120
+DEFAULT_DEDUP_WINDOW = 10
+
+# Decisions that count as "already answered" for idempotency purposes.
+_FINAL_DECISIONS = (
+    "approved", "denied", "stopped", "auto_approved", "auto_denied", "timeout",
+    "allow_all", "guard_denied",
+)
+
+
+_RISK_RANK = {risk_engine.LOW: 0, risk_engine.MEDIUM: 1, risk_engine.HIGH: 2, risk_engine.CRITICAL: 3}
+
+
+def _rank(level: str) -> int:
+    return _RISK_RANK.get(level, 1)
+
+
+class NotConfigured(Exception):
+    pass
+
+
+def _recent_decision(command: str, window_seconds: int):
+    """Return the most recent final decision for an identical command made within
+    `window_seconds`, else None. Lets a duplicate hook fire reuse a just-made
+    decision instead of posting a second, stale prompt."""
+    if window_seconds <= 0:
+        return None
+    now = datetime.now()
+    for rec in reversed(list_approvals()):
+        if rec.get("command") != command:
+            continue
+        decision = rec.get("decision")
+        if decision not in _FINAL_DECISIONS:
+            continue
+        ts = rec.get("timestamp")
+        try:
+            when = datetime.fromisoformat(ts) if ts else None
+        except ValueError:
+            when = None
+        if when is None:
+            return None
+        # The newest matching command decides it: reuse only if still fresh.
+        return decision if (now - when).total_seconds() <= window_seconds else None
+    return None
+
+
+def _save_instruction(text: str) -> None:
+    add_instruction(text, now_iso())
+    log_event("instruction_added", text=text)
+    # A "don't touch X" instruction becomes an enforced guard.
+    keyword = guards.maybe_add_from_instruction(text)
+    if keyword:
+        log_event("guard_added", keyword=keyword, text=text)
+        cfg = load_config()
+        token, chat_id = cfg.get("telegram_bot_token"), cfg.get("telegram_chat_id")
+        if token and chat_id:
+            try:
+                telegram_bot.send_message(
+                    token, chat_id,
+                    f"🛡️ *Guard set* — I'll block commands touching `{keyword}`.",
+                )
+            except Exception:
+                pass
+
+
+def request_approval(command: str, timeout: int = DEFAULT_TIMEOUT, risk_override: str = None, tool_name: str = None, details: str = None, prompt: str = None, session_id: str = None) -> str:
+    """Run the full approval flow for a command. Returns one of:
+    'approved', 'denied', 'stopped', 'auto_approved', 'auto_denied', 'timeout'.
+
+    `risk_override` forces the severity instead of classifying `command` — used
+    for non-Bash tools (Write/Edit), whose subject string isn't a shell command
+    and must not be run through the regex classifier (a path like `cat.py` would
+    falsely match LOW and auto-approve).
+    """
+    risk = risk_override or risk_engine.classify(command)
+    log_event("approval_requested", command=command, risk=risk)
+
+    cfg = load_config()
+
+    # Cloud-relay backend: when paired with the relay (`backend: "relay"`), route
+    # the whole approval through it (guards, auto-rules, push, and the phone
+    # decision all live server-side). The Telegram path below is the alternative.
+    from . import relay_client
+
+    if relay_client.is_relay_configured(cfg):
+        kind = "Shell Command" if not tool_name or tool_name == "Bash" else "File Edit"
+        decision = relay_client.request_approval_relay(command, risk, kind=kind, timeout=timeout, cfg=cfg, details=details, prompt=prompt, session_id=session_id)
+        add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": decision})
+        log_event("relay_decision", command=command, risk=risk, decision=decision)
+        return decision
+
+    # Phone-set guards ("Do not touch auth") hard-block any matching command,
+    # regardless of risk — before it can be auto-approved or reach the phone.
+    guard = guards.violated_by(command)
+    if guard:
+        add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "guard_denied"})
+        log_event("guard_blocked", command=command, risk=risk, guard=guard.get("keyword"))
+        token, chat_id = cfg.get("telegram_bot_token"), cfg.get("telegram_chat_id")
+        if token and chat_id:
+            try:
+                telegram_bot.send_message(
+                    token, chat_id,
+                    f"🛡️ *Blocked by your guard* (_{guard.get('text')}_):\n```\n{command}\n```",
+                )
+            except Exception:
+                pass
+        return "guard_denied"
+
+    mirror_all = bool(cfg.get("mirror_all", False))
+    car_mode = bool(cfg.get("car_mode", False))
+
+    if car_mode:
+        # Car Mode: auto-approve anything below the ask threshold so routine
+        # commands don't interrupt you while driving; only risk >= threshold
+        # reaches the phone (CRITICAL is asked, not auto-denied, here).
+        threshold = cfg.get("car_ask_above", "high")
+        if _rank(risk) < _rank(threshold):
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_approved"})
+            log_event("car_auto_approved", command=command, risk=risk, threshold=threshold)
+            return "auto_approved"
+    elif not mirror_all:
+        # In mirror mode every command is forwarded to the phone — the auto-approve
+        # (LOW) and auto-deny (CRITICAL) shortcuts are skipped so nothing is decided
+        # without you.
+        if risk == risk_engine.LOW:
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_approved"})
+            log_event("auto_approved", command=command, risk=risk)
+            return "auto_approved"
+
+        if risk == risk_engine.CRITICAL:
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_denied"})
+            log_event("auto_denied", command=command, risk=risk, reason="critical_default")
+            return "auto_denied"
+
+    token = cfg.get("telegram_bot_token")
+    chat_id = cfg.get("telegram_chat_id")
+    if not token or not chat_id:
+        raise NotConfigured("Run `agentguard init` first.")
+
+    # Idempotency: a duplicate hook fire for a command decided moments ago reuses
+    # that decision instead of posting a second, stale Approve/Deny prompt.
+    window = int(cfg.get("dedup_window_seconds", DEFAULT_DEDUP_WINDOW))
+    prior = _recent_decision(command, window)
+    if prior is not None:
+        log_event("dedup_reused", command=command, risk=risk, decision=prior)
+        verb = "approved" if prior in ("approved", "auto_approved") else prior
+        try:
+            telegram_bot.send_message(
+                token,
+                chat_id,
+                f"↩️ *Already answered* ({verb}) — not asking again:\n```\n{command}\n```",
+            )
+        except Exception:
+            pass
+        return prior
+
+    quick = presets.for_command(command)
+    car_mode = bool(cfg.get("car_mode"))
+    openai_key = cfg.get("openai_api_key") or os.environ.get("OPENAI_API_KEY")
+    message_id = telegram_bot.send_approval_request(token, chat_id, command, risk, presets=quick, allow_all_label=tool_name)
+    log_event("telegram_sent", command=command, risk=risk, message_id=message_id)
+    if car_mode and cfg.get("car_speak", True):
+        telegram_bot.speak(token, chat_id, f"Approval needed. {risk} risk. Command: {command}. Reply approve, deny, or stop.")
+
+    decision = telegram_bot.wait_for_decision(
+        token=token,
+        chat_id=chat_id,
+        message_id=message_id,
+        command=command,
+        risk=risk,
+        timeout=timeout,
+        on_instruction=_save_instruction,
+        presets=quick,
+        allow_all_label=tool_name,
+        car_mode=car_mode,
+        openai_key=openai_key,
+    )
+
+    add_approval({
+        "timestamp": now_iso(),
+        "command": command,
+        "risk": risk,
+        "decision": decision,
+    })
+    log_event(decision, command=command, risk=risk)
+    return decision

agentguard/audit.py

@@ -0,0 +1,31 @@
+import json
+from datetime import datetime
+
+from .config import AUDIT_FILE, ensure_dir
+
+
+def now_iso() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def log_event(event: str, **fields) -> None:
+    ensure_dir()
+    record = {"timestamp": now_iso(), "event": event, **fields}
+    try:
+        items = json.loads(AUDIT_FILE.read_text(encoding="utf-8"))
+        if not isinstance(items, list):
+            items = []
+    except (json.JSONDecodeError, FileNotFoundError):
+        items = []
+    items.append(record)
+    AUDIT_FILE.write_text(json.dumps(items, indent=2), encoding="utf-8")
+
+
+def load_log() -> list:
+    if not AUDIT_FILE.exists():
+        return []
+    try:
+        data = json.loads(AUDIT_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else []
+    except json.JSONDecodeError:
+        return []