Writing Triggers

Writing Injection Triggers

Triggers are the extensible mechanism used by LFI to allow testers to specify conditions that should hold for an error to be injected into the application. Custom triggers can be written as needed in C/C++ and plugged into LFI. The default distribution comes with triggers based on call-stack, call-count, random injection and more advanced conditions, e.g. injecting when the calling thread holds a lock.

Technically, a trigger is a class that implements the Trigger interface:

class Trigger
{
public:
  virtual void Init(xmlNodePtr initData);
  virtual bool Eval(const string* functionName, ...) = 0;
};

The implementation of the Init function is optional and should be used only when the trigger can be initialized with different parameters, e.g. a random injection trigger could be initialized to fire 20% of the time, 70% of the time or any other value. The initialization data is passed in the form of an xmlNodePtr which represents an XML sub-tree that the function is responsible of parsing. See the triggers included with LFI and the libxml2 documentation for more implementation details.

The Eval function is called when LFI intercepts a library call and has to decide whether to inject a fault or not. The first argument is the name of the function that is being intercepted. Depending on the injection scenario (see Injection Scenarios for details) the Eval function can also receive the arguments that the program used to make the library call. The function must return true if a fault is to be injected and false otherwise.

When writing your own triggers, you should:

• #include "../Trigger.h" in your trigger class declaration file

• use the DEFINE_TRIGGER macro to declare your trigger class in a header file e.g., ExampleTrigger.h

   #include "../Trigger.h"
   DEFINE_TRIGGER( ExampleTrigger ) {
   public:
     ExampleTrigger();
     bool Eval(const string& functionName, ...);
   private:
     // any private data you need
   };
  

• define your trigger class in an associated file e.g., ExampleTrigger.cpp

   #include "ExampleTrigger.h"
   ExampleTrigger::ExampleTrigger() { }
   bool ExampleTrigger::Eval(const string* functionName, ...) {
     return true;
   }
  

• place the source code files (ExampleTrigger.h and ExampleTrigger.cpp) in the triggers/ folder

Caveats

• Trigger Init and Eval functions should be prepared to be executed before any static initializers from the same translation unit.