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
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).
Starting Ocular's Interactive Shell
Go ahead and launch Ocular in your shell:
A console session will start and you will see a prompt:
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.
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:
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
TAB-completion is available for all CPGQL Directives, and for top-level commands. For more descriptive assistance, use the
help command, like so:
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
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
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:
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
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:
Another layer up gives us an if statement, much better:
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
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
As a final step, exit Ocular completly:
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.