External Tool Node Guide

Overview

The External Tool Node allows you to execute custom tools on your own infrastructure as part of NINA workflows. Unlike Operation Nodes that run tools on NINA's platform, External Tool Nodes delegate execution to a BEAM agent running on your machines, giving you full control over your data, secrets, and execution environment.

Use Cases

• Running proprietary security tools not available in NINA's tool registry
• Executing scans against internal networks unreachable from the cloud
• Integrating custom scripts (Bash, Python, PowerShell) into workflows
• Querying internal APIs or services behind a firewall
• Processing sensitive data that must remain on-premises
• Wrapping existing tooling without code changes

Creating an External Tool Node

Basic Setup

1. Drag an External Tool node from the Script menu onto your workflow canvas
2. Connect one or more input sources (e.g. Input Nodes, Script Nodes, or other upstream nodes)
3. In the Network Config dropdown, select your local agent configuration
4. Enter the Tool Name that matches a tool registered on your BEAM agent

Prerequisites

Before using this node, you need a running BEAM agent with at least one registered tool. See the BEAM Agent documentation for setup instructions.

Configuration Options

Node Properties

Property	Description
Name	A descriptive label for the node
Network Config	Select your local agent configuration from the dropdown
Tool Name	Must exactly match the name of a tool registered on your BEAM agent

How Tool Name Matching Works

The tool name you enter in the node configuration is sent as a parameter to your BEAM agent. The agent looks up the tool by this exact name and executes it. If no tool matches, the node will fail with a "Tool not registered" error.

For example, if your agent registers a tool like this:

@beam_tool(name="port_scanner", timeout=120)
async def scan_ports(input_paths, output_path, parameters):
    ...

Then you must enter port_scanner as the Tool Name in the node configuration.

How External Tool Nodes Work

When a workflow is executed:

1. NINA sends a message to your organization's SQS work queue containing the tool name, parameters, and input file references
2. Your BEAM agent picks up the message from the queue
3. The agent downloads any input files from S3 (output from previous nodes)
4. The agent looks up the registered tool by name and executes it
5. The tool processes the input and writes its output
6. The agent uploads the output to S3 and sends a completion event back to NINA
7. NINA receives the result and passes it to the next node in the workflow

Input and Output

• Input: The node can receive data from multiple upstream nodes. Each connected input becomes a separate file, and all are passed to your tool as input_paths (a list of file paths)
• Output: Your tool returns a result (JSON, text, or binary), which becomes available to downstream nodes
• Default input and output types are file

Timeouts

Tool execution timeout is controlled by your BEAM agent configuration. If a tool exceeds its timeout, the agent reports a timeout failure to NINA and the node is marked as failed. See the Configuration guide for timeout settings.

Best Practices

• Exact Tool Names: Double-check that the tool name in the node matches the registered name on your agent exactly — matching is case-sensitive
• Test Locally First: Verify your tool works on the agent before using it in a workflow
• Handle Missing Input: Your tool may receive an empty input_paths list if the previous node produced no output — handle this gracefully
• Structured Output: Return JSON from your tools for easier processing by downstream Script Nodes
• Keep Secrets Local: Store API keys and credentials on the agent machine as environment variables — never pass them through workflow parameters

Example Configurations

Example 1: Custom Port Scanner

Setting	Value	Description
Tool Name	port_scanner	Matches the registered tool name

The tool receives targets from the previous node via input_paths and returns scan results as JSON.

Example 2: Internal API Query

Setting	Value	Description
Tool Name	internal_api	Queries an internal service via the agent

The agent runs on your network, so it can reach internal APIs that NINA's platform cannot access directly.

Example 3: Wrapping an Existing Script

Setting	Value	Description
Tool Name	legacy_scanner	Wraps a Bash script with no code changes

Register existing scripts on the agent using factory functions:

from beam_agent import bash_script

scanner = bash_script("legacy_scanner", "/opt/tools/scanner.sh")
agent.register_tool("legacy_scanner", scanner)

Troubleshooting

Issue	Resolution
Tool not registered	Verify the tool name matches exactly and the tool is imported before agent.start()
Node stays pending	Check that your BEAM agent is running and polling the queue
Timeout errors	Increase timeout settings in the agent's config.yaml
Empty results	Verify upstream nodes produced output and your tool reads from input_paths
Connection errors	Check agent connectivity to AWS (outbound HTTPS) and verify your config

Next Steps

After adding an External Tool Node, consider connecting it to:

• Script Nodes: To transform or filter the tool's output
• Output Nodes: To export results from the workflow
• Other Operation or External Tool Nodes: To build multi-stage pipelines combining NINA tools with your custom tools

For building and registering tools on your agent, see the BEAM Agent documentation.

Updated: 2026-03-30