Merge pull request #9 from GitHubSecurityLab/content_set

feat(field-flow): enhance dataflow tracking

Author: Alvaro Muñoz

ql/lib/codeql/actions/Ast.qll

@@ -95,6 +95,8 @@ class OutputsStmt extends Statement instanceof YamlMapping {
     this.(YamlMapping).lookup(name).(YamlMapping).lookup("value") = result or
     this.(YamlMapping).lookup(name) = result
   }
+
+  string getAnOutputName() { this.(YamlMapping).maps(any(YamlString s | s.getValue() = result), _) }
 }
 
 class InputExpr extends Expression instanceof YamlString {
@@ -158,6 +160,10 @@ class JobStmt extends Statement instanceof Actions::Job {
    *     arg1: value1
    */
   JobUsesExpr getUsesExpr() { result.getJobStmt() = this }
+
+  predicate usesReusableWorkflow() {
+    this.(YamlMapping).maps(any(YamlString s | s.getValue() = "uses"), _)
+  }
 }
 
 /**
@@ -353,106 +359,164 @@ class ExprAccessExpr extends Expression instanceof YamlString {
   string getExpression() { result = expr }
 
   JobStmt getJobStmt() { result.getAChildNode*() = this }
+}
+
+/**
+ * A context access expression.
+ * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
+ */
+class CtxAccessExpr extends ExprAccessExpr {
+  CtxAccessExpr() {
+    expr.regexpMatch([
+        stepsCtxRegex(), needsCtxRegex(), jobsCtxRegex(), envCtxRegex(), inputsCtxRegex()
+      ])
+  }
+
+  abstract string getFieldName();
 
   abstract Expression getRefExpr();
 }
 
+private string stepsCtxRegex() { result = "steps\\.([A-Za-z0-9_-]+)\\.outputs\\.([A-Za-z0-9_-]+)" }
+
+private string needsCtxRegex() { result = "needs\\.([A-Za-z0-9_-]+)\\.outputs\\.([A-Za-z0-9_-]+)" }
+
+private string jobsCtxRegex() { result = "jobs\\.([A-Za-z0-9_-]+)\\.outputs\\.([A-Za-z0-9_-]+)" }
+
+private string envCtxRegex() { result = "env\\.([A-Za-z0-9_-]+)" }
+
+private string inputsCtxRegex() { result = "inputs\\.([A-Za-z0-9_-]+)" }
+
 /**
- * Holds for an ExprAccessExpr accesing the `steps` context.
+ * Holds for an expression accesing the `steps` context.
  * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
  * e.g. `${{ steps.changed-files.outputs.all_changed_files }}`
  */
-class StepOutputAccessExpr extends ExprAccessExpr {
+class StepsCtxAccessExpr extends CtxAccessExpr {
   string stepId;
-  string varName;
+  string fieldName;
 
-  StepOutputAccessExpr() {
-    stepId =
-      this.getExpression().regexpCapture("steps\\.([A-Za-z0-9_-]+)\\.outputs\\.[A-Za-z0-9_-]+", 1) and
-    varName =
-      this.getExpression().regexpCapture("steps\\.[A-Za-z0-9_-]+\\.outputs\\.([A-Za-z0-9_-]+)", 1)
+  StepsCtxAccessExpr() {
+    expr.regexpMatch(stepsCtxRegex()) and
+    stepId = expr.regexpCapture(stepsCtxRegex(), 1) and
+    fieldName = expr.regexpCapture(stepsCtxRegex(), 2)
   }
 
+  override string getFieldName() { result = fieldName }
+
   override Expression getRefExpr() {
     this.getLocation().getFile() = result.getLocation().getFile() and
     result.(StepStmt).getId() = stepId
   }
 }
 
 /**
- * Holds for an ExprAccessExpr accesing the `needs` or `job` contexts.
+ * Holds for an expression accesing the `needs` context.
+ * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
+ * e.g. `${{ needs.job1.outputs.foo}}`
+ */
+class NeedsCtxAccessExpr extends CtxAccessExpr {
+  JobStmt job;
+  string jobId;
+  string fieldName;
+
+  NeedsCtxAccessExpr() {
+    expr.regexpMatch(needsCtxRegex()) and
+    jobId = expr.regexpCapture(needsCtxRegex(), 1) and
+    fieldName = expr.regexpCapture(needsCtxRegex(), 2) and
+    job.getId() = jobId
+  }
+
+  predicate usesReusableWorkflow() { job.usesReusableWorkflow() }
+
+  override string getFieldName() { result = fieldName }
+
+  override Expression getRefExpr() {
+    job.getLocation().getFile() = this.getLocation().getFile() and
+    (
+      // regular jobs
+      job.getOutputStmt().getOutputExpr(fieldName) = result
+      or
+      // jobs calling reusable workflows
+      job.getUsesExpr() = result
+    )
+  }
+}
+
+/**
+ * Holds for an expression accesing the `jobs` context.
  * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
- * e.g. `${{ needs.job1.outputs.foo}}` or `${{ jobs.job1.outputs.foo}}` (for reusable workflows)
+ * e.g. `${{ jobs.job1.outputs.foo}}` (within reusable workflows)
  */
-class JobOutputAccessExpr extends ExprAccessExpr {
+class JobsCtxAccessExpr extends CtxAccessExpr {
   string jobId;
-  string varName;
-
-  JobOutputAccessExpr() {
-    jobId =
-      this.getExpression()
-          .regexpCapture("(needs|jobs)\\.([A-Za-z0-9_-]+)\\.outputs\\.[A-Za-z0-9_-]+", 2) and
-    varName =
-      this.getExpression()
-          .regexpCapture("(needs|jobs)\\.[A-Za-z0-9_-]+\\.outputs\\.([A-Za-z0-9_-]+)", 2)
+  string fieldName;
+
+  JobsCtxAccessExpr() {
+    expr.regexpMatch(jobsCtxRegex()) and
+    jobId = expr.regexpCapture(jobsCtxRegex(), 1) and
+    fieldName = expr.regexpCapture(jobsCtxRegex(), 2)
   }
 
+  override string getFieldName() { result = fieldName }
+
   override Expression getRefExpr() {
     exists(JobStmt job |
       job.getId() = jobId and
       job.getLocation().getFile() = this.getLocation().getFile() and
-      (
-        // A Job can have multiple outputs, so we need to check both
-        // jobs.<job_id>.outputs.<output_name>
-        job.getOutputStmt().getOutputExpr(varName) = result
-        or
-        // jobs.<job_id>.uses (variables returned from the reusable workflow
-        job.getUsesExpr() = result
-      )
+      job.getOutputStmt().getOutputExpr(fieldName) = result
     )
   }
 }
 
 /**
- * Holds for an ExprAccessExpr accesing the `inputs` context.
+ * Holds for an expression the `inputs` context.
  * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
  * e.g. `${{ inputs.foo }}`
  */
-class InputAccessExpr extends ExprAccessExpr {
-  string paramName;
+class InputsCtxAccessExpr extends CtxAccessExpr {
+  string fieldName;
 
-  InputAccessExpr() {
-    paramName = this.getExpression().regexpCapture("inputs\\.([A-Za-z0-9_-]+)", 1)
+  InputsCtxAccessExpr() {
+    expr.regexpMatch(inputsCtxRegex()) and
+    fieldName = expr.regexpCapture(inputsCtxRegex(), 1)
   }
 
+  override string getFieldName() { result = fieldName }
+
   override Expression getRefExpr() {
     exists(ReusableWorkflowStmt w |
       w.getLocation().getFile() = this.getLocation().getFile() and
-      w.getInputsStmt().getInputExpr(paramName) = result
+      w.getInputsStmt().getInputExpr(fieldName) = result
     )
     or
     exists(CompositeActionStmt a |
       a.getLocation().getFile() = this.getLocation().getFile() and
-      a.getInputsStmt().getInputExpr(paramName) = result
+      a.getInputsStmt().getInputExpr(fieldName) = result
     )
   }
 }
 
 /**
- * Holds for an ExprAccessExpr accesing the `env` context.
+ * Holds for an expression accesing the `env` context.
  * https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability
  * e.g. `${{ env.foo }}`
  */
-class EnvAccessExpr extends ExprAccessExpr {
-  string varName;
+class EnvCtxAccessExpr extends CtxAccessExpr {
+  string fieldName;
+
+  EnvCtxAccessExpr() {
+    expr.regexpMatch(envCtxRegex()) and
+    fieldName = expr.regexpCapture(envCtxRegex(), 1)
+  }
 
-  EnvAccessExpr() { varName = this.getExpression().regexpCapture("env\\.([A-Za-z0-9_-]+)", 1) }
+  override string getFieldName() { result = fieldName }
 
   override Expression getRefExpr() {
-    exists(JobUsesExpr s | s.getEnvExpr(varName) = result)
+    exists(JobUsesExpr s | s.getEnvExpr(fieldName) = result)
     or
-    exists(StepUsesExpr s | s.getEnvExpr(varName) = result)
+    exists(StepUsesExpr s | s.getEnvExpr(fieldName) = result)
     or
-    exists(RunExpr s | s.getEnvExpr(varName) = result)
+    exists(RunExpr s | s.getEnvExpr(fieldName) = result)
   }
 }

ql/lib/codeql/actions/ast/internal/Actions.qll

@@ -294,8 +294,10 @@ module Actions {
     /** Gets the owner and name of the repository where the Action comes from, e.g. `actions/checkout` in `actions/checkout@v2`. */
     string getGitHubRepository() {
       result =
-        this.getValue().regexpCapture(usesParser(), 1) + "/" +
-          this.getValue().regexpCapture(usesParser(), 2)
+        (
+          this.getValue().regexpCapture(usesParser(), 1) + "/" +
+            this.getValue().regexpCapture(usesParser(), 2)
+        ).toLowerCase()
     }
 
     /** Gets the version reference used when checking out the Action, e.g. `v2` in `actions/checkout@v2`. */

ql/lib/codeql/actions/dataflow/ExternalFlow.qll

@@ -2,21 +2,31 @@ private import internal.ExternalFlowExtensions as Extensions
 import codeql.actions.DataFlow
 import actions
 
-/** Holds if a source model exists for the given parameters. */
+/**
+ * MaD sources
+ * Fields:
+ *    - action: Fully-qualified action name (NWO)
+ *    - version: Either '*' or a specific SHA/Tag
+ *    - output arg: To node (prefixed with either `env.` or `output.`)
+ *    - trigger: Triggering event under which this model introduces tainted data. Use `*` for any event.
+ */
 predicate sourceModel(string action, string version, string output, string trigger, string kind) {
   Extensions::sourceModel(action, version, output, trigger, kind)
 }
 
-/** Holds if a sink model exists for the given parameters. */
+/**
+ * MaD summaries
+ * Fields:
+ *    - action: Fully-qualified action name (NWO)
+ *    - version: Either '*' or a specific SHA/Tag
+ *    - input arg: From node (prefixed with either `env.` or `input.`)
+ *    - output arg: To node (prefixed with either `env.` or `output.`)
+ *    - kind: Either 'Taint' or 'Value'
+ */
 predicate summaryModel(string action, string version, string input, string output, string kind) {
   Extensions::summaryModel(action, version, input, output, kind)
 }
 
-/** Holds if a sink model exists for the given parameters. */
-predicate sinkModel(string action, string version, string input, string kind) {
-  Extensions::sinkModel(action, version, input, kind)
-}
-
 /**
  * MaD sinks
  * Fields:
@@ -25,15 +35,63 @@ predicate sinkModel(string action, string version, string input, string kind) {
  *    - input arg: sink node (prefixed with either `env.` or `input.`)
  *    - kind: sink kind
  */
-predicate sinkNode(DataFlow::ExprNode sink, string kind) {
+predicate sinkModel(string action, string version, string input, string kind) {
+  Extensions::sinkModel(action, version, input, kind)
+}
+
+predicate externallyDefinedSource(DataFlow::Node source, string sourceType, string fieldName) {
+  exists(UsesExpr uses, string action, string version, string trigger, string kind |
+    sourceModel(action, version, fieldName, trigger, kind) and
+    uses.getCallee() = action.toLowerCase() and
+    (
+      if version.trim() = "*"
+      then uses.getVersion() = any(string v)
+      else uses.getVersion() = version.trim()
+    ) and
+    (
+      if fieldName.trim().matches("env.%")
+      then source.asExpr() = uses.getEnvExpr(fieldName.trim().replaceAll("env\\.", ""))
+      else
+        if fieldName.trim().matches("output.%")
+        then
+          // 'output.' is the default qualifier
+          source.asExpr() = uses
+        else none()
+    ) and
+    sourceType = kind
+  )
+}
+
+predicate externallyDefinedSummary(DataFlow::Node pred, DataFlow::Node succ, DataFlow::ContentSet c) {
+  exists(UsesExpr uses, string action, string version, string input, string output |
+    c = any(DataFlow::FieldContent ct | ct.getName() = output.replaceAll("output\\.", "")) and
+    summaryModel(action, version, input, output, "taint") and
+    uses.getCallee() = action.toLowerCase() and
+    (
+      if version.trim() = "*"
+      then uses.getVersion() = any(string v)
+      else uses.getVersion() = version.trim()
+    ) and
+    (
+      if input.trim().matches("env.%")
+      then pred.asExpr() = uses.getEnvExpr(input.trim().replaceAll("env\\.", ""))
+      else
+        // 'input.' is the default qualifier
+        pred.asExpr() = uses.getArgumentExpr(input.trim().replaceAll("input\\.", ""))
+    ) and
+    succ.asExpr() = uses
+  )
+}
+
+predicate externallyDefinedSink(DataFlow::ExprNode sink, string kind) {
   exists(UsesExpr uses, string action, string version, string input |
     (
       if input.trim().matches("env.%")
       then sink.asExpr() = uses.getEnvExpr(input.trim().replaceAll("input\\.", ""))
       else sink.asExpr() = uses.getArgumentExpr(input.trim())
     ) and
     sinkModel(action, version, input, kind) and
-    uses.getCallee() = action and
+    uses.getCallee() = action.toLowerCase() and
     (
       if version.trim() = "*"
       then uses.getVersion() = any(string v)

ql/lib/codeql/actions/dataflow/FlowSources.qll

@@ -126,40 +126,14 @@ private class EventSource extends RemoteFlowSource {
 }
 
 /**
- * MaD sources
- * Fields:
- *    - action: Fully-qualified action name (NWO)
- *    - version: Either '*' or a specific SHA/Tag
- *    - output arg: To node (prefixed with either `env.` or `output.`)
- *    - trigger: Triggering event under which this model introduces tainted data. Use `*` for any event.
+ * A Source of untrusted data defined in a MaD specification
  */
 private class ExternallyDefinedSource extends RemoteFlowSource {
-  string soutceType;
-
-  ExternallyDefinedSource() {
-    exists(
-      UsesExpr uses, string action, string version, string output, string trigger, string kind
-    |
-      sourceModel(action, version, output, trigger, kind) and
-      uses.getCallee() = action and
-      (
-        if version.trim() = "*"
-        then uses.getVersion() = any(string v)
-        else uses.getVersion() = version.trim()
-      ) and
-      (
-        if output.trim().matches("env.%")
-        then this.asExpr() = uses.getEnvExpr(output.trim().replaceAll("output\\.", ""))
-        else
-          // 'output.' is the default qualifier
-          // TODO: Taint just the specified output
-          this.asExpr() = uses
-      ) and
-      soutceType = kind
-    )
-  }
+  string sourceType;
+
+  ExternallyDefinedSource() { externallyDefinedSource(this, sourceType, _) }
 
-  override string getSourceType() { result = soutceType }
+  override string getSourceType() { result = sourceType }
 }
 
 /**