Metadata-Version: 2.4
Name: sentinel-lab
Version: 0.1.5
Summary: Local-first runtime observability for AI agent security experiments.
Author: Sentinel Lab Contributors
License-Expression: MIT
Keywords: ai,agents,security,observability,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Sentinel Labs

Sentinel Labs is a local-first sandbox and runtime wrapper for AI-agent security experiments. Version `0.1.5` packages the Sentinel CLI, framework launcher, sandbox backend abstraction, AI employee experiment templates, SQLite event store, evidence-backed diagnosis engine, local API/SSE service, and localhost security dashboard together.

Runtime data stays on your machine. The deployed Attack Log dashboard is only the visual template; Sentinel's local session store is the source of truth.

## Installation

```bash
python -m pip install sentinel-lab==0.1.5
sentinel help
```

The PyPI project is `sentinel-lab`; the primary CLI command is `sentinel`.

## Configure frameworks

```bash
sentinel agents
```

`sentinel agents` opens a Critiqor-style selector with OpenClaw, CC, Codex, and Custom. Built-in frameworks use their launch command internally, so users only need to run the Sentinel monitor command. Custom frameworks persist their name, executable, arguments, and launch command in `~/.sentinel-lab/config.json`.

Codex is launched with `codex` under the hood. The terminal output stays focused on the Sentinel command so the wrapper feels like one workflow instead of a second thing to babysit.

Non-interactive examples:

```bash
sentinel agents --framework openclaw
sentinel agents --framework cc
sentinel agents --framework codex
sentinel agents --framework custom --name "My Agent" --command "my-agent tui"
sentinel agents --list
```

After setup, Sentinel prints the recommended command, such as:

```bash
sentinel monitor openclaw
```

## AI employees

Sentinel includes reusable prompt-injection research employees and experiment templates:

```bash
sentinel employees
sentinel employees --employee injection-researcher --json
sentinel employees --scaffold --employee injection-researcher --directory ./sentinel-employees
```

The scaffolder creates the operating files from the research spec: `MISSION.md`, `EMPLOYEE.md`, `PERMISSIONS.md`, `QUALITY.md`, `PROMPT.md`, `STATE.md`, `KNOWLEDGE.md`, `DECISIONS.md`, `TASKS.md`, and `work/<experiment>/` briefs.

## Run an experiment

```bash
sentinel monitor openclaw --attack prompt_injection --defense tool_permission_boundary
```

Other built-ins:

```bash
sentinel monitor cc
sentinel monitor codex
```

To run a prompt-injection template with Codex:

```bash
sentinel monitor codex --employee injection-researcher --experiment-template instruction-override
```

Sentinel creates a unique session, prepares the selected sandbox backend, starts the configured agent runtime inside that backend, preserves the interactive TUI where the backend allows it, injects `SENTINEL_LAB_API_URL`, `SENTINEL_LAB_SESSION_ID`, `SENTINEL_LAB_FRAMEWORK`, and `SENTINEL_LAB_SANDBOX_DIR`, then records sandbox, process, policy, and structured framework telemetry.

Employee/template metadata fills the session objective, attack type, injection design, mitigation focus, and wrapper scorecard so the dashboard starts from a reproducible experiment rather than blank labels.

Sandbox backends are explicit about their guarantees. On macOS, Sentinel uses `sandbox-exec` when available to deny host filesystem access and outbound network by default while allowing the session workspace and required system executable paths. On platforms without an enforcing backend, Sentinel uses a reduced process-group backend and records that filesystem/network containment is unavailable.

The reduced backend is useful for lifecycle control and telemetry, but it is not a security sandbox. Sentinel does not market process groups as container or VM isolation.

To end an active experiment from another terminal:

```bash
sentinel finalize
```

`sentinel finalize` stops the wrapper and monitored runtime, generates the session diagnosis/evidence/workflow artifacts, and opens the local dashboard for that exact session:

```text
http://127.0.0.1:43117/investigations/<SESSION_ID>
```

Open the latest completed investigation later:

```bash
sentinel dashboard
```

## Observability boundary

Sentinel records generic process-level information for every configured framework: session ID, framework, PID, timestamps, duration, lifecycle, and shutdown/finalization events.

For deeper security telemetry, the agent runtime or a framework-specific adapter should emit structured Sentinel events. That is how Sentinel can capture model events, tool calls, tool results, external content, defenses, suspicious activity, parent/child relationships, and workflow evidence. A generic terminal wrapper cannot infer hidden framework internals that the framework never exposes.

## Instrument Python

Framework adapters and agents can send structured runtime evidence with the injected environment variables:

```python
from sentinel_lab import SentinelLabs, SentinelLabsClient

observed_agent = SentinelLabs.wrap(existing_agent)
result = observed_agent.run("Summarize the supplied page")

log = SentinelLabsClient()
log.external_content({
    "origin": "https://research.local/notes",
    "content_excerpt": "Untrusted page content",
})

with log.tool_call("browser.open", payload={"arguments": {"url": "https://example.test"}}):
    result = browser.open("https://example.test")
```

Plain process wrapping still works without instrumentation, but tool/model-level claims require structured events.

## 5/5 wrapper criteria

A Sentinel run is designed to satisfy five wrapper criteria:

- One command starts runtime capture for the selected framework.
- Every run has session-scoped artifacts and an exact local dashboard route.
- Sandbox/backend capability evidence is recorded rather than assumed.
- Structured event ingestion can capture model/tool/security events when frameworks emit them.
- The dashboard turns events into evidence-linked observations for conclusions about the attack.

## Trust boundary

```text
UNTRUSTED
Agent, model output, agent subprocesses, downloaded/tool-generated content

TRUST BOUNDARY

TRUSTED
Sentinel orchestrator, sandbox policy, host collector, event store, analyzer, dashboard
```

Agent telemetry is untrusted input until the host collector normalizes it, assigns Sentinel event IDs, persists it, and links it to a session.

## Local dashboard

The bundled dashboard is served by Sentinel on localhost and reads only real Sentinel data:

```text
Agent Runtime
  -> Sandbox backend
  -> Sentinel Wrapper / telemetry bridge
  -> Event Stream
  -> SQLite / Session Store
  -> Diagnosis + Evidence + Workflow
  -> Local API / SSE
  -> Local Dashboard
```

Routes include `/`, `/live`, `/investigations/<SESSION_ID>`, `/workflow`, and `/settings`. Empty installs show empty states, not mock sessions.

## Run artifacts

Each run is isolated under `~/.sentinel-lab/sessions/<session-id>/`:

```text
session.json     session metadata and complete event snapshot
events.jsonl     append-only raw event stream
diagnosis.json   claims, evidence references, and attack trace
evidence.json    claim-supporting event records
workflow.json    reconstructed nodes and edges
```

SQLite remains the query store at `~/.sentinel-lab/sentinel-lab.sqlite3`.

Useful commands:

```bash
sentinel status
sentinel sessions
sentinel inspect SESSION-0001
sentinel inspect SESSION-0001 --json
sentinel --version
```

## Configuration

```bash
export SENTINEL_LAB_HOME="$PWD/.sentinel-lab-data"
export SENTINEL_LAB_HOST=127.0.0.1
export SENTINEL_LAB_PORT=43117
export SENTINEL_LAB_SANDBOX_BACKEND=process-group-observation
```

Legacy `ATTACK_LOG_*` variables remain supported for adapter compatibility.

`SENTINEL_LAB_SANDBOX_BACKEND` can be set to `darwin-sandbox-exec` or `process-group-observation`. If the requested enforcing backend cannot actually apply on the host, Sentinel records the reduced fallback rather than claiming secure containment.

## Publish 0.1.5

From the repository root:

```bash
./scripts/publish-pypi.sh
```

Enter a PyPI API token when prompted. The script cleans old release artifacts, builds, validates, verifies `sentinel --version` is `0.1.5`, and uploads `sentinel-lab==0.1.5`. See [PUBLISHING.md](PUBLISHING.md) for details.

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
PYTHONPATH=src python -m unittest discover -s tests -v
python -m build
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for the system design.
