Merge pull request #84 from microsoft/powershell-cfg-skeleton

PS: Initial CFG skeleton

Author: MathiasVP

powershell/ql/lib/qlpack.yml

@@ -6,4 +6,6 @@ groups:
 dbscheme: semmlecode.powershell.dbscheme
 extractor: powershell
 library: true
+dependencies:
+  codeql/controlflow: ${workspace}
 warnOnImplicitThis: true

powershell/ql/lib/semmle/code/powershell/AssignmentStatement.qll

@@ -9,5 +9,5 @@ class AssignStmt extends @assignment_statement, Stmt {
 
   Stmt getRightHandSide() { assignment_statement(this, _, _, result) }
 
-  override string toString() { result = "AssignmentStatement at: " + this.getLocation().toString() }
+  override string toString() { result = "...=..." }
 }

powershell/ql/lib/semmle/code/powershell/Ast.qll

@@ -3,7 +3,7 @@ import powershell
 class Ast extends @ast {
   string toString() { none() }
 
-  Ast getParent() { parent(result, this) }
+  Ast getParent() { parent(this, result) } // TODO: Flip parent and child in relation in the extractor
 
   Location getLocation() { none() }
 }

powershell/ql/lib/semmle/code/powershell/Cfg.qll

@@ -0,0 +1,5 @@
+/** Provides classes representing the control flow graph. */
+
+import controlflow.ControlFlowGraph
+import controlflow.CfgNodes as CfgNodes
+import controlflow.BasicBlocks

powershell/ql/lib/semmle/code/powershell/CommandExpression.qll

@@ -3,13 +3,13 @@ import powershell
 class CmdExpr extends @command_expression, CmdBase {
   override SourceLocation getLocation() { command_expression_location(this, result) }
 
-  Expr getExpression() { command_expression(this, result, _) }
+  Expr getExpr() { command_expression(this, result, _) }
 
   int getNumRedirections() { command_expression(this, _, result) }
 
   Redirection getRedirection(int i) { command_expression_redirection(this, i, result) }
 
   Redirection getARedirection() { result = this.getRedirection(_) }
 
-  override string toString() { result = "CommandExpression at: " + this.getLocation().toString() }
+  override string toString() { result = this.getExpr().toString() }
 }

powershell/ql/lib/semmle/code/powershell/ConstantExpression.qll

@@ -7,5 +7,5 @@ class ConstExpr extends @constant_expression, BaseConstExpr {
 
   StringLiteral getValue() { constant_expression_value(this, result) }
 
-  override string toString() { result = "ConstantExpression at: " + this.getLocation().toString() }
+  override string toString() { result = this.getValue().toString() }
 }

powershell/ql/lib/semmle/code/powershell/ScriptBlock.qll

@@ -1,7 +1,7 @@
 import powershell
 
 class ScriptBlock extends @script_block, Ast {
-  override string toString() { result = "ScriptBlock at: " + this.getLocation().toString() }
+  override string toString() { result = this.getLocation().getFile().getBaseName() }
 
   override SourceLocation getLocation() { script_block_location(this, result) }
 

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

@@ -0,0 +1,259 @@
+/** Provides classes representing basic blocks. */
+
+private import powershell
+private import ControlFlowGraph
+private import CfgNodes
+private import SuccessorTypes
+
+/**
+ * A basic block, that is, a maximal straight-line sequence of control flow nodes
+ * without branches or joins.
+ */
+class BasicBlock extends TBasicBlockStart {
+  /** Gets the scope of this basic block. */
+  final CfgScope getScope() { result = this.getFirstNode().getScope() }
+
+  /** Gets an immediate successor of this basic block, if any. */
+  BasicBlock getASuccessor() { result = this.getASuccessor(_) }
+
+  /** Gets an immediate successor of this basic block of a given type, if any. */
+  BasicBlock getASuccessor(SuccessorType t) {
+    result.getFirstNode() = this.getLastNode().getASuccessor(t)
+  }
+
+  /** Gets an immediate predecessor of this basic block, if any. */
+  BasicBlock getAPredecessor() { result.getASuccessor() = this }
+
+  /** Gets an immediate predecessor of this basic block of a given type, if any. */
+  BasicBlock getAPredecessor(SuccessorType t) { result.getASuccessor(t) = this }
+
+  /** Gets the control flow node at a specific (zero-indexed) position in this basic block. */
+  CfgNode getNode(int pos) { bbIndex(this.getFirstNode(), result, pos) }
+
+  /** Gets a control flow node in this basic block. */
+  CfgNode getANode() { result = this.getNode(_) }
+
+  /** Gets the first control flow node in this basic block. */
+  CfgNode getFirstNode() { this = TBasicBlockStart(result) }
+
+  /** Gets the last control flow node in this basic block. */
+  CfgNode getLastNode() { result = this.getNode(this.length() - 1) }
+
+  /** Gets the length of this basic block. */
+  int length() { result = strictcount(this.getANode()) }
+
+  /**
+   * Holds if this basic block immediately dominates basic block `bb`.
+   *
+   * That is, all paths reaching basic block `bb` from some entry point
+   * basic block must go through this basic block (which is an immediate
+   * predecessor of `bb`).
+   */
+  predicate immediatelyDominates(BasicBlock bb) { bbIDominates(this, bb) }
+
+  /**
+   * Holds if this basic block strictly dominates basic block `bb`.
+   *
+   * That is, all paths reaching basic block `bb` from some entry point
+   * basic block must go through this basic block (which must be different
+   * from `bb`).
+   */
+  predicate strictlyDominates(BasicBlock bb) { bbIDominates+(this, bb) }
+
+  /**
+   * Holds if this basic block dominates basic block `bb`.
+   *
+   * That is, all paths reaching basic block `bb` from some entry point
+   * basic block must go through this basic block.
+   */
+  predicate dominates(BasicBlock bb) {
+    bb = this or
+    this.strictlyDominates(bb)
+  }
+
+  /**
+   * Holds if `df` is in the dominance frontier of this basic block.
+   * That is, this basic block dominates a predecessor of `df`, but
+   * does not dominate `df` itself.
+   */
+  predicate inDominanceFrontier(BasicBlock df) {
+    this.dominatesPredecessor(df) and
+    not this.strictlyDominates(df)
+  }
+
+  /**
+   * Holds if this basic block dominates a predecessor of `df`.
+   */
+  private predicate dominatesPredecessor(BasicBlock df) { this.dominates(df.getAPredecessor()) }
+
+  /**
+   * Gets the basic block that immediately dominates this basic block, if any.
+   *
+   * That is, all paths reaching this basic block from some entry point
+   * basic block must go through the result, which is an immediate basic block
+   * predecessor of this basic block.
+   */
+  BasicBlock getImmediateDominator() { bbIDominates(result, this) }
+
+  /**
+   * Holds if this basic block strictly post-dominates basic block `bb`.
+   *
+   * That is, all paths reaching a normal exit point basic block from basic
+   * block `bb` must go through this basic block (which must be different
+   * from `bb`).
+   */
+  predicate strictlyPostDominates(BasicBlock bb) { bbIPostDominates+(this, bb) }
+
+  /**
+   * Holds if this basic block post-dominates basic block `bb`.
+   *
+   * That is, all paths reaching a normal exit point basic block from basic
+   * block `bb` must go through this basic block.
+   */
+  predicate postDominates(BasicBlock bb) {
+    this.strictlyPostDominates(bb) or
+    this = bb
+  }
+
+  /** Holds if this basic block is in a loop in the control flow graph. */
+  predicate inLoop() { this.getASuccessor+() = this }
+
+  /** Gets a textual representation of this basic block. */
+  string toString() { result = this.getFirstNode().toString() }
+
+  /** Gets the location of this basic block. */
+  Location getLocation() { result = this.getFirstNode().getLocation() }
+}
+
+cached
+private module Cached {
+  /** Internal representation of basic blocks. */
+  cached
+  newtype TBasicBlock = TBasicBlockStart(CfgNode cfn) { startsBB(cfn) }
+
+  /** Holds if `cfn` starts a new basic block. */
+  private predicate startsBB(CfgNode cfn) {
+    not exists(cfn.getAPredecessor()) and exists(cfn.getASuccessor())
+    or
+    cfn.isJoin()
+    or
+    cfn.getAPredecessor().isBranch()
+    or
+    exists(cfn.getAPredecessor(any(SuccessorTypes::ConditionalSuccessor s)))
+  }
+
+  /**
+   * Holds if `succ` is a control flow successor of `pred` within
+   * the same basic block.
+   */
+  private predicate intraBBSucc(CfgNode pred, CfgNode succ) {
+    succ = pred.getASuccessor() and
+    not startsBB(succ)
+  }
+
+  /**
+   * Holds if `cfn` is the `i`th node in basic block `bb`.
+   *
+   * In other words, `i` is the shortest distance from a node `bb`
+   * that starts a basic block to `cfn` along the `intraBBSucc` relation.
+   */
+  cached
+  predicate bbIndex(CfgNode bbStart, CfgNode cfn, int i) =
+    shortestDistances(startsBB/1, intraBBSucc/2)(bbStart, cfn, i)
+
+  /**
+   * Holds if the first node of basic block `succ` is a control flow
+   * successor of the last node of basic block `pred`.
+   */
+  private predicate succBB(BasicBlock pred, BasicBlock succ) { succ = pred.getASuccessor() }
+
+  /** Holds if `dom` is an immediate dominator of `bb`. */
+  cached
+  predicate bbIDominates(BasicBlock dom, BasicBlock bb) =
+    idominance(entryBB/1, succBB/2)(_, dom, bb)
+
+  /** Holds if `pred` is a basic block predecessor of `succ`. */
+  private predicate predBB(BasicBlock succ, BasicBlock pred) { succBB(pred, succ) }
+
+  /** Holds if `bb` is an exit basic block that represents normal exit. */
+  private predicate normalExitBB(BasicBlock bb) { bb.getANode().(AnnotatedExitNode).isNormal() }
+
+  /** Holds if `dom` is an immediate post-dominator of `bb`. */
+  cached
+  predicate bbIPostDominates(BasicBlock dom, BasicBlock bb) =
+    idominance(normalExitBB/1, predBB/2)(_, dom, bb)
+
+  cached
+  predicate immediatelyControls(ConditionBlock cb, BasicBlock succ, ConditionalSuccessor s) {
+    succ = cb.getASuccessor(s) and
+    forall(BasicBlock pred | pred = succ.getAPredecessor() and pred != cb | succ.dominates(pred))
+  }
+
+  cached
+  predicate controls(ConditionBlock cb, BasicBlock controlled, ConditionalSuccessor s) {
+    exists(BasicBlock succ | cb.immediatelyControls(succ, s) | succ.dominates(controlled))
+  }
+}
+
+private import Cached
+
+/** Holds if `bb` is an entry basic block. */
+private predicate entryBB(BasicBlock bb) { bb.getFirstNode() instanceof EntryNode }
+
+/**
+ * An entry basic block, that is, a basic block whose first node is
+ * an entry node.
+ */
+class EntryBasicBlock extends BasicBlock {
+  EntryBasicBlock() { entryBB(this) }
+}
+
+/**
+ * An annotated exit basic block, that is, a basic block whose last node is
+ * an annotated exit node.
+ */
+class AnnotatedExitBasicBlock extends BasicBlock {
+  private boolean normal;
+
+  AnnotatedExitBasicBlock() {
+    exists(AnnotatedExitNode n |
+      n = this.getANode() and
+      if n.isNormal() then normal = true else normal = false
+    )
+  }
+
+  /** Holds if this block represent a normal exit. */
+  final predicate isNormal() { normal = true }
+}
+
+/**
+ * An exit basic block, that is, a basic block whose last node is
+ * an exit node.
+ */
+class ExitBasicBlock extends BasicBlock {
+  ExitBasicBlock() { this.getLastNode() instanceof ExitNode }
+}
+
+/** A basic block that terminates in a condition, splitting the subsequent control flow. */
+class ConditionBlock extends BasicBlock {
+  ConditionBlock() { this.getLastNode().isCondition() }
+
+  /**
+   * Holds if basic block `succ` is immediately controlled by this basic
+   * block with conditional value `s`. That is, `succ` is an immediate
+   * successor of this block, and `succ` can only be reached from
+   * the callable entry point by going via the `s` edge out of this basic block.
+   */
+  predicate immediatelyControls(BasicBlock succ, ConditionalSuccessor s) {
+    immediatelyControls(this, succ, s)
+  }
+
+  /**
+   * Holds if basic block `controlled` is controlled by this basic block with
+   * conditional value `s`. That is, `controlled` can only be reached from
+   * the callable entry point by going via the `s` edge out of this basic block.
+   */
+  predicate controls(BasicBlock controlled, ConditionalSuccessor s) {
+    controls(this, controlled, s)
+  }
+}

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

@@ -0,0 +1,5 @@
+/** Provides classes representing the control flow graph. */
+
+import ControlFlowGraph
+import CfgNodes as CfgNodes
+import BasicBlocks

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

@@ -0,0 +1,52 @@
+/** Provides classes representing nodes in a control flow graph. */
+
+private import powershell
+private import BasicBlocks
+private import ControlFlowGraph
+private import internal.ControlFlowGraphImpl as CfgImpl
+
+/** An entry node for a given scope. */
+class EntryNode extends CfgNode, CfgImpl::EntryNode {
+  override string getAPrimaryQlClass() { result = "EntryNode" }
+
+  final override EntryBasicBlock getBasicBlock() { result = super.getBasicBlock() }
+}
+
+/** An exit node for a given scope, annotated with the type of exit. */
+class AnnotatedExitNode extends CfgNode, CfgImpl::AnnotatedExitNode {
+  override string getAPrimaryQlClass() { result = "AnnotatedExitNode" }
+
+  final override AnnotatedExitBasicBlock getBasicBlock() { result = super.getBasicBlock() }
+}
+
+/** An exit node for a given scope. */
+class ExitNode extends CfgNode, CfgImpl::ExitNode {
+  override string getAPrimaryQlClass() { result = "ExitNode" }
+}
+
+/**
+ * A node for an AST node.
+ *
+ * Each AST node maps to zero or more `AstCfgNode`s: zero when the node is unreachable
+ * (dead) code or not important for control flow, and multiple when there are different
+ * splits for the AST node.
+ */
+class AstCfgNode extends CfgNode, CfgImpl::AstCfgNode {
+  /** Gets the name of the primary QL class for this node. */
+  override string getAPrimaryQlClass() { result = "AstCfgNode" }
+}
+
+/** A control-flow node that wraps an AST expression. */
+class ExprCfgNode extends AstCfgNode {
+  override string getAPrimaryQlClass() { result = "ExprCfgNode" }
+
+  Expr e;
+
+  ExprCfgNode() { e = this.getAstNode() }
+
+  /** Gets the underlying expression. */
+  Expr getExpr() { result = e }
+}
+
+/** Provides classes for control-flow nodes that wrap AST expressions. */
+module ExprNodes { }