diff --git a/www/analyzer/checker_dev_manual.html b/www/analyzer/checker_dev_manual.html index 5368eb0..25327d4 100644 --- a/www/analyzer/checker_dev_manual.html +++ b/www/analyzer/checker_dev_manual.html @@ -28,15 +28,20 @@ for general developer guidelines and information.

Getting Started

@@ -103,7 +108,7 @@ for general developer guidelines and information.

  • GenericDataMap - constraints on symbolic values -

    Interaction with Checkers

    +

    Interaction with Checkers

    Checkers are not merely passive receivers of the analyzer core changes - they actively participate in the ProgramState construction through the GenericDataMap which can be used to store the checker-defined part @@ -114,7 +119,7 @@ for general developer guidelines and information.

    in the predefined order; thus, calling all the checkers adds a chain to the ExplodedGraph. -

    Representing Values

    +

    Representing Values

    During symbolic execution, SVal objects are used to represent the semantic evaluation of expressions. They can represent things like concrete @@ -127,7 +132,7 @@ for general developer guidelines and information.

    number. In some cases, SVal is not a symbol, but it really should be a symbolic value. This happens when the analyzer cannot reason about something (yet). An example is floating point numbers. In such cases, the - SVal will evaluate to UnknownVal. + SVal will evaluate to UnknownVal. This represents a case that is outside the realm of the analyzer's reasoning capabilities. SVals are value objects and their values can be viewed using the .dump() method. Often they wrap persistent objects such as @@ -196,6 +201,76 @@ values (e.g., the number 1). Symbols
    FunctionalObjects are used throughout. --> +

    Custom Program States

    + +

    Checkers often need to keep track of information specific to the checks they +perform. However, since checkers have no guarantee about the order in which the +program will be explored (or that some paths will be explored at all), no state +information can be kept within individual checkers. Therefore, if checkers need +to store custom information, they need to add new categories of data to the +ProgramState. The preferred way to do so is to use one of several macros +designed for this purpose. They are: + +

    + +

    All of these macros take as parameters the name to be used for the custom +category of state information, and the data type(s) to be used for storage. The +data type(s) specified will also become the parameter and/or return type of the +functions that manipulate the new category of state information. Each of these +methods are templated with the name of the custom data type, so if there was a +data type declared as + +

    +REGISTER_TRAIT_WITH_PROGRAMSTATE(ExampleDataType, int)
+
    + +The data would be accessed with the function + +
    +ProgramStateRef state;
+...
+int currentlValue = state->get<ExampleDataType>();
+
    + +and set with the function + +
    +ProgramStateRef state;
+...
+ProgramStateRef newState = state->set<ExampleDataType>(newValue);
+
    + +

    These macros will cover a majority of use cases; however, they still have a +few limitations. They cannot be used inside namespaces (since they expand to +contain top-level namespace references), and the data types that they define +cannot be referenced from more than one file. + +

    Note that ProgramStates are immutable; instead of modifying an existing +one, functions that modify the state will return a copy of the previous state +with the change applied. This updated state must be then provided to the +analyzer by calling the CheckerContext::addTransition function. +

    Idea for a Checker

    Here are several questions which you should consider when evaluating your checker idea: @@ -222,35 +297,26 @@ values (e.g., the number 1). All checker implementation files are located in clang/lib/StaticAnalyzer/Checkers folder. Follow the steps below to register a new checker with the analyzer.
      -
    1. Create a new checker implementation file, for example ./lib/StaticAnalyzer/Checkers/NewChecker.cpp +
    2. Create a new checker implementation file, for example ./lib/StaticAnalyzer/Checkers/SimpleStreamChecker.cpp. +
    3. Include the following code (replacing SimpleStreamChecker with the name of the new checker). 
      -using namespace clang;
-using namespace ento;
-
-namespace {
-class NewChecker: public Checker< check::PreStmt<CallExpr> > {
-public:
-  void checkPreStmt(const CallExpr *CE, CheckerContext &Ctx) const {}
-}
-}
 void ento::registerNewChecker(CheckerManager &mgr) {
-  mgr.registerChecker<NewChecker>();
+  mgr.registerChecker<SimpleStreamChecker>();
 }
    4. Pick the package name for your checker and add the registration code to ./lib/StaticAnalyzer/Checkers/Checkers.td. Note, all checkers should -first be developed as experimental. Suppose our new checker performs security -related checks, then we should add the following lines under -SecurityExperimental package: +first be developed as "alpha". Since the SimpleStreamChecker performs UNIX API +checks, add the following to the UnixAlpha package: 
      -let ParentPackage = SecurityExperimental in {
+let ParentPackage = UnixAlpha in {
 ...
-def NewChecker : Checker<"NewChecker">,
-  HelpText<"This text should give a short description of the checks performed.">,
-  DescFile<"NewChecker.cpp">;
+def SimpleStreamChecker : Checker<"SimpleStream">,
+  HelpText<"Check for misuses of stream APIs">,
+  DescFile<"SimpleStreamChecker.cpp">;
 ...
-} // end "security.experimental"
+} // end "alpha.unix"
    5. Make the source code file visible to CMake by adding it to @@ -259,20 +325,129 @@ def NewChecker : Checker<"NewChecker">,
    6. Compile and see your checker in the list of available checkers by running:
      $clang -cc1 -analyzer-checker-help
    -

    Checker Skeleton

    - There are two main decisions you need to make: - +

    Checkers fundamentally extend the class +Checker, but they do so in an unusual way. The "class" Checker +is actually a templated class, and checkers extend a specialization of this +class. Unlike the standard +Curiously Recurring Template Pattern, the specialization being extended uses +as its parameter(s) the type of events that the checker is interested in +processing. The various types of events that are available are described in the +file +CheckerDocumentation.cpp + +

    For each event type requested, a corresponding function with the name +check<event> must be defined in the checker class +(CheckerDocumentation.cpp shows the correct function signature for each +event type). + +

    As an example, consider SimpleStreamChecker, a checker that warns +about improper use of file stream APIs. This checker needs to take action at the +following times: + +

    + +

    These events that will be used for each of these actions are, respectively, PreCall, +PostCall, +DeadSymbols, +and PointerEscape. +The high-level structure of the checker's class is thus: + +

    +class SimpleStreamChecker : public Checker<check::PreCall,
+                                           check::PostCall,
+                                           check::DeadSysbols,
+                                           check::PointerEscape> {
+    public:
+
+    void checkPreCall(const CallEvent &Call, CheckerContext &C) const;
+
+    void checkPostCall(const CallEvent &Call, CheckerContext &C) const;
+
+    void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const;
+
+    ProgramStateRef checkPointerEscape(ProgramStateRef State,
+                                       const InvalidatedSymbols &Escaped,
+                                       const CallEvent *Call,
+                                       PointerEscapeKind Kind) const;
+};
+

    Bug Reports

    + +

    + When a checker detects a mistake in the analyzed code, it needs a way to report + it to the Analyzer so that it can be displayed. This uses two classes: + BugType + and + BugReport. + +

    +BugType, as the name would suggest, represents a type of bug. The +constructor for BugType takes two parameters: The name of the bug +type, and the name of the category of the bug. These are used (e.g.) in the +summary page generated by the scan-build tool. + +

    + The BugReport class represents a specific occurrence of an bug. In + the most common case, three parameters are used to form a BugReport: +

      +
    1. The type of bug, specified as an instance of the BugType class. +
    2. A short descriptive string. This is placed at the location of the bug in +the detailed line-by-line output generated by scan-build. +
    3. The context in which the bug occurred. This includes both the location of +the bug in the code and the program's state when this location is reached. This +is in the form of a node in the ExplodedGraph. +
    + +

    The node representing this context can be obtained one of two ways: + +

      +
    1. If the state has been updated, then the CheckerContext::addTransition +function will return the updated state node. +
    2. If the state has not been updated, it can be obtained by calling the CheckerContext::getState +function. +
    + +In addition, the checker needs to decide if the analysis should continue along +the current path. This will depend on the nature of the bug, and whether it +would prevent the program could continuing. For example, leaking of a resource +should not stop analysis, as the program can continue to run after the leak. +Dereferencing a null pointer, on the other hand, should stop analysis, as there +is no way for the program to meaningfully continue after such an error. + +If analysis should not continue, then the current state should be transitioned +into a so-called sink node, a node from which no further analysis will be +performed. This is done by calling the +CheckerContext::generateSink function. + +

    +After a BugReport is created, it should be passed to the +EmitReport function of the CheckerContext. +

    AST Visitors

    Some checks might not require path-sensitivity to be effective. Simple AST walk might be sufficient. If that is the case, consider implementing a Clang @@ -356,6 +531,31 @@ To dump AST of a method that the current ExplodedNode belongs to:
    • +

    Additional Sources of Information

    + +Here are some additional resources that are useful when working on the Clang +Static Analyzer: + + +