Quickstart

Ocular is a command-line tool for static code analysis. Ocular can help you find and correct security vulnerabilities in programs with hundreds of thousands lines of code, including flaws that are extremely difficult to detect. It includes an interactive shell and powerful automation capabilities, all centered around a data structure specifically designed for vulnerability discovery: the Code Property Graph.

This article introduces you to the basics of working with Ocular. You learn how to create and modify Code Property Graphs, how to query them using the Code Property Graph Query Language and about organisational commands at your disposal. If you have not yet installed Ocular, you can do so by following these instructions.

Obtaining the Sample Program

Before you start Ocular, you should have a program ready to analyze. Clone the following git repository which contains a simple program named X42:

git clone [e-mail]:ShiftLeftSecurity/x42.git

Let us start with a problem statement. Show - without running the program - that an input exists for which X42 always writes a string to standard error (STDERR).

// X42.c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(int argc, char *argv[]) {
  if (argc > 1 && strcmp(argv[1], "42") == 0) {
    fprintf(stderr, "It depends!\n");
    exit(42);
  }
  printf("What is the meaning of life?\n");
  exit(0);
}

Starting Ocular's Interactive Shell

Go ahead and launch Ocular in your shell:

sl ocular

A console session will start and you will see a prompt:

ocular>

The prompt you are looking at is the prompt of a Scala-based REPL. If you have no experience with Scala or read-eval-print-loops, don't worry, you can accomplish a lot with Ocular by focusing only on what its commands allow you to do. If you are familiar with Scala and REPLs, you may be pleasantly surprised at the flexibility it provides you with.

Importing the Code

We create a Code Property Graph for the X42 program using the command importCode, which requires the path to the source code to be passed as a first argument, and a project name as a second argument. In particular, importCode creates a new project directory and stores a binary representation of the Code Property Graph in it.

ocular> importCode(inputPath="./x42/c", projectName="x42-c")
Creating project `x42-c` for code at `x42/c`
... output omitted
res1: Option[Cpg] = Some(io.shiftleft.codepropertygraph.Cpg@31ed46c5)

If you see an error and a return value of None, you have probably pointed Ocular to the wrong input path for the directory containing the source code for the sample project.

Querying the Code Property Graph

You are ready to analyze your first program using Ocular and the Code Property Graph. Code analysis in Ocular is done using the Code Property Graph Query Language, a domain-specific language designed specifically for work with the Code Property Graph. It contains practical representations of the various nodes found in the Code Property Graph, and useful functions for querying their properties and relationships between each other. The top-level entry point into a Code Property Graph loaded in memory, and the root object of the Code Property Graph Query Language is cpg. If you evaluate cpg at the prompt, the output is underwhelming:

ocular> cpg
res2: Cpg = io.shiftleft.codepropertygraph.Cpg@cb0d5241

Rest assured, a lot is hidden behind that simple statement. You will discover the full set of commands in time, but for now, you should learn a helpful Ocular trick: TAB-completion. In the Ocular prompt, type cpg., do not press ENTER, but instead press TAB. You will see a list of available functions cpg supports:

ocular> cpg. 
all                            comment                        finding                        local                          newArgumentDescriptorSource    newReturnSource                runScript                      types
annotation                     configfile                     flow                           member                         newArgumentSink                newTagForMethodsWithFullName   scalaGraph                     write
argument                       cpg                            graph                          metaData                       newArgumentSource              newTagForParameter             sensitiveType
arithmetic                     dependency                     help                           method                         newExposedParameterSink        newTagForParameterWithIndex    sensitiveVariable
assignment                     dom                            id                             methodRef                      newExposedParameterSource      newTagForParameterWithIndexes  sink
blacklist                      exposedMethod                  identifier                     methodReturn                   newLiteralSource               packagePrefix                  source
call                           exposedOutputParameter         ioFlow                         namespace                      newMethodSummary               parameter                      tag
callChain                      exposedParameter               jsp                            namespaceBlock                 newReturnDescriptorSource      read                           transform
close                          file                           literal                        newArgumentDescriptorSink      newReturnSink                  returns                        typeDecl

TAB-completion is available for all CPGQL Directives, and for top-level commands. For more descriptive assistance, use the help command, like so:

ocular> help.cpg 
res3: String = """
Upon importing code, a project is created that holds an intermediate
representation called `Code Property Graph`. This graph is a composition of
low-level program representations such as abstract syntax trees and control flow
graphs, but it can be arbitrarily extended to hold any information relevant in
your audit, information about HTTP entry points, IO routines, information flows,
or locations of vulnerable code. Think of Ocular as a CPG editor.

In practice, `cpg` is the root object of the query language, that is, all query
language constructs can be invoked starting from `cpg`. For exanple,
`cpg.method.l` lists all methods, while `cpg.finding.l` lists all findings of
potentially vulnerable code."""

Solving the Challenge

Now that we have a good set of basic commands, and a Code Property Graph loaded in memory, let us return to our X42 program and the problem we want to solve using Ocular. To reiterate, the problem statement is Show that an input exists for which the X42 program always writes a string to STDERR. And this is the X42 program:

// X42.c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(int argc, char *argv[]) {
  if (argc > 1 && strcmp(argv[1], "42") == 0) {
    fprintf(stderr, "It depends!\n");
    exit(42);
  }
  printf("What is the meaning of life?\n");
  exit(0);
}

There are two parts in the problem statement: 1. does the program write anything to STDERR?, and 2. if there is a call writing to STDERR, is it conditional on a value passed in as argument to the X42 program?

Ocular makes answering both questions easy. To answer the first one, whether the program writes anything to STDERR, we can search for nodes of type CALL in the graph, and use the where directive to only select those calls which have connections to nodes of type ARGUMENT that have the string stderr as the value of their CODE property. We find exactly one:

ocular> cpg.call.where(_.argument.code("stderr")).l
res4: List[Call] = List(
  Call(
    id -> 24L,
    code -> "fprintf(stderr, \"It depends!\\n\")",
    name -> "fprintf",
    order -> 1,
    methodInstFullName -> None,
    methodFullName -> "fprintf",
    argumentIndex -> 1,
    dispatchType -> "STATIC_DISPATCH",
    signature -> "TODO assignment signature",
    typeFullName -> "ANY",
    dynamicTypeHintFullName -> List(),
    lineNumber -> Some(7),
    columnNumber -> Some(4),
    resolved -> None,
    depthFirstOrder -> Some(-8),
    internalFlags -> Some(4)
  )
)

With this query we have proven the first part of our problem statement correct, there is a place in the X42 program that writes to STDERR. Let us move to the second part, the check whether the call that writes something to STDERR is conditional on a value passed as input to the X42 program. Since we are analyzing a program written in C, we will search the Code Property Graph for the conventional argc or argv parameters of the main function as the input that potentially triggers the call which writes to STDERR.

Using the query from the previous step, we can use the astParent construct to find out more about the surroundings around the fprintf call by moving up in the hierarchy of the abstract syntax tree that is part of the Code Property Graph. Moving up one level in the AST hierarchy gives us a block; not very helpful:

ocular> cpg.call.where(_.argument.code("stderr")).astParent.l
res5: List[AstNode] = List(
  Block(
    id -> 23L,
    code -> "",
    order -> 2,
    argumentIndex -> 2,
    typeFullName -> "void",
    dynamicTypeHintFullName -> List(),
    lineNumber -> Some(6),
    columnNumber -> Some(46),
    depthFirstOrder -> Some(-24),
    internalFlags -> Some(0)
  )
)

Another layer up gives us an if statement, much better:

ocular> cpg.call.where(_.argument.code("stderr")).astParent.astParent.l
res6: List[AstNode] = List(
  ControlStructure(
    id -> 11L,
    code -> "if (argc > 1 && strcmp(argv[1], \"42\") == 0)",
    columnNumber -> Some(2),
    lineNumber -> Some(6),
    order -> 1,
    parserTypeName -> "IfStatement",
    argumentIndex -> 1,
    depthFirstOrder -> None,
    internalFlags -> None
  )
)

The CODE property of the CONTROL_STRUCTURE node you just found proves the second part of our problem statement correct, the call that writes to STDERR is conditional on argc and argv. Hence, the whole problem statement is correct.

Closing the Project

Now that we've finished the analysis, let us close the project, which also unloads the Code Property Graph from memory. You do not have to worry about losing any data, because it will remain on disk in the x42-c project you created earlier with importCode. Close the project using the aptly-named close:

ocular> close 
2020-05-08 01:13:01.752 WARN clearing 105 references - this may take some time
2020-05-08 01:13:01.756 WARN cleared all clearable references
res7: Option[io.shiftleft.console.workspacehandling.Project] = Some(
  Project(
    ProjectFile("/home/user/x42/c", "x42-c"),
    /home/user/.shiftleft/ocular/workspace/x42-c,
    None
  )
)

As a final step, exit Ocular completly:

ocular> exit 
Bye!
Would you like to save changes? (y/N)
y
saving.

Congratulations, you have succesfully queried your first Code Property Graph using Ocular and the Code Property Graph Query Language! In subsequent articles, you will learn the more advanced features of Ocular and also how to use it to find your first real-world vulnerability.