Plugin Security
GuardRails guards are security infrastructure. An untrusted guard plugin could bypass protections, exfiltrate data, or create false negatives. The plugin security model enforces that only reviewed, signed assemblies can be loaded.
context.Input, context.Output, context.Metadata, TenantId, UserId, and all node data. Never load unsigned or unreviewed guard assemblies.
Plugin Security Components
| Component | File | Responsibility |
|---|---|---|
IPluginSignatureValidator |
Registry/PluginSignatureValidator.cs |
Verifies the assembly's cryptographic signature against trusted publisher certificates. Unsigned assemblies are rejected before any code loads. |
IPluginCodeReviewMetadata |
Registry/PluginCodeReviewMetadata.cs |
Attaches code review evidence to loaded plugins. Guards the review requirement gate — plugins without review metadata are flagged in health checks. |
IGuardPluginLoader |
Registry/GuardPluginLoader.cs |
Orchestrates the full load sequence: discover → verify signature → verify review → register. Any step failure rejects the plugin. |
Plugin Load Sequence
Discover plugin assemblies
GuardPluginLoader scans configured plugin directories for DLLs matching the guard assembly naming convention.
Verify signature
IPluginSignatureValidator checks the assembly's strong-name signature against trusted publisher keys. Any unsigned or tampered assembly fails here — no code from that DLL executes.
Check code review metadata
IPluginCodeReviewMetadata looks up the assembly in the review registry. Plugins without a review record are rejected or flagged with a warning in the health endpoint.
Register in GuardRegistry
The verified plugin is registered as a GuardDefinition in GuardRegistry. It becomes available for configuration by name in node guard configs.
Fail-Secure at the Plugin Level
The plugin loader fails closed. If a signature check fails, the plugin is rejected. If the review metadata is missing, behavior depends on configuration:
- Strict mode: Missing review metadata → plugin rejected. Deployment fails safe.
- Permissive mode: Missing review metadata → plugin loaded with a warning in the health endpoint. Suitable for internal development environments.
Transient Failure Protection
The ITransientFailureWindow service (50 transient failures per 60-second window) prevents a flaky guard from being excluded by the circuit breaker due to temporary network issues. Transient failures (timeouts, temporary unavailability) reset the failure counter rather than accumulating toward the circuit open threshold.
Security Principles
| Principle | How GuardRails Enforces It |
|---|---|
| Defense in Depth | Multiple independent guards cover the same concern (e.g., PiiDetection in Pre + PiiRedaction in Post) |
| Fail-Secure | IsSecurityCritical=true guards block when their own circuit is open |
| Zero Trust | Every node execution runs the full guard pipeline regardless of caller identity |
| Supply Chain Protection | Plugin signature validation prevents tampered guard code from being loaded |
| Least Privilege | Guards receive only the execution context — they cannot call internal platform APIs unless injected via DI |