LIEF: Library to Instrument Executable Formats Version 0.17.0
Loading...
Searching...
No Matches
Abstract/Binary.hpp
Go to the documentation of this file.
1/* Copyright 2017 - 2025 R. Thomas
2 * Copyright 2017 - 2025 Quarkslab
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16#ifndef LIEF_ABSTRACT_BINARY_H
17#define LIEF_ABSTRACT_BINARY_H
18
19#include <vector>
20#include <memory>
21#include <unordered_map>
22
23#include "LIEF/visibility.h"
24#include "LIEF/Object.hpp"
25#include "LIEF/iterators.hpp"
26#include "LIEF/errors.hpp"
27#include "LIEF/span.hpp"
28
31
34
35namespace llvm {
36class MCInst;
37}
38
40namespace LIEF {
41class Section;
42class Relocation;
43class Symbol;
44
45class DebugInfo;
46
47namespace assembly {
48class Engine;
49}
50
59class LIEF_API Binary : public Object {
60 public:
61
63 enum class VA_TYPES {
66 AUTO = 0,
67
69 RVA = 1,
70
72 VA = 2
73 };
74
82
83 using functions_t = std::vector<Function>;
84
86 using sections_t = std::vector<Section*>;
87
90
93
95 using symbols_t = std::vector<Symbol*>;
96
99
102
104 using relocations_t = std::vector<Relocation*>;
105
108
111
114
115 public:
118
119 ~Binary() override;
120
121 Binary& operator=(const Binary&) = delete;
122 Binary(const Binary&) = delete;
123
125 FORMATS format() const {
126 return format_;
127 }
128
130 Header header() const {
131 return get_abstract_header();
132 }
133
136 return get_abstract_symbols();
137 }
138
141 return const_cast<Binary*>(this)->get_abstract_symbols();
142 }
143
145 bool has_symbol(const std::string& name) const {
146 return get_symbol(name) != nullptr;
147 }
148
151 const Symbol* get_symbol(const std::string& name) const;
152
153 Symbol* get_symbol(const std::string& name) {
154 return const_cast<Symbol*>(static_cast<const Binary*>(this)->get_symbol(name));
155 }
156
159 return get_abstract_sections();
160 }
161
163 return const_cast<Binary*>(this)->get_abstract_sections();
164 }
165
167 virtual void remove_section(const std::string& name, bool clear = false) = 0;
168
171 return get_abstract_relocations();
172 }
173
175 return const_cast<Binary*>(this)->get_abstract_relocations();
176 }
177
179 virtual uint64_t entrypoint() const = 0;
180
182 uint64_t original_size() const {
183 return original_size_;
184 }
185
188 return get_abstract_exported_functions();
189 }
190
192 std::vector<std::string> imported_libraries() const {
193 return get_abstract_imported_libraries();
194 }
195
198 return get_abstract_imported_functions();
199 }
200
202 virtual result<uint64_t> get_function_address(const std::string& func_name) const;
203
205 void accept(Visitor& visitor) const override;
206
207 std::vector<uint64_t> xref(uint64_t address) const;
208
215 virtual void patch_address(uint64_t address, const std::vector<uint8_t>& patch_value,
216 VA_TYPES addr_type = VA_TYPES::AUTO) = 0;
217
224 virtual void patch_address(uint64_t address, uint64_t patch_value, size_t size = sizeof(uint64_t),
225 VA_TYPES addr_type = VA_TYPES::AUTO) = 0;
226
228 virtual span<const uint8_t>
229 get_content_from_virtual_address(uint64_t virtual_address, uint64_t size,
230 VA_TYPES addr_type = VA_TYPES::AUTO) const = 0;
231
233 template<class T>
235 uint64_t va, VA_TYPES addr_type = VA_TYPES::AUTO) const
236 {
237 T value;
238 static_assert(std::is_integral<T>::value, "Require an integral type");
239 span<const uint8_t> raw = get_content_from_virtual_address(va, sizeof(T), addr_type);
240 if (raw.empty() || raw.size() < sizeof(T)) {
242 }
243
244 std::copy(raw.data(), raw.data() + sizeof(T),
245 reinterpret_cast<uint8_t*>(&value));
246 return value;
247 }
248
254 void original_size(uint64_t size) {
255 original_size_ = size;
256 }
257
259 virtual bool is_pie() const = 0;
260
262 virtual bool has_nx() const = 0;
263
265 virtual uint64_t imagebase() const = 0;
266
268 virtual functions_t ctor_functions() const = 0;
269
274 virtual result<uint64_t> offset_to_virtual_address(uint64_t offset, uint64_t slide = 0) const = 0;
275
276 virtual std::ostream& print(std::ostream& os) const {
277 return os;
278 }
279
280 LIEF_API friend std::ostream& operator<<(std::ostream& os, const Binary& binary) {
281 binary.print(os);
282 return os;
283 }
284
299
311 instructions_it disassemble(uint64_t address, size_t size) const;
312
323 instructions_it disassemble(uint64_t address) const;
324
335 instructions_it disassemble(const std::string& function) const;
336
341 instructions_it disassemble(const uint8_t* buffer, size_t size,
342 uint64_t address = 0) const;
343
344
349 instructions_it disassemble(const std::vector<uint8_t>& buffer,
350 uint64_t address = 0) const {
351 return disassemble(buffer.data(), buffer.size(), address);
352 }
353
355 uint64_t address = 0) const {
356 return disassemble(buffer.data(), buffer.size(), address);
357 }
358
359 instructions_it disassemble(LIEF::span<uint8_t> buffer, uint64_t address = 0) const {
360 return disassemble(buffer.data(), buffer.size(), address);
361 }
362
376 std::vector<uint8_t> assemble(uint64_t address, const std::string& Asm,
378
383 std::vector<uint8_t> assemble(uint64_t address, const llvm::MCInst& inst);
384
389 std::vector<uint8_t> assemble(uint64_t address,
390 const std::vector<llvm::MCInst>& insts);
391
394 virtual uint64_t page_size() const;
395
411 DebugInfo* load_debug_info(const std::string& path);
412
413 protected:
414 FORMATS format_ = FORMATS::UNKNOWN;
415 mutable std::unique_ptr<DebugInfo> debug_info_;
416 mutable std::unordered_map<uint32_t, std::unique_ptr<assembly::Engine>> engines_;
417 uint64_t original_size_ = 0;
418
419 assembly::Engine* get_engine(uint64_t address) const;
420
421 template<uint32_t Key, class F>
422 LIEF_LOCAL assembly::Engine* get_cache_engine(uint64_t address, F&& f) const;
423
424 // These functions need to be overloaded by the object that claims to extend this Abstract Binary
425 virtual Header get_abstract_header() const = 0;
426 virtual symbols_t get_abstract_symbols() = 0;
427 virtual sections_t get_abstract_sections() = 0;
428 virtual relocations_t get_abstract_relocations() = 0;
429
430 virtual functions_t get_abstract_exported_functions() const = 0;
431 virtual functions_t get_abstract_imported_functions() const = 0;
432 virtual std::vector<std::string> get_abstract_imported_libraries() const = 0;
433};
434
437
438}
439
440
441#endif
Header header() const
Return the abstract header of the binary.
Definition Abstract/Binary.hpp:130
ref_iterator< symbols_t > it_symbols
Iterator that outputs LIEF::Symbol&.
Definition Abstract/Binary.hpp:98
virtual void patch_address(uint64_t address, const std::vector< uint8_t > &patch_value, VA_TYPES addr_type=VA_TYPES::AUTO)=0
Patch the content at virtual address address with patch_value.
std::vector< Function > functions_t
Definition Abstract/Binary.hpp:83
functions_t imported_functions() const
Return functions imported by the binary.
Definition Abstract/Binary.hpp:197
virtual uint64_t entrypoint() const =0
Binary's entrypoint (if any).
const_ref_iterator< relocations_t > it_const_relocations
Iterator that outputs const LIEF::Relocation&.
Definition Abstract/Binary.hpp:110
FORMATS
Definition Abstract/Binary.hpp:75
@ UNKNOWN
Definition Abstract/Binary.hpp:76
@ ELF
Definition Abstract/Binary.hpp:77
@ OAT
Definition Abstract/Binary.hpp:80
@ PE
Definition Abstract/Binary.hpp:78
@ MACHO
Definition Abstract/Binary.hpp:79
virtual result< uint64_t > offset_to_virtual_address(uint64_t offset, uint64_t slide=0) const =0
Convert the given offset into a virtual address.
bool has_symbol(const std::string &name) const
Check if a Symbol with the given name exists.
Definition Abstract/Binary.hpp:145
const Symbol * get_symbol(const std::string &name) const
Return the Symbol with the given name If the symbol does not exist, return a nullptr.
Symbol * get_symbol(const std::string &name)
Definition Abstract/Binary.hpp:153
LIEF::result< T > get_int_from_virtual_address(uint64_t va, VA_TYPES addr_type=VA_TYPES::AUTO) const
Get the integer value at the given virtual address.
Definition Abstract/Binary.hpp:234
FORMATS format() const
Executable format (ELF, PE, Mach-O) of the underlying binary.
Definition Abstract/Binary.hpp:125
friend std::ostream & operator<<(std::ostream &os, const Binary &binary)
Definition Abstract/Binary.hpp:280
ref_iterator< sections_t > it_sections
Iterator that outputs LIEF::Section&.
Definition Abstract/Binary.hpp:89
it_const_sections sections() const
Definition Abstract/Binary.hpp:162
const_ref_iterator< sections_t > it_const_sections
Iterator that outputs const LIEF::Section&.
Definition Abstract/Binary.hpp:92
virtual void remove_section(const std::string &name, bool clear=false)=0
Remove all the sections in the underlying binary.
it_relocations relocations()
Return an iterator over the binary relocation (LIEF::Relocation).
Definition Abstract/Binary.hpp:170
it_const_symbols symbols() const
Return an iterator over the abstracted symbols in which the elements can't be modified.
Definition Abstract/Binary.hpp:140
std::vector< Symbol * > symbols_t
Internal container.
Definition Abstract/Binary.hpp:95
~Binary() override
instructions_it disassemble(uint64_t address, size_t size) const
Disassemble code starting at the given virtual address and with the given size.
DebugInfo * load_debug_info(const std::string &path)
Load and associate an external debug file (e.g., DWARF or PDB) with this binary.
void original_size(uint64_t size)
Change binary's original size.
Definition Abstract/Binary.hpp:254
VA_TYPES
Enumeration of virtual address types used for patching and memory access.
Definition Abstract/Binary.hpp:63
@ VA
Absolute Virtual Address.
Definition Abstract/Binary.hpp:72
@ RVA
Relative Virtual Address (RVA), offset from image base.
Definition Abstract/Binary.hpp:69
@ AUTO
Automatically determine if the address is absolute or relative (default behavior).
Definition Abstract/Binary.hpp:66
instructions_it disassemble(const std::string &function) const
Disassemble code for the given symbol name.
std::vector< uint64_t > xref(uint64_t address) const
std::vector< Section * > sections_t
Internal container.
Definition Abstract/Binary.hpp:86
virtual bool is_pie() const =0
Check if the binary is position independent.
functions_t exported_functions() const
Return the functions exported by the binary.
Definition Abstract/Binary.hpp:187
virtual uint64_t page_size() const
Get the default memory page size according to the architecture and the format of the current binary.
virtual span< const uint8_t > get_content_from_virtual_address(uint64_t virtual_address, uint64_t size, VA_TYPES addr_type=VA_TYPES::AUTO) const =0
Return the content located at the given virtual address.
virtual std::ostream & print(std::ostream &os) const
Definition Abstract/Binary.hpp:276
std::vector< uint8_t > assemble(uint64_t address, const std::string &Asm, assembly::AssemblerConfig &config=assembly::AssemblerConfig::default_config())
Assemble and patch the provided assembly code at the specified address.
const_ref_iterator< symbols_t > it_const_symbols
Iterator that outputs const LIEF::Symbol&.
Definition Abstract/Binary.hpp:101
virtual void patch_address(uint64_t address, uint64_t patch_value, size_t size=sizeof(uint64_t), VA_TYPES addr_type=VA_TYPES::AUTO)=0
Patch the address with the given value.
it_symbols symbols()
Return an iterator over the abstracted symbols in which the elements can be modified.
Definition Abstract/Binary.hpp:135
virtual result< uint64_t > get_function_address(const std::string &func_name) const
Return the address of the given function name.
std::vector< uint8_t > assemble(uint64_t address, const std::vector< llvm::MCInst > &insts)
Assemble and patch the address with the given LLVM MCInst.
it_sections sections()
Return an iterator over the binary's sections (LIEF::Section).
Definition Abstract/Binary.hpp:158
virtual functions_t ctor_functions() const =0
Constructor functions that are called prior any other functions.
instructions_it disassemble(uint64_t address) const
Disassemble code starting at the given virtual address.
std::vector< uint8_t > assemble(uint64_t address, const llvm::MCInst &inst)
Assemble and patch the address with the given LLVM MCInst.
Binary & operator=(const Binary &)=delete
iterator_range< assembly::Instruction::Iterator > instructions_it
Instruction iterator.
Definition Abstract/Binary.hpp:113
virtual uint64_t imagebase() const =0
Default image base address if the ASLR is not enabled.
std::vector< std::string > imported_libraries() const
Return libraries which are imported by the binary.
Definition Abstract/Binary.hpp:192
instructions_it disassemble(const std::vector< uint8_t > &buffer, uint64_t address=0) const
Disassemble code provided by the given vector of bytes at the specified address parameter.
Definition Abstract/Binary.hpp:349
Binary(FORMATS fmt)
DebugInfo * debug_info() const
Return the debug info if present. It can be either a LIEF::dwarf::DebugInfo or a LIEF::pdb::DebugInfo...
uint64_t original_size() const
Binary's original size.
Definition Abstract/Binary.hpp:182
void accept(Visitor &visitor) const override
Method so that a visitor can visit us.
it_const_relocations relocations() const
Definition Abstract/Binary.hpp:174
ref_iterator< relocations_t > it_relocations
Iterator that outputs LIEF::Relocation&.
Definition Abstract/Binary.hpp:107
std::vector< Relocation * > relocations_t
Internal container.
Definition Abstract/Binary.hpp:104
instructions_it disassemble(LIEF::span< uint8_t > buffer, uint64_t address=0) const
Definition Abstract/Binary.hpp:359
Binary(const Binary &)=delete
instructions_it disassemble(LIEF::span< const uint8_t > buffer, uint64_t address=0) const
Definition Abstract/Binary.hpp:354
instructions_it disassemble(const uint8_t *buffer, size_t size, uint64_t address=0) const
Disassemble code provided by the given buffer at the specified address parameter.
virtual bool has_nx() const =0
Check if the binary uses NX protection.
This class provides a generic interface for accessing debug information from different formats such a...
Definition Abstract/DebugInfo.hpp:38
Definition Abstract/Header.hpp:40
Class which represents an abstracted Relocation.
Definition Abstract/Relocation.hpp:27
Class which represents an abstracted section.
Definition Abstract/Section.hpp:29
This class represents a symbol in an executable format.
Definition Abstract/Symbol.hpp:28
Definition Visitor.hpp:210
This class exposes the different elements that can be configured to assemble code.
Definition AssemblerConfig.hpp:29
static AssemblerConfig & default_config()
Default configuration.
Definition AssemblerConfig.hpp:50
This class interfaces the assembler/disassembler support.
Definition Engine.hpp:36
Definition iterators.hpp:486
Iterator which returns reference on container's values.
Definition iterators.hpp:46
Wrapper that contains an Object (T) or an error.
Definition errors.hpp:75
@ read_error
Definition errors.hpp:24
tl::unexpected< lief_errors > make_error_code(lief_errors e)
Create an standard error code from lief_errors.
Definition errors.hpp:52
Namespace related to assembly/disassembly support.
Definition Abstract/Binary.hpp:47
LIEF namespace.
Definition Abstract/Binary.hpp:40
tcb::span< ElementType, Extent > span
Definition span.hpp:22
ref_iterator< CT, U, typename decay_t< CT >::const_iterator > const_ref_iterator
Iterator which return const ref on container's values.
Definition iterators.hpp:257
const char * to_string(Binary::VA_TYPES e)
Definition Abstract/Binary.hpp:35
#define LIEF_API
Definition visibility.h:41
#define LIEF_LOCAL
Definition visibility.h:42