-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Find gadgets for return-oriented programming on x86
--   
--   Traditional buffer-overflow attacks work by filling a data buffer with
--   exploit code and then redirecting execution to that buffer. As a
--   countermeasure, modern operating systems will forbid (by default) the
--   execution of writable memory regions.
--   
--   Return-oriented programming [1] is an alternative exploitation
--   strategy that works around this restriction. The exploit payload is
--   built by chaining together short code sequences ("gadgets") which are
--   already present in the exploited program, and thus are allowed to be
--   executed.
--   
--   dewdrop is a Haskell library for finding useful gadgets in 32- and
--   64-bit x86 ELF binaries. You can describe the desired gadget
--   properties with a Haskell function, and use the <tt>Dewdrop</tt>
--   module to make a customized gadget-finder program. Or you can import
--   <tt>Dewdrop.Analyze</tt> and integrate this functionality into a
--   larger program.
--   
--   [1] Shacham, Hovav. <i>The Geometry of Innocent Flesh on the Bone:</i>
--   <i>Return-into-libc without Function Calls (on the x86)</i>. CCS 2007,
--   pages 552-561.
@package dewdrop
@version 0.1


-- | Analyze the ROP gadgets in an ELF binary.
--   
--   Use this module if you need more control, or integration with a larger
--   program. The module <a>Dewdrop</a> provides a simpler way to put
--   together a standalone gadget finder.
module Dewdrop.Analyze

-- | A sequence of instructions, each with metadata.
--   
--   The <tt><a>Show</a></tt> instance produces assembly code with labeled
--   offsets, so you can <tt><a>print</a></tt> these directly.
newtype Gadget
Gadget :: [Metadata] -> Gadget

-- | Find possible gadgets.
--   
--   You can filter these further using <tt><a>valid</a></tt> or other
--   tests.
gadgets :: Elf -> [Gadget]

-- | Rejects gadgets which are probably not useful for return-oriented
--   programming. This includes gadgets containing invalid or privileged
--   instructions.
valid :: Gadget -> Bool

-- | Configuration of the gadget finder.
data Config
Config :: Syntax -> Vendor -> Int -> Config

-- | Assembly syntax for display
cfgSyntax :: Config -> Syntax

-- | CPU vendor; affects decoding of a few instructions
cfgVendor :: Config -> Vendor

-- | Maximum size of a gadget, in bytes
cfgMaxSize :: Config -> Int

-- | Default configuration of the gadget finder.
defaultConfig :: Config

-- | Find possible gadgets, using a custom configuration.
gadgetsWith :: Config -> Elf -> [Gadget]
instance Typeable Gadget
instance Typeable Config
instance Eq Gadget
instance Ord Gadget
instance Data Gadget
instance Eq Config
instance Ord Config
instance Read Config
instance Show Config
instance Data Config
instance Show Gadget


-- | Print ROP gadgets having some desired property.
--   
--   This module provides the quickest way to get started:
--   
--   <pre>
--   $ cat find.hs
--   
--   import Dewdrop
--   main = dewdrop (any (usesRegister RBP))
--   
--   $ runhaskell find.hs /bin/ls
--   00402e56:
--     pop %rbp
--     ret
--   
--   0040afe7:
--     shl %cl, -0x15(%rbp)
--     rep ret
--   
--   ...
--   </pre>
--   
--   If you need more control, see <a>Dewdrop.Analyze</a>.
module Dewdrop

-- | Opens the ELF binary file passed as the first command-line argument,
--   and prints all ROP gadgets satisfying the specified property.
dewdrop :: ([Metadata] -> Bool) -> IO ()

-- | Does this instruction use a given register?
--   
--   This only includes registers explicitly mentioned in disassembly, and
--   not e.g. the <tt>rsi</tt> / <tt>rdi</tt> operands of <tt>movsd</tt>.
usesRegister :: GPR -> Metadata -> Bool

-- | Does this instruction mention a given segment register?
--   
--   This only includes explicit overrides, and loads/stores of segment
--   registers.
usesSegment :: Segment -> Metadata -> Bool

-- | Get the <tt><a>Opcode</a></tt> directly from an
--   instruction-with-metadata.
opcode :: Metadata -> Opcode