<cfexecute> runs a program directly on the server, the same as if it had been launched from a terminal, and can capture whatever that program prints back. It's the CFML equivalent of shelling out to run another executable.
Learning Objectives
After completing this lesson, you'll be able to:
- Run an external program with cfexecute and capture its output into a variable or a file.
- Understand what timeout actually controls, and what happens when it's 0 versus a real value.
- Recognize the real security risk: building arguments from unvalidated user input is a command-injection vulnerability.
How cfexecute Fits In
Your Code
cfexecute
External Program
Output Captured
Running a Program and Capturing Its Output
<cfexecute name="C:\Windows\System32\netstat.exe"
arguments="-an"
variable="result"
timeout="10">
<cfoutput>#result#</cfoutput>cfexecute(
name = "C:\Windows\System32\netstat.exe",
arguments = "-an",
variable = "result",
timeout = 10
);
writeOutput(result);name must be the program's absolute path, and on Windows it needs the file extension (.exe). arguments can be a single string or an array of separate arguments.
What timeout Actually Controls
timeout defaults to 0, meaning cfexecute doesn't wait at all, it fires the process and moves on immediately. If nothing is capturing output (no variable or outputFile), whatever the program prints is simply lost. A real timeout value makes cfexecute wait up to that many seconds for the program to produce output before continuing regardless of whether it's finished.
Process Spawned
Wait Up To timeout Seconds
Output Available? Continue
A timeout being reached does not necessarily stop the spawned process on Adobe ColdFusion, it just stops CFML from waiting any longer. Lucee's terminateOnTimeout attribute can actually end the process when its timeout is hit.
The Full Attribute Reference
| Attribute | Meaning |
|---|---|
| name | Absolute path of the program to run (required); needs a file extension on Windows |
| arguments | Command-line arguments, as a single string or an array |
| variable | Captures the program's standard output into a variable |
| outputFile | Writes the program's standard output to a file instead |
| errorVariable | Captures the program's error output into a variable |
| errorFile | Writes the program's error output to a file |
| timeout | Seconds to wait for output; 0 (the default) means don't wait at all |
Two real restrictions worth knowing: cfexecute tags cannot be nested inside one another, and no other CFML tags can appear between a cfexecute tag's start and end.
A Real Gotcha: Command Injection
That's the permissions-side security exception Adobe's own documentation calls out, cfexecute genuinely can fail for legitimate permission reasons. But the bigger, easy-to-miss risk is different: if any part of name or arguments is built from unvalidated user input, an attacker can potentially inject additional commands or arguments the application never intended to run. This is the exact same class of vulnerability as SQL injection, just aimed at the operating system instead of a database.
The effective user of the ColdFusion executing thread does not have permissions to execute the process.
Lucee-Specific Extensions Worth Knowing
| Attribute | What it adds |
|---|---|
| terminateOnTimeout | Actually ends the spawned process once its timeout is reached (Lucee 4.5+), rather than just giving up on waiting |
| directory | Sets the working directory the command runs from (Lucee 5.3.8+) |
| exitCodeVariable | Captures the process's exit code into a variable |
| environment | A struct of environment variables to set for the spawned process (Lucee 7.0.0.185+) |
| result | Captures output, error, and exitCode together in a single struct (Lucee 7.0.0.186+) |
| onProgress / onError | UDF callbacks that receive output as it streams in, rather than waiting for the process to finish (Lucee 7.0.0.188+) |
None of these exist on Adobe ColdFusion's cfexecute. terminateOnTimeout in particular is worth knowing about even if unused, since Adobe's own timeout behavior surprises people expecting it to also kill the process.
Common Beginner Mistakes
Forgetting the file extension in name on Windows
Windows requires it explicitly, e.g. C:\tools\app.exe, not just C:\tools\app.
Leaving timeout at its default of 0 and expecting output to be captured
0 means cfexecute doesn't wait at all. Without a real timeout value, output the program produces after cfexecute moves on is simply lost.
Building name or arguments directly from user input
This is a real command-injection vulnerability, the same class of risk as building a SQL query directly from user input. Validate and constrain any user-influenced value first.
Assuming a timed-out process actually stops running on Adobe ColdFusion
It doesn't by default, timeout only controls how long CFML waits, not whether the spawned process itself is terminated. Lucee's terminateOnTimeout attribute is the one built specifically to actually stop it.
Best Practices
- Never build name or arguments from unvalidated user input, treat it with the same caution as a dynamic SQL query.
- Set a real timeout value whenever the program's output actually matters, rather than leaving the non-waiting default.
- Capture both variable and errorVariable, a program's error stream often explains a failure that its normal output doesn't.
- Prefer an explicit allow-list of programs the application is permitted to run, rather than accepting a program path from configuration or user input.
Interview Questions
What does a timeout of 0 mean for cfexecute, and why is it the default?
It means cfexecute doesn't wait for the spawned program at all, it fires the process and continues immediately. Any output produced after that point, with nothing set up to capture it, is simply lost.
Why is cfexecute a real security concern beyond just permissions failures?
If name or arguments is built from unvalidated user input, an attacker can potentially inject unintended commands or arguments, the same class of vulnerability as SQL injection, aimed at the operating system.
Does reaching cfexecute's timeout stop the spawned process itself?
Not on Adobe ColdFusion by default, timeout only controls how long CFML waits for output. Lucee's terminateOnTimeout attribute is specifically built to actually end the process when its timeout is hit.
Can cfexecute tags be nested?
No, cfexecute tags cannot be nested inside one another, and no other CFML tags may appear between a cfexecute tag's start and end.
Name a cfexecute attribute available in Lucee but not in Adobe ColdFusion.
terminateOnTimeout, directory, exitCodeVariable, environment, result, and the onProgress/onError callbacks are all Lucee-specific.
Summary
In this lesson, you ran an external program with cfexecute and captured its output into a variable, learned what timeout actually controls (and that 0 means no waiting at all), covered real Lucee-only extensions like terminateOnTimeout and result, and covered the real security risk that cfexecute is a command-injection vector when its arguments come from unvalidated input.
What's Next?
The next lesson covers cfftp, connecting to an FTP server directly from CFML to upload, download, and manage remote files.