{"id":48701364,"url":"https://github.com/flohofstetter/shoreguard","last_synced_at":"2026-04-24T00:00:51.400Z","repository":{"id":347168590,"uuid":"1187835574","full_name":"FloHofstetter/shoreguard","owner":"FloHofstetter","description":"Open source control plane for NVIDIA OpenShell","archived":false,"fork":false,"pushed_at":"2026-04-11T10:03:01.000Z","size":3395,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T10:29:43.154Z","etag":null,"topics":["ai-agents","control-plane","fastapi","nvidia","openshell","sandbox","security"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/shoreguard/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FloHofstetter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T08:31:26.000Z","updated_at":"2026-04-11T10:02:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"2a2fdc66-042a-44a8-b852-3a4145027e86","html_url":"https://github.com/FloHofstetter/shoreguard","commit_stats":null,"previous_names":["flohofstetter/shoreguard"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/FloHofstetter/shoreguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloHofstetter%2Fshoreguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloHofstetter%2Fshoreguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloHofstetter%2Fshoreguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloHofstetter%2Fshoreguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FloHofstetter","download_url":"https://codeload.github.com/FloHofstetter/shoreguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloHofstetter%2Fshoreguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32203362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T20:19:26.138Z","status":"ssl_error","status_checked_at":"2026-04-23T20:19:23.520Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","control-plane","fastapi","nvidia","openshell","sandbox","security"],"created_at":"2026-04-11T10:22:20.907Z","updated_at":"2026-04-24T00:00:51.393Z","avatar_url":"https://github.com/FloHofstetter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShoreGuard\n\n[![CI](https://github.com/FloHofstetter/shoreguard/actions/workflows/ci.yml/badge.svg)](https://github.com/FloHofstetter/shoreguard/actions/workflows/ci.yml)\n[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)\n\n**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.\n\n![Sandbox Overview](docs/screenshots/sandbox-overview.png)\n\n---\n\n## Architecture\n\nShoreGuard 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.\n\n```mermaid\ngraph LR\n    subgraph \"Operators — all use ShoreGuard REST API\"\n        UI[\"ShoreGuard Web UI\"]\n        TF[\"Terraform Provider\"]\n        PC[\"Paperclip\"]\n        OC[\"OpenClaw\"]\n    end\n\n    subgraph \"Observability\"\n        Grafana[\"Grafana\"]\n    end\n\n    subgraph \"ShoreGuard — Management Plane\"\n        SG[\"ShoreGuard API\"]\n        DB[(\"PostgreSQL\")]\n        Metrics[\"/metrics\"]\n    end\n\n    subgraph \"Gateway: dev\"\n        OS1[\"OpenShell Controller\"]\n        subgraph \"Sandbox\"\n            Agent1[\"Agent\"]\n        end\n        Proxy1[\"inference.local/v1\"]\n    end\n\n    subgraph \"Gateway: staging\"\n        OS2[\"OpenShell Controller\"]\n        subgraph \"Sandbox \"\n            Agent2[\"Agent\"]\n        end\n        Proxy2[\"inference.local/v1\"]\n    end\n\n    subgraph \"LLM Providers\"\n        LLM[\"Anthropic / NVIDIA / OpenAI\"]\n    end\n\n    UI --\u003e SG\n    TF --\u003e SG\n    PC --\u003e|\"adapter plugin\"| SG\n    OC --\u003e|\"slash commands\"| SG\n    PC -.-\u003e|\"controls\"| Agent1\n    OC -.-\u003e|\"controls\"| Agent1\n    Grafana --\u003e Metrics\n    SG --\u003e DB\n    SG --\u003e Metrics\n    SG -- \"gRPC + mTLS\" --\u003e OS1\n    SG -- \"gRPC + mTLS\" --\u003e OS2\n    OS1 --\u003e Agent1\n    OS2 --\u003e Agent2\n    Agent1 -. \"inference.local\" .-\u003e Proxy1\n    Agent2 -. \"inference.local\" .-\u003e Proxy2\n    Proxy1 -- \"real API key\" --\u003e LLM\n    Proxy2 -- \"real API key\" --\u003e LLM\n\n    style SG fill:#1a7f37,color:#fff,stroke:#1a7f37\n    style Agent1 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20\n    style Agent2 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20\n    style Proxy1 fill:#ffe0b2,stroke:#e65100,color:#bf360c\n    style Proxy2 fill:#ffe0b2,stroke:#e65100,color:#bf360c\n    style Grafana fill:#bbdefb,stroke:#1565c0,color:#0d47a1\n```\n\n\u003e **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).\n\n---\n\n## Why ShoreGuard?\n\n[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.\n\nShoreGuard adds the missing management layer:\n\n| Capability | OpenShell CLI | NemoClaw | ShoreGuard |\n|------------|:---:|:---:|:---:|\n| Sandbox creation | CLI | CLI | Web UI + API + Terraform |\n| Multi-gateway | — | — | Multiple gateways, one dashboard |\n| Visual policy editor | — | — | Drag-and-drop with revision history |\n| Approval flow | — | — | Real-time notifications |\n| Inference routing | CLI | Blueprint profiles | API-driven, per-gateway |\n| Audit trail | — | — | Persistent, filterable, exportable |\n| RBAC | — | — | Admin / Operator / Viewer |\n| Agent frameworks | — | OpenClaw only | Paperclip, OpenClaw, custom |\n| Webhooks | — | — | Slack, Discord, Email, HMAC-signed |\n\n---\n\n## Quick Start\n\n### Local development\n\n```bash\npip install shoreguard\nshoreguard --local --no-auth\n```\n\nOpen [http://localhost:8888](http://localhost:8888). The `--local` flag enables Docker-based gateway management, `--no-auth` skips login.\n\n### Docker Compose (production)\n\n```bash\ngit clone https://github.com/FloHofstetter/shoreguard.git\ncd shoreguard/deploy\ncp .env.example .env    # edit: set SHOREGUARD_SECRET_KEY, passwords\ndocker compose up -d    # core: ShoreGuard + OpenShell + Caddy (HTTPS)\n```\n\nThe stack automatically generates mTLS certificates, registers an OpenShell gateway, and provides HTTPS via Caddy with self-signed certificates.\n\n#### Optional profiles\n\n```bash\n# Add Paperclip agent orchestration\ndocker compose --profile paperclip up -d\n\n# Add OpenClaw agent gateway (sandboxed)\ndocker compose --profile openclaw up -d\n```\n\nSee the [deployment guide](https://flohofstetter.github.io/shoreguard/admin/deployment/) for production hardening, custom domains, and Let's Encrypt.\n\n### Verifying release integrity\n\nDocker images on GHCR and wheels on PyPI are signed via [sigstore](https://sigstore.dev/) keyless (GitHub OIDC → Fulcio → Rekor). Verify before running:\n\n```bash\ncosign verify ghcr.io/flohofstetter/shoreguard:0.30.3 \\\n  --certificate-identity-regexp 'https://github.com/FloHofstetter/shoreguard/.*' \\\n  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'\n```\n\nPyPI 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.\n\n---\n\n## Features\n\n### Sandbox Management\n\n- **Sandbox wizard** — step-by-step creation with community images, GPU support, and policy presets\n- **Visual policy editor** — network rules, filesystem paths, process settings with revision history and diff viewer\n- **[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\n- **[Multi-stage approvals](https://flohofstetter.github.io/shoreguard/guides/approval-workflows/)** — per-sandbox quorum with escalation deadlines\n- **[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\n- **[Boot hooks](https://flohofstetter.github.io/shoreguard/guides/boot-hooks/)** — pre/post-create validation gates and warm-up tasks attached to each sandbox\n- **Templates** — pre-configured sandboxes for data science, web development, and secure coding\n\n### Policy \u0026 Verification\n\n- **[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\n- **[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\n- **[Bypass Detection](https://flohofstetter.github.io/shoreguard/guides/bypass-detection/)** — OCSF events classified as policy bypass attempts, with MITRE ATT\u0026CK mapping\n\n### Infrastructure \u0026 Supply Chain\n\n- **Multi-gateway** — manage dev, staging, and production OpenShell clusters from one dashboard\n- **[Gateway discovery](https://flohofstetter.github.io/shoreguard/guides/gateway-discovery/)** — auto-register gateways from `_openshell._tcp.\u003cdomain\u003e` DNS SRV records\n- **RBAC** — Admin, Operator, Viewer roles with gateway-scoped overrides\n- **Audit log** — persistent, filterable, exportable trail of all state changes\n- **Health monitoring** — automatic gateway probing with status indicators\n- **[SBOM / Supply-Chain Viewer](https://flohofstetter.github.io/shoreguard/guides/sbom/)** — per-sandbox CycloneDX ingestion with component search, severity filter, and offline CVE browsing\n\n### Integrations\n\n- **REST API** — full CRUD for gateways, sandboxes, policies, providers, and inference (see the [API reference](https://flohofstetter.github.io/shoreguard/reference/api/))\n- **[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\n- **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`)\n- **Prometheus metrics** — `/metrics` endpoint for Grafana and standard monitoring\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eScreenshots\u003c/strong\u003e\u003c/summary\u003e\n\n| Sandbox Overview | Policy Editor |\n|:---:|:---:|\n| ![Sandbox Overview](docs/screenshots/sandbox-overview.png) | ![Policy Editor](docs/screenshots/policy.png) |\n\n| Network Policies | Gateway Detail |\n|:---:|:---:|\n| ![Network Policies](docs/screenshots/network-policies.png) | ![Gateway Detail](docs/screenshots/gateway-detail.png) |\n\n| Providers | Audit Log |\n|:---:|:---:|\n| ![Providers](docs/screenshots/providers.png) | ![Audit Log](docs/screenshots/audit-log.png) |\n\n\u003c/details\u003e\n\n---\n\n## Ecosystem\n\n| Project | Description |\n|---------|-------------|\n| [Terraform Provider](https://github.com/FloHofstetter/terraform-provider-shoreguard) | Manage gateways, sandboxes, providers, and policies as code |\n| [Paperclip Plugin + Adapter](https://github.com/FloHofstetter/paperclip-plugin-shoreguard) | Run Paperclip agents in isolated OpenShell sandboxes |\n| [OpenClaw Plugin](https://github.com/FloHofstetter/openclaw-plugin-shoreguard) | `/shoreguard` slash commands for OpenClaw agents |\n| [OpenClaw Sandbox Image](images/openclaw/) | Hardened OpenClaw image for OpenShell deployment |\n| [Docker Compose Stack](deploy/) | One-command setup: ShoreGuard + OpenShell + Caddy + optional integrations |\n\n---\n\n## Roadmap\n\n**Shipped:**\n\n- Multi-gateway management with health monitoring + DNS SRV auto-discovery\n- Multi-region federation (in-k8s via `tests/fixtures/charts/openshell-cluster`, host-to-host via `scripts/m8_demo.py`)\n- RBAC with gateway-scoped overrides\n- Sandbox wizard with community images, presets, and pre/post-create boot hooks\n- Visual policy editor with revision history\n- Real-time approval flow with binary SHA-256, process ancestry, and L7 request samples\n- Multi-stage approval workflows (quorum + escalation)\n- Policy pinning (HTTP 423 on all writes while active)\n- Z3 policy prover with four built-in verification templates\n- GitOps policy sync (YAML export/apply + `shoreguard policy` CLI + optional drift detection)\n- Bypass Detection dashboard with MITRE ATT\u0026CK mapping\n- SBOM / Supply-Chain Viewer (CycloneDX ingestion, offline CVE browse)\n- Terraform provider (v0.30.0 mirroring server version)\n- Helm chart (`charts/shoreguard`) with production preset + NetworkPolicy + PDB + helm test\n- Persistent audit log with export\n- Webhooks (Slack, Discord, Email) with HMAC signing and quorum/drift events\n- Prometheus metrics\n- Paperclip adapter ([`@shoreguard/paperclip-plugin`](https://www.npmjs.com/package/@shoreguard/paperclip-plugin) + [`@shoreguard/paperclip-adapter`](https://www.npmjs.com/package/@shoreguard/paperclip-adapter))\n- Docker Compose stack with Caddy auto-TLS\n- Inference routing via OpenShell L7 proxy\n- OpenClaw sandbox image with NemoClaw-style hardening\n\n**In progress:**\n\n- Hardened sandbox deployment via gRPC API (blocked by [OpenShell API limitations](images/openclaw/README.md#known-limitations))\n- Routed inference for Paperclip adapter (replace credential injection with `inference.local`)\n\n**Planned:**\n\n- DigitalOcean Marketplace integration\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/FloHofstetter/shoreguard.git\ncd shoreguard\nuv sync --group dev\nuv run pre-commit install --hook-type pre-commit --hook-type pre-push\nuv run shoreguard --local --no-auth\n```\n\nRun checks with [just](https://github.com/casey/just):\n\n```bash\njust check    # lint + format + typecheck + tests\njust dev      # start dev server\njust test     # run unit tests\n```\n\nSee the [contributing guide](https://flohofstetter.github.io/shoreguard/development/contributing/) for details.\n\n## Documentation\n\nFull docs: **[flohofstetter.github.io/shoreguard](https://flohofstetter.github.io/shoreguard/)**\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflohofstetter%2Fshoreguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflohofstetter%2Fshoreguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflohofstetter%2Fshoreguard/lists"}