The Guardrails Service is an optional Python microservice that provides ML-powered security scanning. When deployed alongside Declaw, it replaces the built-in regex scanners with production-grade models:
- PII detection: Microsoft Presidio with Named Entity Recognition (NER) for unstructured PII (person names, locations, passport numbers, driver’s licenses)
- Prompt injection detection: an ML classifier plus an LLM judge that score content for injection likelihood
If the Guardrails Service is unreachable, the security proxy automatically falls back to the built-in regex scanners. No configuration change is required for this fallback.
Architecture
The security proxy sends scan requests to the Guardrails Service HTTP API at GUARDRAILS_URL/api/v1/scan. The service runs scanners in parallel and returns results within the 10-second proxy timeout.
Deploy on GCP
This provisions a GCP VM with the Guardrails Service installed and started via systemd. The service listens on port 8000.
Connect to Declaw
Set the GUARDRAILS_URL environment variable before running the Declaw deploy script, and it will be detected automatically:
Or set it manually on the Declaw VM after deployment:
Manual connection
In the SDK, set GUARDRAILS_URL in the environment before creating sandboxes:
The orchestrator reads GUARDRAILS_URL at startup and passes it to each sandbox’s security proxy.
Guardrails Service API
The service exposes one scan endpoint and a health check:
Response:
Each scanner entry may include per-request overrides (e.g. "pii_scanner": { "confidence_threshold": 0.8, "entities": ["EMAIL_ADDRESS"] }) alongside scanner_type.
Supported scanners
Invisible text scanner
The Guardrails Service includes a scanner that detects invisible Unicode characters used in prompt injection attacks:
These characters can be embedded in text that appears clean to the human eye but contains hidden instructions to the LLM.
Model loading and caching
Models are downloaded once at service startup and cached on disk. The orchestrator is designed to load models in a non-blocking background thread so the service accepts requests before all models are ready, with a degraded mode that skips unavailable scanners.
Model files are stored at /opt/guardrails/models/ on the service VM.
Local development
Run the Guardrails Service locally with Docker:
Or with the provided Docker Compose configuration:
Then point Declaw at it:
Fallback behavior
If GUARDRAILS_URL is set but the service is unreachable:
- The security proxy logs a warning
- PII detection falls back to the built-in regex scanner (SSN, credit card, email, phone patterns)
- Injection detection falls back to the built-in pattern library
- No error is surfaced to the agent workload
The fallback is automatic and requires no code changes. The proxy checks liveness on each scan request with a 10-second timeout.
The built-in regex fallback does not support unstructured PII types like person_name. If your security policy depends on NER-based detection, monitor the Guardrails Service availability and alert on fallback events in the audit log.
