A Brief Introduction to the Standard Annotation Language (SAL)
18-May-2006
Michael Howard
http://blogs.msdn.com/michael_howard
Introduction
Even though a prior blog I wrote “Code Scanning Tools Do N ot m ake Softw are Secure” at
http://blogs.msdn.com/michael_howard/archive/2006/01/26/517975.aspx may have left some thinking
I don’t like static analysis tools, nothing could be farther from the truth. In fact, there is a code analysis
technology designed by Microsoft Research which is included with Visual Studio 2005 that I simply love,
and that is the Standard Annotation Language, or SAL. SAL is a meta-language that can help static
analysis tools, such as the /analyze switch in Visual Studio 2005 Team System and Visual Studio 2005
Team Edition for Developers, find bugs— including security bugs— in your C or C++ code at compile time.
Using SAL is relatively easy. You simply add annotations to your function prototypes that describe more
contextual information about the function being annotated. This can include annotations to function
arguments and to function return values. The initial focus of SAL is to annotate functions that
manipulate read and write buffers. In Windows Vista we are annotating all appropriate functions before
the product is released to customers to help us find bugs as early as possible.
The main benefit of SAL is that you can find more bugs with just a little bit of upfront work. We have
found that the process of adding SAL annotations to existing code can also find bugs as the developer
questions the assumptions previously made about how the function being annotated works. By this I
mean that as a developer adds annotations to a function, she must think about how the function works
in more detail than simply assuming it was written correctly. This process finds assumption flaws.
Any bugs found in SAL annotated functions tend to be real bugs, not false positives, which has the
benefit of speedier bug triage and code fixes.
Finally, SAL is highly leveraged; when you annotate a function, any code that calls that function will get
the benefit of the annotation. To this end, we have annotated the majority of C Runtime functions
included with Visual Studio 2005 and the Windows SDK functions. Over time we will add more
annotations to more functions to help find bugs in code written to use the functions. In short, this
means you will get the benefit of the annotations added by Microsoft, and you might find bugs in your
code!
Digging Deeper
Let m e give an exam ple of w hat SAL can do. Let’s say you have a C/C++ function like this:
void FillString(
TCHAR* buf,
size_t cchBuf,