Example: regulated-industry agent controls

[sdarive]

User Story

As a platform or security engineer at a regulated company (bank, insurer, healthcare),
I want a runnable example that maps OpenShell policy to the controls my risk team asks for,
so that I can show them how an AI agent would be governed before they approve a use case.

Problem Statement

The examples today show individual features well (L7 rules, providers, private IPs, the policy advisor). None show how they combine into the control set a risk or compliance review expects for one agent: least privilege, credential isolation, human approval, need-to-know data access, and approved vendors, with an audit trail.

Impact / Why This Matters

In enterprise reviews, agents stall because risk teams can't see how controls would be enforced. Teams assemble this story themselves from several examples and docs. One example written in the language of a risk review lowers the barrier to adopting OpenShell in regulated industries.

Proposed Design

A new examples/regulated-industry-controls/ directory, in the style of sandbox-policy-quickstart:

• A fictional bank (synthetic data) on a private Docker network: a core API and an unapproved vendor.
• One policy.yaml covering five controls:
  1. Least privilege: an L7 allow rule for reads only; writes are denied.
  2. Credential isolation: a provider with credential_binding, so the agent holds a placeholder and the token only reaches the core API.
  3. Need to know: deny_rules for sensitive paths (tax IDs, bulk export).
  4. Human approval: a write is denied until a person adds one narrow rule with openshell policy update --add-allow.
  5. Approved vendors: a vendor endpoint in audit, then moved to enforce.
• A README walkthrough and a demo.sh that runs all five and checks each outcome.

Acceptance Criteria

• bash examples/regulated-industry-controls/demo.sh runs end to end against a local gateway and checks each of the five outcomes.
• The README walks through each control manually with the expected result.
• Uses only synthetic data and existing OpenShell features; no product changes.

Alternatives Considered

• Extending sandbox-policy-quickstart: a separate example keeps the quickstart short for first-time users.
• A docs tutorial instead of an example: a runnable script is easier to hand to a risk team and to keep tested.

Agent Investigation

I built and ran this against OpenShell 0.1.2 on a Linux host; all five controls pass. Notes:

• The default base image doesn't include curl, so the example builds a small agent image from nvcr.io/nvidia/base/ubuntu:24.04.
• openshell policy update --add-endpoint keeps an existing endpoint's audit enforcement ("ignores incoming 'enforce'"), so the example switches to enforce by exporting the live policy (policy get --base) and applying it with policy set.
• A working version of the same scenario runs at https://shikologic.com/demo.

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request