Merge pull request #280 from github/hmac-cli-injection

Add CLI Injection query

Author: hmac

ql/lib/codeql/ruby/Concepts.qll

@@ -9,6 +9,7 @@ private import codeql.ruby.CFG
 private import codeql.ruby.DataFlow
 private import codeql.ruby.Frameworks
 private import codeql.ruby.dataflow.RemoteFlowSources
+private import codeql.ruby.ApiGraphs
 
 /**
  * A data-flow node that executes SQL statements.
@@ -312,3 +313,32 @@ module HTTP {
     }
   }
 }
+
+/**
+ * A data flow node that executes an operating system command,
+ * for instance by spawning a new process.
+ */
+class SystemCommandExecution extends DataFlow::Node instanceof SystemCommandExecution::Range {
+  /** Holds if a shell interprets `arg`. */
+  predicate isShellInterpreted(DataFlow::Node arg) { super.isShellInterpreted(arg) }
+
+  /** Gets an argument to this execution that specifies the command or an argument to it. */
+  DataFlow::Node getAnArgument() { result = super.getAnArgument() }
+}
+
+module SystemCommandExecution {
+  /**
+   * A data flow node that executes an operating system command, for instance by spawning a new
+   * process.
+   *
+   * Extend this class to model new APIs. If you want to refine existing API models,
+   * extend `SystemCommandExecution` instead.
+   */
+  abstract class Range extends DataFlow::Node {
+    /** Gets an argument to this execution that specifies the command or an argument to it. */
+    abstract DataFlow::Node getAnArgument();
+
+    /** Holds if a shell interprets `arg`. */
+    predicate isShellInterpreted(DataFlow::Node arg) { none() }
+  }
+}

ql/lib/codeql/ruby/Frameworks.qll

@@ -5,3 +5,4 @@
 private import codeql.ruby.frameworks.ActionController
 private import codeql.ruby.frameworks.ActiveRecord
 private import codeql.ruby.frameworks.ActionView
+private import codeql.ruby.frameworks.StandardLibrary

ql/lib/codeql/ruby/frameworks/StandardLibrary.qll

@@ -0,0 +1,245 @@
+private import codeql.ruby.AST
+private import codeql.ruby.Concepts
+private import codeql.ruby.DataFlow
+private import codeql.ruby.ApiGraphs
+private import codeql.ruby.dataflow.internal.DataFlowDispatch
+private import codeql.ruby.dataflow.internal.DataFlowImplCommon
+
+/**
+ * The `Kernel` module is included by the `Object` class, so its methods are available
+ * in every Ruby object. In addition, its module methods can be called by
+ * providing a specific receiver as in `Kernel.exit`.
+ */
+class KernelMethodCall extends MethodCall {
+  KernelMethodCall() {
+    this = API::getTopLevelMember("Kernel").getAMethodCall(_).asExpr().getExpr()
+    or
+    // we assume that if there's no obvious target for this method call
+    // and the method name matches a Kernel method, then it is a Kernel method call.
+    // TODO: ApiGraphs should ideally handle this case
+    not exists(DataFlowCallable method, DataFlowCall call |
+      viableCallable(call) = method and call.getExpr() = this
+    ) and
+    (
+      this.getReceiver() instanceof Self and isPrivateKernelMethod(this.getMethodName())
+      or
+      isPublicKernelMethod(this.getMethodName())
+    )
+  }
+}
+
+/**
+ * Public methods in the `Kernel` module. These can be invoked on any object via the usual dot syntax.
+ * ```ruby
+ * arr = []
+ * arr.send("push", 5) # => [5]
+ * ```
+ */
+private predicate isPublicKernelMethod(string method) {
+  method in ["class", "clone", "frozen?", "tap", "then", "yield_self", "send"]
+}
+
+/**
+ * Private methods in the `Kernel` module.
+ * These can be be invoked on `self`, on `Kernel`, or using a low-level primitive like `send` or `instance_eval`.
+ * ```ruby
+ * puts "hello world"
+ * Kernel.puts "hello world"
+ * 5.instance_eval { puts "hello world" }
+ * 5.send("puts", "hello world")
+ * ```
+ */
+private predicate isPrivateKernelMethod(string method) {
+  method in [
+      "Array", "Complex", "Float", "Hash", "Integer", "Rational", "String", "__callee__", "__dir__",
+      "__method__", "`", "abort", "at_exit", "autoload", "autoload?", "binding", "block_given?",
+      "callcc", "caller", "caller_locations", "catch", "chomp", "chop", "eval", "exec", "exit",
+      "exit!", "fail", "fork", "format", "gets", "global_variables", "gsub", "iterator?", "lambda",
+      "load", "local_variables", "loop", "open", "p", "pp", "print", "printf", "proc", "putc",
+      "puts", "raise", "rand", "readline", "readlines", "require", "require_relative", "select",
+      "set_trace_func", "sleep", "spawn", "sprintf", "srand", "sub", "syscall", "system", "test",
+      "throw", "trace_var", "trap", "untrace_var", "warn"
+    ]
+}
+
+/**
+ * A system command executed via subshell literal syntax.
+ * E.g.
+ * ```ruby
+ * `cat foo.txt`
+ * %x(cat foo.txt)
+ * %x[cat foo.txt]
+ * %x{cat foo.txt}
+ * %x/cat foo.txt/
+ * ```
+ */
+class SubshellLiteralExecution extends SystemCommandExecution::Range {
+  SubshellLiteral literal;
+
+  SubshellLiteralExecution() { this.asExpr().getExpr() = literal }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = literal.getComponent(_) }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) { arg = getAnArgument() }
+}
+
+/**
+ * A system command executed via shell heredoc syntax.
+ * E.g.
+ * ```ruby
+ * <<`EOF`
+ * cat foo.text
+ * EOF
+ * ```
+ */
+class SubshellHeredocExecution extends SystemCommandExecution::Range {
+  HereDoc heredoc;
+
+  SubshellHeredocExecution() { this.asExpr().getExpr() = heredoc and heredoc.isSubShell() }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = heredoc.getComponent(_) }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) { arg = getAnArgument() }
+}
+
+/**
+ * A system command executed via the `Kernel.system` method.
+ * `Kernel.system` accepts three argument forms:
+ * - A single string. If it contains no shell meta characters, keywords or
+ *   builtins, it is executed directly in a subprocess.
+ *   Otherwise, it is executed in a subshell.
+ *   ```ruby
+ *   system("cat foo.txt | tail")
+ *   ```
+ * - A command and one or more arguments.
+ *   The command is executed in a subprocess.
+ *   ```ruby
+ *   system("cat", "foo.txt")
+ *   ```
+ * - An array containing the command name and argv[0], followed by zero or more arguments.
+ *   The command is executed in a subprocess.
+ *   ```ruby
+ *   system(["cat", "cat"], "foo.txt")
+ *   ```
+ * In addition, `Kernel.system` accepts an optional environment hash as the
+ * first argument and an optional options hash as the last argument.
+ * We don't yet distinguish between these arguments and the command arguments.
+ * ```ruby
+ * system({"FOO" => "BAR"}, "cat foo.txt | tail", {unsetenv_others: true})
+ * ```
+ * Ruby documentation: https://docs.ruby-lang.org/en/3.0.0/Kernel.html#method-i-system
+ */
+class KernelSystemCall extends SystemCommandExecution::Range {
+  KernelMethodCall methodCall;
+
+  KernelSystemCall() {
+    methodCall.getMethodName() = "system" and
+    this.asExpr().getExpr() = methodCall
+  }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = methodCall.getAnArgument() }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) {
+    // Kernel.system invokes a subshell if you provide a single string as argument
+    methodCall.getNumberOfArguments() = 1 and arg.asExpr().getExpr() = methodCall.getAnArgument()
+  }
+}
+
+/**
+ * A system command executed via the `Kernel.exec` method.
+ * `Kernel.exec` takes the same argument forms as `Kernel.system`. See `KernelSystemCall` for details.
+ * Ruby documentation: https://docs.ruby-lang.org/en/3.0.0/Kernel.html#method-i-exec
+ */
+class KernelExecCall extends SystemCommandExecution::Range {
+  KernelMethodCall methodCall;
+
+  KernelExecCall() {
+    methodCall.getMethodName() = "exec" and
+    this.asExpr().getExpr() = methodCall
+  }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = methodCall.getAnArgument() }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) {
+    // Kernel.exec invokes a subshell if you provide a single string as argument
+    methodCall.getNumberOfArguments() = 1 and arg.asExpr().getExpr() = methodCall.getAnArgument()
+  }
+}
+
+/**
+ * A system command executed via the `Kernel.spawn` method.
+ * `Kernel.spawn` takes the same argument forms as `Kernel.system`.
+ * See `KernelSystemCall` for details.
+ * Ruby documentation: https://docs.ruby-lang.org/en/3.0.0/Kernel.html#method-i-spawn
+ * TODO: document and handle the env and option arguments.
+ * ```
+ * spawn([env,] command... [,options]) → pid
+ * ```
+ */
+class KernelSpawnCall extends SystemCommandExecution::Range {
+  KernelMethodCall methodCall;
+
+  KernelSpawnCall() {
+    methodCall.getMethodName() = "spawn" and
+    this.asExpr().getExpr() = methodCall
+  }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = methodCall.getAnArgument() }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) {
+    // Kernel.spawn invokes a subshell if you provide a single string as argument
+    methodCall.getNumberOfArguments() = 1 and arg.asExpr().getExpr() = methodCall.getAnArgument()
+  }
+}
+
+/**
+ * A system command executed via one of the `Open3` methods.
+ * These methods take the same argument forms as `Kernel.system`.
+ * See `KernelSystemCall` for details.
+ */
+class Open3Call extends SystemCommandExecution::Range {
+  MethodCall methodCall;
+
+  Open3Call() {
+    this.asExpr().getExpr() = methodCall and
+    this =
+      API::getTopLevelMember("Open3")
+          .getAMethodCall(["popen3", "popen2", "popen2e", "capture3", "capture2", "capture2e"])
+  }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = methodCall.getAnArgument() }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) {
+    // These Open3 methods invoke a subshell if you provide a single string as argument
+    methodCall.getNumberOfArguments() = 1 and arg.asExpr().getExpr() = methodCall.getAnArgument()
+  }
+}
+
+/**
+ * A pipeline of system commands constructed via one of the `Open3` methods.
+ * These methods accept a variable argument list of commands.
+ * Commands can be in any form supported by `Kernel.system`. See `KernelSystemCall` for details.
+ * ```ruby
+ * Open3.pipeline("cat foo.txt", "tail")
+ * Open3.pipeline(["cat", "foo.txt"], "tail")
+ * Open3.pipeline([{}, "cat", "foo.txt"], "tail")
+ * Open3.pipeline([["cat", "cat"], "foo.txt"], "tail")
+ */
+class Open3PipelineCall extends SystemCommandExecution::Range {
+  MethodCall methodCall;
+
+  Open3PipelineCall() {
+    this.asExpr().getExpr() = methodCall and
+    this =
+      API::getTopLevelMember("Open3")
+          .getAMethodCall(["pipeline_rw", "pipeline_r", "pipeline_w", "pipeline_start", "pipeline"])
+  }
+
+  override DataFlow::Node getAnArgument() { result.asExpr().getExpr() = methodCall.getAnArgument() }
+
+  override predicate isShellInterpreted(DataFlow::Node arg) {
+    // A command in the pipeline is executed in a subshell if it is given as a single string argument.
+    arg.asExpr().getExpr() instanceof StringlikeLiteral and
+    arg.asExpr().getExpr() = methodCall.getAnArgument()
+  }
+}

ql/lib/codeql/ruby/security/CommandInjectionCustomizations.qll

@@ -0,0 +1,54 @@
+/**
+ * Provides default sources, sinks and sanitizers for reasoning about
+ * command-injection vulnerabilities, as well as extension points for
+ * adding your own.
+ */
+
+private import codeql.ruby.DataFlow
+private import codeql.ruby.dataflow.RemoteFlowSources
+private import codeql.ruby.Concepts
+private import codeql.ruby.Frameworks
+private import codeql.ruby.ApiGraphs
+
+module CommandInjection {
+  /**
+   * A data flow source for command-injection vulnerabilities.
+   */
+  abstract class Source extends DataFlow::Node {
+    /** Gets a string that describes the type of this remote flow source. */
+    abstract string getSourceType();
+  }
+
+  /**
+   * A data flow sink for command-injection vulnerabilities.
+   */
+  abstract class Sink extends DataFlow::Node { }
+
+  /**
+   * A sanitizer for command-injection vulnerabilities.
+   */
+  abstract class Sanitizer extends DataFlow::Node { }
+
+  /** A source of remote user input, considered as a flow source for command injection. */
+  class RemoteFlowSourceAsSource extends Source {
+    RemoteFlowSourceAsSource() { this instanceof RemoteFlowSource }
+
+    override string getSourceType() { result = "a user-provided value" }
+  }
+
+  /**
+   * A command argument to a function that initiates an operating system command.
+   */
+  class SystemCommandExecutionSink extends Sink {
+    SystemCommandExecutionSink() { exists(SystemCommandExecution c | c.isShellInterpreted(this)) }
+  }
+
+  /**
+   * A call to `Shellwords.escape` or `Shellwords.shellescape` sanitizes its input.
+   */
+  class ShellwordsEscapeAsSanitizer extends Sanitizer {
+    ShellwordsEscapeAsSanitizer() {
+      this = API::getTopLevelMember("Shellwords").getAMethodCall(["escape", "shellescape"])
+    }
+  }
+}

ql/lib/codeql/ruby/security/CommandInjectionQuery.qll

@@ -0,0 +1,32 @@
+/**
+ * Provides a taint tracking configuration for reasoning about
+ * command-injection vulnerabilities (CWE-078).
+ *
+ * Note, for performance reasons: only import this file if
+ * `CommandInjection::Configuration` is needed, otherwise
+ * `CommandInjectionCustomizations` should be imported instead.
+ */
+
+import ruby
+import codeql.ruby.TaintTracking
+import CommandInjectionCustomizations::CommandInjection
+import codeql.ruby.DataFlow
+import codeql.ruby.dataflow.BarrierGuards
+
+/**
+ * A taint-tracking configuration for reasoning about command-injection vulnerabilities.
+ */
+class Configuration extends TaintTracking::Configuration {
+  Configuration() { this = "CommandInjection" }
+
+  override predicate isSource(DataFlow::Node source) { source instanceof Source }
+
+  override predicate isSink(DataFlow::Node sink) { sink instanceof Sink }
+
+  override predicate isSanitizer(DataFlow::Node node) { node instanceof Sanitizer }
+
+  override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+    guard instanceof StringConstCompare or
+    guard instanceof StringConstArrayInclusionCall
+  }
+}