Metadata-Version: 2.4
Name: sentinel-lab
Version: 0.1.2
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 runtime observability wrapper for AI-agent security experiments. Version `0.1.2` packages the runtime monitor, SQLite event store, evidence-backed diagnosis, workflow reconstruction, API, event stream, and dashboard together. Runtime data stays on localhost; the deployed Attack Log UI is used only as the visual template.

## Install and configure

```bash
python -m pip install sentinel-lab==0.1.2
sentinel-lab agents
```

The setup asks you to choose OpenClaw, Claude Code, Codex CLI, or a custom framework. It stores the framework's onboarding/launch command in `~/.sentinel-lab/config.json` and prints the exact monitor command.

Non-interactive examples:

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

`sentinel` and `attack-log` are compatibility command aliases for `sentinel-lab`.

## Run an experiment

Launch the selected framework and its interactive TUI under observation:

```bash
sentinel-lab start --attack prompt_injection --defense tool_permission_boundary
```

Or name a configured framework explicitly:

```bash
sentinel monitor openclaw --attack prompt_injection
sentinel-lab monitor claude --attack tool_misuse
```

The agent keeps control of the terminal. Sentinel Labs starts its local service in the background, creates a run-specific session, injects `SENTINEL_LAB_API_URL` and `SENTINEL_LAB_SESSION_ID`, records process boundaries plus adapter/client events, and finalizes the run when the TUI exits.

You can finalize an active session from another terminal and open its investigation:

```bash
sentinel-lab stop
```

Open the latest or a specific local dashboard without stopping anything:

```bash
sentinel-lab dashboard
sentinel-lab dashboard SESSION-0001
```

Both commands open `http://127.0.0.1:43117/investigations/<session-id>`. Sessions, Live Monitor, Investigations, Workflow, and Settings all read the local API; no example runs are injected.

## Wrap a command

For non-interactive programs, Sentinel can also capture stdout, stderr, process boundaries, and one-line JSON events:

```bash
sentinel-lab start \
  --agent "Research Agent" \
  --attack prompt_injection \
  --defense egress_guard \
  -- python demo_agent.py
```

Plain lines become `COMMAND_OUTPUT` events. JSON objects with `type` or `event_type` become structured runtime events.

## Instrument Python

Framework adapters and agents can send richer model, tool, external-content, and defense events using the automatically 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")
```

An interactive TUI must emit through this client or a framework adapter for tool/model-level visibility. Without instrumentation, Sentinel still records the complete observable process lifecycle, but it does not scrape private framework internals from the terminal.

## Run artifacts

Each run is isolated under `~/.sentinel-lab/runs/<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 are:

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

## Configuration

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

Legacy `ATTACK_LOG_*` variables remain supported. The local API includes session, event, workflow, diagnosis, evidence, investigation, control, config, and SSE endpoints under `/api`.

## Publish 0.1.2

From the repository root, run:

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

Enter an account-wide PyPI API token when prompted. The script builds, validates, and uploads both release files as `sentinel-lab==0.1.2`. See [PUBLISHING.md](PUBLISHING.md) for the prerequisites and post-upload checks.

## 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.
