Technical Overview — Source-Available HTTP/REST Middleware for IBM i
IBM i middleware that bridges core systems to external HTTP clients sits on a critical trust boundary. Closed-source middleware products ask security teams to certify that boundary on vendor assurances alone — no code review, no static analysis, no independent verification. In regulated environments subject to PCI-DSS, SOX, HIPAA, FFIEC, FedRAMP, CMMC, or DISA STIGs, that gap is increasingly difficult to defend. A SOC 2 report and an NDA-gated code-review appointment where no notes are permitted are not the same as a reproducible, auditor-readable verification. Your certification rests on trust in the vendor, and cannot be independently reproduced.
ZCOMX is built on the opposite premise: the code your auditor reads is the code that runs.
ZCOMX is specifically designed to require no source code changes and no recompiles to any existing IBM i program. Ever. Programs written in RPG, COBOL, CL, or C run exactly as they are today. Nothing about them changes when they are exposed as HTTP endpoints.
All operational control lives on the server side, in configuration. How a program is called, what parameters it receives, what data types those parameters use, what authentication is required, which IP addresses are permitted, whether the payload must be encrypted, how the response is mapped back to JSON — all of it is defined in the ZCOMX configuration file, invisible to the requesting client.
The client sends plain JSON. It has no knowledge of:
This means the system operator has fine-grained, centralized control over every aspect of how the IBM i estate is exposed — without touching a single line of production program code. Adding a new endpoint, changing a parameter mapping, tightening access to a specific transaction, or rerouting a call to a different program library are all one-line configuration changes. No development cycle, no recompile, no redeployment of the called program, no coordinated change across clients.
It also has a security implication: a client cannot probe the backend structure because it has no visibility into it. The calling mechanism is a server-side secret.
ZCOMX has been designed from the ground up as an AI-forward product. This is not a feature added after the fact — it is a deliberate design assumption that the operators, auditors, and developers working with ZCOMX will use AI agents as a natural part of their workflow.
AI-assisted code audit. The source-available model is the foundation. An AI agent can read every line of ZCOMX — authentication logic, cryptographic key handling, request parsing, the audit trail — and answer specific questions about how the system behaves. A CISO asking “show me every place a credential touches memory and confirm it is zeroed” gets a precise answer from the code, not from a vendor datasheet.
AI-assisted configuration. ZCOMX configuration can
be complex — transaction mappings, authentication schemes, encryption
keys, IP restrictions, XMLSERVICE typed-parameter maps. ZCOMX ships with
a built-in CLAUDE.md file that serves as a comprehensive
context document for AI agents. When an operator asks an AI agent to
generate a configuration block for an IBM i program, or to explain what
a particular map definition does, or to recommend the right
authentication scheme for a deployment, the agent has the full
architectural context it needs to answer correctly. The
CLAUDE.md is maintained alongside the source code and
covers configuration options, security constraints, calling conventions,
and known pitfalls — exactly the knowledge an AI agent needs to give
reliable recommendations rather than plausible-sounding guesses.
AI-assisted customization and understanding. For
organizations that exercise their right to modify ZCOMX for internal
use, AI agents dramatically reduce the barrier to doing so safely. The
same CLAUDE.md that guides configuration assistance also
guides code-level changes — an agent asked to add a new authentication
scheme or extend a transaction type has the full context of the
architecture, the ILE C constraints, the IBM i-specific patterns, and
the explicit list of things not to change and why. Source-available code
that an AI can read and reason about is a fundamentally different
proposition from source-available code that requires a human expert to
navigate.
The MCP connection. ZCOMX’s Model Context Protocol support means the same IBM i programs it exposes as REST endpoints are immediately available as tools for any AI agent. The AI-forward design runs in both directions: AI helps operate and configure ZCOMX, and ZCOMX connects AI to IBM i.
[External Client]
↓ HTTPS/TLS
[NGINX reverse proxy on IBM i]
↓ Unix domain socket (AF_UNIX, 0660 permissions)
[ZCOMX worker pool — 20–30 concurrent workers]
↓ IBM i Machine Interface CALL PGM()
[IBM i programs — RPG, COBOL, CL, C — unchanged]Each layer is independently auditable. NGINX handles TLS termination using standard, human-readable configuration — auditors can verify cipher suites, certificate management, and protocol version constraints directly. The domain socket is a local OS pipe with filesystem permissions; there is no network hop between NGINX and ZCOMX, eliminating an entire class of interception risk. Workers are pre-forked ILE C processes, each an independent IBM i job with isolated static storage, its own spoolfile, and no shared mutable state. The IBM i programs they call are existing production code that has not been modified or recompiled.
ZCOMX supports six transaction types, covering the full range of IBM i program and file operations. All are configured server-side; clients see only a JSON request and a JSON response.
Program calls (CALLPGM). Calls any IBM
i *PGM object — ILE or OPM, written in RPG, COBOL, CL, or
ILE C. No recompile, no PCML, no source language requirement. Three
calling conventions are supported:
1/0) and a 132-byte error message field.
Provides a clean separation between business data and error status.
Recommended for new programs.parmdata is a JSON object;
ZCOMX serializes it and passes the JSON string directly to the program.
The program handles its own JSON parsing. No mapping configuration
required.Service program procedure calls
(CALLSRVPROC). Calls a named procedure in an IBM i
*SRVPGM object. Supports both simple character-buffer
interfaces and fully typed parameters via XMLSERVICE — packed decimal,
zoned decimal, binary integers, unsigned integers, boolean, and
character fields of any declared length, with explicit in,
out, both, and return directions.
Procedures that return pre-built JSON strings (common with DB2 JSON
functions) are supported directly. Type specifications live in
server-side configuration; the client sends plain JSON field names and
values.
File read (GETFILE). Returns file
content as a JSON array. Three sources are supported:
LIB/FILE(MBR) pathsSELECT statement or stored
procedure call against DB2 for i and returns the result set. Dynamic SQL
can be enabled for authenticated clients; stored procedure calls are the
default. Empty result sets return HTTP 200 with an empty array — not an
error.File write (PUTFILE). Writes content to
an IFS path or a QSYS physical file member. Supports append and
overwrite modes. IFS writes handle CCSID translation automatically.
Health check (HEALTH). An
unauthenticated endpoint that returns server status — worker identity,
uptime, and configuration state. Designed for load balancer health
probes and monitoring systems. The only endpoint that bypasses
authentication by design.
Model Context Protocol (MCP). Accepts
JSON-RPC tool calls from any LLM with an MCP connector and routes them
to the configured IBM i program or service procedure. Uses the same
transaction definitions, authentication, and audit trail as REST
clients. Described further in the AI and MCP integration section
below.
Authentication. All supported schemes — Basic/AS400, LDAP, static bearer token, HMAC-SHA256 signed bearer, and pluggable custom schemes — are implemented in readable ILE C. Every authentication decision is reachable from a single source file. Authentication ordering, cache behavior, credential length limits, and the signed-token format are all inspectable.
Cryptography. The recommended deployment terminates SSL/TLS at NGINX, which typically runs on the IBM i partition itself — keeping encrypted traffic decrypted only within the partition boundary. This uses standard, well-understood TLS configuration that auditors can verify directly against the NGINX config file.
As an option for environments where TLS is unavailable or impractical
— air-gapped networks, constrained IoT devices that cannot perform a
full TLS handshake — ZCOMX supports application-level AES-128 or AES-256
payload encryption as an additional layer. AES encryption and
HMAC-SHA256 token signing use IBM i’s native QC3
cryptographic APIs. Key material is held in *DTAARA objects
and resolved at call time — not stored in worker memory for the process
lifetime. Keys are zeroed from memory before each function returns using
volatile-pointer writes that cannot be eliminated by the compiler
optimizer. The IV construction contract (session-GUID derived, fresh per
request) is documented and verifiable.
Audit trail. Every transaction is written to the
ZCOMLOG physical file with user profile, source IP, program
called, timing, success/failure, error codes, and optionally full
input/output payloads. The audit trail cannot be suppressed by client
behavior; it records rejected requests as completely as successful ones.
ZCOMLOG can be queried with standard IBM i database tools
or any SQL client.
Whitelist and access control. IP allowlists and
per-transaction restrictedto restrictions are enforced in
code auditors can read, before any program is called.
No hidden channels. Worker source contains no outbound network calls outside the authorized request/response path. There is no telemetry, no phone-home, no update mechanism.
ZCOMX has been subjected to multiple rounds of security testing across the following categories:
What the testing covers: the attack surface available to an authenticated caller, plus unauthenticated boundary conditions at the HTTP parsing layer.
What it does not cover: authentication bypass, privilege escalation between users, IBM i CCSID and ILE exception edge cases, encryption key management, configuration security, and the behavior of customer programs called via CALLPGM. Those areas remain for your own assessment.
IBM Integrated Web Services (IWS). IWS generates
SOAP/REST endpoints by reading PCML parameter metadata from compiled
program objects. This creates three operational constraints: programs
must have been compiled with specific debug options; interface changes
require re-running a wizard, regenerating a WSDL, and redeploying; and
CL programs cannot be exposed at all — CL has no PCML support, so IWS
requires a thin RPG or COBOL wrapper around every CL program. In the
largest ZCOMX production deployment, approximately 98% of calls go to CL
programs. ZCOMX uses the IBM i Machine Interface CALL PGM()
— language-agnostic, working on any *PGM object regardless
of source language, compile options, or age, with no wrappers and no
wizards.
XMLSERVICE-based client tools (itoolkit, iService, custom wrappers). These require the calling application to supply IBM i data types — packed decimal field widths, zoned lengths, binary integer sizes. The client must know the backend structure. When a program interface changes, every client changes. ZCOMX inverts this entirely: parameter types, field lengths, and calling conventions live in server-side configuration. The client sends plain JSON and knows nothing about the backend. A program interface change is a one-line server config edit; no client is notified, updated, or redeployed.
Handler-code frameworks. Writing HTTP endpoints as RPG procedures requires mid-to-senior free-format RPG skills for each endpoint — procedure interfaces, ILE binding, the framework’s handler API. Every new endpoint is custom code. That skill set is retiring faster than it is being replaced; the average RPG developer is in their late 50s and computer science programs do not teach RPG. In five to ten years, an RPG-handler-based system becomes progressively harder to extend without expensive contractors. ZCOMX requires no RPG to operate: adding an endpoint means editing a JSON config file that any developer familiar with JSON can manage. The existing IBM i programs run unchanged.
ZCOMX implements the Model Context Protocol (Streamable HTTP, 2025 revision), allowing any LLM with an MCP connector to call IBM i programs as tools — with no additional configuration. The same transaction definitions, authentication schemes, audit trail, and IP restrictions that govern REST clients govern AI clients identically. An IBM i program callable via REST is immediately available as an MCP tool. There is no separate tool inventory, no additional trust boundary, and no program modification required. The LLM is just another authenticated client; the audit log entry for an AI-driven call is indistinguishable from one made by a web application.
ZCOMX is designed to support — not replace — your existing compliance program. Source availability at the middleware boundary addresses specific control requirements that closed-source products cannot satisfy:
ZCOMX is source-available under a commercial license. Licensees have full rights to use, modify, deploy, and internally review the source code, including security audit and operational customization within their own organization. Redistribution and incorporation into other products or projects are not permitted.
Bill Herron — bill.herron@zanden.com
Operations guide, security rationale document, and auditor brief available on request.