mirror of
https://github.com/we-promise/sure.git
synced 2026-04-07 14:31:25 +00:00
Add Pipelock operational templates, docs, and config hardening (#1102)
* feat(helm): add Pipelock ConfigMap, scanning config, and consolidate compose - Add ConfigMap template rendering DLP, response scanning, MCP input/tool scanning, and forward proxy settings from values - Mount ConfigMap as /etc/pipelock/pipelock.yaml volume in deployment - Add checksum/config annotation for automatic pod restart on config change - Gate HTTPS_PROXY/HTTP_PROXY env injection on forwardProxy.enabled (skip in MCP-only mode) - Use hasKey for all boolean values to prevent Helm default swallowing false - Single source of truth for ports (forwardProxy.port/mcpProxy.port) - Pipelock-specific imagePullSecrets with fallback to app secrets - Merge standalone compose.example.pipelock.yml into compose.example.ai.yml - Add pipelock.example.yaml for Docker Compose users - Add exclude-paths to CI workflow for locale file false positives * Add external assistant support (OpenAI-compatible SSE proxy) Allow self-hosted instances to delegate chat to an external AI agent via an OpenAI-compatible streaming endpoint. Configurable per-family through Settings UI or ASSISTANT_TYPE env override. - Assistant::External::Client: SSE streaming HTTP client (no new gems) - Settings UI with type selector, env lock indicator, config status - Helm chart and Docker Compose env var support - 45 tests covering client, config, routing, controller, integration * Add session key routing, email allowlist, and config plumbing Route to the actual OpenClaw session via x-openclaw-session-key header instead of creating isolated sessions. Gate external assistant access behind an email allowlist (EXTERNAL_ASSISTANT_ALLOWED_EMAILS env var). Plumb session_key and allowedEmails through Helm chart, compose, and env template. * Add HTTPS_PROXY support to External::Client for Pipelock integration Net::HTTP does not auto-read HTTPS_PROXY/HTTP_PROXY env vars (unlike Faraday). Explicitly resolve proxy from environment in build_http so outbound traffic to the external assistant routes through Pipelock's forward proxy when enabled. Respects NO_PROXY for internal hosts. * Add UI fields for external assistant config (Setting-backed with env fallback) Follow the same pattern as OpenAI settings: database-backed Setting fields with env var defaults. Self-hosters can now configure the external assistant URL, token, and agent ID from the browser (Settings > Self-Hosting > AI Assistant) instead of requiring env vars. Fields disable when the corresponding env var is set. * Improve external assistant UI labels and add help text Change placeholder to generic OpenAI-compatible URL pattern. Add help text under each field explaining where the values come from: URL from agent provider, token for authentication, agent ID for multi-agent routing. * Add external assistant docs and fix URL help text Add External AI Assistant section to docs/hosting/ai.md covering setup (UI and env vars), how it works, Pipelock security scanning, access control, and Docker Compose example. Drop "chat completions" jargon from URL help text. * Harden external assistant: retry logic, disconnect UI, error handling, and test coverage - Add retry with backoff for transient network errors (no retry after streaming starts) - Add disconnect button with confirmation modal in self-hosting settings - Narrow rescue scope with fallback logging for unexpected errors - Safe cleanup of partial responses on stream interruption - Gate ai_available? on family assistant_type instead of OR-ing all providers - Truncate conversation history to last 20 messages - Proxy-aware HTTP client with NO_PROXY support - Sanitize protocol to use generic headers (X-Agent-Id, X-Session-Key) - Full test coverage for streaming, retries, proxy routing, config, and disconnect * Exclude external assistant client from Pipelock scan-diff False positive: `@token` instance variable flagged as "Credential in URL". Temporary workaround until Pipelock supports inline suppression. * Address review feedback: NO_PROXY boundary fix, SSE done flag, design tokens - Fix NO_PROXY matching to require domain boundary (exact match or .suffix), case-insensitive. Prevents badexample.com matching example.com. - Add done flag to SSE streaming so read_body stops after [DONE] - Move MAX_CONVERSATION_MESSAGES to class level - Use bg-success/bg-destructive design tokens for status indicators - Add rationale comment for pipelock scan exclusion - Update docs last-updated date * Address second round of review feedback - Allowlist email comparison is now case-insensitive and nil-safe - Cap SSE buffer at 1 MB to prevent memory blowup from malformed streams - Don't expose upstream HTTP response body in user-facing errors (log it instead) - Fix frozen string warning on buffer initialization - Fix "builtin" typo in docs (should be "built-in") * Protect completed responses from cleanup, sanitize error messages - Don't destroy a fully streamed assistant message if post-stream metadata update fails (only cleanup partial responses) - Log raw connection/HTTP errors internally, show generic messages to users to avoid leaking network/proxy details - Update test assertions for new error message wording * Fix SSE content guard and NO_PROXY test correctness Use nil check instead of present? for SSE delta content to preserve whitespace-only chunks (newlines, spaces) that can occur in code output. Fix NO_PROXY test to use HTTP_PROXY matching the http:// client URL so the proxy resolution and NO_PROXY bypass logic are actually exercised. * Forward proxy credentials to Net::HTTP Pass proxy_uri.user and proxy_uri.password to Net::HTTP.new so authenticated proxies (http://user:pass@host:port) work correctly. Without this, credentials parsed from the proxy URL were silently dropped. Nil values are safe as positional args when no creds exist. * Update pipelock integration to v0.3.1 with full scanning config Bump Helm image tag from 0.2.7 to 0.3.1. Add missing security sections to both the Helm ConfigMap and compose example config: mcp_tool_policy, mcp_session_binding, and tool_chain_detection. These protect the /mcp endpoint against tool injection, session hijacking, and multi-step exfiltration chains. Add version and mode fields to config files. Enable include_defaults for DLP and response scanning to merge user patterns with the 35 built-in patterns. Remove redundant --mode CLI flag from the Helm deployment template since mode is now in the config file. * Pipelock Helm hardening + docs for external assistant and pipelock Helm templates: - ServiceMonitor for Prometheus scraping on /metrics (proxy port) - Ingress template for MCP reverse proxy (external AI agent access) - PodDisruptionBudget with minAvailable/maxUnavailable mutual exclusion - topologySpreadConstraints on Deployment - Structured logging config (format, output, include_allowed/blocked) - extraConfig escape hatch for additional pipelock.yaml sections - requireForExternalAssistant guard (fails when assistant enabled without pipelock) - Component label on Service metadata for ServiceMonitor targeting - NOTES.txt pipelock section with health, access, security, metrics info - Bump pipelock image tag 0.3.1 -> 0.3.2 - Fix: rename _asserts.tpl -> asserts.tpl (Helm skipped _ prefixed file) Documentation: - Helm chart README: full Pipelock section - docs/hosting/pipelock.md: dedicated hosting guide (Docker + Kubernetes) - docs/hosting/docker.md: AI features section (external assistant, pipelock) - .env.example: external assistant and MCP env vars Infra: - Chart.lock pinning dependency versions - .gitignore for vendored subchart tarballs * Fix bot comments: quote ingress host, fix sidecar wording, add code block lang * Fail fast when pipelock ingress enabled with empty hosts * Fail fast when pipelock ingress host has empty paths * Messed up the conflict merge --------- Signed-off-by: Juan José Mata <juanjo.mata@gmail.com> Co-authored-by: Juan José Mata <juanjo.mata@gmail.com> Co-authored-by: Juan José Mata <jjmata@jjmata.com>
This commit is contained in:
LPW
15
.env.example
15
.env.example
@@ -25,6 +25,21 @@ OPENAI_ACCESS_TOKEN=
|
||||
OPENAI_MODEL=
|
||||
OPENAI_URI_BASE=
|
||||
|
||||
# Optional: External AI Assistant — delegates chat to a remote AI agent
|
||||
# instead of calling LLMs directly. The agent calls back to Sure's /mcp endpoint.
|
||||
# See docs/hosting/ai.md for full details.
|
||||
# ASSISTANT_TYPE=external
|
||||
# EXTERNAL_ASSISTANT_URL=https://your-agent-host/v1/chat/completions
|
||||
# EXTERNAL_ASSISTANT_TOKEN=your-api-token
|
||||
# EXTERNAL_ASSISTANT_AGENT_ID=main
|
||||
# EXTERNAL_ASSISTANT_SESSION_KEY=agent:main:main
|
||||
# EXTERNAL_ASSISTANT_ALLOWED_EMAILS=user@example.com
|
||||
|
||||
# Optional: MCP server endpoint — enables /mcp for external AI assistants.
|
||||
# Both values are required. MCP_USER_EMAIL must match an existing user's email.
|
||||
# MCP_API_TOKEN=your-random-bearer-token
|
||||
# MCP_USER_EMAIL=user@example.com
|
||||
|
||||
# Optional: Langfuse config
|
||||
LANGFUSE_HOST=https://cloud.langfuse.com
|
||||
LANGFUSE_PUBLIC_KEY=
|
||||
|
||||
2
charts/sure/.gitignore
vendored
Normal file
2
charts/sure/.gitignore
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
# Vendored subchart tarballs (regenerated by `helm dependency build`)
|
||||
charts/
|
||||
@@ -5,7 +5,7 @@ All notable changes to the Sure Helm chart will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.6.9-alpha] - 2026-03-01
|
||||
## [0.6.9-alpha] - 2026-03-02
|
||||
|
||||
### Added
|
||||
- **Pipelock security proxy** (`pipelock.enabled=true`): Separate Deployment + Service that provides two scanning layers
|
||||
@@ -20,11 +20,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- Boolean safety: uses `hasKey` to prevent Helm's `default` from swallowing explicit `false`
|
||||
- Configurable ports via `forwardProxy.port` and `mcpProxy.port` (single source of truth across Service, Deployment, and env vars)
|
||||
- `pipelock.example.yaml` reference config for Docker Compose deployments
|
||||
- **Pipelock operational hardening**:
|
||||
- `pipelock.serviceMonitor`: Prometheus Operator ServiceMonitor for /metrics on the proxy port
|
||||
- `pipelock.ingress`: Ingress template for MCP reverse proxy (external AI assistant access in k8s)
|
||||
- `pipelock.pdb`: PodDisruptionBudget with minAvailable/maxUnavailable mutual exclusion guard
|
||||
- `pipelock.topologySpreadConstraints`: Pod spread across nodes
|
||||
- `pipelock.logging`: Structured logging config (format, output, include_allowed, include_blocked)
|
||||
- `pipelock.extraConfig`: Escape hatch for additional pipelock.yaml config sections
|
||||
- `pipelock.requireForExternalAssistant`: Helm guard that fails when externalAssistant is enabled without pipelock
|
||||
- Component label (`app.kubernetes.io/component: pipelock`) on Service metadata for selector targeting
|
||||
- NOTES.txt: Pipelock health check commands, MCP access info, security notes, metrics status
|
||||
|
||||
### Changed
|
||||
- Bumped `pipelock.image.tag` from `0.3.1` to `0.3.2`
|
||||
- Consolidated `compose.example.pipelock.yml` into `compose.example.ai.yml` — Pipelock now runs alongside Ollama in one compose file with health checks, config volume mount, and MCP env vars (`MCP_API_TOKEN`, `MCP_USER_EMAIL`)
|
||||
- CI: Pipelock scan `fail-on-findings` changed from `false` to `true`; added `exclude-paths` for locale help text false positives
|
||||
|
||||
### Fixed
|
||||
- Renamed `_asserts.tpl` to `asserts.tpl` — Helm's `_` prefix convention prevented guards from executing
|
||||
|
||||
## [0.6.7-alpha] - 2026-01-10
|
||||
|
||||
### Added
|
||||
|
||||
9
charts/sure/Chart.lock
Normal file
9
charts/sure/Chart.lock
Normal file
@@ -0,0 +1,9 @@
|
||||
dependencies:
|
||||
- name: cloudnative-pg
|
||||
repository: https://cloudnative-pg.github.io/charts
|
||||
version: 0.27.1
|
||||
- name: redis-operator
|
||||
repository: https://ot-container-kit.github.io/helm-charts
|
||||
version: 0.23.0
|
||||
digest: sha256:5ffa5c535cb5feea62a29665045a79da8a5d058c3ba11c4db37a4afa97563e3e
|
||||
generated: "2026-03-02T21:16:32.757224371-05:00"
|
||||
@@ -12,6 +12,7 @@ Official Helm chart for deploying the Sure Rails application on Kubernetes. It s
|
||||
- Optional subcharts
|
||||
- CloudNativePG (operator) + Cluster CR for PostgreSQL with HA support
|
||||
- OT-CONTAINER-KIT redis-operator for Redis HA (replication by default, optional Sentinel)
|
||||
- Optional Pipelock AI agent security proxy (forward proxy + MCP reverse proxy with DLP, prompt injection, and tool poisoning detection)
|
||||
- Security best practices: runAsNonRoot, readOnlyRootFilesystem, optional existingSecret, no hardcoded secrets
|
||||
- Scalability
|
||||
- Replicas (web/worker), resources, topology spread constraints
|
||||
@@ -637,6 +638,112 @@ hpa:
|
||||
targetCPUUtilizationPercentage: 70
|
||||
```
|
||||
|
||||
## Pipelock (AI agent security proxy)
|
||||
|
||||
Pipelock is an optional sidecar that scans AI agent traffic for secret exfiltration, prompt injection, and tool poisoning. It runs as a separate Deployment with two listeners:
|
||||
|
||||
- **Forward proxy** (port 8888): Scans outbound HTTPS from Faraday-based AI clients. Auto-injected via `HTTPS_PROXY` env vars when enabled.
|
||||
- **MCP reverse proxy** (port 8889): Scans inbound MCP traffic from external AI assistants.
|
||||
|
||||
### Enabling Pipelock
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
enabled: true
|
||||
image:
|
||||
tag: "0.3.2"
|
||||
mode: balanced # strict, balanced, or audit
|
||||
```
|
||||
|
||||
### Exposing MCP to external AI assistants
|
||||
|
||||
When running in Kubernetes, external AI agents need network access to the MCP reverse proxy port. Enable the Pipelock Ingress:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
enabled: true
|
||||
ingress:
|
||||
enabled: true
|
||||
className: nginx
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: letsencrypt
|
||||
hosts:
|
||||
- host: pipelock.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
tls:
|
||||
- hosts: [pipelock.example.com]
|
||||
secretName: pipelock-tls
|
||||
```
|
||||
|
||||
Security: The Ingress routes to port `mcp` (8889). Ensure `MCP_API_TOKEN` is set so the MCP endpoint requires authentication. The Ingress itself does not add auth.
|
||||
|
||||
### Metrics (Prometheus)
|
||||
|
||||
Pipelock exposes `/metrics` on the forward proxy port. Enable scraping with a ServiceMonitor:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
serviceMonitor:
|
||||
enabled: true
|
||||
interval: 30s
|
||||
portName: proxy # matches Service port name for 8888
|
||||
additionalLabels:
|
||||
release: prometheus # match your Prometheus Operator selector
|
||||
```
|
||||
|
||||
### PodDisruptionBudget
|
||||
|
||||
Protect Pipelock from node drains:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
pdb:
|
||||
enabled: true
|
||||
maxUnavailable: 1 # safe for single-replica; use minAvailable when replicas > 1
|
||||
```
|
||||
|
||||
Note: Setting `minAvailable` with `replicas=1` blocks eviction entirely. Use `maxUnavailable` for single-replica deployments.
|
||||
|
||||
### Structured logging
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
logging:
|
||||
format: json # json or text
|
||||
output: stdout
|
||||
includeAllowed: false
|
||||
includeBlocked: true
|
||||
```
|
||||
|
||||
### Extra config (escape hatch)
|
||||
|
||||
For Pipelock config sections not covered by structured values (session profiling, data budgets, kill switch, etc.), use `extraConfig`:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
extraConfig:
|
||||
session_profiling:
|
||||
enabled: true
|
||||
max_sessions: 1000
|
||||
data_budget:
|
||||
max_bytes_per_session: 10485760
|
||||
```
|
||||
|
||||
These are appended verbatim to `pipelock.yaml`. Do not duplicate keys already rendered by the chart.
|
||||
|
||||
### Requiring Pipelock for external assistants
|
||||
|
||||
To enforce that Pipelock is enabled whenever the external AI assistant feature is active:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
requireForExternalAssistant: true
|
||||
```
|
||||
|
||||
This causes `helm template` / `helm install` to fail if `rails.externalAssistant.enabled=true` and `pipelock.enabled=false`. Note: this only guards the `externalAssistant` path. Direct MCP access via `MCP_API_TOKEN` is configured through env vars and not detectable from Helm values.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Never commit secrets in `values.yaml`. Use `rails.existingSecret` or a tool like Sealed Secrets.
|
||||
@@ -660,6 +767,7 @@ See `values.yaml` for the complete configuration surface, including:
|
||||
- `migrations.*`: strategy job or initContainer
|
||||
- `simplefin.encryption.*`: enable + backfill options
|
||||
- `cronjobs.*`: custom CronJobs
|
||||
- `pipelock.*`: AI agent security proxy (forward proxy, MCP reverse proxy, DLP, injection scanning, logging, serviceMonitor, ingress, PDB, extraConfig)
|
||||
- `service.*`, `ingress.*`, `serviceMonitor.*`, `hpa.*`
|
||||
|
||||
## Helm tests
|
||||
|
||||
@@ -41,7 +41,40 @@ Troubleshooting
|
||||
- For CloudNativePG, verify the RW service exists and the primary is Ready.
|
||||
- For redis-operator, verify the RedisSentinel CR reports Ready and that the master service resolves.
|
||||
|
||||
{{- if .Values.pipelock.enabled }}
|
||||
|
||||
Pipelock (AI agent security proxy)
|
||||
-----------------------------------
|
||||
5) Verify pipelock is running:
|
||||
kubectl rollout status deploy/{{ include "sure.fullname" . }}-pipelock -n {{ .Release.Namespace }}
|
||||
kubectl logs deploy/{{ include "sure.fullname" . }}-pipelock -n {{ .Release.Namespace }} --tail=20
|
||||
|
||||
6) MCP access for external AI assistants:
|
||||
{{- if .Values.pipelock.ingress.enabled }}
|
||||
{{- range .Values.pipelock.ingress.hosts }}
|
||||
- Ingress: http{{ if $.Values.pipelock.ingress.tls }}s{{ end }}://{{ .host }}
|
||||
{{- end }}
|
||||
{{- else }}
|
||||
- No Ingress configured. Port-forward for local access:
|
||||
kubectl port-forward -n {{ .Release.Namespace }} svc/{{ include "sure.fullname" . }}-pipelock 8889:{{ .Values.pipelock.mcpProxy.port | default 8889 }}
|
||||
{{- end }}
|
||||
|
||||
Security: Enable TLS on the pipelock Ingress and ensure MCP_API_TOKEN is set.
|
||||
The MCP endpoint requires authentication but the Ingress does not add it.
|
||||
|
||||
7) Metrics:
|
||||
{{- if .Values.pipelock.serviceMonitor.enabled }}
|
||||
- ServiceMonitor enabled — Prometheus will scrape /metrics on port {{ .Values.pipelock.serviceMonitor.portName }}.
|
||||
{{- else }}
|
||||
- ServiceMonitor not enabled. Metrics are available at http://<pipelock-pod>:{{ .Values.pipelock.forwardProxy.port | default 8888 }}/metrics
|
||||
Enable with: pipelock.serviceMonitor.enabled=true
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
Security reminder
|
||||
-----------------
|
||||
- For production, prefer immutable image tags (for example, image.tag=v1.2.3) instead of 'latest'.
|
||||
- Provide secrets via an existing Kubernetes Secret or a secret manager (External Secrets, Sealed Secrets).
|
||||
{{- if .Values.pipelock.enabled }}
|
||||
- When exposing MCP to external AI assistants, always enable pipelock to scan inbound traffic.
|
||||
{{- end }}
|
||||
@@ -1,7 +0,0 @@
|
||||
{{/*
|
||||
Mutual exclusivity and configuration guards
|
||||
*/}}
|
||||
|
||||
{{- if and .Values.redisOperator.managed.enabled .Values.redisSimple.enabled -}}
|
||||
{{- fail "Invalid configuration: Both redisOperator.managed.enabled and redisSimple.enabled are true. Enable only one in-cluster Redis provider." -}}
|
||||
{{- end -}}
|
||||
23
charts/sure/templates/asserts.tpl
Normal file
23
charts/sure/templates/asserts.tpl
Normal file
@@ -0,0 +1,23 @@
|
||||
{{/*
|
||||
Mutual exclusivity and configuration guards
|
||||
*/}}
|
||||
|
||||
{{- if and .Values.redisOperator.managed.enabled .Values.redisSimple.enabled -}}
|
||||
{{- fail "Invalid configuration: Both redisOperator.managed.enabled and redisSimple.enabled are true. Enable only one in-cluster Redis provider." -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- $extEnabled := false -}}
|
||||
{{- if .Values.rails -}}{{- if .Values.rails.externalAssistant -}}{{- if .Values.rails.externalAssistant.enabled -}}
|
||||
{{- $extEnabled = true -}}
|
||||
{{- end -}}{{- end -}}{{- end -}}
|
||||
{{- $plEnabled := false -}}
|
||||
{{- if .Values.pipelock -}}{{- if .Values.pipelock.enabled -}}
|
||||
{{- $plEnabled = true -}}
|
||||
{{- end -}}{{- end -}}
|
||||
{{- $requirePL := false -}}
|
||||
{{- if .Values.pipelock -}}{{- if .Values.pipelock.requireForExternalAssistant -}}
|
||||
{{- $requirePL = true -}}
|
||||
{{- end -}}{{- end -}}
|
||||
{{- if and $extEnabled (not $plEnabled) $requirePL -}}
|
||||
{{- fail "pipelock.requireForExternalAssistant is true but pipelock.enabled is false. Enable pipelock (pipelock.enabled=true) when using rails.externalAssistant, or set pipelock.requireForExternalAssistant=false." -}}
|
||||
{{- end -}}
|
||||
@@ -64,6 +64,20 @@
|
||||
{{- $chainAction = .Values.pipelock.toolChainDetection.action | default "warn" -}}
|
||||
{{- $chainWindow = int (.Values.pipelock.toolChainDetection.windowSize | default 20) -}}
|
||||
{{- $chainGap = int (.Values.pipelock.toolChainDetection.maxGap | default 3) -}}
|
||||
{{- end -}}
|
||||
{{- $logFormat := "json" -}}
|
||||
{{- $logOutput := "stdout" -}}
|
||||
{{- $logIncludeAllowed := false -}}
|
||||
{{- $logIncludeBlocked := true -}}
|
||||
{{- if .Values.pipelock.logging -}}
|
||||
{{- $logFormat = .Values.pipelock.logging.format | default "json" -}}
|
||||
{{- $logOutput = .Values.pipelock.logging.output | default "stdout" -}}
|
||||
{{- if hasKey .Values.pipelock.logging "includeAllowed" -}}
|
||||
{{- $logIncludeAllowed = .Values.pipelock.logging.includeAllowed -}}
|
||||
{{- end -}}
|
||||
{{- if hasKey .Values.pipelock.logging "includeBlocked" -}}
|
||||
{{- $logIncludeBlocked = .Values.pipelock.logging.includeBlocked -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
@@ -116,4 +130,12 @@ data:
|
||||
action: {{ $chainAction }}
|
||||
window_size: {{ $chainWindow }}
|
||||
max_gap: {{ $chainGap }}
|
||||
logging:
|
||||
format: {{ $logFormat }}
|
||||
output: {{ $logOutput }}
|
||||
include_allowed: {{ $logIncludeAllowed }}
|
||||
include_blocked: {{ $logIncludeBlocked }}
|
||||
{{- if .Values.pipelock.extraConfig }}
|
||||
{{- toYaml .Values.pipelock.extraConfig | nindent 4 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
@@ -96,4 +96,6 @@ spec:
|
||||
{{- toYaml (.Values.pipelock.affinity | default dict) | nindent 8 }}
|
||||
tolerations:
|
||||
{{- toYaml (.Values.pipelock.tolerations | default list) | nindent 8 }}
|
||||
topologySpreadConstraints:
|
||||
{{- toYaml (.Values.pipelock.topologySpreadConstraints | default (list)) | nindent 8 }}
|
||||
{{- end }}
|
||||
|
||||
42
charts/sure/templates/pipelock-ingress.yaml
Normal file
42
charts/sure/templates/pipelock-ingress.yaml
Normal file
@@ -0,0 +1,42 @@
|
||||
{{- if and .Values.pipelock.enabled .Values.pipelock.ingress.enabled }}
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: {{ include "sure.fullname" . }}-pipelock
|
||||
labels:
|
||||
{{- include "sure.labels" . | nindent 4 }}
|
||||
{{- with .Values.pipelock.ingress.annotations }}
|
||||
annotations:
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
{{- if .Values.pipelock.ingress.className }}
|
||||
ingressClassName: {{ .Values.pipelock.ingress.className }}
|
||||
{{- end }}
|
||||
{{- if .Values.pipelock.ingress.hosts }}
|
||||
rules:
|
||||
{{- range .Values.pipelock.ingress.hosts }}
|
||||
{{- if not .paths }}
|
||||
{{- fail "each entry in pipelock.ingress.hosts must include at least one paths item" }}
|
||||
{{- end }}
|
||||
- host: {{ .host | quote }}
|
||||
http:
|
||||
paths:
|
||||
{{- range .paths }}
|
||||
- path: {{ .path }}
|
||||
pathType: {{ .pathType }}
|
||||
backend:
|
||||
service:
|
||||
name: {{ include "sure.fullname" $ }}-pipelock
|
||||
port:
|
||||
name: mcp
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- else }}
|
||||
{{- fail "pipelock.ingress.enabled=true requires at least one entry in pipelock.ingress.hosts" }}
|
||||
{{- end }}
|
||||
{{- if .Values.pipelock.ingress.tls }}
|
||||
tls:
|
||||
{{- toYaml .Values.pipelock.ingress.tls | nindent 4 }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
21
charts/sure/templates/pipelock-pdb.yaml
Normal file
21
charts/sure/templates/pipelock-pdb.yaml
Normal file
@@ -0,0 +1,21 @@
|
||||
{{- if and .Values.pipelock.enabled .Values.pipelock.pdb.enabled }}
|
||||
{{- if and .Values.pipelock.pdb.minAvailable .Values.pipelock.pdb.maxUnavailable }}
|
||||
{{- fail "pipelock.pdb: set either minAvailable or maxUnavailable, not both." -}}
|
||||
{{- end }}
|
||||
apiVersion: policy/v1
|
||||
kind: PodDisruptionBudget
|
||||
metadata:
|
||||
name: {{ include "sure.fullname" . }}-pipelock
|
||||
labels:
|
||||
{{- include "sure.labels" . | nindent 4 }}
|
||||
spec:
|
||||
{{- if .Values.pipelock.pdb.minAvailable }}
|
||||
minAvailable: {{ .Values.pipelock.pdb.minAvailable }}
|
||||
{{- else if .Values.pipelock.pdb.maxUnavailable }}
|
||||
maxUnavailable: {{ .Values.pipelock.pdb.maxUnavailable }}
|
||||
{{- end }}
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/component: pipelock
|
||||
{{- include "sure.selectorLabels" . | nindent 6 }}
|
||||
{{- end }}
|
||||
@@ -13,6 +13,7 @@ metadata:
|
||||
name: {{ include "sure.fullname" . }}-pipelock
|
||||
labels:
|
||||
{{- include "sure.labels" . | nindent 4 }}
|
||||
app.kubernetes.io/component: pipelock
|
||||
spec:
|
||||
type: {{ (.Values.pipelock.service).type | default "ClusterIP" }}
|
||||
selector:
|
||||
|
||||
21
charts/sure/templates/pipelock-servicemonitor.yaml
Normal file
21
charts/sure/templates/pipelock-servicemonitor.yaml
Normal file
@@ -0,0 +1,21 @@
|
||||
{{- if and .Values.pipelock.enabled .Values.pipelock.serviceMonitor.enabled }}
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: ServiceMonitor
|
||||
metadata:
|
||||
name: {{ include "sure.fullname" . }}-pipelock
|
||||
labels:
|
||||
{{- include "sure.labels" . | nindent 4 }}
|
||||
{{- with .Values.pipelock.serviceMonitor.additionalLabels }}
|
||||
{{- toYaml . | nindent 4 }}
|
||||
{{- end }}
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/component: pipelock
|
||||
{{- include "sure.selectorLabels" . | nindent 6 }}
|
||||
endpoints:
|
||||
- interval: {{ .Values.pipelock.serviceMonitor.interval }}
|
||||
scrapeTimeout: {{ .Values.pipelock.serviceMonitor.scrapeTimeout }}
|
||||
path: {{ .Values.pipelock.serviceMonitor.path }}
|
||||
port: {{ .Values.pipelock.serviceMonitor.portName }}
|
||||
{{- end }}
|
||||
@@ -488,7 +488,7 @@ pipelock:
|
||||
enabled: false
|
||||
image:
|
||||
repository: ghcr.io/luckypipewrench/pipelock
|
||||
tag: "0.3.1"
|
||||
tag: "0.3.2"
|
||||
pullPolicy: IfNotPresent
|
||||
imagePullSecrets: []
|
||||
replicas: 1
|
||||
@@ -541,3 +541,52 @@ pipelock:
|
||||
nodeSelector: {}
|
||||
tolerations: []
|
||||
affinity: {}
|
||||
topologySpreadConstraints: []
|
||||
|
||||
# Prometheus Operator ServiceMonitor for /metrics on the proxy port
|
||||
serviceMonitor:
|
||||
enabled: false
|
||||
interval: 30s
|
||||
scrapeTimeout: 10s
|
||||
path: /metrics
|
||||
portName: proxy # matches Service port name "proxy" (8888)
|
||||
additionalLabels: {}
|
||||
|
||||
# Ingress for MCP reverse proxy (port 8889) — external AI assistants need this in k8s
|
||||
ingress:
|
||||
enabled: false
|
||||
className: ""
|
||||
annotations: {}
|
||||
hosts:
|
||||
- host: pipelock.local
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
tls: []
|
||||
|
||||
# PodDisruptionBudget — protects pipelock during node drains.
|
||||
# WARNING: minAvailable with replicas=1 blocks eviction entirely.
|
||||
# Use maxUnavailable: 1 for single-replica deployments, or increase replicas.
|
||||
pdb:
|
||||
enabled: false
|
||||
minAvailable: "" # set to 1 when replicas > 1
|
||||
maxUnavailable: 1 # safe default: allows 1 pod to be evicted
|
||||
|
||||
# Structured logging for k8s log aggregation
|
||||
logging:
|
||||
format: json
|
||||
output: stdout
|
||||
includeAllowed: false
|
||||
includeBlocked: true
|
||||
|
||||
# Escape hatch: ADDITIONAL config sections appended to pipelock.yaml.
|
||||
# Use for sections not covered by structured values above (session_profiling,
|
||||
# data_budget, adaptive_enforcement, kill_switch, internal CIDRs, etc.)
|
||||
# Do NOT duplicate keys already rendered above — behavior is parser-dependent.
|
||||
extraConfig: {}
|
||||
|
||||
# Hard-fail helm template when externalAssistant is enabled without pipelock.
|
||||
# NOTE: This only guards the rails.externalAssistant path. Direct MCP access
|
||||
# (/mcp endpoint with MCP_API_TOKEN) is not detectable from Helm values.
|
||||
# For full coverage, also ensure pipelock is enabled whenever MCP_API_TOKEN is set.
|
||||
requireForExternalAssistant: false
|
||||
|
||||
@@ -152,6 +152,62 @@ Your app is now set up. You can visit it at `http://localhost:3000` in your brow
|
||||
|
||||
If you find bugs or have a feature request, be sure to read through our [contributing guide here](https://github.com/we-promise/sure/wiki/How-to-Contribute-Effectively-to-Sure).
|
||||
|
||||
## AI features, external assistant, and Pipelock
|
||||
|
||||
Sure ships with a separate compose file for AI-related features: `compose.example.ai.yml`. It adds:
|
||||
|
||||
- **Pipelock** (always on): AI agent security proxy that scans outbound LLM calls and inbound MCP traffic
|
||||
- **Ollama + Open WebUI** (optional `--profile ai`): local LLM inference
|
||||
|
||||
### Using the AI compose file
|
||||
|
||||
```bash
|
||||
# Download both compose files
|
||||
curl -o compose.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.yml
|
||||
curl -o compose.ai.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.ai.yml
|
||||
curl -o pipelock.example.yaml https://raw.githubusercontent.com/we-promise/sure/main/pipelock.example.yaml
|
||||
|
||||
# Run with Pipelock (no local LLM)
|
||||
docker compose -f compose.ai.yml up -d
|
||||
|
||||
# Run with Pipelock + Ollama
|
||||
docker compose -f compose.ai.yml --profile ai up -d
|
||||
```
|
||||
|
||||
### Setting up the external AI assistant
|
||||
|
||||
The external assistant delegates chat to a remote AI agent instead of calling LLMs directly. The agent calls back to Sure's `/mcp` endpoint for financial data (accounts, transactions, balance sheet).
|
||||
|
||||
1. Set the MCP endpoint credentials in your `.env`:
|
||||
```bash
|
||||
MCP_API_TOKEN=generate-a-random-token-here
|
||||
MCP_USER_EMAIL=your@email.com # must match an existing Sure user
|
||||
```
|
||||
|
||||
2. Set the external assistant connection:
|
||||
```bash
|
||||
EXTERNAL_ASSISTANT_URL=https://your-agent/v1/chat/completions
|
||||
EXTERNAL_ASSISTANT_TOKEN=your-agent-api-token
|
||||
```
|
||||
|
||||
3. Choose how to activate:
|
||||
- **Per-family (UI):** Go to Settings > Self-Hosting > AI Assistant, select "External"
|
||||
- **Global (env):** Set `ASSISTANT_TYPE=external` to force all families to use external
|
||||
|
||||
See [docs/hosting/ai.md](ai.md) for full configuration details including agent ID, session keys, and email allowlisting.
|
||||
|
||||
### Pipelock security proxy
|
||||
|
||||
Pipelock sits between Sure and external services, scanning AI traffic for:
|
||||
|
||||
- **Secret exfiltration** (DLP): catches API keys, tokens, or personal data leaking in prompts
|
||||
- **Prompt injection**: detects attempts to override system instructions
|
||||
- **Tool poisoning**: validates MCP tool calls against known-safe patterns
|
||||
|
||||
When using `compose.example.ai.yml`, Pipelock is always running. External AI agents should connect to port 8889 (MCP reverse proxy) instead of directly to Sure's `/mcp` on port 3000.
|
||||
|
||||
For full Pipelock configuration, see [docs/hosting/pipelock.md](pipelock.md).
|
||||
|
||||
## How to update your app
|
||||
|
||||
The mechanism that updates your self-hosted Sure app is the GHCR (Github Container Registry) Docker image that you see in the `compose.yml` file:
|
||||
|
||||
219
docs/hosting/pipelock.md
Normal file
219
docs/hosting/pipelock.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Pipelock: AI Agent Security Proxy
|
||||
|
||||
[Pipelock](https://github.com/luckyPipewrench/pipelock) is an optional security proxy that scans AI agent traffic flowing through Sure. It protects against secret exfiltration, prompt injection, and tool poisoning.
|
||||
|
||||
## What Pipelock does
|
||||
|
||||
Pipelock runs as a separate proxy service alongside Sure with two listeners:
|
||||
|
||||
| Listener | Port | Direction | What it scans |
|
||||
|----------|------|-----------|---------------|
|
||||
| Forward proxy | 8888 | Outbound (Sure to LLM) | DLP (secrets in prompts), response injection |
|
||||
| MCP reverse proxy | 8889 | Inbound (agent to Sure /mcp) | Prompt injection, tool poisoning, DLP |
|
||||
|
||||
### Forward proxy (outbound)
|
||||
|
||||
When `HTTPS_PROXY=http://pipelock:8888` is set, outbound HTTPS requests from Faraday-based clients (like `ruby-openai`) are routed through Pipelock. It scans request bodies for leaked secrets and response bodies for prompt injection.
|
||||
|
||||
**Covered:** OpenAI API calls via ruby-openai (uses Faraday).
|
||||
**Not covered:** SimpleFIN, Coinbase, Plaid, or anything using Net::HTTP/HTTParty directly. These bypass `HTTPS_PROXY`.
|
||||
|
||||
### MCP reverse proxy (inbound)
|
||||
|
||||
External AI assistants that call Sure's `/mcp` endpoint should connect through Pipelock on port 8889 instead of directly to port 3000. Pipelock scans:
|
||||
|
||||
- Tool call arguments (DLP, shell obfuscation detection)
|
||||
- Tool responses (injection payloads)
|
||||
- Session binding (detects tool inventory manipulation)
|
||||
- Tool call chains (multi-step attack patterns like recon then exfil)
|
||||
|
||||
## Docker Compose setup
|
||||
|
||||
The `compose.example.ai.yml` file includes Pipelock. To use it:
|
||||
|
||||
1. Download the compose file and Pipelock config:
|
||||
```bash
|
||||
curl -o compose.ai.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.ai.yml
|
||||
curl -o pipelock.example.yaml https://raw.githubusercontent.com/we-promise/sure/main/pipelock.example.yaml
|
||||
```
|
||||
|
||||
2. Start the stack:
|
||||
```bash
|
||||
docker compose -f compose.ai.yml up -d
|
||||
```
|
||||
|
||||
3. Verify Pipelock is healthy:
|
||||
```bash
|
||||
docker compose -f compose.ai.yml ps pipelock
|
||||
# Should show "healthy"
|
||||
```
|
||||
|
||||
### Connecting external AI agents
|
||||
|
||||
External agents should use the MCP reverse proxy port:
|
||||
|
||||
```text
|
||||
http://your-server:8889
|
||||
```
|
||||
|
||||
The agent must include the `MCP_API_TOKEN` as a Bearer token in requests. Set this in your `.env`:
|
||||
|
||||
```bash
|
||||
MCP_API_TOKEN=generate-a-random-token
|
||||
MCP_USER_EMAIL=your@email.com
|
||||
```
|
||||
|
||||
### Running without Pipelock
|
||||
|
||||
To use `compose.example.ai.yml` without Pipelock, remove the `pipelock` service and its `depends_on` entries from `web` and `worker`, then unset the proxy env vars (`HTTPS_PROXY`, `HTTP_PROXY`).
|
||||
|
||||
Or use the standard `compose.example.yml` which does not include Pipelock.
|
||||
|
||||
## Helm (Kubernetes) setup
|
||||
|
||||
Enable Pipelock in your Helm values:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
enabled: true
|
||||
image:
|
||||
tag: "0.3.2"
|
||||
mode: balanced
|
||||
```
|
||||
|
||||
This creates a separate Deployment, Service, and ConfigMap. The chart auto-injects `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` into web and worker pods.
|
||||
|
||||
### Exposing MCP to external agents (Kubernetes)
|
||||
|
||||
In Kubernetes, external agents cannot reach the MCP port by default. Enable the Pipelock Ingress:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
enabled: true
|
||||
ingress:
|
||||
enabled: true
|
||||
className: nginx
|
||||
hosts:
|
||||
- host: pipelock.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
tls:
|
||||
- hosts: [pipelock.example.com]
|
||||
secretName: pipelock-tls
|
||||
```
|
||||
|
||||
Or port-forward for testing:
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/sure-pipelock 8889:8889 -n sure
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
Enable the ServiceMonitor for Prometheus scraping:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
serviceMonitor:
|
||||
enabled: true
|
||||
interval: 30s
|
||||
additionalLabels:
|
||||
release: prometheus
|
||||
```
|
||||
|
||||
Metrics are available at `/metrics` on the forward proxy port (8888).
|
||||
|
||||
### Eviction protection
|
||||
|
||||
For production, enable the PodDisruptionBudget:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
pdb:
|
||||
enabled: true
|
||||
maxUnavailable: 1
|
||||
```
|
||||
|
||||
See the [Helm chart README](../../charts/sure/README.md#pipelock-ai-agent-security-proxy) for all configuration options.
|
||||
|
||||
## Pipelock configuration file
|
||||
|
||||
The `pipelock.example.yaml` file (Docker Compose) or ConfigMap (Helm) controls scanning behavior. Key sections:
|
||||
|
||||
| Section | What it controls |
|
||||
|---------|-----------------|
|
||||
| `mode` | `strict` (block threats), `balanced` (warn + block critical), `audit` (log only) |
|
||||
| `forward_proxy` | Outbound HTTPS scanning (tunnel timeouts, idle timeouts) |
|
||||
| `dlp` | Data loss prevention (scan env vars, built-in patterns) |
|
||||
| `response_scanning` | Scan LLM responses for prompt injection |
|
||||
| `mcp_input_scanning` | Scan inbound MCP requests |
|
||||
| `mcp_tool_scanning` | Validate tool calls, detect drift |
|
||||
| `mcp_tool_policy` | Pre-execution rules (shell obfuscation, etc.) |
|
||||
| `mcp_session_binding` | Pin tool inventory, detect manipulation |
|
||||
| `tool_chain_detection` | Multi-step attack patterns |
|
||||
| `websocket_proxy` | WebSocket frame scanning (disabled by default) |
|
||||
| `logging` | Output format (json/text), verbosity |
|
||||
|
||||
For the Helm chart, most sections are configurable via `values.yaml`. For additional sections not covered by structured values (session profiling, data budgets, kill switch), use the `extraConfig` escape hatch:
|
||||
|
||||
```yaml
|
||||
pipelock:
|
||||
extraConfig:
|
||||
session_profiling:
|
||||
enabled: true
|
||||
max_sessions: 1000
|
||||
```
|
||||
|
||||
## Modes
|
||||
|
||||
| Mode | Behavior | Use case |
|
||||
|------|----------|----------|
|
||||
| `strict` | Block all detected threats | Production with sensitive data |
|
||||
| `balanced` | Warn on low-severity, block on high-severity | Default; good for most deployments |
|
||||
| `audit` | Log everything, block nothing | Initial rollout, testing |
|
||||
|
||||
Start with `audit` mode to see what Pipelock detects without blocking anything. Review the logs, then switch to `balanced` or `strict`.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Forward proxy only covers Faraday-based HTTP clients. Net::HTTP, HTTParty, and other libraries ignore `HTTPS_PROXY`.
|
||||
- Docker Compose has no egress network policies. The `/mcp` endpoint on port 3000 is still reachable directly (auth token required). For enforcement, use Kubernetes NetworkPolicies.
|
||||
- Pipelock scans text content. Binary payloads (images, file uploads) are passed through by default.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pipelock container not starting
|
||||
|
||||
Check the config file is mounted correctly:
|
||||
```bash
|
||||
docker compose -f compose.ai.yml logs pipelock
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- Missing `pipelock.example.yaml` file
|
||||
- YAML syntax errors in config
|
||||
- Port conflicts (8888 or 8889 already in use)
|
||||
|
||||
### LLM calls failing with proxy errors
|
||||
|
||||
If AI chat stops working after enabling Pipelock:
|
||||
```bash
|
||||
# Check Pipelock logs for blocked requests
|
||||
docker compose -f compose.ai.yml logs pipelock --tail=50
|
||||
```
|
||||
|
||||
If requests are being incorrectly blocked, switch to `audit` mode in the config file and restart:
|
||||
```yaml
|
||||
mode: audit
|
||||
```
|
||||
|
||||
### MCP requests not reaching Sure
|
||||
|
||||
Verify the MCP upstream is configured correctly:
|
||||
```bash
|
||||
# Test from inside the Pipelock container
|
||||
docker compose -f compose.ai.yml exec pipelock /pipelock healthcheck --addr 127.0.0.1:8888
|
||||
```
|
||||
|
||||
Check that `MCP_API_TOKEN` and `MCP_USER_EMAIL` are set in your `.env` file and that the email matches an existing Sure user.
|
||||
Reference in New Issue
Block a user