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] MITRE CWE-78: Improper Neutralization of Special Elements Used in an OS Command ('OS Command Injection'). Common Weakness Enumeration (n.d.). Defines OS command injection as externally influenced input altering command syntax through unneutralized special elements. withdrawn registry ↩