sentinel-lab added to PyPI

Sentinel Labs has recently made its debut on the Python Package Index (PyPI) with the release of version 0.1.2. This innovative tool serves as a local-first runtime observability wrapper specifically designed for AI-agent security experiments. By packaging various components such as a runtime monitor, SQLite event store, evidence-backed diagnosis, workflow reconstruction, API, event stream, and dashboard, Sentinel Labs aims to streamline the process of monitoring and diagnosing AI agents in a secure environment.

The core functionality of Sentinel Labs revolves around maintaining data privacy. All runtime data is stored on the local machine, ensuring that sensitive information does not leave the user's environment. The deployed Attack Log User Interface (UI) functions solely as a visual template, reinforcing the commitment to local data handling.

Setup and Configuration

Setting up Sentinel Labs requires users to select from several frameworks, including OpenClaw, Claude Code, Codex CLI, or even a custom framework. The chosen framework's onboarding or launch command is stored in a configuration file located at ~/.sentinel-lab/config.json. This setup process is designed to be straightforward, as it prints the exact command needed to initiate the monitoring process.

Once the setup is complete, the agent retains control of the terminal, allowing Sentinel Labs to start its local service in the background. It creates a run-specific session, injecting necessary environment variables such as SENTINEL_LAB_API_URL and SENTINEL_LAB_SESSION_ID. Additionally, it records process boundaries and adapter/client events, finalizing the run when the Text User Interface (TUI) exits.

Users have the flexibility to finalize an active session from a different terminal, enabling them to open investigations into their sessions. Both commands lead to a local investigation URL, which allows users to access detailed information about their session at http://127.0.0.1:43117/investigations/<session-id>. The various components of the system, including Sessions, Live Monitor, Investigations, Workflow, and Settings, all interact with the local API, ensuring that no example runs are injected into the system.

Event Capture and Data Handling

For users working with non-interactive programs, Sentinel Labs offers the capability to capture standard output (stdout), standard error (stderr), process boundaries, and one-line JSON events. In this context, plain lines are categorized as COMMAND_OUTPUT events, while JSON objects that include type or event_type are recognized as structured runtime events.

Framework adapters and agents can enhance their event reporting by sending richer model, tool, external-content, and defense events. This is facilitated through automatically injected environment variables, which provide a more comprehensive view of the interactions taking place within the AI agent's runtime environment. However, it is important to note that an interactive TUI must emit events through this client or a framework adapter to achieve tool or model-level visibility. Without proper instrumentation, Sentinel Labs will still capture the complete observable process lifecycle, but it will not delve into private framework internals from the terminal.

Legacy ATTACK_LOG_* variables continue to be supported, ensuring compatibility with previous versions. The local API encompasses a wide range of endpoints, including session, event, workflow, diagnosis, evidence, investigation, control, config, and Server-Sent Events (SSE) under the /api path.

To publish a new version of Sentinel Labs, users are required to enter an account-wide PyPI API token when prompted. The script takes care of building, validating, and uploading both release files, which are labeled as sentinel-lab==0.1.2. For those interested in contributing or utilizing the package, detailed instructions can be found in the PUBLISHING.md file, which outlines prerequisites and post-upload verification steps.

For installation, users can download the appropriate file for their platform. If there is uncertainty regarding which file to choose, additional resources are available to guide users through the installation process. Furthermore, for those unfamiliar with the file name format, information on wheel file names is also provided, ensuring a smooth installation experience.

Why it matters

The introduction of Sentinel Labs to PyPI marks a significant advancement in the realm of AI-agent security experimentation. By offering a local-first approach to runtime observability, it addresses critical concerns surrounding data privacy and security, which are paramount in today's technology landscape. For creators and technologists, this tool not only simplifies the monitoring and diagnostic processes but also empowers them to conduct experiments in a secure and controlled environment. As the use of AI continues to expand, tools like Sentinel Labs will be essential for ensuring that these technologies are developed and deployed responsibly, with an emphasis on security and privacy.