Metadata-Version: 2.4
Name: shoreguard
Version: 0.35.0
Summary: Open source control plane for NVIDIA OpenShell
Project-URL: Homepage, https://github.com/FloHofstetter/shoreguard
Project-URL: Repository, https://github.com/FloHofstetter/shoreguard
Project-URL: Documentation, https://flohofstetter.github.io/shoreguard/
Project-URL: Issues, https://github.com/FloHofstetter/shoreguard/issues
Author-email: Florian Hofstetter <flo.max.hofstetter@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,control-plane,nvidia,openshell,sandbox,security
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.14
Requires-Dist: aiosmtplib>=3.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: alembic>=1.15
Requires-Dist: dnspython>=2.6
Requires-Dist: fastapi>=0.135
Requires-Dist: grpcio>=1.78
Requires-Dist: httpx>=0.28
Requires-Dist: jinja2>=3.1
Requires-Dist: opentelemetry-api>=1.29
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.29
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.50b0
Requires-Dist: opentelemetry-instrumentation-grpc>=0.50b0
Requires-Dist: opentelemetry-sdk>=1.29
Requires-Dist: prometheus-client>=0.21
Requires-Dist: protobuf>=5.29
Requires-Dist: pwdlib[bcrypt]>=0.2
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pyjwt[crypto]>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.42
Requires-Dist: websockets>=16.0
Requires-Dist: z3-solver>=4.13
Description-Content-Type: text/markdown

# ShoreGuard

[![CI](https://github.com/FloHofstetter/shoreguard/actions/workflows/ci.yml/badge.svg)](https://github.com/FloHofstetter/shoreguard/actions/workflows/ci.yml)
[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

**Open-source control plane for [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell).** Manage AI agent sandboxes, inference routing, and security policies — from a web UI, REST API, or Terraform.

![Sandbox Overview](docs/screenshots/sandbox-overview.png)

---

## Architecture

ShoreGuard sits between operators and OpenShell's secure runtime. Agents run inside hardened sandboxes with routed inference — they never see real API keys or provider endpoints.

```mermaid
graph LR
    subgraph "Operators — all use ShoreGuard REST API"
        UI["ShoreGuard Web UI"]
        TF["Terraform Provider"]
        PC["Paperclip"]
        OC["OpenClaw"]
    end

    subgraph "Observability"
        Grafana["Grafana"]
    end

    subgraph "ShoreGuard — Management Plane"
        SG["ShoreGuard API"]
        DB[("PostgreSQL")]
        Metrics["/metrics"]
    end

    subgraph "Gateway: dev"
        OS1["OpenShell Controller"]
        subgraph "Sandbox"
            Agent1["Agent"]
        end
        Proxy1["inference.local/v1"]
    end

    subgraph "Gateway: staging"
        OS2["OpenShell Controller"]
        subgraph "Sandbox "
            Agent2["Agent"]
        end
        Proxy2["inference.local/v1"]
    end

    subgraph "LLM Providers"
        LLM["Anthropic / NVIDIA / OpenAI"]
    end

    UI --> SG
    TF --> SG
    PC -->|"adapter plugin"| SG
    OC -->|"slash commands"| SG
    PC -.->|"controls"| Agent1
    OC -.->|"controls"| Agent1
    Grafana --> Metrics
    SG --> DB
    SG --> Metrics
    SG -- "gRPC + mTLS" --> OS1
    SG -- "gRPC + mTLS" --> OS2
    OS1 --> Agent1
    OS2 --> Agent2
    Agent1 -. "inference.local" .-> Proxy1
    Agent2 -. "inference.local" .-> Proxy2
    Proxy1 -- "real API key" --> LLM
    Proxy2 -- "real API key" --> LLM

    style SG fill:#1a7f37,color:#fff,stroke:#1a7f37
    style Agent1 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    style Agent2 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    style Proxy1 fill:#ffe0b2,stroke:#e65100,color:#bf360c
    style Proxy2 fill:#ffe0b2,stroke:#e65100,color:#bf360c
    style Grafana fill:#bbdefb,stroke:#1565c0,color:#0d47a1
```

> **Key insight:** The agent inside the sandbox only knows `inference.local/v1`. OpenShell's L7 proxy injects the real credentials and routes to the actual provider. API keys are managed by ShoreGuard, never exposed to agent code. All operators — whether human (Web UI, Terraform) or agent platforms (Paperclip, OpenClaw) — use the same ShoreGuard REST API. One ShoreGuard instance manages multiple gateways (dev, staging, production).

---

## Why ShoreGuard?

[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) provides hardened sandboxes for AI agents — but ships with only a CLI. [NemoClaw](https://github.com/NVIDIA/NemoClaw) adds orchestration, but is single-gateway and CLI-driven.

ShoreGuard adds the missing management layer:

| Capability | OpenShell CLI | NemoClaw | ShoreGuard |
|------------|:---:|:---:|:---:|
| Sandbox creation | CLI | CLI | Web UI + API + Terraform |
| Multi-gateway | — | — | Multiple gateways, one dashboard |
| Visual policy editor | — | — | Drag-and-drop with revision history |
| Approval flow | — | — | Real-time notifications |
| Inference routing | CLI | Blueprint profiles | API-driven, per-gateway |
| Audit trail | — | — | Persistent, filterable, exportable |
| RBAC | — | — | Admin / Operator / Viewer |
| Agent frameworks | — | OpenClaw only | Paperclip, OpenClaw, custom |
| Webhooks | — | — | Slack, Discord, Email, HMAC-signed |

---

## Quick Start

### Local development

```bash
pip install shoreguard
shoreguard --local --no-auth
```

Open [http://localhost:8888](http://localhost:8888). The `--local` flag enables Docker-based gateway management, `--no-auth` skips login.

### Docker Compose (production)

```bash
git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard/deploy
cp .env.example .env    # edit: set SHOREGUARD_SECRET_KEY, passwords
docker compose up -d    # core: ShoreGuard + OpenShell + Caddy (HTTPS)
```

The stack automatically generates mTLS certificates, registers an OpenShell gateway, and provides HTTPS via Caddy with self-signed certificates.

#### Optional profiles

```bash
# Add Paperclip agent orchestration
docker compose --profile paperclip up -d

# Add OpenClaw agent gateway (sandboxed)
docker compose --profile openclaw up -d
```

See the [deployment guide](https://flohofstetter.github.io/shoreguard/admin/deployment/) for production hardening, custom domains, and Let's Encrypt.

### Verifying release integrity

Docker images on GHCR and wheels on PyPI are signed via [sigstore](https://sigstore.dev/) keyless (GitHub OIDC → Fulcio → Rekor). Verify before running:

```bash
cosign verify ghcr.io/flohofstetter/shoreguard:0.30.3 \
  --certificate-identity-regexp 'https://github.com/FloHofstetter/shoreguard/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'
```

PyPI wheels ship with [PEP 740 attestations](https://peps.python.org/pep-0740/) — modern `pip`/`uv` verify them automatically. See the [installation guide](https://flohofstetter.github.io/shoreguard/getting-started/installation/#verifying-release-integrity) for explicit verification.

---

## Features

### Sandbox Management

- **Sandbox wizard** — step-by-step creation with community images, GPU support, and policy presets
- **Visual policy editor** — network rules, filesystem paths, process settings with revision history and diff viewer
- **[Approval flow](https://flohofstetter.github.io/shoreguard/guides/approvals/)** — agents request endpoint access, operators approve or deny in real-time, with binary SHA-256 + process ancestry + L7 request samples for full context
- **[Multi-stage approvals](https://flohofstetter.github.io/shoreguard/guides/approval-workflows/)** — per-sandbox quorum with escalation deadlines
- **[Policy pinning](https://flohofstetter.github.io/shoreguard/guides/policy-pinning/)** — freeze the active policy version during incidents or change freezes; all writes return HTTP 423
- **[Boot hooks](https://flohofstetter.github.io/shoreguard/guides/boot-hooks/)** — pre/post-create validation gates and warm-up tasks attached to each sandbox
- **Templates** — pre-configured sandboxes for data science, web development, and secure coding

### Policy & Verification

- **[Policy Prover](https://flohofstetter.github.io/shoreguard/guides/policy-prover/)** — Z3 formal verification with built-in templates (`can_exfiltrate`, `unrestricted_egress`, `binary_bypass`, `write_despite_readonly`) that return a SAT witness when a property fails
- **[GitOps policy sync](https://flohofstetter.github.io/shoreguard/guides/gitops/)** — declarative YAML policies via `shoreguard policy export|diff|apply`, optimistic-locked via `policy_hash` etag, CI apply counts as one quorum vote under an active workflow
- **[Bypass Detection](https://flohofstetter.github.io/shoreguard/guides/bypass-detection/)** — OCSF events classified as policy bypass attempts, with MITRE ATT&CK mapping

### Infrastructure & Supply Chain

- **Multi-gateway** — manage dev, staging, and production OpenShell clusters from one dashboard
- **[Gateway discovery](https://flohofstetter.github.io/shoreguard/guides/gateway-discovery/)** — auto-register gateways from `_openshell._tcp.<domain>` DNS SRV records
- **RBAC** — Admin, Operator, Viewer roles with gateway-scoped overrides
- **Audit log** — persistent, filterable, exportable trail of all state changes
- **Health monitoring** — automatic gateway probing with status indicators
- **[SBOM / Supply-Chain Viewer](https://flohofstetter.github.io/shoreguard/guides/sbom/)** — per-sandbox CycloneDX ingestion with component search, severity filter, and offline CVE browsing

### Integrations

- **REST API** — full CRUD for gateways, sandboxes, policies, providers, and inference (see the [API reference](https://flohofstetter.github.io/shoreguard/reference/api/))
- **[Terraform provider](https://github.com/FloHofstetter/terraform-provider-shoreguard)** — declarative infrastructure as code (gateways, groups, approval workflows, policy pins, boot hooks); policy content lives in the GitOps flow, not Terraform state
- **Webhooks** — Slack, Discord, Email, and generic webhooks with HMAC-SHA256 signing, including quorum events (`approval.vote_cast` / `quorum_met` / `escalated`) and drift detection (`policy.drift_detected`)
- **Prometheus metrics** — `/metrics` endpoint for Grafana and standard monitoring

<details>
<summary><strong>Screenshots</strong></summary>

| Sandbox Overview | Policy Editor |
|:---:|:---:|
| ![Sandbox Overview](docs/screenshots/sandbox-overview.png) | ![Policy Editor](docs/screenshots/policy.png) |

| Network Policies | Gateway Detail |
|:---:|:---:|
| ![Network Policies](docs/screenshots/network-policies.png) | ![Gateway Detail](docs/screenshots/gateway-detail.png) |

| Providers | Audit Log |
|:---:|:---:|
| ![Providers](docs/screenshots/providers.png) | ![Audit Log](docs/screenshots/audit-log.png) |

</details>

---

## Ecosystem

| Project | Description |
|---------|-------------|
| [Terraform Provider](https://github.com/FloHofstetter/terraform-provider-shoreguard) | Manage gateways, sandboxes, providers, and policies as code |
| [Paperclip Plugin + Adapter](https://github.com/FloHofstetter/paperclip-plugin-shoreguard) | Run Paperclip agents in isolated OpenShell sandboxes |
| [OpenClaw Plugin](https://github.com/FloHofstetter/openclaw-plugin-shoreguard) | `/shoreguard` slash commands for OpenClaw agents |
| [OpenClaw Sandbox Image](images/openclaw/) | Hardened OpenClaw image for OpenShell deployment |
| [Docker Compose Stack](deploy/) | One-command setup: ShoreGuard + OpenShell + Caddy + optional integrations |

---

## Roadmap

**Shipped:**

- Multi-gateway management with health monitoring + DNS SRV auto-discovery
- Multi-region federation (in-k8s via `tests/fixtures/charts/openshell-cluster`, host-to-host via `scripts/m8_demo.py`)
- RBAC with gateway-scoped overrides
- Sandbox wizard with community images, presets, and pre/post-create boot hooks
- Visual policy editor with revision history
- Real-time approval flow with binary SHA-256, process ancestry, and L7 request samples
- Multi-stage approval workflows (quorum + escalation)
- Policy pinning (HTTP 423 on all writes while active)
- Z3 policy prover with four built-in verification templates
- GitOps policy sync (YAML export/apply + `shoreguard policy` CLI + optional drift detection)
- Bypass Detection dashboard with MITRE ATT&CK mapping
- SBOM / Supply-Chain Viewer (CycloneDX ingestion, offline CVE browse)
- Terraform provider (v0.30.0 mirroring server version)
- Helm chart (`charts/shoreguard`) with production preset + NetworkPolicy + PDB + helm test
- Persistent audit log with export
- Webhooks (Slack, Discord, Email) with HMAC signing and quorum/drift events
- Prometheus metrics
- Paperclip adapter ([`@shoreguard/paperclip-plugin`](https://www.npmjs.com/package/@shoreguard/paperclip-plugin) + [`@shoreguard/paperclip-adapter`](https://www.npmjs.com/package/@shoreguard/paperclip-adapter))
- Docker Compose stack with Caddy auto-TLS
- Inference routing via OpenShell L7 proxy
- OpenClaw sandbox image with NemoClaw-style hardening

**In progress:**

- Hardened sandbox deployment via gRPC API (blocked by [OpenShell API limitations](images/openclaw/README.md#known-limitations))
- Routed inference for Paperclip adapter (replace credential injection with `inference.local`)

**Planned:**

- DigitalOcean Marketplace integration

---

## Development

```bash
git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync --group dev
uv run pre-commit install --hook-type pre-commit --hook-type pre-push
uv run shoreguard --local --no-auth
```

Run checks with [just](https://github.com/casey/just):

```bash
just check    # lint + format + typecheck + tests
just dev      # start dev server
just test     # run unit tests
```

See the [contributing guide](https://flohofstetter.github.io/shoreguard/development/contributing/) for details.

## Documentation

Full docs: **[flohofstetter.github.io/shoreguard](https://flohofstetter.github.io/shoreguard/)**

## License

[Apache 2.0](LICENSE)
