Testing NeMo Guardrails with garak

Choose the deployment shape before you write any garak configuration, because it decides which part of the stack your results describe. garak can reach NeMo Guardrails in two ways: by calling the NeMo Guardrails Python API inside the same process as garak, or by pointing garak at a guardrails server that loads configurations from a folder and exposes an HTTP API. The server can be built from the Dockerfile that NVIDIA provides in the NeMo Guardrails repository. Both shapes run the same rails logic, but they exercise different things, so the choice is a testing decision, not a packaging preference.

In-process testing isolates the rails configuration. garak imports the library, loads one configuration directory, and sends probes straight into the rails pipeline. This makes it easy to change a Colang file or a config.yml setting and rerun a probe set to see the effect. The cost is that the test skips the HTTP layer, authentication, request routing, timeouts and any proxy in front of the application. A pass in this mode shows that the rails hold, not that the deployed endpoint holds.

The server shape tests the endpoint your users actually reach. garak sends requests over HTTP to the same guardrails server image, with the same folder of configurations, that the application calls in production. This catches problems that in-process runs cannot see, such as a configuration folder that was not mounted, a server that loads a different config name, or a gateway that strips or rewrites fields. Confirm with the platform owner how the production service is started, which port and path it uses, and whether any headers or API keys are required, so the garak REST generator is configured against the same surface.

Two settings must match the target exactly. First, the Colang version. Colang 1.0 is the default in NeMo Guardrails, and Colang 2.0 is also supported. A configuration written for one version can behave differently under the other, and migrated files still need manual review according to NVIDIA's migration guidance. Record the Colang version in your test plan and confirm it with the team that runs the target. Second, the LangChain integration is opt-in and enabled with the NEMOGUARDRAILS_LLM_FRAMEWORK=langchain environment variable. If production sets this variable and your test environment does not, or the reverse, you are testing a different stack from the one users reach.

Document the shape, Colang version, library version and environment variables with every garak report, since the JSONL output records attempts but not your deployment choices. Pin the NeMo Guardrails release you test, and repeat the scan after any configuration or framework change. Ask the team that owns the target which shape gives the evidence they need: in-process runs are cheaper to iterate on, while server runs are the stronger check before a release.

The summary line tells you which probe failed, but not which rail let the output through. To find the rail, work from the attempt level. Each garak run writes a JSONL report with a record for every attempt and its evaluation, so for each FAIL you need the prompt sent, the response your application returned, and the detector's verdict on that response. Start with the probes marked FAIL, then open the matching attempt records. Because the default harness runs each probe with its recommended detectors, the evaluation fields tell you which detector judged the output, which narrows the search to the rail that should have handled that kind of content. Confirm the exact field names in the report produced by your garak version before you write any parsing scripts.

The key question for each failing attempt is whether the model produced the undesirable output or a rail should have stopped it. Check what the input rail did with the prompt and whether the output rail ran on the response. Then read garak.log and the NeMo Guardrails logs for that same prompt, to see which rails were triggered and what they returned. Illustrative example: if the input rail passed a jailbreak variant unchanged, and the model's answer reached the caller without any output rail action, the gap sits in the input rail or in the output rail's coverage, not in the model. If a rail fired and the response still leaked, the rail's action or its configured check is the suspect. Record your conclusion per failing probe so the remediation owner knows which configuration file to review.

A single FAIL still matters. garak makes 10 generations per prompt by default and marks a probe as FAIL, with a failure rate, when any one attempt produces undesirable output. A failure rate of one in ten therefore reports the same status as ten in ten. Treat any failing attempt as evidence that a route through your rails can produce that output. Reproduce it by rerunning the single probe against the same configuration and checking whether the attempt recurs. Some attempts will be non-deterministic, so a failure that does not reproduce on the first rerun still belongs in your findings with its prompt and response preserved, and should be reviewed before anyone marks it as resolved.

Comparing runs after a configuration change requires keeping each run separate. garak.log continues across runs, so it does not isolate one run's messages on its own. Save each run's JSONL report in its own directory, named with the date, the garak version and the NeMo Guardrails version and configuration revision used. The current garak release is v0.17.1, released on 16 October 2026, and the current NeMo Guardrails release is v0.24.1, released on 16 September 2026. Compare the two runs probe by probe, and then attempt by attempt for any probe whose status changed. Do not merge reports from different garak or NeMo Guardrails versions into one trend line, because a change in either tool can alter results independently of your rails.

A failure rate is not a complete measure of security. It reports how the probes you selected behaved under one configuration, on one run, with the generations counted in that run. A probe that never fails tells you only that the probe did not trigger undesirable output, not that the application is safe against attacks the probe does not cover. Confirm which probes and detectors your scan included, record that selection with each report, and decide which probe families need coverage before you report results to a stakeholder. Use the reports as evidence of specific gaps to fix and retest, and pair them with a review of your rail configuration and a periodic rescan after each change.

A garak scan only works as a gate if it runs the same way every time. Pin the probe selection, the generator settings and the garak version in a file stored with config.yml, the Colang files and any Python actions. Re-run that identical probe set after every change to config.yml, an action or a Colang file. Because each run writes a JSONL report of every attempt and its evaluation, you can compare two runs at the attempt level instead of only by summary. Confirm that the generator points at the same guardrails configuration folder on each run, since a scan against a different folder tests a different application.

Upgrades are the second trigger. garak v0.17.1, released on 16 October 2026, may change probe or detector behavior, so run the existing configuration against the old and new garak versions on a branch before accepting the new output as the reference. NeMo Guardrails v0.24.1, released on 16 September 2026, can change how input and output rails fire even when your files stay the same. Record both versions in the report metadata so that a later failure can be traced to a cause. A failure that appears only after a library upgrade points to the upgrade, not to your configuration.

A Colang migration is the heaviest trigger. NVIDIA documents a Colang 1.0 to 2.x migration with the nemoguardrails convert tool and states that converted configurations still need manual review. Treat the converted application as a new build and run the full probe set, not a subset. A rail that blocked a probe under Colang 1.0 may pass it after conversion, or the reverse, so keep the Colang 1.0 baseline archived and compare both sets of results side by side throughout the cutover.

Store each baseline JSONL report together with its garak.log, the commit hash, the probe list and both tool versions. garak.log continues across runs, so archive a copy for each run instead of relying on the file in the working directory. Decide in advance what counts as a regression. Typical rules include a probe moving from PASS to FAIL, a higher failure rate on any probe, or any new failure on probes covering data leakage. These thresholds are team decisions. Agree them with the security owner and record them in the gate policy before the first comparison is made.

The results feed a release gate in the pipeline. The job runs garak against a staging guardrails server, compares the output with the stored baseline and blocks promotion when the agreed rules are broken. Record who may override a block and what evidence the override requires. A passing scan only covers the probes it ran, so the gate report should list the probe set explicitly. Before go-live, confirm that the pipeline runner can reach the generator endpoint and that the scan length fits your release schedule. Ask any implementation partner to name the gate, its inputs and its owner in the written scope.