Command Builder Interface¶
Interface — instantiates Control/Data Boundary Enforcement
Builds commands from typed arguments and allowlisted operations rather than raw strings.
A Command Builder Interface is an API surface that constructs a command as structure — a chosen operation plus a list of typed arguments — instead of as a string that a shell or automation engine will later re-parse. Its defining idea is that the caller never gets to hand over free-form command text: the operation is picked from a fixed, allowlisted set, and each argument is passed as a discrete value in its own slot, so a user-supplied argument can never be re-read as an extra flag, a pipe, a second command, or a redirection. Where a string-concatenating call invites the interpreter to discover syntax inside the data, a command builder gives the interpreter a pre-structured invocation with nothing left to parse.
Example¶
A deployment bot lets engineers restart a named service in a Kubernetes cluster from a chat message. The naïve version formats a shell string: kubectl rollout restart deployment $NAME. An engineer — or a spoofed message — sets the service name to web; kubectl delete namespace prod. Concatenated and handed to a shell, that name stops being a name and becomes a second, destructive command.
Routed through a command builder, the same request is expressed as run(op="rollout_restart", deployment=NAME). The operation rollout_restart is one of a handful the interface exposes; there is no delete namespace operation to reach at all. NAME is passed as a single argument value in an argv array — never spliced into a command line — so the semicolon and the trailing text are just odd characters in a deployment name that does not exist, and the call fails cleanly instead of executing anything. The structure of the command was fixed before the untrusted value arrived.
How it works¶
- Operation from an allowlist. The caller selects among a closed set of named operations; there is no path to express an operation the interface did not intend to offer.
- Arguments as typed slots. Each argument is supplied as a discrete, typed value bound to a named parameter, assembled into an argument vector rather than a command line — so no argument can carry shell metacharacters into a parsing context.
- No shell round-trip. The builder invokes the target directly (execve-style argv, an SDK call) so there is no intermediate string for a shell to re-interpret.
- Reject unrepresentable requests. Anything that cannot be expressed as (allowed operation, valid typed arguments) is refused at construction, not sanitized into shape.
Tuning parameters¶
- Operation catalog breadth — how many operations the interface exposes. A narrow catalog is safer and easier to reason about; a broad one is convenient but widens what a confused caller can reach.
- Argument typing strictness — how tightly each slot is typed (enum, bounded integer, opaque identifier vs. free text). Stricter types close more escapes; looser ones defer risk to the target.
- Argument-vector vs. string assembly — whether the builder truly passes argv or ultimately renders a string. True argv is the whole point; a builder that re-serializes to a shell line reopens the hole it was meant to close.
- Composition policy — whether callers may chain operations. Forbidding composition keeps each call auditable; allowing it recovers expressiveness at the cost of a larger effective grammar.
When it helps, and when it misleads¶
Its strength is that it removes the syntactic seam where OS command injection lives: if no argument is ever parsed as syntax, there is nothing for a metacharacter to escape into.[1] It is the natural boundary for shell, CLI, and automation surfaces where the alternative is string formatting.
Its failure mode is the builder that is only skin-deep — one that assembles a friendly typed call and then, underneath, renders a shell string and calls system() on it, restoring the exact vulnerability it advertised away. It also does nothing about which operations are dangerous once composition or an over-broad catalog is allowed. The discipline that keeps it honest is to pass a real argument vector all the way to the target, keep the operation catalog minimal, and refuse — rather than quietly rewrite — any request that will not fit the structure.
How it implements the components¶
typed_parse_contract— the interface is the contract: a command may only be (an allowlisted operation, a set of typed argument slots), so each untrusted value can occupy exactly one data slot and nothing more.effect_allowlist— the closed set of named operations is an allowlist of permitted effects; an effect the catalog does not name cannot be constructed at all.
It does not neutralize a value for a database interpreter by binding it as a parameter (input_inertization_layer) — that is Parameterized Query API — nor contain the resulting process under isolation once it runs (sandboxed_interpreter), which is Sandboxed Execution Environment.
Related¶
- Instantiates: Control/Data Boundary Enforcement — it is the structural-construction mechanism for shell and automation contexts.
- Sibling mechanisms: Parameterized Query API · Prepared Statement · Capability-Scoped Tool Gateway · Sandboxed Execution Environment · Schema-Validated Message Envelope · LLM Instruction/Data Boundary · Injection Boundary Red-Team · Taint-Tracking Analysis · Contextual Output Encoding
Editorial Notes¶
Form Classification¶
Form family: Control, Automation & Runtime
Rationale: At execution time the builder restricts operations to an allowlist, binds typed arguments into an argument vector, invokes the target without a shell, and rejects unrepresentable requests, so it is runtime effect control.
Nearest alternative: Interface, Display & Cue — It exposes an operation-and-argument interface, but its defining work is technical construction and enforcement inside execution rather than presenting a user-facing surface.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Secure API design established structured allowlisted commands with typed argument vectors instead of re-parsed raw strings.
Related originating lineages:
- Security Studies & Intelligence Analysis — Injection prevention supplies the adversarial control-data boundary.
Review resolution: Both reviewers agree on computer_science as primary. Reading the source mechanism confirms that its defining operation belongs to that lineage; the final record retains security_intelligence only where it materially formed the mechanism and keeps present-day application breadth separate from provenance.
Review outcome: Reconciled after independent review; high confidence.
References¶
[1] OS command injection (CWE-78) is the flaw in which externally influenced input is incorporated into a command passed to a shell, letting the input alter the command. Building an argument vector directly, without a shell to re-parse it, removes the syntactic context the flaw depends on. withdrawn registry ↩