Metadata-Version: 2.4
Name: suy-sideguy
Version: 0.1.3
Summary: Runtime safety guard for autonomous AI agents
Author-email: Hermes Labs <lpcisystems@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/roli-lpci/suy-sideguy
Project-URL: Repository, https://github.com/roli-lpci/suy-sideguy
Project-URL: Bug Tracker, https://github.com/roli-lpci/suy-sideguy/issues
Keywords: security,ai-agent,runtime-monitoring,incident-response
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Requires-Dist: PyYAML>=6.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# Suy Sideguy

[![PyPI version](https://img.shields.io/pypi/v/suy-sideguy)](https://pypi.org/project/suy-sideguy/)
[![Python versions](https://img.shields.io/pypi/pyversions/suy-sideguy)](https://pypi.org/project/suy-sideguy/)
[![License](https://img.shields.io/github/license/roli-lpci/suy-sideguy)](https://github.com/roli-lpci/suy-sideguy/blob/main/LICENSE)
[![CI](https://github.com/roli-lpci/suy-sideguy/actions/workflows/ci.yml/badge.svg)](https://github.com/roli-lpci/suy-sideguy/actions/workflows/ci.yml)

Runtime safety guard for autonomous AI agents.

Suy Sideguy watches a running agent process and decides whether actions should be **SAFE**, **FLAGGED**, **HALTED**, or **KILLED** based on your policy.

---

## What this tool is (and is not)

### ✅ What it does
- Watches process, file, and network behavior for an agent process
- Applies policy rules (optionally with a local LLM judge via Ollama)
- **HALT** suspicious actions (freeze + alert) before they escalate
- **KILL** severe violations with `SIGKILL` when policy requires it
- Stores evidence and can generate incident-ready forensic reports

### ⚠️ What it does not do
- It is **not kernel-level enforcement** (it runs in userspace)
- File visibility via `psutil.open_files()` is best-effort and OS-dependent
- Network checks are based on observed remote IP/port; domain matching can be lossy after DNS

---

## Relationship to Little Canary

- **Little Canary** protects the **input side** (prompt-injection sensing)
- **Suy Sideguy** protects the **runtime/output side** (containment + forensics)

Use both for defense in depth.

---

## Install

```bash
pip install suy-sideguy
```

Requires Python 3.9+.

For development:

```bash
git clone https://github.com/roli-lpci/suy-sideguy.git
cd suy-sideguy
pip install -e ".[dev]"
```

---

## 5-minute quickstart

### 1) Choose target process
Use one of:
- `--agent-pid` (recommended for production)
- `--agent-name` (convenient, but can match unintended processes)

### 2) Start from the example policy scope
- Open `examples/scope.openclaw.yaml`
- For staged rollout, start with `examples/scope.low-disruption.yaml`
- Narrow allowlists to only what your workload truly needs

### 3) Run the warden

```bash
# Safer targeting: PID
suy-warden --scope examples/scope.openclaw.yaml --agent-pid 12345 --poll 0.5

# Convenience targeting: process name
suy-warden --scope examples/scope.openclaw.yaml --agent-name openclaw --poll 0.5
```

### 4) Generate report after a run

```bash
suy-forensic-report --last-hours 24
```

---

## Where logs and evidence go

Default paths:

- `~/.local/share/sysmond/warden.log`
- `~/.local/share/sysmond/logs/actions_*.jsonl`
- `~/.local/share/sysmond/logs/incidents/*.json`

Tip: treat these as security artifacts. Protect access and define retention/rotation.

---

## Recommended rollout strategy

1. **Audit-first**: observe and tune policy without auto-kill pressure.
2. **Confirm mode** for ambiguous events.
3. **Enforce mode** only after your hard invariants are validated.

---

## Important safety caveats

- `SIGKILL` is immediate and can interrupt legitimate work if policy is too broad.
- Name matching (`--agent-name`) can over-match; prefer PID targeting in production.
- This project should be one part of a layered defense strategy.

## Verdict levels

| Verdict | Meaning | Response |
|---------|---------|----------|
| `SAFE` | Action is within policy | Continue |
| `FLAG` | Suspicious, below threshold | Log, continue |
| `HALT` | Dangerous pattern detected | Freeze, alert operator |
| `KILL` | Critical violation | `SIGKILL` immediately |

### HALT triggers (freeze + alert, agent is not killed)
- **3+ file deletions in 10 seconds** — mass deletion pattern
- **curl or wget spawned** — unexpected outbound data transfer
- **50+ network calls in 60 seconds** — bulk messaging / API spam
- **Write outside allowed workspace** — unexpected filesystem access

### KILL triggers (immediate, no recovery)
- **SSH key access** — any read/write to `~/.ssh/` or `*id_rsa*`, `*id_ed25519*`
- **Config tampering** — writing to `~/.openclaw/openclaw.json`
- **rm -rf on non-tmp paths** — destructive sweep outside `/tmp`
- **Forbidden paths** — any path in your scope's `deny_write` list

---

## Expected flag noise (early rollout)

Early flag noise is normal during policy calibration on real workloads.

- Treat early `FLAG` events as calibration data, not immediate defects.
- Use policy thresholds (`flag_threshold`, `flag_window`) to control when accumulated risk escalates to kill.
- Keep **hard invariants** (e.g., forbidden secrets paths / destructive commands) as immediate stop conditions.
- Start in audit-first mode, then tighten only after reviewing forensic logs.

---


## Release quality status

_Current status based on repository checks and CI configuration; not a formal security certification._


- ✅ Tests in repo (`pytest`)
- ✅ Package buildable (`python -m build`)
- ✅ CI workflow (`.github/workflows/ci.yml`)
- ✅ Publish workflow (`.github/workflows/publish.yml`)
- ✅ Security disclosure policy (`SECURITY.md`)

## Development

```bash
pip install -e .[dev]
pytest
```

Also see:
- `CONTRIBUTING.md`
- `SECURITY.md`
- `PUBLISH_CHECKLIST.md`
- `AGENTS.md`
- `CODE_OF_CONDUCT.md`
- Audit checklist: `docs/AUDIT_CHECKLIST.md`
- Layered plan: `docs/IMPLEMENTATION_PLAN_LAYERED.md`
