Browse files

document

  • Loading branch information...
1 parent 95acee3 commit a6856231047483825b5bf9dd70f7e3a7a5090e2e @kmcallister committed Aug 28, 2011
Showing with 104 additions and 8 deletions.
  1. +45 −1 Dewdrop.hs
  2. +29 −5 Dewdrop/Analyze.hs
  3. +10 −0 README
  4. +20 −2 dewdrop.cabal
View
46 Dewdrop.hs
@@ -1,6 +1,38 @@
+{- | Print ROP gadgets having some desired property.
+
+This module provides the quickest way to get started:
+
+> $ 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
+>
+> ...
+
+If you need more control, see "Dewdrop.Analyze".
+
+-}
+
module Dewdrop
- ( dewdrop
+ ( -- * Finding gadgets
+ dewdrop
+
+ -- * Helpers for selecting gadgets
, usesRegister, usesSegment, opcode
+
+ -- * Re-export of disassembler
+ --
+ -- | The types and functions of @Hdis86@
+ -- are re-exported for convenience.
, module Hdis86
) where
@@ -20,6 +52,9 @@ import qualified Generics.SYB as G
import Data.Elf
import Hdis86
+-- | 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 ()
dewdrop wanted = do
args@(~(elf_file:_)) <- getArgs
@@ -32,11 +67,20 @@ dewdrop wanted = do
hasSub :: (Typeable a, Eq a, Data b) => a -> b -> Bool
hasSub x = not . null . G.listify (== x)
+-- | Does this instruction use a given register?
+--
+-- This only includes registers explicitly mentioned in disassembly,
+-- and not e.g. the @rsi@ / @rdi@ operands of @movsd@.
usesRegister :: GPR -> Metadata -> Bool
usesRegister = hasSub
+-- | Does this instruction mention a given segment register?
+--
+-- This only includes explicit overrides, and loads/stores of
+-- segment registers.
usesSegment :: Segment -> Metadata -> Bool
usesSegment = hasSub
+-- | Get the @'Opcode'@ directly from an instruction-with-metadata.
opcode :: Metadata -> Opcode
opcode = inOpcode . mdInst
View
34 Dewdrop/Analyze.hs
@@ -1,9 +1,19 @@
{-# LANGUAGE
DeriveDataTypeable #-}
+
+-- | Analyze the ROP gadgets in an ELF binary.
+--
+-- Use this module if you need more control, or integration with a larger
+-- program. The module "Dewdrop" provides a simpler way to put together a
+-- standalone gadget finder.
module Dewdrop.Analyze
- ( Gadget(..)
+ ( -- * Finding gadgets
+ Gadget(..)
, gadgets, valid
- , gadgetsWith, Config(..), defaultConfig
+
+ -- * Configuring the gadget finder
+ , Config(..), defaultConfig
+ , gadgetsWith
) where
import Text.Printf
@@ -18,6 +28,10 @@ import Data.Elf
import Hdis86 hiding ( Config(..) )
import qualified Hdis86 as H
+-- | A sequence of instructions, each with metadata.
+--
+-- The @'Show'@ instance produces assembly code with labeled offsets,
+-- so you can @'print'@ these directly.
newtype Gadget = Gadget [Metadata]
deriving (Eq, Ord, Typeable, Data)
@@ -29,15 +43,19 @@ instance Show Gadget where
| otherwise = "%08x:\n"
asm = map ((" "++) . mdAssembly) g
+-- | Configuration of the gadget finder.
data Config = Config
- { cfgSyntax :: Syntax
- , cfgVendor :: Vendor
- , cfgMaxSize :: Int
+ { cfgSyntax :: Syntax -- ^ Assembly syntax for display
+ , cfgVendor :: Vendor -- ^ CPU vendor; affects decoding of a
+ -- few instructions
+ , cfgMaxSize :: Int -- ^ Maximum size of a gadget, in bytes
} deriving (Eq, Ord, Read, Show, Typeable, Data)
+-- | Default configuration of the gadget finder.
defaultConfig :: Config
defaultConfig = Config SyntaxATT Intel 20
+-- | Find possible gadgets, using a custom configuration.
gadgetsWith :: Config -> Elf -> [Gadget]
gadgetsWith cfg elf = map Gadget $ concatMap scanSect exec where
hcfg = intel32 {
@@ -61,9 +79,15 @@ gadgetsWith cfg elf = map Gadget $ concatMap scanSect exec where
- fromIntegral (B.length subseq)
return $ disassembleMetadata (hcfg { H.cfgOrigin = addr }) subseq
+-- | Find possible gadgets.
+--
+-- You can filter these further using @'valid'@ or other tests.
gadgets :: Elf -> [Gadget]
gadgets = gadgetsWith defaultConfig
+-- | Rejects gadgets which are probably not useful for return-oriented
+-- programming. This includes gadgets containing invalid or privileged
+-- instructions.
valid :: Gadget -> Bool
valid = \(Gadget g) -> all ($ g) [(>1) . length, opcodesOk] where
-- scoped outside the lambda, to share evaluation between calls
View
10 README
@@ -0,0 +1,10 @@
+dewdrop is a Haskell library for finding gadgets for return-oriented
+programming in 32- and 64-bit x86 ELF binaries.
+
+Documentation is hosted at http://hackage.haskell.org/package/dewdrop
+
+To build the documentation yourself, run
+
+ $ cabal configure && cabal haddock --hyperlink-source
+
+This will produce HTML documentation under dist/doc/html/dewdrop.
View
22 dewdrop.cabal
@@ -2,15 +2,33 @@ name: dewdrop
version: 0.1
license: BSD3
license-file: LICENSE
-synopsis: FIXME
+synopsis: Find gadgets for return-oriented programming on x86
category: Reverse Engineering, Security
author: Nelson Elhage <nelhage@nelhage.com>, Keegan McAllister <mcallister.keegan@gmail.com>
maintainer: Keegan McAllister <mcallister.keegan@gmail.com>
homepage: https://github.com/kmcallister/dewdrop
build-type: Simple
cabal-version: >=1.6
description:
- FIXME
+ 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 @Dewdrop@ module to make a customized
+ gadget-finder program. Or you can import @Dewdrop.Analyze@ and integrate
+ this functionality into a larger program.
+ .
+ \[1\] Shacham, Hovav. /The Geometry of Innocent Flesh on the Bone:/
+ /Return-into-libc without Function Calls (on the x86)/. CCS 2007,
+ pages 552-561.
library
exposed-modules:

0 comments on commit a685623

Please sign in to comment.