Static Information Flow Analysis.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Defaulting to user installation because normal site-packages is not writeable\n",
      "Processing /home/daniel/Dropbox/Uni/Vorlesungsmaterialien/Automated Debugging/staticinflowanalysis\n",
      "Requirement already satisfied: flake8>=3.7 in /home/daniel/.local/lib/python3.9/site-packages (from staticinflowanalysis==0.1.0) (3.8.4)\n",
      "Requirement already satisfied: importlib-metadata>=0.9 in /usr/lib/python3.9/site-packages (from staticinflowanalysis==0.1.0) (3.4.0)\n",
      "Requirement already satisfied: astor>=0.1 in /home/daniel/.local/lib/python3.9/site-packages (from staticinflowanalysis==0.1.0) (0.8.1)\n",
      "Requirement already satisfied: pycodestyle<2.7.0,>=2.6.0a1 in /home/daniel/.local/lib/python3.9/site-packages (from flake8>=3.7->staticinflowanalysis==0.1.0) (2.6.0)\n",
      "Requirement already satisfied: pyflakes<2.3.0,>=2.2.0 in /home/daniel/.local/lib/python3.9/site-packages (from flake8>=3.7->staticinflowanalysis==0.1.0) (2.2.0)\n",
      "Requirement already satisfied: mccabe<0.7.0,>=0.6.0 in /home/daniel/.local/lib/python3.9/site-packages (from flake8>=3.7->staticinflowanalysis==0.1.0) (0.6.1)\n",
      "Requirement already satisfied: zipp>=0.5 in /usr/lib/python3.9/site-packages (from importlib-metadata>=0.9->staticinflowanalysis==0.1.0) (3.4.1)\n",
      "Using legacy 'setup.py install' for staticinflowanalysis, since package 'wheel' is not installed.\n",
      "Installing collected packages: staticinflowanalysis\n",
      "  Attempting uninstall: staticinflowanalysis\n",
      "    Found existing installation: staticinflowanalysis 0.1.0\n",
      "    Uninstalling staticinflowanalysis-0.1.0:\n",
      "      Successfully uninstalled staticinflowanalysis-0.1.0\n",
      "    Running setup.py install for staticinflowanalysis ... \u001b[?25ldone\n",
      "\u001b[?25hSuccessfully installed staticinflowanalysis-0.1.0\n"
     ]
    }
   ],
   "source": [
    "!pip install ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Project 4: Static Information Flow Analysis using Hoare logic in and for Python\n",
    "\n",
    "Author: Daniel Gusenburger\n",
    "\n",
    "Student ID: 2544941\n",
    "\n",
    "**Note**: My teammate dropped out before we/I started with this project and after the teams had been fixed so I had to it as a single person project.\n",
    "\n",
    "## What is this ?\n",
    "\n",
    "This project was partly inspired by the _Program Analysis_ lecture by Prof. Dr. Jan Reineke from Saarland University as well as the chapter on [\"Tracking Failure Origins\"](https://www.debuggingbook.org/html/Slicer.html) from [The Debugging Book](https://www.debuggingbook.org/).\n",
    "The goal of this project was to create a plugin for Flake8 to statically analyse\n",
    "your code and find dependencies between variables deemed _confidential_ or\n",
    "_inconfidential_ (high/low in terms of security classes) by the user.\n",
    "\n",
    "In the following code for example, we don't want any information about the\n",
    "variable `high` to be leaked to the public. We furthermore have a variable `low`\n",
    "that is available to the public. Note, that for Python specifically, this may\n",
    "be less feasible as the inspection of variables is far easier than it is for\n",
    "compiled languages like C. \n",
    "\n",
    "```python\n",
    "def foo(high, low): # flow: High, Low\n",
    "    if high > 10:\n",
    "        low = 10\n",
    "    else:\n",
    "        low = 0\n",
    "    return low\n",
    "```\n",
    "\n",
    "Since high is a high confidentiality variable, we assume that the public does\n",
    "not know anything about this variable. In the example function however, we have\n",
    "an interaction between a publically accessible variable and a confidential\n",
    "variable. The public variable is modified depending on the context of the\n",
    "confidential variable and thus leaks information about the confidential\n",
    "variable.\n",
    "\n",
    "Using Static Flow Analysis, we can determine that in fact, there is an\n",
    "information flow from a high to a low variable anbd display it as a Flake8\n",
    "error.\n",
    "\n",
    "## Disclaimer\n",
    "\n",
    "As Static Information Flow Analysis may not be that useful in Python due to\n",
    "inspection being easy, this could still be extended to work on ASTs for other\n",
    "languages, e.g. C (check out the [pycparser project](https://github.com/eliben/pycparser)).\n",
    "This however is just a simple demonstration of Static Information Flow Analysis\n",
    "based on a so called _Hoare-Logic_. I added a binding to flake8 such\n",
    "that we can also display the results in an IDE using this linter.\n",
    "\n",
    "# Installation and Usage\n",
    "\n",
    "To install this plugin just clone the repo and run these commands:\n",
    "\n",
    "```sh\n",
    "pip install -r requirements.txt\n",
    "pip install .\n",
    "```\n",
    "\n",
    "After that the plugin should be installed warnings be reported inside _flake8_\n",
    "To test whether it works, run\n",
    "\n",
    "```sh\n",
    "flake8 test_code.py \n",
    "```\n",
    "\n",
    "and you should see an output like this:\n",
    "\n",
    "```\n",
    "test_code.py:1:1: STA101 Information flow from low variable 'a_long_variable_name' to high variable 'y' in function 'fo\n",
    "o'\n",
    "test_code.py:1:1: STA101 Information flow from low variable 'a_long_variable_name' to high variable 'z' in function 'fo\n",
    "o'\n",
    "test_code.py:8:1: STA301 Information flow from low variable 'x' to local high variable 'c' in function 'bar'\n",
    "test_code.py:8:1: STA101 Information flow from low variable 'x' to high variable 'y' in function 'bar'\n",
    "test_code.py:17:5: STA101 Information flow from low variable 'y' to high variable 'z' in inner function 'foobar'\n",
    "```\n",
    "\n",
    "If you see this the installation was successful and you can use this inside your\n",
    "favourite IDE/text editor.\n",
    "\n",
    "![Screenshot of _flake8_ error messages in NeoVim](screenshot.png)\n",
    "\n",
    "# The Theory\n",
    "\n",
    "## Hoare Logic\n",
    "\n",
    "Without going into too much detail, Hoare logic is basically nothing else than a\n",
    "set of rules that allows to make certain statements about the correctness of a\n",
    "programme. The main concept here is that of a so called _Hoare triple_\n",
    "consisting of a _pre-condition $\\{P\\}$_, a _command_ $\\{C\\}$ and a post-condition\n",
    "$\\{Q\\}$ that holds after execution of the command in a state that satisfies the\n",
    "pre-condition. (see references)\n",
    "\n",
    "How is this useful for Static Information Flow Analysis ? \n",
    "\n",
    "We define a set of rules, one for each statement we want to analyse (e.g.\n",
    "`while` loops, assignments, or `if` statements), that specify how a set of\n",
    "so-called _independences_ (the pre-condition) is modified (the post-condition) under a statement (the\n",
    "command).\n",
    "These rules can then be used in the analysis phase to compute the postconditions\n",
    "while traversing the **AST**.\n",
    "\n",
    "The exact nature of these rules will not be discussed here and the interested\n",
    "reader can look them up in the references down below.\n",
    "\n",
    "## Independences \n",
    "\n",
    "As already mentioned above, the analysis revolves around the concept of\n",
    "_independences_. A set of independences $\\{[x\\#y,z], [y\\#x]\\}$ simply states\n",
    "that the **current value** of the variable $x$ is _independent_ of the **initial** value of both $y$ and\n",
    "$z$ and similarly the **current value** of the variable $y$ is _independent_ of\n",
    "the **initial** value of $x$.\n",
    "\n",
    "After visiting a statement we can infer from the set of rules that we formed how\n",
    "these independences changed.\n",
    "\n",
    "For example after analysing the assignment $x = y$ we can deduce that $x$ is now\n",
    "indepent of everything that $y$ is independent of and our new set of\n",
    "independencies becomes $\\{[x\\#x], [y\\#x]\\}$.\n",
    "\n",
    "## Context\n",
    "\n",
    "The final concept is that of the context. A context encapsulates _implicit\n",
    "dependencies_, i.e. dependencies that are imposed by the flow of the programme.\n",
    "More specifically this occurs whenever we encounter a conditional loop or `if`\n",
    "statement. \n",
    "\n",
    "Take for example \n",
    "```python\n",
    "if x < 5:\n",
    "    y = 10\n",
    "else:\n",
    "    y = 5\n",
    "```\n",
    "\n",
    "The value of $y$ is implicitally dependent on the initial value of $x$ since it\n",
    "is changed to 10 or 5 depending on the value of $x$.\n",
    "\n",
    "## Limitations\n",
    "\n",
    "There are some limitations for this implementation that could be solved by a\n",
    "more sophisticated implementation.\n",
    "\n",
    "One of these limitations is the following case:\n",
    "\n",
    "```python\n",
    "if x < 5:\n",
    "    y = 10\n",
    "else:\n",
    "    y = 10\n",
    "```\n",
    "\n",
    "Obviously, $y$ is not dependent on $x$ here as it is always assigned the same\n",
    "value but the analysis is not able to capture that and will raise an error.\n",
    "\n",
    "Another case is \n",
    "```python\n",
    "x = y - y\n",
    "```\n",
    "\n",
    "Again, x is obviously not dependent on the initial value of y since it is always\n",
    "0 but the implementation is not quite able to grasp that. A solution would be to\n",
    "implement the _strongest semantic postcondition_ which is able to resolve this\n",
    "issue."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Implementation\n",
    "\n",
    "It was important for me to have correct type annotations everywhere, since this makes understanding the program a bit easier by abstracting away some of the implementation details. Over the course of the implementation I added some type definitions where I saw fit to abbreviate the signatures of a few functions and methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Core Library modules\n",
    "from typing import Dict, Set, List, Tuple, Callable\n",
    "from enum import Enum\n",
    "\n",
    "\n",
    "class Confidentiality(Enum):\n",
    "    High = \"High\"\n",
    "    Low = \"Low\"\n",
    "    NA = \"None\"\n",
    "\n",
    "\n",
    "Variables = Set[str]\n",
    "Indeps = Dict[str, Set[str]]\n",
    "Errors = List[Tuple[int, int, str]]\n",
    "FlowConfig = Dict[str, List[Confidentiality]]\n",
    "ErrorCode = Callable[[str, str, str, str], str]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First off all, I had to find out the context a.k.a. the set of all variables that we want to analyse. For this, I just a simple `ast.NodeVisitor` that visits all `ast.Name` nodes and collects the values. I had to make some distinctions vis à vis left and right hand side variables as this is important to know for the analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Core Library modules\n",
    "import ast\n",
    "\n",
    "class VariableCollector(ast.NodeVisitor):\n",
    "\n",
    "    def __init__(self) -> None:\n",
    "        self.vars: Variables = set()\n",
    "        self.free_only: bool = False\n",
    "\n",
    "    def visit_Call(self, node: ast.Call) -> None:\n",
    "        # IMPORTANT: Do not collect function names\n",
    "        for arg in node.args:\n",
    "            self.visit(arg)\n",
    "\n",
    "    def visit_Name(self, node: ast.Name) -> None:\n",
    "        # Distinguish between left and right hand side variables\n",
    "        if not self.free_only or isinstance(node.ctx, ast.Load):\n",
    "            self.vars.add(node.id)\n",
    "\n",
    "    def visit_For(self, node: ast.For) -> None:\n",
    "        self.visit(node.iter)\n",
    "        for n in node.body + node.orelse:\n",
    "            self.visit(n)\n",
    "\n",
    "    def collect(self, tree: ast.AST, free_only: bool = True) -> Variables:\n",
    "        self.vars = set()\n",
    "        self.free_only = free_only\n",
    "        self.visit(tree)\n",
    "        return self.vars"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With this visitor, I implemented the two basic functions for collecting information from the AST, `collect_free_variables` and `collect_all_variables`. As the names imply, `collect_all_variables` just simply iterates over all `ast.Name` nodes and collects their id."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def collect_all_variables(tree: ast.AST) -> Variables:\n",
    "    c = VariableCollector()\n",
    "    return c.collect(tree, free_only=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`collect_free_variables` on the other hand is mainly used on not-top-level nodes to find the free variables in an expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "def collect_free_variables(tree: ast.AST) -> Variables:\n",
    "    c = VariableCollector()\n",
    "    return c.collect(tree)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These functions might look almost exactly the same, but for the sake of readability, I decided to implement them as separate functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Analysis domain\n",
    "\n",
    "Every static analysis operates in a domain. This domain in a theoretical sense defines _join_ and _meet_ operators that are useful for combining information from different analysis branches. I will not go into too much detail about the theory behind all of this since it would go far beyond the scope of this project. In this case the domain is basically given by the _independency set_ and the _join_ operator. The independency set is implemented as a mapping $\\texttt{str} \\rightarrow \\texttt{Set[str]}$ where each variable is mapped to a set of variables whose initial values it is independent of.\n",
    "\n",
    "Over the course of the analysis we will also need to join two such indepedency sets together. This is usually done by simply intersecting the mapped sets for each variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def join(s1: Indeps, s2: Indeps) -> Indeps:\n",
    "    \"\"\" Join two independency sets by intersection \"\"\"\n",
    "    return {x: s1[x] & s2[x] for x in s1}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From a theoretical standpoint this does make sense, since we want to find out which variables the analysed variables does not depend on. So if there is a branch where e.g. $x$ depends on $y$ and another where it does not, the logical decision is to assume that it depends on $y$ and omit $y$ from the dependency set.\n",
    "\n",
    "Furthermore, I implemented some convenience functions that allow me to intersect/union any amount of sets in a simple and concise way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Sequence\n",
    "\n",
    "def intersect(sets: Sequence[Variables]) -> Variables:\n",
    "    \"\"\" Compute intersection of the given sets \"\"\"\n",
    "    if not sets:\n",
    "        return set()\n",
    "    combined: Variables = sets[0].copy()\n",
    "    for s in sets:\n",
    "        combined &= s\n",
    "    return combined\n",
    "\n",
    "\n",
    "def union(sets: Sequence[Variables]) -> Variables:\n",
    "    \"\"\" Compute union of the given sets \"\"\"\n",
    "    if not sets:\n",
    "        return set()\n",
    "    combined: Variables = sets[0].copy()\n",
    "    for s in sets:\n",
    "        combined |= s\n",
    "    return combined"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The main work is done in the `Hoare` class, where the analysis is performed on the AST."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Hoare(ast.NodeVisitor):\n",
    "    STA100: ErrorCode = (\n",
    "        \"STA100 Information flow from high variable '{high}' to \"\n",
    "        \"low variable '{low}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "    STA101: ErrorCode = (\n",
    "        \"STA101 Information flow from low variable '{low}' to \"\n",
    "        \"high variable '{high}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "    STA200: ErrorCode = (\n",
    "        \"STA200 Information flow from local high variable '{high}' to \"\n",
    "        \"low variable '{low}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "    STA201: ErrorCode = (\n",
    "        \"STA201 Information flow from local low variable '{low}' to \"\n",
    "        \"high variable '{high}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "    STA300: ErrorCode = (\n",
    "        \"STA300 Information flow from high variable '{high}' to \"\n",
    "        \"local low variable '{low}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "    STA301: ErrorCode = (\n",
    "        \"STA301 Information flow from low variable '{low}' to \"\n",
    "        \"local high variable '{high}' in {inner_func}function '{func}'\".format\n",
    "    )\n",
    "\n",
    "    def __init__(self, lines: Sequence[str], varset: Variables) -> None:\n",
    "        # Context for Hoare logic\n",
    "        self.context: Variables = set()\n",
    "        # Independency sets for Hoare Logic\n",
    "        self.indeps: Indeps = {}\n",
    "        # Set of all variables that we want to consider for the analysis\n",
    "        self.all_vars: Variables = varset\n",
    "        # Errors we found (for flake8).\n",
    "        # TODO: Might have to be extracted to a different module since this is\n",
    "        # not really Hoare logic related\n",
    "        self.errors: Errors = []\n",
    "\n",
    "        # High and low variables. Extracted during the analysis\n",
    "        self.high: Variables = set()\n",
    "        self.low: Variables = set()\n",
    "        self.locals: Variables = set()\n",
    "        self.level = 0\n",
    "\n",
    "        # Parameters\n",
    "        # Code lines\n",
    "        self.lines: Sequence[str] = lines\n",
    "\n",
    "        # Initialize independency sets\n",
    "        for var in varset:\n",
    "            self.indeps[var] = {x for x in varset if x != var}\n",
    "\n",
    "    def calc_indeps(self, free_vars_in_expr: Variables) -> Variables:\n",
    "        \"\"\"Calculate the set of independencies for the\n",
    "        given set of variables by intersecting the independency \n",
    "        sets of all variables in the expression.\"\"\"\n",
    "        if not free_vars_in_expr:\n",
    "            return self.all_vars\n",
    "\n",
    "        indeps: Variables = intersect([self.indeps[x] for x in free_vars_in_expr])\n",
    "        return indeps\n",
    "\n",
    "    def calc_deps(self, free_vars_in_expr: Variables) -> Variables:\n",
    "        \"\"\"Calculate the set of dependencies for the\n",
    "        given set of variables by union-ing the complements \n",
    "        of the independency set of every variable in the expression.\"\"\"\n",
    "        return union([self.all_vars - self.indeps[var] for var in free_vars_in_expr])\n",
    "\n",
    "    def add_var(self, var: str, confidentiality: Confidentiality) -> None:\n",
    "        \"\"\"Add a variable with a given confidentiality to the respective set\n",
    "        (high/low)\"\"\"\n",
    "        if confidentiality == Confidentiality.High:\n",
    "            self.high.add(var)\n",
    "        elif confidentiality == Confidentiality.Low:\n",
    "            self.low.add(var)\n",
    "\n",
    "    def add_error(\n",
    "        self,\n",
    "        line: int,\n",
    "        col: int,\n",
    "        tp: ErrorCode,\n",
    "        low: str,\n",
    "        high: str,\n",
    "        func: str,\n",
    "        inner_func: bool = False,\n",
    "    ) -> None:\n",
    "        \"\"\"Add an error of type `tp` at line `line` and column `col` to the\n",
    "        error list\"\"\"\n",
    "        self.errors += [\n",
    "            (\n",
    "                line,\n",
    "                col,\n",
    "                tp(\n",
    "                    low=low,\n",
    "                    high=high,\n",
    "                    func=func,\n",
    "                    inner_func=\"inner \" if inner_func else \"\",\n",
    "                ),\n",
    "            )\n",
    "        ]\n",
    "\n",
    "    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:\n",
    "        \"\"\"For each function detect if there is any flow from high to low or\n",
    "        low to high variables.\"\"\"\n",
    "        flow_conf = extract_flow_config(self.lines[node.lineno - 1])\n",
    "        var_names: List[str] = [arg.arg for arg in node.args.args]\n",
    "\n",
    "        old_high = self.high.copy()\n",
    "        old_low = self.low.copy()\n",
    "        old_locals = self.locals.copy()\n",
    "\n",
    "        self.high = set()\n",
    "        self.low = set()\n",
    "        self.locals = set()\n",
    "        self.level += 1\n",
    "\n",
    "        for x, y in zip(var_names, flow_conf):\n",
    "            self.add_var(x, y)\n",
    "\n",
    "        self.generic_visit(node)\n",
    "\n",
    "        for high_var in self.high:\n",
    "            for low_var in self.low:\n",
    "                error_type: ErrorCode\n",
    "                if low_var not in self.indeps[high_var]:\n",
    "                    # Information flow from low_var to high_var\n",
    "                    if low_var in self.locals:\n",
    "                        error_type = self.STA201\n",
    "                    elif high_var in self.locals:\n",
    "                        error_type = self.STA301\n",
    "                    else:\n",
    "                        error_type = self.STA101\n",
    "\n",
    "                    self.add_error(\n",
    "                        line=node.lineno,\n",
    "                        col=node.col_offset,\n",
    "                        tp=error_type,\n",
    "                        low=low_var,\n",
    "                        high=high_var,\n",
    "                        func=node.name,\n",
    "                        inner_func=self.level > 1,\n",
    "                    )\n",
    "                if high_var not in self.indeps[low_var]:\n",
    "                    # Information flow from high_var to low_var\n",
    "                    if high_var in self.locals:\n",
    "                        error_type = self.STA200\n",
    "                    elif low_var in self.locals:\n",
    "                        error_type = self.STA300\n",
    "                    else:\n",
    "                        error_type = self.STA100\n",
    "\n",
    "                    self.add_error(\n",
    "                        line=node.lineno,\n",
    "                        col=node.col_offset,\n",
    "                        tp=error_type,\n",
    "                        low=low_var,\n",
    "                        high=high_var,\n",
    "                        func=node.name,\n",
    "                        inner_func=self.level > 1,\n",
    "                    )\n",
    "                    \n",
    "        # Restore old variables (in case of nested functions)\n",
    "        self.high = old_high\n",
    "        self.low = old_low\n",
    "        self.locals = old_locals\n",
    "        self.level = max(0, self.level - 1)\n",
    "\n",
    "    def visit_While(self, node: ast.While) -> None:\n",
    "        \"\"\" Fixpoint iteration for Hoare logic \"\"\"\n",
    "        free_vars: Variables = collect_free_variables(node.test)\n",
    "        old_ctx: Variables = self.context.copy()\n",
    "\n",
    "        while True:\n",
    "            deps: Variables = self.calc_deps(free_vars)\n",
    "            prev_indeps = copy.deepcopy(self.indeps)\n",
    "            self.context |= deps\n",
    "\n",
    "            for n in node.body:\n",
    "                self.visit(n)\n",
    "\n",
    "            self.indeps = join(self.indeps, prev_indeps)\n",
    "\n",
    "            if self.indeps == prev_indeps:\n",
    "                break\n",
    "\n",
    "        self.context = old_ctx\n",
    "\n",
    "    def visit_For(self, node: ast.For) -> None:\n",
    "        \"\"\" Fixpoint iteration for Hoare logic \"\"\"\n",
    "        free_vars: Variables = collect_free_variables(node.iter)\n",
    "        old_ctx: Variables = self.context.copy()\n",
    "\n",
    "        while True:\n",
    "            deps: Variables = self.calc_deps(free_vars)\n",
    "            prev_indeps = copy.deepcopy(self.indeps)\n",
    "            self.context |= deps\n",
    "\n",
    "            for n in node.body:\n",
    "                self.visit(n)\n",
    "\n",
    "            self.indeps = join(self.indeps, prev_indeps)\n",
    "\n",
    "            if self.indeps == prev_indeps:\n",
    "                break\n",
    "\n",
    "        self.context = old_ctx\n",
    "\n",
    "    def visit_Assign(self, node: ast.Assign) -> None:\n",
    "        extracted = extract_flow_config(self.lines[node.lineno - 1])\n",
    "        var_node: ast.Name = node.targets[0]\n",
    "        if extracted:\n",
    "            # If there was a flow configuration for this assignment, we assume\n",
    "            # that it was an initial assignment and thus do not analyse it at\n",
    "            # this point in time.\n",
    "            self.add_var(var_node.id, extracted[0])\n",
    "            self.locals.add(var_node.id)\n",
    "            return\n",
    "        free_vars: Variables = collect_free_variables(node.value)\n",
    "        indeps: Variables = self.calc_indeps(free_vars) - self.context\n",
    "        self.indeps[var_node.id] = indeps\n",
    "\n",
    "    def visit_AugAssign(self, node: ast.AugAssign) -> None:\n",
    "        old_ctx: Variables = self.context.copy()\n",
    "        target: ast.Name = node.target\n",
    "        self.context |= {target.id}\n",
    "        free_vars: Variables = collect_free_variables(node.value)\n",
    "        indeps: Variables = self.calc_indeps(free_vars) - self.context\n",
    "        self.indeps[target.id] = indeps\n",
    "        self.context = old_ctx\n",
    "\n",
    "    def visit_If(self, node: ast.If) -> None:\n",
    "        old_ctx: Variables = self.context.copy()\n",
    "\n",
    "        free_vars: Variables = collect_free_variables(node.test)\n",
    "\n",
    "        deps: Variables = self.calc_deps(free_vars)\n",
    "        self.context |= deps\n",
    "        intermediate_ctx: Variables = self.context.copy()\n",
    "\n",
    "        for n in node.body:\n",
    "            self.visit(n)\n",
    "\n",
    "        if_indeps: Indeps = copy.deepcopy(self.indeps)\n",
    "\n",
    "        if hasattr(node, \"orelse\"):\n",
    "            self.context = intermediate_ctx\n",
    "\n",
    "            for n in node.body:\n",
    "                self.visit(n)\n",
    "\n",
    "            else_indeps: Indeps = copy.deepcopy(self.indeps)\n",
    "\n",
    "            self.indeps = join(if_indeps, else_indeps)\n",
    "\n",
    "        self.context = old_ctx"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The analysis is triggered every time a function definition is visited. To make sure that is also works with nested functions, I keep track of the old function and restore it once the analysis is done.\n",
    "\n",
    "For every other node, I implemented the inference rule for this type of expression. \n",
    "The exact nature of these inference rules can be looked up by the interested reader in the paper provided in the references."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Flow configuration\n",
    "\n",
    "You will notice that in the `visit_Assign` method, I use a function called `extract_flow_config`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "import re\n",
    "\n",
    "# Matches any code line followed by \"# flow: \"\n",
    "flow_regex = re.compile(r\".*#\\ *(flow:).*$\")\n",
    "\n",
    "def extract_flow_config(line: str) -> List[Confidentiality]:\n",
    "    match = re.match(flow_regex, line)\n",
    "    if not match:\n",
    "        return []\n",
    "    start_flow = match.end(1)\n",
    "\n",
    "    return [\n",
    "        Confidentiality(x.strip()) for x in line[start_flow:].split(\",\")\n",
    "    ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This function is important for the integration with flake8 and tackles the issue of \"What variables are confidential/trusted/high and which are inconfidential/untrusted/low?\".\n",
    "\n",
    "This flow configuration can be defined by the user by adding comments to assignments and function definitions that clearly define which variables belong to what class.\n",
    "\n",
    "We have already seen an example for that in the preface, but I will reiterate the usage here anyway to make it clear how to use the plugin.\n",
    "\n",
    "If you have a function `foo` that depends on two variables $x$ and $y$ and you want to find out whether there is information flowing from your untrusted variable $y$ to your trusted variable $x$, you would use it as follows:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def foo(x, y):  # flow: High, Low\n",
    "    return x * y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also have local variables inside each function and assign them a confidentiality class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def foo(x, y):  # flow: High, Low\n",
    "    c = 1337  # flow: High\n",
    "    return (x * y) % c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is also a file called `test_code.py` that you can can look into to see how it is used but it should be fairly intuitive and self-explanatory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Integration with Flake8\n",
    "\n",
    "Flake8 provides a simple way to define and create plugins by simply specifying the entry point for your module in the `setup.py` or `setup.cfg`. The entry point is a module containing a class called `Plugin` that is defined in a fairly specific way.\n",
    "\n",
    "There is a [great tutorial by Martin Thoma](https://medium.com/analytics-vidhya/how-to-write-flake8-plugins-5c5c47faffc2) that I followed to set up everything and get started with the integration to flake8 in addition to the follwing youtube video."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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\n",
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"560\"\n",
       "            height=\"315\"\n",
       "            src=\"https://www.youtube.com/embed/ot5Z4KQPBL8\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "        ></iframe>\n",
       "        "
      ],
      "text/plain": [
       "<IPython.lib.display.YouTubeVideo at 0x7efcb032e280>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.display import YouTubeVideo\n",
    "\n",
    "YouTubeVideo(id=\"ot5Z4KQPBL8\", width=560, height=315)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For convenience, I implemted this method called `analyse` that can also be used programmatically to find and display all errors found."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[(2, 0, \"STA101 Information flow from low variable 'x' to high variable 'y' in function 'foo'\")]\n"
     ]
    }
   ],
   "source": [
    "from typing import Optional\n",
    "\n",
    "def analyse(\n",
    "    tree: ast.AST, lines: Sequence[str], var_set: Optional[Variables] = None\n",
    ") -> Errors:\n",
    "    \"\"\"Statically analyze the given tree using Hoare logic and return any\n",
    "    errors found\"\"\"\n",
    "    if not var_set:\n",
    "        var_set = collect_all_variables(tree)\n",
    "    hoare = Hoare(lines, var_set)\n",
    "    hoare.visit(tree)\n",
    "    return hoare.errors\n",
    "\n",
    "code = \"\"\"\n",
    "def foo(x, y):  # flow: Low, High\n",
    "    y = 3 * x\n",
    "    return y\n",
    "\"\"\"\n",
    "\n",
    "tree = ast.parse(code)\n",
    "errors = analyse(tree, code.split(\"\\n\"))\n",
    "\n",
    "print(errors)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, the plugin is defined in `staticinflowanalysis/plugin.py` and contains the plugin class that is used by flake8."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Core Library modules\n",
    "import ast\n",
    "import sys\n",
    "from typing import Any, Generator, Tuple, Type, Sequence\n",
    "\n",
    "if sys.version_info < (3, 8):\n",
    "    # Third party modules\n",
    "    import importlib_metadata\n",
    "else:\n",
    "    import importlib.metadata as importlib_metadata\n",
    "\n",
    "# First party modules\n",
    "from staticinflowanalysis.hoare import analyse\n",
    "\n",
    "\n",
    "class Plugin:\n",
    "\n",
    "    name = 'flake8-staticinflowanalysis'\n",
    "    version = importlib_metadata.version(name)\n",
    "\n",
    "    def __init__(self, tree: ast.AST, lines: Sequence[str]):\n",
    "        self._tree = tree\n",
    "        self._lines = lines\n",
    "\n",
    "    def run(self) -> Generator[Tuple[int, int, str, Type[Any]], None, None]:\n",
    "        errors = analyse(self._tree, self._lines)\n",
    "\n",
    "        for line, col, msg in errors:\n",
    "            yield line, col, msg, type(self)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run this plugin in flake8, you have follow the install directions above and if everything works out, the following line should be executed and display the same errors as displayed in the install section"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "test_code.py:1:1: STA101 Information flow from low variable 'a_long_variable_name' to high variable 'z' in function 'foo'\r\n",
      "test_code.py:1:1: STA101 Information flow from low variable 'a_long_variable_name' to high variable 'y' in function 'foo'\r\n",
      "test_code.py:9:5: STA101 Information flow from low variable 'y' to high variable 'z' in inner function 'foobar'\r\n",
      "test_code.py:15:1: STA100 Information flow from high variable 'y' to low variable 'x' in function 'bar'\r\n"
     ]
    }
   ],
   "source": [
    "!flake8 test_code.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# References\n",
    "\n",
    "  - Torben Amtoft, Anindya Banerjee: \n",
    "    [A logic for information flow analysis with an application to forward slicing of simple imperative programs](https://doi.org/10.1016/j.scico.2006.03.002)\n",
    "    \n",
    "  - Prof. Dr. Jan Reineke: Lecture Notes for Program Analysis (Winter term 2020/2021), Saarland University\n",
    "  \n",
    "  - Andreas Zeller: [The Debugging Book, Tools and Techniques for Automated Software Debugging](https://www.debuggingbook.org)\n",
    "  \n",
    "  - [Flake8 plugin tutorial by Martin Thoma](https://medium.com/analytics-vidhya/how-to-write-flake8-plugins-5c5c47faffc2)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}