Skip to content

CLAUDE.md

Latest commit

 

History

History
55 lines (43 loc) · 2.28 KB

CLAUDE.md

File metadata and controls

55 lines (43 loc) · 2.28 KB
Raw

Suy Sideguy

Runtime safety guard for autonomous AI agents. Monitors process/file/network behavior, applies policy rules, terminates violations.

Commands

  • pip install -e ".[dev]" -- Install with dev deps
  • pytest -- Run all 15 tests
  • pytest tests/test_scope.py -v -- Single test module
  • ruff check suy_sideguy/ -- Lint
  • mypy suy_sideguy/ -- Type check
  • python -m build -- Build wheel + sdist
  • suy-warden --scope examples/scope.openclaw.yaml --agent-pid 12345 --poll 0.5 -- Run warden
  • suy-forensic-report --last-hours 24 -- Generate incident report

Architecture

suy_sideguy/
  warden.py          # Main loop: observe → evaluate → enforce (entry point)
  observer.py        # Process/file/network monitoring via psutil
  policy.py          # Rule evaluation engine
  scope.py           # YAML scope parser (allowlists, blocklists, thresholds)
  enforcement.py     # SIGKILL dispatch
  forensic_report.py # Evidence aggregation, incident report export
  models.py          # Shared dataclasses (Action, Observation, Verdict)
  cli.py             # Argument parsing

5-stage pipeline: Observer → Rule Engine (instant scope checks) → LLM Judge (Ollama, ambiguous cases) → Killswitch (SIGKILL) → Responder (forensic report).

Key Constraints

  • Python 3.9+ required (from __future__ import annotations in all modules)
  • Three runtime deps only: psutil, PyYAML, httpx
  • SIGKILL is irreversible — kill-path changes need tests + forensic validation
  • Fail-open on observer errors (log and continue, don't crash the warden)
  • LLM judge calls Ollama /api/chat — no abstraction layer yet
  • Scope files are YAML with OS-specific path comments

Code Style

  • from __future__ import annotations in every module
  • Dataclasses + Enum for structured data
  • logging.getLogger(__name__) per module
  • Type hints on all public functions
  • Ruff line length: 100, target Python 3.9

Gotchas

  • psutil.open_files() visibility is OS-dependent and best-effort
  • Network checks match IP/port, not domain — DNS resolution is lossy
  • --agent-name can over-match processes; prefer --agent-pid in production
  • Log/evidence paths default to ~/.local/share/sysmond/ (legacy naming)
  • The scope YAML flag_threshold and flag_window control when flags escalate to kill