falcon 0.6.0

A Binary Analysis Framework in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

use crate::il;
use std::default;

/// An edge that will not be detected by Falcon's translator, but should exist.
///
/// This is used for re-lifting functions after Raptor has performed its jump
/// table analysis.
#[derive(Clone, Debug)]
pub struct ManualEdge {
    head_address: u64,
    tail_address: u64,
    condition: Option<il::Expression>,
}

impl ManualEdge {
    /// Create a new manual edge
    ///
    /// * `head_address` - The address of the instruction where this manual edge
    ///   should begin.
    /// * `tail_address` - The address of the block this edge should point to.
    /// * `condition` - An optional condition which guards this edge.
    ///
    /// If there is no block at `tail_address`, this will cause the translator
    /// to lift a block at the `tail_address`.
    pub fn new(
        head_address: u64,
        tail_address: u64,
        condition: Option<il::Expression>,
    ) -> ManualEdge {
        ManualEdge {
            head_address,
            tail_address,
            condition,
        }
    }

    /// Get the address of the instruction where this manual edge begins
    pub fn head_address(&self) -> u64 {
        self.head_address
    }

    /// Get the address of the block where this manual edge ends.
    pub fn tail_address(&self) -> u64 {
        self.tail_address
    }

    /// If this condition is guarded by a condition, get the condition
    pub fn condition(&self) -> Option<&il::Expression> {
        self.condition.as_ref()
    }
}

/// Various options that can be passed to the translator. Options will change
/// the behavior of the translator.
#[derive(Clone, Debug, Default)]
pub struct Options {
    manual_edges: Vec<ManualEdge>,
    unsupported_are_intrinsics: bool,
}

impl Options {
    /// Create a new set of Options with the default settings.
    pub fn new() -> Options {
        Options::default()
    }

    /// Set the value of the, "Unsupported are intrinsics," option.
    pub fn set_unsupported_are_intrinsics(&mut self, unsupported_are_intrinsics: bool) {
        self.unsupported_are_intrinsics = unsupported_are_intrinsics;
    }

    /// Whether the translator should throw an error for unhandled instruction,
    /// or simply lift them to an intrinsic.
    ///
    /// By default, lifters throw an error when they encounter an architecture
    /// instruction for which they have no semantics. This is not appropriate
    /// for all analyses. Sometimes we just want as many semantics as we can
    /// get. This flag tells lifters to emit intrinsic operations for
    /// unsupported instructions.
    pub fn unsupported_are_intrinsics(&self) -> bool {
        self.unsupported_are_intrinsics
    }

    /// Add a manual edge to the translator logic. See documentation on
    /// `ManualEdge` for further details.
    pub fn add_manual_edge(&mut self, manual_edge: ManualEdge) {
        self.manual_edges.push(manual_edge);
    }

    /// Get the manual edges this translator should enforce
    pub fn manual_edges(&self) -> &[ManualEdge] {
        &self.manual_edges
    }
}

/// Create your options with the builder pattern.
///
/// For more details on the options, see `translator::Options`
pub struct OptionsBuilder {
    options: Options,
}

impl OptionsBuilder {
    /// Create a new builder for translator options.
    pub fn new() -> OptionsBuilder {
        OptionsBuilder {
            options: Options::default(),
        }
    }

    /// Set the, "Unsupported are intrinsics," option. By default this is false.
    pub fn unsupported_are_intrinsics(
        mut self,
        unsupported_are_intrinsics: bool,
    ) -> OptionsBuilder {
        self.options.unsupported_are_intrinsics = unsupported_are_intrinsics;
        self
    }

    pub fn add_manual_edge(mut self, manual_edge: ManualEdge) -> OptionsBuilder {
        self.options.add_manual_edge(manual_edge);
        self
    }

    pub fn build(self) -> Options {
        self.options
    }
}

impl default::Default for OptionsBuilder {
    fn default() -> OptionsBuilder {
        OptionsBuilder::new()
    }
}