Merge pull request #92 from microsoft/powershell-dataflow-skeleton

PS: Add dataflow skeleton

Author: MathiasVP

powershell/ql/lib/qlpack.yml

@@ -9,4 +9,6 @@ library: true
 upgrades: upgrades
 dependencies:
   codeql/controlflow: ${workspace}
+  codeql/dataflow: ${workspace}
+  codeql/util: ${workspace}
 warnOnImplicitThis: true

powershell/ql/lib/semmle/code/powershell/controlflow/CfgNodes.qll

@@ -48,5 +48,28 @@ class ExprCfgNode extends AstCfgNode {
   Expr getExpr() { result = e }
 }
 
+/** A control-flow node that wraps an AST statement. */
+class StmtCfgNode extends AstCfgNode {
+  override string getAPrimaryQlClass() { result = "StmtCfgNode" }
+
+  Stmt s;
+
+  StmtCfgNode() { s = this.getAstNode() }
+
+  /** Gets the underlying expression. */
+  Stmt getStmt() { result = s }
+}
+
 /** Provides classes for control-flow nodes that wrap AST expressions. */
 module ExprNodes { }
+
+module StmtNodes {
+  /** A control-flow node that wraps a `Cmd` AST expression. */
+  class CallCfgNode extends StmtCfgNode {
+    override string getAPrimaryQlClass() { result = "CallCfgNode" }
+
+    override Cmd s;
+
+    override Cmd getStmt() { result = super.getStmt() }
+  }
+}

powershell/ql/lib/semmle/code/powershell/dataflow/DataFlow.qll

@@ -0,0 +1,13 @@
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+
+import powershell
+
+module DataFlow {
+  private import internal.DataFlowImplSpecific
+  private import codeql.dataflow.DataFlow
+  import DataFlowMake<Location, PowershellDataFlow>
+  import internal.DataFlowImpl
+}

powershell/ql/lib/semmle/code/powershell/dataflow/internal/DataFlowDispatch.qll

@@ -0,0 +1,203 @@
+private import powershell
+private import semmle.code.powershell.Cfg
+private import DataFlowPrivate
+private import codeql.util.Boolean
+private import codeql.util.Unit
+
+newtype TReturnKind = TNormalReturnKind()
+
+/**
+ * Gets a node that can read the value returned from `call` with return kind
+ * `kind`.
+ */
+OutNode getAnOutNode(DataFlowCall call, ReturnKind kind) { call = result.getCall(kind) }
+
+/**
+ * A return kind. A return kind describes how a value can be returned
+ * from a callable.
+ */
+abstract class ReturnKind extends TReturnKind {
+  /** Gets a textual representation of this position. */
+  abstract string toString();
+}
+
+/**
+ * A value returned from a callable using a `return` statement or an expression
+ * body, that is, a "normal" return.
+ */
+class NormalReturnKind extends ReturnKind, TNormalReturnKind {
+  override string toString() { result = "return" }
+}
+
+/** A callable defined in library code, identified by a unique string. */
+abstract class LibraryCallable extends string {
+  bindingset[this]
+  LibraryCallable() { any() }
+
+  /** Gets a call to this library callable. */
+  Cmd getACall() { none() }
+}
+
+/**
+ * A callable. This includes callables from source code, as well as callables
+ * defined in library code.
+ */
+class DataFlowCallable extends TDataFlowCallable {
+  /**
+   * Gets the underlying CFG scope, if any.
+   *
+   * This is usually a `Callable`, but can also be a `Toplevel` file.
+   */
+  CfgScope asCfgScope() { this = TCfgScope(result) }
+
+  /** Gets the underlying library callable, if any. */
+  LibraryCallable asLibraryCallable() { this = TLibraryCallable(result) }
+
+  /** Gets a textual representation of this callable. */
+  string toString() { result = [this.asCfgScope().toString(), this.asLibraryCallable()] }
+
+  /** Gets the location of this callable. */
+  Location getLocation() {
+    result = this.asCfgScope().getLocation()
+    or
+    this instanceof TLibraryCallable and
+    result instanceof EmptyLocation
+  }
+
+  /** Gets a best-effort total ordering. */
+  int totalorder() { none() }
+}
+
+/**
+ * A call. This includes calls from source code, as well as call(back)s
+ * inside library callables with a flow summary.
+ */
+abstract class DataFlowCall extends TDataFlowCall {
+  /** Gets the enclosing callable. */
+  abstract DataFlowCallable getEnclosingCallable();
+
+  /** Gets the underlying source code call, if any. */
+  abstract CfgNodes::StmtNodes::CallCfgNode asCall();
+
+  /** Gets a textual representation of this call. */
+  abstract string toString();
+
+  /** Gets the location of this call. */
+  abstract Location getLocation();
+
+  DataFlowCallable getARuntimeTarget() { none() }
+
+  ArgumentNode getAnArgumentNode() { none() }
+
+  /** Gets a best-effort total ordering. */
+  int totalorder() { none() }
+
+  /**
+   * Holds if this element is at the specified location.
+   * The location spans column `startcolumn` of line `startline` to
+   * column `endcolumn` of line `endline` in file `filepath`.
+   * For more information, see
+   * [Locations](https://codeql.github.com/docs/writing-codeql-queries/providing-locations-in-codeql-queries).
+   */
+  predicate hasLocationInfo(
+    string filepath, int startline, int startcolumn, int endline, int endcolumn
+  ) {
+    this.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
+  }
+}
+
+class NormalCall extends DataFlowCall, TNormalCall {
+  private CfgNodes::StmtNodes::CallCfgNode c;
+
+  NormalCall() { this = TNormalCall(c) }
+
+  override CfgNodes::StmtNodes::CallCfgNode asCall() { result = c }
+
+  override DataFlowCallable getEnclosingCallable() { result = TCfgScope(c.getScope()) }
+
+  override string toString() { result = c.toString() }
+
+  override Location getLocation() { result = c.getLocation() }
+}
+
+/** A call for which we want to compute call targets. */
+private class RelevantCall extends CfgNodes::StmtNodes::CallCfgNode { }
+
+/** Holds if `call` may resolve to the returned source-code method. */
+private DataFlowCallable viableSourceCallable(DataFlowCall call) {
+  none() // TODO
+  or
+  result = any(AdditionalCallTarget t).viableTarget(call.asCall())
+}
+
+/**
+ * A unit class for adding additional call steps.
+ *
+ * Extend this class to add additional call steps to the data flow graph.
+ */
+class AdditionalCallTarget extends Unit {
+  /**
+   * Gets a viable target for `call`.
+   */
+  abstract DataFlowCallable viableTarget(CfgNodes::StmtNodes::CallCfgNode call);
+}
+
+/** Holds if `call` may resolve to the returned summarized library method. */
+DataFlowCallable viableLibraryCallable(DataFlowCall call) {
+  exists(LibraryCallable callable |
+    result = TLibraryCallable(callable) and
+    call.asCall().getStmt() = callable.getACall()
+  )
+}
+
+cached
+private module Cached {
+  cached
+  newtype TDataFlowCallable =
+    TCfgScope(CfgScope scope) or
+    TLibraryCallable(LibraryCallable callable)
+
+  cached
+  newtype TDataFlowCall = TNormalCall(CfgNodes::StmtNodes::CallCfgNode c)
+
+  /** Gets a viable run-time target for the call `call`. */
+  cached
+  DataFlowCallable viableCallable(DataFlowCall call) {
+    result = viableSourceCallable(call)
+    or
+    result = viableLibraryCallable(call)
+  }
+
+  cached
+  newtype TArgumentPosition =
+    TPositionalArgumentPosition(int pos) { exists(Cmd c | exists(c.getArgument(pos))) }
+
+  cached
+  newtype TParameterPosition = TPositionalParameterPosition(int pos) { none() /* TODO */ }
+}
+
+import Cached
+
+/** A parameter position. */
+class ParameterPosition extends TParameterPosition {
+  /** Holds if this position represents a positional parameter at position `pos`. */
+  predicate isPositional(int pos) { this = TPositionalParameterPosition(pos) }
+
+  /** Gets a textual representation of this position. */
+  string toString() { exists(int pos | this.isPositional(pos) and result = "position " + pos) }
+}
+
+/** An argument position. */
+class ArgumentPosition extends TArgumentPosition {
+  /** Holds if this position represents a positional argument at position `pos`. */
+  predicate isPositional(int pos) { this = TPositionalArgumentPosition(pos) }
+
+  /** Gets a textual representation of this position. */
+  string toString() { exists(int pos | this.isPositional(pos) and result = "position " + pos) }
+}
+
+/** Holds if arguments at position `apos` match parameters at position `ppos`. */
+pragma[nomagic]
+predicate parameterMatch(ParameterPosition ppos, ArgumentPosition apos) {
+  exists(int pos | ppos.isPositional(pos) and apos.isPositional(pos))
+}

powershell/ql/lib/semmle/code/powershell/dataflow/internal/DataFlowImpl.qll

@@ -0,0 +1,4 @@
+private import DataFlowImplCommon
+private import DataFlowImplSpecific::Private
+import DataFlowImplSpecific::Public
+import DataFlowImplCommonPublic

powershell/ql/lib/semmle/code/powershell/dataflow/internal/DataFlowImplCommon.qll

@@ -0,0 +1,4 @@
+private import powershell
+private import DataFlowImplSpecific
+private import codeql.dataflow.internal.DataFlowImplCommon
+import MakeImplCommon<Location, PowershellDataFlow>

powershell/ql/lib/semmle/code/powershell/dataflow/internal/DataFlowImplSpecific.qll

@@ -0,0 +1,24 @@
+/**
+ * Provides Powershell-specific definitions for use in the data flow library.
+ */
+
+private import powershell
+private import codeql.dataflow.DataFlow
+
+module Private {
+  import DataFlowPrivate
+  import DataFlowDispatch
+}
+
+module Public {
+  import DataFlowPublic
+}
+
+module PowershellDataFlow implements InputSig<Location> {
+  import Private
+  import Public
+
+  class ParameterNode = Private::ParameterNodeImpl;
+
+  Node exprNode(DataFlowExpr e) { result = Public::exprNode(e) }
+}