Module: PWN::Plugins::AFLplusplus

Defined in:
lib/pwn/plugins/aflplusplus.rb

Overview

AFL++ / libFuzzer campaign wrapper with corpus, dictionary, and RE triage handoff.

Class Method Summary collapse

Class Method Details

.authors ⇒ Object 



163
164
165
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 163

public_class_method def self.authors
  "AUTHOR(S):\n  0day Inc. <[email protected]>\n"
end

.campaign(opts = {}) ⇒ Object

Raises:

  • (ArgumentError) 


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 102

public_class_method def self.campaign(opts = {})
  opts = opts.transform_keys(&:to_sym)
  in_dir = prepare_corpus(opts)
  out_dir = (opts[:out_dir] || opts[:output]).to_s
  raise ArgumentError, 'out_dir is required' if out_dir.empty?

  FileUtils.mkdir_p(out_dir)
  bin = binary_from_target(target: opts[:target])
  dict_info = File.file?(bin.to_s) ? dictionary_from_binary(path: bin) : { dict: '', tokens: [] }
  dict_path = File.join(out_dir, 'tokens.dict')
  File.write(dict_path, dict_info[:dict].to_s)
  unless opts[:skip_fuzz]
    argv = fuzzer_argv(opts.merge(in_dir: in_dir, dict: dict_path, binary: bin, out_dir: out_dir))
    run_fuzzer(argv: argv, max_runtime: opts[:max_runtime], env: opts[:env], cwd: opts[:cwd])
  end
  crash_triage(out_dir: out_dir, target: bin || opts[:target], handoff: opts.fetch(:handoff, true))
end

.campaign_command(opts = {}) ⇒ Object 



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 77

public_class_method def self.campaign_command(opts = {})
  payload = {
    engine: opts[:engine] || 'aflplusplus',
    in_dir: opts[:in_dir],
    out_dir: opts[:out_dir],
    target: opts[:target],
    max_runtime: opts[:max_runtime],
    cwd: opts[:cwd],
    env: opts[:env],
    handoff: opts.fetch(:handoff, true)
  }
  b64 = Base64.strict_encode64(JSON.generate(payload))
  Shellwords.join(
    [
      RbConfig.ruby,
      '-rpwn',
      '-rjson',
      '-rbase64',
      '-e',
      'PWN::Plugins::AFLplusplus.campaign(JSON.parse(Base64.decode64(ARGV[0]), symbolize_names: true))',
      b64
    ]
  )
end

.crash_triage(opts = {}) ⇒ Object 



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 120

public_class_method def self.crash_triage(opts = {})
  out_dir = (opts[:out_dir] || opts[:output]).to_s
  raise 'ERROR: out_dir is required' if out_dir.empty?

  files = crash_files(out_dir: out_dir)
  target = binary_from_target(target: opts[:target])
  groups = Hash.new { |hash, key| hash[key] = { files: [] } }
  files.each do |path|
    stdin = File.binread(path)
    crash = replay_crash(target: target, stdin: stdin)
    key = backtrace_hash(crash: crash)
    groups[key][:files] << path
    groups[key][:crash] ||= crash
    groups[key][:stdin] ||= stdin
  end
  triaged = []
  if opts[:handoff] != false
    groups.each do |key, group|
      triaged << handoff_re003(target: target, crash: group[:crash], stdin: group[:stdin], files: group[:files], backtrace_hash: key)
    end
  end
  hashes = files.map { |path| [path, Digest::SHA256.file(path).hexdigest] }
  {
    crashes: files,
    unique: groups.keys,
    triaged: triaged,
    pipeline: 'pwn-re-003',
    asan: files.any? { |path| File.binread(path).include?('AddressSanitizer') },
    artifacts: hashes.map { |path, sha| { path: path, sha256: sha } }
  }
end

.dictionary_from_binary(opts = {}) ⇒ Object

Raises:

  • (ArgumentError) 


48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 48

public_class_method def self.dictionary_from_binary(opts = {})
  path = (opts[:path] || opts[:target] || opts[:bin]).to_s
  raise ArgumentError, 'path is required' if path.empty?

  triage = PWN::Plugins::BinaryParser.triage(path: path, session_id: opts[:session_id] || 'fuzz-dict')
  strings = triage[:interesting_strings] || {}
  tokens = []
  tokens.concat(Array(strings[:urls]))
  tokens.concat(Array(strings[:paths]))
  tokens.concat(Array(strings[:format_strings]))
  tokens.concat(Array(strings[:keys]))
  tokens.concat(Array(triage[:imports]).map(&:to_s).grep(/\A[A-Za-z_]{3,}/).first(20))
  tokens = tokens.map(&:to_s).uniq.reject(&:empty?).first(200)
  quoted = tokens.map { |token| format('"%s"', token.gsub('\\', '\\\\').gsub('"', '\\"')) }
  { path: path, tokens: tokens, dict: quoted.join("\n") }
end

.fuzz(opts = {}) ⇒ Object 



19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 19

public_class_method def self.fuzz(opts = {})
  PWN::Plugins::PreflightChecker.require_bin!(name: 'afl-fuzz')
  in_dir = opts[:in_dir] || opts[:corpus]
  out_dir = opts[:out_dir] || opts[:output]
  target = opts[:target]
  raise 'ERROR: in_dir, out_dir, and target are required' if in_dir.to_s.empty? || out_dir.to_s.empty? || target.to_s.empty?

  cmd = ['afl-fuzz', '-i', in_dir.to_s, '-o', out_dir.to_s, '--', target.to_s]
  cmd.concat(Array(opts[:args]))
  stdout, stderr, status = Open3.capture3(*cmd)
  { stdout: stdout, stderr: stderr, exit: status.exitstatus }
end

.help ⇒ Object 



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 167

public_class_method def self.help
  puts "USAGE:
    # List host binaries this module expects to be installed.
    #{self}.required_bins

    # Run fuzz and return its result
    #{self}.fuzz(
      in_dir: 'required - in dir value consumed by #fuzz (defaults to opts[:corpus])',
      corpus: 'optional - corpus value consumed by #fuzz',
      out_dir: 'required - out dir value consumed by #fuzz (defaults to opts[:output])',
      output: 'optional - output value consumed by #fuzz',
      target: 'required - hostname, IP, or CIDR to scan',
      args: 'optional - Array args value consumed by #fuzz'
    )

    # Parse AFL fuzzer_stats (execs_per_sec, paths, crashes) from out_dir.
    #{self}.parse_stats(
      out_dir: 'required - AFL output directory containing fuzzer_stats',
      output: 'optional - alias for out_dir'
    )

    # Build an AFL/libFuzzer dictionary from interesting strings in a binary.
    #{self}.dictionary_from_binary(
      path: 'required - filesystem path of the fuzz target ELF',
      target: 'optional - alias for path',
      bin: 'optional - alias for path',
      session_id: 'optional - artifact session id for BinaryParser.triage'
    )

    # Ensure a corpus directory exists and contains at least one seed.
    #{self}.prepare_corpus(
      in_dir: 'required - corpus directory (defaults to opts[:corpus])',
      corpus: 'optional - alias for in_dir',
      seeds: 'optional - extra seed file paths to copy into the corpus'
    )

    # Build a durable Jobs command that runs campaign then RE triage.
    #{self}.campaign_command(
      engine: 'optional - aflplusplus or libfuzzer (defaults to aflplusplus)',
      in_dir: 'required - corpus directory',
      out_dir: 'required - fuzzer output directory',
      target: 'required - fuzz target command or binary path',
      max_runtime: 'optional - seconds the supervisor may run',
      cwd: 'optional - working directory',
      env: 'optional - string environment map',
      handoff: 'optional - false skips PWN-RE-003 crash handoff (defaults to true)'
    )

    # Prepare corpus/dict, run AFL++ or libFuzzer, then triage unique crashes.
    #{self}.campaign(
      engine: 'optional - aflplusplus or libfuzzer (defaults to aflplusplus)',
      in_dir: 'required - corpus directory',
      out_dir: 'required - fuzzer output directory',
      output: 'optional - alias for out_dir',
      target: 'required - fuzz target command or binary path',
      max_runtime: 'optional - seconds forwarded to the fuzzer',
      cwd: 'optional - working directory',
      env: 'optional - string environment map',
      skip_fuzz: 'optional - true harvests existing crashes without launching a fuzzer',
      handoff: 'optional - false skips PWN-RE-003 crash handoff (defaults to true)',
      seeds: 'optional - extra seed file paths to copy into the corpus'
    )

    # Dedup crashes by backtrace hash and hand unique ones to PWN-RE-003 triage.
    #{self}.crash_triage(
      out_dir: 'required - AFL output directory containing crashes/',
      output: 'optional - alias for out_dir',
      target: 'optional - fuzz target binary used to replay crashes',
      handoff: 'optional - false skips GDBMI/BinaryParser/ExploitDev handoff (defaults to true)'
    )

    # Minimize a crash input with afl-tmin when present.
    #{self}.minimize(
      crash: 'required - path to a crashing input',
      out: 'required - path to write the minimized input',
      target: 'required - fuzz target binary'
    )

    # Print the AUTHOR(S) string for this module.
    #{self}.authors
  "
  constants.sort
end

.minimize(opts = {}) ⇒ Object 



152
153
154
155
156
157
158
159
160
161
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 152

public_class_method def self.minimize(opts = {})
  crash = opts[:crash].to_s
  out = opts[:out].to_s
  target = opts[:target].to_s
  raise 'ERROR: crash, out, and target are required' if crash.empty? || out.empty? || target.empty?
  return { error: 'afl-tmin missing', hint: 'pwn setup --profile re' } unless PWN::Plugins::PreflightChecker.bin?(name: 'afl-tmin')

  stdout, stderr, status = Open3.capture3('afl-tmin', '-i', crash, '-o', out, '--', target)
  { stdout: stdout, stderr: stderr, exit: status.exitstatus, out: out }
end

.parse_stats(opts = {}) ⇒ Object 



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 32

public_class_method def self.parse_stats(opts = {})
  out_dir = (opts[:out_dir] || opts[:output]).to_s
  raise 'ERROR: out_dir is required' if out_dir.empty?

  path = File.join(out_dir, 'fuzzer_stats')
  path = File.join(out_dir, 'default', 'fuzzer_stats') unless File.file?(path)
  return {} unless File.file?(path)

  File.read(path).each_line.with_object({}) do |line, acc|
    key, val = line.split(':', 2)
    next if key.to_s.strip.empty?

    acc[key.strip.to_sym] = val.to_s.strip
  end
end

.prepare_corpus(opts = {}) ⇒ Object

Raises:

  • (ArgumentError) 


65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 65

public_class_method def self.prepare_corpus(opts = {})
  in_dir = (opts[:in_dir] || opts[:corpus]).to_s
  raise ArgumentError, 'in_dir is required' if in_dir.empty?

  FileUtils.mkdir_p(in_dir)
  File.binwrite(File.join(in_dir, 'seed'), "A\n") unless Dir.children(in_dir).any? { |name| File.file?(File.join(in_dir, name)) }
  Array(opts[:seeds]).each_with_index do |seed, idx|
    FileUtils.cp(seed, File.join(in_dir, "seed-#{idx}")) if File.file?(seed.to_s)
  end
  in_dir
end

.required_bins ⇒ Object 



15
16
17
 
# File 'lib/pwn/plugins/aflplusplus.rb', line 15

public_class_method def self.required_bins
  %w[afl-fuzz]
end