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

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:

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:

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

Or name a configured framework explicitly:

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:

sentinel-lab stop

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

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:

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:

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>/:

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:

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

Configuration

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:

./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 for the prerequisites and post-upload checks.

Development

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 for the system design.