bump to 0.20.3

Author: dmulyalin

docs/development/adr_fastmcp_task_call_guardrails.md

@@ -4,12 +4,18 @@
 
 1. Fixing nornir tests nfcli shell to pass verbose_on_fail to results processing, to make sure return results as table even when have failed tests.
 
+## FEATURES
+
+1. Added FastMCP tool call guardrails to reject unsafe MCP tool calls before NorFab job dispatch. Guardrails can be defined by tasks or FastMCP inventory, support `regex`, `contains`, and `equals` checks, can disable built-in task guardrails with `tools.disable_builtin_guardrails`, and are visible through `show fastmcp tools`.
+
 ## ENHANCEMENTS
 
 1. Extended Nornir worker statistics with SID, NetBox, Containerlab inventory load statuses and managed `nornir_hosts` count.
 2. Enhanced NetBox worker REST filtering to route task-side `pynetbox.filter()` calls through adaptive `bulk_filter`, automatically chunking long list filters to avoid URI length errors while preserving query options such as `fields`, `limit`, and `ordering`.
 3. Improved result status coloring for nornir test task
 4. Nornir show hosts table added index column
+5. Enhanced Nornir `cli` task MCP metadata with default guardrails that block reboot, reload, restart, configuration-mode, shell-mode, OS/image/package operations, outbound `ssh`/`telnet`, commit, delete, clear, debug, reset, zeroize, and related state-changing commands when called through FastMCP.
+6. Enhanced Nornir `cfg` task MCP metadata with default guardrails that block reboot, reload, restart, `do ...` and `run ...` operational escapes, delete, erase, zeroize, and outbound `ssh`/`telnet` commands when called through FastMCP.
 
 ## CHANGES
 

docs/norfab_changelog.md

@@ -217,3 +217,111 @@ tools:
     Task names can be inspected at runtime with the `show fastmcp tools` CLI
     command or the `get_tools` API call. Published prompts can be inspected
     with `show fastmcp prompts` or `get_prompts`.
+
+---
+
+## Tool Call Guardrails
+
+FastMCP guardrails reject specific MCP tool calls by inspecting the call
+arguments before the NorFab job is dispatched. They are useful for allowing a
+flexible task such as `nornir.cli` while blocking unsafe command values.
+
+Guardrails do not replace `tools.policy`. Policy decides whether a task is
+published and callable. Guardrails decide whether one specific call to an
+allowed task is acceptable.
+
+Task authors can define default guardrails in task MCP metadata. FastMCP
+inventory can add deployment-specific guardrails under `tools.guardrails`.
+Built-in task guardrails are enabled by default.
+
+```yaml
+tools:
+  guardrails:
+    - service: nornir
+      task: cli
+      description: Reject commit confirmed commands through MCP.
+      field: commands
+      type: contains
+      match: commit confirmed
+      message: "MCP guardrail rejected a commit confirmed command."
+```
+
+`tools.guardrails` is a list of guardrail entries.
+
+Set `tools.disable_builtin_guardrails: true` to ignore guardrails declared by
+tasks. Inventory-defined guardrails still apply:
+
+```yaml
+tools:
+  disable_builtin_guardrails: true
+  guardrails:
+    - service: nornir
+      task: cli
+      field: commands
+      type: regex
+      match: "(?i)^\\s*reload\\b.*"
+      message: "MCP guardrail rejected a reload command."
+```
+
+Inventory options:
+
+| Key | Type | Description |
+|---|---|---|
+| `disable_builtin_guardrails` | boolean | Optional flag under `tools`; defaults to `false` |
+
+Guardrail entry keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `service` | string | Exact NorFab service name, for example `nornir` |
+| `task` | string | Exact NorFab task name, for example `cli` |
+| `description` | string | Optional human-readable explanation for operators |
+| `field` | string | Top-level tool argument field to inspect |
+| `type` | `contains` / `equals` / `regex` | Match strategy |
+| `match` | string or list of strings | Text value or regex value to match |
+| `message` | string | Optional client-facing rejection message |
+
+When `match` is a list, FastMCP rejects the call if any selected argument
+value matches any configured match value. `contains` and `equals` checks are
+always case-insensitive; regex checks use the flags declared in the regex
+value.
+
+!!! warning
+    Guardrails inspect only the inline MCP call arguments. They do not
+    download NorFab URLs or inspect content resolved later by service workers,
+    such as `nf://cli/commands.txt` files rendered by the Nornir worker at
+    runtime.
+
+Use NFCLI to inspect effective guardrails for a published task:
+
+```bash
+show fastmcp tools service nornir name *cli*
+```
+
+Example with several regex values:
+
+```yaml
+tools:
+  guardrails:
+    - service: nornir
+      task: cli
+      description: Reject CLI commands that enter configuration mode.
+      field: commands
+      type: regex
+      match:
+        - "(?i)^\\s*configure\\s+terminal\\b.*"
+        - "(?i)^\\s*configuration\\b.*"
+        - "(?i)^\\s*conf\\s+t\\b.*"
+      message: "MCP guardrail rejected a configuration mode command."
+```
+
+The Nornir `cli` task includes default MCP guardrails that reject `reboot` and
+related reload or restart commands, configuration-mode commands such as
+`configure terminal`, `configuration`, and `conf t`, and destructive or
+state-changing commands such as `commit`, `delete`, `clear`, and `debug`.
+It also rejects shell-mode commands such as `bash`, `shell`, `start shell`,
+`request system shell`, and `guestshell`, OS/image/package operations, and
+outbound session commands such as `ssh` and `telnet`.
+The Nornir `cfg` task includes default MCP guardrails that reject operational
+command escapes in configuration input, such as `do ...` and `run ...`, plus
+reboot, reload, restart, delete, erase, zeroize, `ssh`, and `telnet` commands.

docs/workers/fastmcp/services_fastmcp_service_inventory.md

@@ -25,6 +25,24 @@ Nornir service `cfg` task designed to send configuration to devices using SSH an
 
 The task returns per-host configuration results. When supported by the plugin and `add_details=True`, output can include `changed`, `diff`, `failed`, `exception`, `connection_retry`, and `task_retry` details.
 
+## MCP Guardrails
+
+When exposed through FastMCP, the `cfg` task includes default guardrails that
+reject configuration input attempting to execute operational commands from
+configuration mode, such as Cisco-style `do ...` and Junos-style `run ...`
+commands. They also reject reboot, reload, restart, delete, erase, zeroize,
+`ssh`, and `telnet` commands. These guardrails apply only to MCP tool calls.
+!!! warning
+    Guardrails inspect inline `config` values only. If `config` points to a
+    Filesharing path such as `nf://cfg/config.txt`, FastMCP checks the path
+    string, not the downloaded or rendered file content.
+
+Use NFCLI to inspect the currently published guardrails:
+
+```bash
+show fastmcp tools service nornir name *cfg*
+```
+
 ## Examples
 
 Example of sending configuration commands to devices.

docs/workers/nornir/services_nornir_service_tasks_cfg.md

@@ -31,6 +31,30 @@ and NAPALM libraries to communicate with devices.
 
 The task returns per-host command output keyed by command. With `add_details=True`, the result can include Nornir task metadata such as failure state, exception text, retry counters, and plugin-specific details.
 
+## MCP Guardrails
+
+When exposed through FastMCP, the `cli` task includes default guardrails that
+reject high-risk command values before a NorFab job is dispatched. The defaults
+block commands that reboot, reload, or restart devices; enter configuration
+mode; enter device shell modes such as `bash`, `shell`, or `guestshell`; or
+change OS images or packages; open outbound sessions such as `ssh` or
+`telnet`; or commit, delete, clear, debug, reset, or otherwise change device
+state.
+
+These guardrails apply only to MCP tool calls. They do not change direct NorFab
+client, NFCLI, FastAPI, or worker behavior. FastMCP operators can add inventory
+guardrails or disable built-in guardrails with `tools.disable_builtin_guardrails`.
+!!! warning
+    Guardrails inspect inline `commands` values only. If `commands` points to a
+    Filesharing path such as `nf://cli/commands.txt`, FastMCP checks the path
+    string, not the downloaded or rendered file content.
+
+Use NFCLI to inspect the currently published guardrails:
+
+```bash
+show fastmcp tools service nornir name *cli*
+```
+
 ## Examples
 
 Below is an example of how to use the Nornir CLI task to retrieve command outputs from devices.

docs/workers/nornir/services_nornir_service_tasks_cli.md

@@ -357,6 +357,11 @@ class Task:
             of MCP prompt definitions associated with the task. Task validates
             and normalizes these definitions before registration. FastMCP
             removes this key before constructing the MCP Tool object.
+            The optional `guardrails` key is a NorFab extension containing a
+            list of MCP task call guardrails. FastMCP validates these
+            definitions during discovery, removes this key before constructing
+            the MCP Tool object, and evaluates guardrails before dispatching
+            tool calls to NorFab services.
 
     Methods:
         __call__(function: Callable) -> Callable:

norfab/core/worker.py

@@ -1,6 +1,15 @@
-from typing import Any, Union
-
-from pydantic import BaseModel, Field, StrictBool, StrictInt, StrictStr
+import re
+from typing import Any, Literal, Union
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    StrictInt,
+    StrictStr,
+    model_validator,
+)
 
 from norfab.models import Result
 
@@ -9,6 +18,30 @@
 # --------------------------------------------------------------------------
 
 
+class TaskMCPGuardrail(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    description: StrictStr = ""
+    field: StrictStr = Field(..., min_length=1)
+    type: Literal["contains", "equals", "regex"]
+    match: Union[StrictStr, list[StrictStr]]
+    message: StrictStr = ""
+
+    @model_validator(mode="after")
+    def validate_regex_values(self) -> "TaskMCPGuardrail":
+        if self.type != "regex":
+            return self
+
+        values = self.match if isinstance(self.match, list) else [self.match]
+        for value in values:
+            try:
+                re.compile(value)
+            except re.error as exc:
+                raise ValueError(f"Invalid guardrail regex match: {exc}") from exc
+
+        return self
+
+
 class GetVersionInput(BaseModel, use_enum_values=True, populate_by_name=True):
     pass