NVIDIA-NeMo / NVIDIA-NeMo/Guardrails

feature: add a NeuralTrust TrustGuard guardrail to the library catalog

Open
#2,347 1 comment 13 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement status: needs triage
Dominant language
Python
Stars
7.2k
Forks
842
Avg merge
3d 1h
Merged PRs (30d)
25

Description

Did you check the docs?
  • I have read all the NeMo-Guardrails docs
Is your feature request related to a problem? Please describe.

The library catalog covers most commercial guardrail vendors — prompt_security, ai_defense, crowdstrike_aidr, patronusai, guardrails_ai, pangea, f5, clavata, trend_micro and others — but there is no rail for NeuralTrust TrustGuard, so its users have to hand-roll a custom action.

That is more error-prone than it sounds, because TrustGuard always answers HTTP 200 and returns a verdict the caller has to enforce. Every user reimplements the same security-sensitive decisions, and the failure modes are quiet ones:

  • Mapping five verdicts (allow / report / transform / ask / block) onto three RailDecision values, including what to do with a verdict Colang has no equivalent for.
  • Scoping fail-open. The obvious implementation fails open on any non-2xx, which silently disables the guardrail when a key is revoked.
  • The transform write-back. A masking verdict returns rewritten text, and getting this wrong forwards exactly the content the policy was meant to remove.

Each of those is easy to get subtly wrong in a way that still looks like it works.

Describe the solution you'd like

A vendor rail at nemoguardrails/library/neuraltrust/, following the existing catalog conventions.

  • Two surfaces, input and output, both declaring transform_target, so a masking policy rewrites the checked message.
  • Verdict mapping: allow and report pass through; transform returns RailOutcome.transform; block and ask both refuse. Colang has no interactive verdict, so ask collapses to a block, which matches TrustGuard's own reduction order.
  • Fail-open scoped to unreachability only: timeout, transport error, 502/504, and a 429 that survives every retry. Authentication failures, 503, TLS failures, unusable transform payloads and unrecognised verdicts always fail closed.
  • A transform whose payload cannot be applied fails closed rather than forwarding the original text.
  • All HTTP through nemoguardrails.http with a declared RetryPolicy, so no new dependency is added. Credentials read from the environment only, never as config fields.
  • Both Colang dialects, unit coverage across every verdict and HTTP failure class, a recorded end-to-end suite, a catalog docs page and example configs.

I have a working implementation on a local branch, feat/neuraltrust-trustguard-rail, modelled on library/crowdstrike_aidr and library/f5, with the repo's validation loop green. Sharing the branch name here per the guidance on work in progress rather than opening a premature PR, happy to open one once this is triaged and assigned.

Describe alternatives you've considered
  1. A docs-only community page, like the Presidio or Fiddler entries. Rejected: it ships no code, so every user still reimplements the verdict mapping and the fail-open scoping themselves, which is where the security-relevant mistakes are.

  2. A third-party pip package providing the rail out of tree. Rejected because it would not be discoverable: RailCatalog.discover_built_ins() rglobs rail.py under nemoguardrails/library with no entry-point hook, and PR #2187 (plugin loading) was closed unmerged, so there is no supported out-of-tree path today.

Additional context

I work on TrustGuard @ Neuraltrust. Prior art against the same POST /v1/evaluate contract, in case it is useful for review: langchain-neuraltrust and trustguard-sdk on PyPI, an n8n community node, and an open native guardrail for LiteLLM (BerriAI/litellm#37165). The rail proposed here follows the same verdict semantics.

One practical note: I have access to a production TrustGuard workspace, so the recorded cassettes are recorded against the real service rather than hand-authored — a benign allow, a jailbreak block, a masking transform on each direction, and a genuine 401 from an invalidated key. They replay under --block-network with no credentials, with the API key, the collector key and tenant-scoped identifiers scrubbed on write.

Known limitation, stated up front: a transform verdict is not applied on the LLMRails streaming path, since that loop checks only whether the outcome is blocked. That is existing shared behaviour affecting the other transform-capable rails too, so the docs page states it with the causing code path rather than working around it.

@Pouyanpi — flagging you as the reviewer on recent library/ contributions, in case this is one to route.

AI assistance: this issue text was drafted with Claude Code and reviewed and edited by me before submitting, per AI_POLICY.md.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the existing patterns in library/crowdstrike_aidr and library/f5, then inspect RailCatalog.discover_built_ins() and the nemoguardrails.http retry support. The proposed work spans the neuraltrust rail, both Colang dialects, unit and recorded end-to-end tests, catalog documentation, and example configs; completion requires the listed verdict and HTTP failure cases to be covered while preserving the documented streaming limitation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design, documentation, security, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.