opnsense_nat_source_add

Instructions

Implementation Reference

• src/tools/nat.ts:229-253 (handler)

  The handler function for the 'opnsense_nat_source_add' tool. Parses input via SourceNatAddSchema, constructs a rule object, converts booleans to '1'/'0' via the flag() helper, and POSTs to /firewall/source_nat/add_rule.

  case "opnsense_nat_source_add": {
    const p = SourceNatAddSchema.parse(args);
    const rule: Record<string, unknown> = {
      enabled: flag(p.enabled),
      interface: p.interface,
      ipprotocol: p.ipprotocol,
      protocol: p.protocol ?? "",
      source_net: p.source_net,
      source_not: flag(p.source_not),
      source_port: p.source_port ?? "",
      destination_net: p.destination_net,
      destination_not: flag(p.destination_not),
      destination_port: p.destination_port ?? "",
      target: p.target ?? "",
      target_port: p.target_port ?? "",
      staticnatport: flag(p.staticnatport),
      nonat: flag(p.nonat),
      log: flag(p.log),
      sequence: String(p.sequence),
      tagged: p.tagged ?? "",
      description: p.description ?? "",
    };
    const result = await client.post("/firewall/source_nat/add_rule", { rule });
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/tools/nat.ts:29-49 (schema)

  The Zod schema (SourceNatAddSchema) that validates and coerces input parameters for opnsense_nat_source_add. Defines fields like enabled, interface, ipprotocol, protocol, source_net, source_not, source_port, destination_net, destination_not, destination_port, target, target_port, staticnatport, nonat, log, sequence, tagged, description, and a confirm flag.

  const SourceNatAddSchema = z.object({
    enabled: CoerceBoolean.optional().default(true),
    interface: z.string().min(1, "interface is required (e.g. 'wan')"),
    ipprotocol: z.enum(["inet", "inet6"]).optional().default("inet"),
    protocol: z.string().optional(), // any | TCP | UDP | TCP/UDP | ...
    source_net: z.string().optional().default("any"),
    source_not: CoerceBoolean.optional().default(false),
    source_port: z.string().optional(),
    destination_net: z.string().optional().default("any"),
    destination_not: CoerceBoolean.optional().default(false),
    destination_port: z.string().optional(),
    target: z.string().optional().default("wanip"), // wanip | <ip> | host alias
    target_port: z.string().optional(),
    staticnatport: CoerceBoolean.optional().default(false),
    nonat: CoerceBoolean.optional().default(false),
    log: CoerceBoolean.optional().default(false),
    sequence: z.coerce.number().int().min(1).max(99999).optional().default(100),
    tagged: z.string().optional(),
    description: z.string().optional(),
    confirm: ConfirmTrue("confirm must be true to add a source NAT rule"),
  });

• src/tools/nat.ts:108-137 (registration)

  The tool registration definition (name, description, inputSchema) for 'opnsense_nat_source_add', exported as part of the natToolDefinitions array.

  {
    name: "opnsense_nat_source_add",
    description:
      "Add a new Source NAT (outbound) rule. After adding, call opnsense_nat_apply to activate. DESTRUCTIVE: requires explicit confirmation.",
    inputSchema: {
      type: "object" as const,
      properties: {
        enabled: { type: "boolean", description: "Rule enabled (default: true)" },
        interface: { type: "string", description: "Interface name (e.g. 'wan', 'lan', 'opt1')" },
        ipprotocol: { type: "string", enum: ["inet", "inet6"], description: "IP version" },
        protocol: { type: "string", description: "Protocol: any/TCP/UDP/TCP/UDP/ICMP/..." },
        source_net: { type: "string", description: "Source network (any/CIDR/alias). Default: any" },
        source_not: { type: "boolean", description: "Invert source match" },
        source_port: { type: "string", description: "Source port/range" },
        destination_net: { type: "string", description: "Destination network. Default: any" },
        destination_not: { type: "boolean", description: "Invert destination match" },
        destination_port: { type: "string", description: "Destination port/range" },
        target: { type: "string", description: "Translation target: 'wanip' (default), specific IP, or alias" },
        target_port: { type: "string", description: "Translation target port" },
        staticnatport: { type: "boolean", description: "Use static source port" },
        nonat: { type: "boolean", description: "If true, exclude this traffic from NAT (no-NAT rule)" },
        log: { type: "boolean", description: "Log packets matching this rule" },
        sequence: { type: "number", description: "Rule order (default: 100)" },
        tagged: { type: "string", description: "Match a packet tag set by another rule" },
        description: { type: "string", description: "Human-readable description" },
        confirm: { type: "boolean", description: "Must be true to confirm", enum: [true] },
      },
      required: ["interface", "confirm"],
    },
  },

• src/index.ts:70-70 (registration)

  Registration of the handler: all NAT tool definitions (including opnsense_nat_source_add) are mapped to handleNatTool in the toolHandlers map.

  for (const def of natToolDefinitions) toolHandlers.set(def.name, handleNatTool);

• src/tools/nat.ts:83-86 (helper)

  Helper function flag() converts a boolean to '1'/'0' string for the OPNsense API, used when building the rule payload.

  function flag(b: boolean | undefined): string | undefined {
    if (b === undefined) return undefined;
    return b ? "1" : "0";
  }