puffin/
cli.rs

1use std::fs::File;
2use std::io::{Read, Write};
3use std::path::{Path, PathBuf};
4use std::process::ExitCode;
5use std::time::Duration;
6use std::{env, fs};
7
8use clap::parser::ValuesRef;
9use clap::{arg, crate_authors, crate_name, value_parser, Command};
10use libafl::inputs::Input;
11use log::LevelFilter;
12use puffin_build::puffin;
13
14use crate::agent::AgentName;
15use crate::algebra::TermType;
16use crate::execution::{DifferentialRunner, ForkedRunner, Runner, TraceRunner};
17use crate::experiment::{format_title, write_experiment_markdown};
18use crate::fuzzer::config::{FuzzerConfig, FuzzingTarget};
19use crate::fuzzer::sanitizer::asan::{asan_info, setup_asan_env};
20use crate::fuzzer::start;
21use crate::graphviz::write_graphviz;
22use crate::log::config_default;
23use crate::protocol::{build_corpus, ProtocolBehavior, ProtocolTypes, ALL_CORPORA};
24use crate::put::{PutDescriptor, PutOptions};
25use crate::put_registry::{PutRegistry, TCP_PUT};
26use crate::trace::{Action, ConfigTrace, ExecutionResult, Source, Spawner, Trace, TraceContext};
27
28fn create_app<S>(title: S) -> Command
29where
30    S: AsRef<str>,
31{
32    Command::new(crate_name!())
33        .version(puffin::version())
34        .author(crate_authors!())
35        .about(title.as_ref().to_owned())
36        .arg(arg!(-T --put <T> "The PUT to use"))
37        .arg(arg!(-c --cores [spec] "Sets the cores to use during fuzzing"))
38        .arg(arg!(-s --seed [n] "(experimental) provide a seed for all clients")
39            .value_parser(value_parser!(u64)))
40        .arg(arg!(-p --port [n] "Port of the broker")
41            .value_parser(value_parser!(u16).range(1..)))
42        .arg(arg!(-i --"max-iters" [i] "Maximum iterations to do")
43            .value_parser(value_parser!(u64).range(0..)))
44        .arg(arg!(--minimizer "Use a minimizer"))
45        .arg(arg!(--tui "Display fuzzing logs using the interactive terminal UI"))
46        .arg(arg!(--"put-use-clear" "Use clearing functionality instead of recreating puts"))
47        .arg(arg!(--"no-launcher" "Do not use the convenient launcher"))
48        .arg(arg!(--"with-bit" "Enable bit-level mutations"))
49        .arg(arg!(--"with-trunc" "Enables failed trace steps truncation"))
50        .arg(arg!(--"step-lock" "Enable step-locked mutation stacking (disabled by default)"))
51        .arg(arg!(--"wo-dy" "Disable DY mutations"))
52        .arg(arg!(--"wo-focus" "Disables focus bit-level mutational stage"))
53        .arg(arg!(-v --verbosity [l] "Verbosity level for (quick) experiments")
54            .value_parser(value_parser!(LevelFilter)))
55        .arg(arg!(--"stats-interval" [n] "Minimum milliseconds between writes per client (core) for stats.json and broker logs [default: 250]")
56            .value_parser(value_parser!(u64).range(1..=3_600_000)))
57        .subcommands(vec![
58            Command::new("quick-experiment").about("Starts a new experiment and writes the results out")
59                .arg(arg!(-c --corpus [c] "Corpus list used to build the initial seed corpus (comma separated). If not provided, uses the ./seed corpus. If neither then uses 'default'").value_delimiter(','))
60            ,
61            Command::new("mapper")
62                .about("Debugging information about the mapper")
63                .arg(arg!(--path "Show the full Rust path of each symbol instead of just its name"))
64                .subcommands(vec![
65                    Command::new("symbols")
66                        .about("Show all function symbols of ProtocolTypes signatures (sorted alphabetically)"),
67                    Command::new("signature")
68                        .about("Show all function symbols with their type signatures (parameter types and output type)"),
69                    Command::new("buildable")
70                        .about("Show, per function symbol, the cost of the cheapest closed term rooted at it, and whether one exists at all"),
71                ]),
72            Command::new("experiment").about("Starts a new experiment and writes the results out")
73                .arg(arg!(-t --title <t> "Title of the experiment"))
74                .arg(arg!(-d --description [d] "Description of the experiment"))
75                .arg(arg!(-c --corpus [c] "Corpus list used to build the initial seed corpus (comma separated). If not provided, uses the ./seed corpus. If neither then uses 'default'").value_delimiter(','))
76            ,
77            Command::new("seed").about("Generates seeds to ./seeds")
78                .arg(arg!(-D --differential "Generates seeds with restricted PUT descriptor parameters for differential fuzzing"))
79                .arg(arg!(-c --corpus [c] "Corpus list used to generate the seed (comma separated names, or `all`)").value_delimiter(','))
80                .arg(arg!(--puts [p] "PUTs to generate for (comma separated names); emits the intersection of supported seeds").value_delimiter(','))
81            ,
82            Command::new("plot")
83                .about("Plots a trace stored in a file")
84                .arg(arg!(<input> "The file which stores a trace"))
85                .arg(arg!(<format> "The format of the plot, can be svg or pdf"))
86                .arg(arg!(<output_prefix> "The file to which the trace should be written"))
87                .arg(arg!(--multiple "Whether we want to output multiple views, additionally to the combined view"))
88                .arg(arg!(--tree "Whether want to use tree mode in the combined view")),
89            Command::new("execute")
90                .about("Executes a trace stored in a file. The exit code describes if more files are available for execution.")
91                .arg(arg!(<inputs> "The file which stores a trace").num_args(1..))
92                .arg(arg!(-n --number <n> "Amount of files to execute starting at index.").value_parser(value_parser!(usize)))
93                .arg(arg!(-i --index <i> "Index of file to execute.").value_parser(value_parser!(usize)))
94                .arg(arg!(--"wo-bit" "Disable evaluating payloads created through bit-level mutations"))
95                .arg(arg!(-s --sort "Sort files in ascending order by the creation date before executing")),
96            Command::new("display-execute")
97                .about("Executes a trace stored in a file and display information")
98                .arg(arg!(<input> "The file which stores a trace"))
99                .arg(arg!(-s --max_step <n> "The step at which to stop").value_parser(value_parser!(usize)))
100                .arg(arg!(-t --show_terms "Show the terms computed at each input step").value_parser(value_parser!(bool)))
101                .arg(arg!(-c --show_claims "Show the claims emitted at each input step").value_parser(value_parser!(bool)))
102                .arg(arg!(-k --show_knowledges "Show the knowledges gathered at each output step").value_parser(value_parser!(bool)))
103                .arg(arg!(-r --show_raw "Show the computed term as raw hex (eg. for use with netcat)").value_parser(value_parser!(bool)))
104                .arg(arg!(-p --differential_post_computations "Evaluate the post execution terms used in differential fuzzing").value_parser(value_parser!(bool)))
105                .arg(arg!(-j --json "Export trace execution as JSON").value_parser(value_parser!(bool)))
106                .arg(arg!(-C --disable_security_oracle "Disable the protocol security oracle").value_parser(value_parser!(bool))),
107            Command::new("binary-attack")
108                .about("Serializes a trace as much as possible and output its")
109                .arg(arg!(<input> "The file which stores a trace"))
110                .arg(arg!(<output> "The file to write serialized data to")),
111            Command::new("tcp")
112                .about("Executes a trace against a TCP client/server")
113                .arg(arg!(<input> "The file which stores a trace"))
114                .arg(arg!(-c --cwd [p] "The current working directory for the binary"))
115                .arg(arg!(-b --binary [p] "The program to start"))
116                .arg(arg!(-a --args [a] "The args of the program"))
117                .arg(arg!(-t --host [h] "The host to connect to, or the server host"))
118                .arg(arg!(-p --port [n] "The client port to connect to, or the server port")
119                    .value_parser(value_parser!(u16).range(1..))),
120            Command::new("differential-execute")
121                .about("Execute a trace on multiple targets, returning the differences between the executions")
122                .arg(arg!(<first_target> "First PUT"))
123                .arg(arg!(<second_target> "Second PUT"))
124                .arg(arg!(<input> "Input trace"))
125                .arg(arg!(-S --"enable-security-oracle" "Enable the protocol security oracle").value_parser(value_parser!(bool)))
126                .arg(arg!(-j --json "Export differences as JSON").value_parser(value_parser!(bool))),
127            Command::new("differential")
128                .about("Start a differential fuzzing campaign")
129                .arg(arg!(<first_target> "The first target to fuzz"))
130                .arg(arg!(<second_target> "The second target to fuzz"))
131                .arg(arg!(-c --corpus [c] "Corpus list used to build the initial seed corpus (comma separated). If not provided, uses the ./seed corpus. If neither then uses 'default'").value_delimiter(',')),
132            Command::new("differential-experiment").about("Starts a new differential fuzzing experiment and writes the results out")
133                .arg(arg!(<first_target> "The first target to fuzz"))
134                .arg(arg!(<second_target> "The second target to fuzz"))
135                .arg(arg!(-t --title <t> "Title of the experiment"))
136                .arg(arg!(-d --description [d] "Description of the experiment"))
137                .arg(arg!(-c --corpus [c] "Corpus list used to build the initial seed corpus (comma separated). If not provided, uses the ./seed corpus. If neither then uses 'default'").value_delimiter(','))
138            ,
139        ])
140}
141
142pub fn main<S, PB>(title: S, put_registry: PutRegistry<PB>) -> ExitCode
143where
144    S: AsRef<str>,
145    PB: ProtocolBehavior + Clone,
146{
147    // Parsing CLI arguments
148    let matches = create_app(title).get_matches();
149
150    let first_core = "0".to_string();
151    let core_definition = matches.get_one("cores").unwrap_or(&first_core);
152    let port: u16 = *matches.get_one::<u16>("port").unwrap_or(&1337u16);
153    let static_seed: Option<u64> = matches.get_one("seed").copied();
154    let max_iters: Option<u64> = matches.get_one("max-iters").copied();
155    let minimizer = matches.get_flag("minimizer");
156    let tui = matches.get_flag("tui");
157    let no_launcher = matches.get_flag("no-launcher");
158    let put_use_clear = matches.get_flag("put-use-clear");
159    let with_bit_level = matches.get_flag("with-bit");
160    let without_dy_mutations = matches.get_flag("wo-dy");
161    let with_truncation = matches.get_flag("with-trunc");
162    let step_lock = matches.get_flag("step-lock");
163    let without_focus = matches.get_flag("wo-focus");
164    let target_put: Option<&String> = matches.get_one("put");
165    let verbosity: LevelFilter = *matches
166        .get_one::<LevelFilter>("verbosity")
167        .unwrap_or(&LevelFilter::Info);
168    let stats_interval =
169        Duration::from_millis(*matches.get_one::<u64>("stats-interval").unwrap_or(&250));
170
171    let mut put_registry = put_registry.clone();
172
173    if let Some(name) = target_put {
174        if let Err((available_puts, non_available_puts)) =
175            check_if_puts_exist(&put_registry, &[name])
176        {
177            println!("Available PUTs: {}", available_puts.join(","));
178            println!("Error: PUT not found: {}", non_available_puts.join(","));
179            return ExitCode::FAILURE;
180        };
181        put_registry
182            .set_default_factory(name)
183            .expect("PUT should exist after validation");
184    };
185
186    log::info!("Version: {}", puffin::full_version());
187    log::info!("Put Versions:");
188    for (id, put) in put_registry.puts() {
189        log::info!("{}:", id);
190        for (component, version) in put.versions().into_iter() {
191            log::info!("    {}: {}", component, version);
192        }
193    }
194    log::info!("Default PUT: {}", put_registry.default_put_name());
195
196    asan_info();
197    setup_asan_env();
198
199    // Set up config
200    let mut config = FuzzerConfig {
201        static_seed,
202        max_iters,
203        core_definition: core_definition.to_string(),
204        broker_port: port,
205        minimizer,
206        tui,
207        no_launcher,
208        verbosity,
209        stats_interval,
210        ..Default::default()
211    };
212
213    if !with_bit_level && without_dy_mutations {
214        log::error!("Both bit-level and DY mutations are disabled. This is not supported.");
215        return ExitCode::FAILURE;
216    }
217    if put_use_clear {
218        config
219            .put_options
220            .add_option("use_clear", put_use_clear.to_string().as_str());
221    }
222    if with_bit_level {
223        config.mutation_config.with_bit_level = true;
224    }
225    if without_dy_mutations {
226        config.mutation_config.with_dy = false;
227        config.mutation_config.term_constraints.must_be_root = true;
228    }
229    if without_focus {
230        config.mutation_config.with_focus = false;
231    }
232    if with_truncation {
233        config.mutation_stage_config.with_truncation = true;
234    }
235    if step_lock {
236        config.mutation_stage_config.step_locked_stacking = true;
237    }
238
239    // Set put_options as default for every PutDescriptor created by the put_registry
240    put_registry.set_default_options(config.put_options.clone());
241
242    // Setup Logging
243    // We need to create the log directory before initializing the logger
244    let base_directory: PathBuf =
245        if let Some(_matches) = matches.subcommand_matches("quick-experiment") {
246            let experiments_root = PathBuf::from("experiments");
247            let title = format_title(None, None, &put_registry, &config);
248            let mut experiment_path = experiments_root.join(&title);
249
250            let mut i = 1;
251            while experiment_path.as_path().exists() {
252                let title = format_title(None, Some(i), &put_registry, &config);
253                experiment_path = experiments_root.join(title);
254                i += 1;
255            }
256            experiments_root.join(&title)
257        } else if let Some(matches) = matches
258            .subcommand_matches("experiment")
259            .or(matches.subcommand_matches("differential-experiment"))
260        {
261            log::info!("Running in experiment mode");
262            config.is_experiment = true;
263            let git_ref = "_".to_string();
264            let title: &str = matches.get_one::<String>("title").unwrap_or(&git_ref);
265            let experiments_root = PathBuf::new().join("experiments");
266            let title = format_title(Some(title), None, &put_registry, &config);
267            let experiment_path = experiments_root.join(title);
268            assert!(
269                !experiment_path.as_path().exists(),
270                "Experiment already exists. Consider creating a new experiment."
271            );
272            experiment_path
273        } else {
274            // Case of non-experiment: plain fuzzing, trace executions, etc.
275            env::current_dir().unwrap()
276        };
277
278    config.corpus_dir = base_directory.join("corpus");
279    config.objective_dir = base_directory.join("objective");
280    config.stats_file = base_directory.join("log/stats.json");
281    config.log_folder = base_directory.join("log/");
282
283    let handle = match log4rs::init_config(config_default(&base_directory.join("./log"))) {
284        Ok(handle) => handle,
285        Err(err) => {
286            eprintln!("error: failed to initialize logging: {err:?}");
287            return ExitCode::FAILURE;
288        }
289    };
290
291    if let Some(matches) = matches.subcommand_matches("seed") {
292        let default_puts = put_registry.default_put_name().to_string();
293
294        let is_differential = matches.get_flag("differential");
295        let corpus: Vec<&str> = matches
296            .get_many::<String>("corpus")
297            .map(|vals| vals.map(String::as_str).collect())
298            .unwrap_or_else(|| vec!["default"]);
299        let puts: Vec<&str> = matches
300            .get_many::<String>("puts")
301            .map(|vals| vals.map(String::as_str).collect())
302            .unwrap_or_else(|| vec![default_puts.as_str()]);
303
304        if let Err((available_puts, non_available_puts)) =
305            check_if_puts_exist(&put_registry, puts.as_slice())
306        {
307            log::error!("PUT not found : {}", non_available_puts.join(","));
308            log::error!("Available PUTs: {}", available_puts.join(","));
309            return ExitCode::FAILURE;
310        }
311
312        if let Err((available_corpora, unknown_corpora)) =
313            check_if_corpora_exist::<PB>(corpus.as_slice())
314        {
315            log::error!("Corpus not found : {}", unknown_corpora.join(","));
316            log::error!("Available corpuses: {}", available_corpora.join(","));
317            return ExitCode::FAILURE;
318        }
319
320        let puts: Vec<PutDescriptor> = puts
321            .into_iter()
322            .map(|name| PutDescriptor::new(name, PutOptions::default()))
323            .collect();
324        let corpus: Vec<String> = corpus.into_iter().map(String::from).collect();
325
326        if let Err(err) = seed(&put_registry, is_differential, corpus, puts) {
327            log::error!("Failed to create seeds on disk: {:?}", err);
328            return ExitCode::FAILURE;
329        }
330    } else if let Some(matches) = matches.subcommand_matches("plot") {
331        // Parse arguments
332        let output_prefix: &String = matches.get_one("output_prefix").unwrap();
333        let input: &String = matches.get_one("input").unwrap();
334        let format: &String = matches.get_one("format").unwrap();
335        let is_multiple = matches.get_flag("multiple");
336        let is_tree = matches.get_flag("tree");
337
338        if let Err(err) = plot::<PB>(input, format, output_prefix, is_multiple, is_tree) {
339            log::error!("Failed to plot trace: {:?}", err);
340            return ExitCode::FAILURE;
341        }
342    } else if let Some(matches) = matches.subcommand_matches("execute") {
343        let inputs: ValuesRef<String> = matches.get_many("inputs").unwrap();
344        let index: usize = *matches.get_one("index").unwrap_or(&0);
345
346        let mut paths = inputs
347            .flat_map(|input| {
348                let input = PathBuf::from(input);
349
350                if input.is_dir() {
351                    fs::read_dir(input)
352                        .expect("failed to read directory")
353                        .map(|entry| entry.expect("failed to read path in directory").path())
354                        .filter(|path| {
355                            !path.file_name().unwrap().to_str().unwrap().starts_with('.')
356                        })
357                        .collect()
358                } else {
359                    vec![input]
360                }
361            })
362            .collect::<Vec<_>>();
363
364        paths.sort_by_key(|path| {
365            fs::metadata(path)
366                .unwrap_or_else(|_| panic!("missing trace file {}", path.display()))
367                .modified()
368                .unwrap()
369        });
370
371        let n: usize = *matches.get_one("number").unwrap_or(&paths.len());
372
373        let mut end_reached = false;
374
375        let lookup_paths = if index < paths.len() {
376            if index + n < paths.len() {
377                &paths[index..index + n]
378            } else {
379                end_reached = true;
380                &paths[index..]
381            }
382        } else {
383            end_reached = true;
384            // empty
385            &paths[0..0]
386        };
387
388        log::info!("execute: found {} inputs", paths.len());
389        log::info!(
390            "execute: running on subset [{}..{}] ({} inputs)",
391            index,
392            index + n,
393            lookup_paths.len()
394        );
395
396        let runner = Runner::new(put_registry.clone(), Spawner::new(put_registry));
397
398        let config_trace = ConfigTrace {
399            with_bit_level,
400            ..Default::default()
401        };
402        if !with_bit_level {
403            log::info!("Execution without payload evaluations...");
404        }
405        for path in lookup_paths {
406            log::info!("Executing: {}", path.display());
407            execute(&runner, path, config_trace);
408        }
409
410        if !lookup_paths.is_empty() {
411            println!(
412                "{}",
413                fs::metadata(&lookup_paths[0])
414                    .unwrap_or_else(|_| panic!("missing trace file {}", lookup_paths[0].display()))
415                    .modified()
416                    .unwrap()
417                    .duration_since(std::time::UNIX_EPOCH)
418                    .unwrap()
419                    .as_millis()
420            );
421        }
422
423        if end_reached {
424            return ExitCode::SUCCESS;
425        } else {
426            return ExitCode::FAILURE;
427        }
428    } else if let Some(matches) = matches.subcommand_matches("display-execute") {
429        let input: &String = matches.get_one("input").unwrap();
430        let max_step: Option<&usize> = matches.get_one("max_step");
431        let show_terms: &bool = matches.get_one("show_terms").unwrap();
432        let show_knowledges: &bool = matches.get_one("show_knowledges").unwrap();
433        let show_claims: &bool = matches.get_one("show_claims").unwrap();
434        let export_json: &bool = matches.get_one("json").unwrap();
435        let differential_post_computations: &bool =
436            matches.get_one("differential_post_computations").unwrap();
437        let show_raw: &bool = matches.get_one("show_raw").unwrap();
438        let disable_security_oracle: &bool = matches.get_one("disable_security_oracle").unwrap();
439
440        let config_trace = ConfigTrace {
441            with_bit_level,
442            ..Default::default()
443        };
444        if !with_bit_level {
445            log::info!("Execution without payload evaluations...");
446        }
447
448        let trace = if let Ok(t) = Trace::<PB::ProtocolTypes>::from_file(input) {
449            t
450        } else {
451            log::error!("Invalid trace file {}", input);
452
453            return ExitCode::FAILURE;
454        };
455
456        log::info!("Agents: {:?}", &trace.descriptors);
457
458        let put_name = put_registry.default_put_name().into();
459        let mut ctx = TraceContext::new_config(Spawner::new(put_registry), config_trace);
460        let (res, err) = match trace.execute_until_step(
461            &mut ctx,
462            *max_step.unwrap_or(&trace.steps.len()),
463            &mut 0,
464            !*disable_security_oracle,
465        ) {
466            Ok(_) => (ExitCode::SUCCESS, None),
467            Err(e) => (ExitCode::FAILURE, Some(e.to_string())),
468        };
469
470        if *differential_post_computations {
471            for t in PB::ProtocolTypes::differential_fuzzing_terms_to_eval(&trace.descriptors) {
472                log::info!("Trying decryption with : {}", t);
473                let k = t.evaluate_dy(&ctx);
474                match k {
475                    Ok(decrypted) => ctx.knowledge_store.add_raw_boxed_knowledge(
476                        decrypted,
477                        None,
478                        Source::Label(Some("Decryption".into())),
479                        None,
480                    ),
481                    Err(err) => log::info!("failed decryption : {}", err),
482                }
483            }
484        }
485
486        let exec = ExecutionResult::from(
487            put_name,
488            err,
489            &trace,
490            ctx,
491            *show_terms,
492            *show_knowledges,
493            *show_claims,
494            *show_raw,
495        );
496
497        if *export_json {
498            println!(
499                "{}",
500                serde_json::to_string_pretty(&exec).unwrap_or("".into())
501            );
502        } else {
503            println!("{}", exec);
504        }
505        return res;
506    } else if let Some(matches) = matches.subcommand_matches("binary-attack") {
507        let input: &String = matches.get_one("input").unwrap();
508        let output: &String = matches.get_one("output").unwrap();
509
510        if let Err(err) = binary_attack(input, output, &put_registry) {
511            log::error!("Failed to create trace output: {:?}", err);
512            return ExitCode::FAILURE;
513        }
514    } else if let Some(matches) = matches.subcommand_matches("tcp") {
515        let input: &String = matches.get_one("input").unwrap();
516        let prog: Option<&String> = matches.get_one("binary");
517        let args: Option<&String> = matches.get_one("args");
518        let cwd: Option<&String> = matches.get_one("cwd");
519        let default_host = "127.0.0.1".to_string();
520        let host: &String = matches.get_one("host").unwrap_or(&default_host);
521        let port = matches
522            .get_one::<u16>("port")
523            .unwrap_or(&44338u16)
524            .to_string();
525
526        let trace = Trace::<PB::ProtocolTypes>::from_file(input).unwrap();
527
528        let mut options = vec![("port", port.as_str()), ("host", host)];
529
530        if let Some(prog) = prog {
531            options.push(("prog", prog));
532        }
533
534        if let Some(args) = args {
535            options.push(("args", args));
536        }
537
538        if let Some(cwd) = cwd {
539            options.push(("cwd", cwd));
540        }
541
542        let server = trace.descriptors[0].name;
543        let put = PutDescriptor::new(TCP_PUT, options);
544        let runner = Runner::new(
545            put_registry.clone(),
546            Spawner::new(put_registry).with_mapping(&[(server, put)]),
547        );
548        let mut context = runner.execute(trace, &mut 0).unwrap();
549
550        let server = AgentName::first();
551        let shutdown = context.find_agent_mut(server).unwrap().shutdown();
552        log::info!("{}", shutdown);
553
554        return ExitCode::SUCCESS;
555    } else if let Some(sub_matches) = matches.subcommand_matches("mapper") {
556        return mapper_cmd::<PB::ProtocolTypes>(sub_matches);
557    } else if let Some(matches) = matches.subcommand_matches("differential-execute") {
558        // differential fuzzing here
559        let first_put: &String = matches.get_one("first_target").unwrap();
560        let second_put: &String = matches.get_one("second_target").unwrap();
561        let input: &String = matches.get_one("input").unwrap();
562        let export_json: &bool = matches.get_one("json").unwrap();
563        let enable_security_oracle: &bool = matches.get_one("enable-security-oracle").unwrap();
564
565        let path = PathBuf::from(input);
566        let trace = match Trace::<PB::ProtocolTypes>::from_file(&path) {
567            Ok(t) => t,
568            Err(_) => {
569                log::error!("Invalid trace file {}", path.display());
570                return ExitCode::FAILURE;
571            }
572        };
573
574        if let Err((available_puts, non_available_puts)) =
575            check_if_puts_exist(&put_registry, &[first_put, second_put])
576        {
577            log::error!("PUT not found : {}", non_available_puts.join(","));
578            log::error!("Available PUTs: {}", available_puts.join(","));
579            return ExitCode::FAILURE;
580        }
581
582        // Uniformise PUT configuration (ciphers, sigalgs, groups) so both PUTs
583        // use a comparable config — same as the test helper does.
584        let trace =
585            <PB::ProtocolTypes as ProtocolTypes>::differential_fuzzing_uniformise_put_config(trace);
586
587        // Map ALL agents in the trace (including prior traces) to the specified PUT.
588        // Without this, agents in prior traces silently fall back to the default PUT.
589        let first_mappings: Vec<_> = trace
590            .all_descriptors()
591            .iter()
592            .map(|d| {
593                (
594                    d.name,
595                    PutDescriptor::new(first_put, put_registry.default_put_options().clone()),
596                )
597            })
598            .collect();
599        let second_mappings: Vec<_> = trace
600            .all_descriptors()
601            .iter()
602            .map(|d| {
603                (
604                    d.name,
605                    PutDescriptor::new(second_put, put_registry.default_put_options().clone()),
606                )
607            })
608            .collect();
609
610        let runner = DifferentialRunner::new(
611            put_registry.clone(),
612            Spawner::new(put_registry.clone()).with_mapping(&first_mappings),
613            Spawner::new(put_registry.clone()).with_mapping(&second_mappings),
614        );
615
616        return match runner.execute_config(
617            trace,
618            ConfigTrace {
619                check_security_violation: *enable_security_oracle,
620                ..Default::default()
621            },
622            &mut 0,
623        ) {
624            Ok(_) => {
625                if *export_json {
626                    println!("[]");
627                } else {
628                    println!("No differences")
629                }
630
631                ExitCode::SUCCESS
632            }
633            Err(e) => {
634                if let crate::error::Error::Difference {
635                    differences: trace_differences,
636                    put1_status: _,
637                    put2_status: _,
638                } = e
639                {
640                    if *export_json {
641                        println!(
642                            "{}",
643                            serde_json::to_string_pretty(&trace_differences).unwrap()
644                        );
645                    } else {
646                        println!("Differences between the PUTs:\n");
647                        for diff in trace_differences {
648                            println!("{}\n", diff);
649                        }
650                    }
651                }
652                ExitCode::FAILURE
653            }
654        };
655    } else {
656        //  Command is "experiment", "quick-experiment", "differential" or "differential-experiment"
657        let experiment_path = if let Some(matches) = matches
658            .subcommand_matches("experiment")
659            .or(matches.subcommand_matches("differential-experiment"))
660        {
661            let git_ref = "_".to_string();
662            let title: &str = matches.get_one::<String>("title").unwrap_or(&git_ref);
663            let format_t = format_title(Some(title), None, &put_registry, &config);
664            let experiment_path = base_directory;
665
666            let base_dec = format_t;
667            let description: &String = matches.get_one("description").unwrap_or(&base_dec);
668            if let Err(err) = write_experiment_markdown(
669                &experiment_path,
670                title,
671                description,
672                &put_registry,
673                matches,
674                port,
675            ) {
676                log::error!("Failed to write readme: {:?}", err);
677                return ExitCode::FAILURE;
678            }
679
680            experiment_path
681        } else if let Some(_matches) = matches.subcommand_matches("quick-experiment") {
682            let description = "No Description, because this is a quick experiment.";
683            let experiment_path = base_directory;
684
685            let title = format_title(None, None, &put_registry, &config);
686
687            if let Err(err) = write_experiment_markdown(
688                &experiment_path,
689                title,
690                description,
691                &put_registry,
692                &matches,
693                port,
694            ) {
695                log::error!("Failed to write readme: {:?}", err);
696                return ExitCode::FAILURE;
697            }
698            experiment_path
699        } else {
700            PathBuf::from(".")
701        };
702
703        if let Err(err) = fs::create_dir_all(&experiment_path) {
704            log::error!("Failed to create directories: {:?}", err);
705            return ExitCode::FAILURE;
706        }
707
708        // Differential fuzzing
709        let target = if let Some(submatches) = matches
710            .subcommand_matches("differential")
711            .or(matches.subcommand_matches("differential-experiment"))
712        {
713            let first_put: &String = submatches.get_one("first_target").unwrap();
714            let second_put: &String = submatches.get_one("second_target").unwrap();
715
716            if let Err((available_puts, non_available_puts)) =
717                check_if_puts_exist(&put_registry, &[first_put, second_put])
718            {
719                log::error!("PUT not found : {}", non_available_puts.join(","));
720                log::error!("Available PUTs: {}", available_puts.join(","));
721                return ExitCode::FAILURE;
722            }
723
724            FuzzingTarget::Differential(
725                PutDescriptor::new(first_put, put_registry.default_put_options().clone()),
726                PutDescriptor::new(second_put, put_registry.default_put_options().clone()),
727            )
728        } else {
729            FuzzingTarget::Single(None)
730        };
731
732        // `None` means the flag was not passed: the fuzzer should fall back to
733        // `./seeds` if it exists, or the `"default"` corpus otherwise. `Some(_)` means
734        // `--corpus` was given explicitly.
735        let requested_corpora: Option<Vec<String>> = matches
736            .subcommand_matches("experiment")
737            .or(matches.subcommand_matches("quick-experiment"))
738            .or(matches.subcommand_matches("differential"))
739            .or(matches.subcommand_matches("differential-experiment"))
740            .and_then(|submatches| submatches.get_many::<String>("corpus"))
741            .map(|values| values.cloned().collect());
742
743        if let Some(corpora) = &requested_corpora {
744            if let Err((available_corpora, unknown_corpora)) = check_if_corpora_exist::<PB>(
745                &corpora.iter().map(String::as_str).collect::<Vec<_>>(),
746            ) {
747                log::error!("Corpus not found : {}", unknown_corpora.join(","));
748                log::error!("Available corpuses: {}", available_corpora.join(","));
749                return ExitCode::FAILURE;
750            }
751        }
752
753        config.target = target;
754        config.initial_corpus = requested_corpora;
755
756        if let Err(err) = start::<PB>(&put_registry, config, handle) {
757            match err {
758                libafl::Error::ShuttingDown => {
759                    log::info!("\nFuzzing stopped by user. Good Bye.");
760                }
761                _ => {
762                    panic!("Fuzzing failed {err:?}")
763                }
764            }
765        }
766    }
767
768    ExitCode::SUCCESS
769}
770
771fn plot<PB: ProtocolBehavior>(
772    input: &str,
773    format: &str,
774    output_prefix: &str,
775    is_multiple: bool,
776    is_tree: bool,
777) -> Result<(), Box<dyn std::error::Error>> {
778    let mut input_file = File::open(input)?;
779
780    // Read trace file
781    let mut buffer = Vec::new();
782    input_file.read_to_end(&mut buffer)?;
783    let trace = postcard::from_bytes::<Trace<PB::ProtocolTypes>>(&buffer)?;
784
785    // All-in-one tree
786    write_graphviz(
787        format!("{}_{}.{}", output_prefix, "all", format).as_str(),
788        format,
789        trace.dot_graph(is_tree).as_str(),
790    )
791    .expect("Failed to generate graph.");
792
793    if is_multiple {
794        for (i, subgraph) in trace.dot_subgraphs(true).iter().enumerate() {
795            let wrapped_subgraph = format!("strict digraph \"\" {{ splines=true; {subgraph} }}");
796            write_graphviz(
797                format!("{output_prefix}_{i}.{format}").as_str(),
798                format,
799                wrapped_subgraph.as_str(),
800            )
801            .expect("Failed to generate graph.");
802        }
803    }
804
805    log::info!("Created plots");
806    Ok(())
807}
808
809fn seed<PB: ProtocolBehavior>(
810    put_registry: &PutRegistry<PB>,
811    differential_fuzzing: bool,
812    corpus: Vec<String>,
813    puts: Vec<PutDescriptor>,
814) -> Result<(), Box<dyn std::error::Error>> {
815    // Wipe previously generated seeds so the directory reflects exactly the
816    // requested corpuses/PUTs. Ignore the error when it does not exist yet.
817    match fs::remove_dir_all("./seeds") {
818        Ok(()) => {}
819        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
820        Err(err) => return Err(err.into()),
821    }
822    fs::create_dir_all("./seeds")?;
823
824    for (mut trace, name) in build_corpus(put_registry, &puts, &corpus) {
825        if differential_fuzzing {
826            trace =
827                <PB::ProtocolTypes as ProtocolTypes>::differential_fuzzing_uniformise_put_config(
828                    trace,
829                );
830        }
831
832        trace.to_file(format!("./seeds/{name}.trace"))?;
833    }
834
835    log::info!("Generated seed traces into the directory ./seeds");
836    Ok(())
837}
838
839/// Validate the requested corpus names against the protocol's registered
840/// corpuses. [`ALL_CORPORA`] is always accepted, since it is expanded to the
841/// full registry by [`build_corpus`]. On failure returns `(available,
842/// unknown)` for error reporting, mirroring [`check_if_puts_exist`].
843fn check_if_corpora_exist<'a, PB: ProtocolBehavior>(
844    corpus_list: &[&'a str],
845) -> Result<(), (Vec<&'static str>, Vec<&'a str>)> {
846    let available: Vec<&'static str> = PB::corpus_registry()
847        .into_iter()
848        .map(|(name, _)| name)
849        .collect();
850
851    let unknown: Vec<&str> = corpus_list
852        .iter()
853        .filter(|name| **name != ALL_CORPORA && !available.iter().any(|a| a == *name))
854        .copied()
855        .collect();
856
857    if unknown.is_empty() {
858        Ok(())
859    } else {
860        Err((available, unknown))
861    }
862}
863
864fn execute<PB: ProtocolBehavior, P: AsRef<Path>>(
865    runner: &Runner<PB>,
866    input: P,
867    config_trace: ConfigTrace,
868) {
869    let trace = if let Ok(t) = Trace::<PB::ProtocolTypes>::from_file(input.as_ref()) {
870        t
871    } else {
872        log::error!("Invalid trace file {}", input.as_ref().display());
873        return;
874    };
875
876    log::debug!("Agents: {:?}", &trace.descriptors);
877
878    // When generating coverage a crash means that no coverage is stored
879    // By executing in a fork, even when that process crashes, the other executed code will still
880    // yield coverage
881    let status = ForkedRunner::new(runner).execute_config(trace, config_trace, &mut 0);
882
883    match status {
884        Ok(s) => log::info!("execution finished with status {s:?}"),
885        Err(reason) => panic!("failed to execute trace: {reason}"),
886    }
887}
888
889fn binary_attack<PB: ProtocolBehavior>(
890    input: &str,
891    output: &str,
892    put_registry: &PutRegistry<PB>,
893) -> Result<(), Box<dyn std::error::Error>> {
894    let spawner = Spawner::new(put_registry.clone());
895    let ctx = TraceContext::new(spawner);
896    let trace = Trace::<PB::ProtocolTypes>::from_file(input)?;
897
898    log::debug!("Agents: {:?}", &trace.descriptors);
899
900    let mut f = File::create(output).expect("Unable to create file");
901
902    for step in trace.steps {
903        match step.action {
904            Action::Input(input) => {
905                if let Ok(evaluated) = input.recipe.evaluate(&ctx) {
906                    f.write_all(&evaluated).expect("Unable to write data");
907                } else {
908                    log::error!("Recipe is not a `ProtocolMessage` or `OpaqueProtocolMessage`!");
909                }
910            }
911            Action::Output(_) => {}
912        }
913    }
914    Ok(())
915}
916
917fn check_if_puts_exist<'a, 'b, PB: ProtocolBehavior>(
918    put_registry: &'b PutRegistry<PB>,
919    put_list: &[&'a str],
920) -> Result<(), (Vec<&'b str>, Vec<&'a str>)> {
921    let available_puts: Vec<&str> = put_registry.puts().map(|(name, _)| name).collect();
922
923    let non_available_puts: Vec<&str> = put_list
924        .iter()
925        .filter_map(|name| {
926            if available_puts.iter().any(|x| x == name) {
927                None
928            } else {
929                Some(*name)
930            }
931        })
932        .collect();
933
934    if non_available_puts.is_empty() {
935        Ok(())
936    } else {
937        Err((available_puts, non_available_puts))
938    }
939}
940
941fn mapper_cmd<PT: ProtocolTypes>(sub_matches: &clap::ArgMatches) -> ExitCode {
942    let show_path = sub_matches.get_flag("path");
943    // Shorten a (possibly generic) type name by stripping module paths from
944    // every path segment while preserving the surrounding structure, e.g.
945    // `alloc::vec::Vec<alloc::vec::Vec<u8>>` -> `Vec<Vec<u8>>`.
946    let display = |full: &'static str| -> String {
947        if show_path {
948            return full.to_string();
949        }
950        let mut out = String::with_capacity(full.len());
951        // Accumulate maximal runs of identifier/path chars, then keep only the
952        // segment after the last `::`. Keep delimiters (`<`, `>`, `,`, `&`,
953        // whitespace, `(`, `)`, ...).
954        let mut segment = String::new();
955        let flush = |segment: &mut String, out: &mut String| {
956            if !segment.is_empty() {
957                out.push_str(segment.rsplit("::").next().unwrap_or(segment));
958                segment.clear();
959            }
960        };
961        for c in full.chars() {
962            if c.is_alphanumeric() || c == '_' || c == ':' {
963                segment.push(c);
964            } else {
965                flush(&mut segment, &mut out);
966                out.push(c);
967            }
968        }
969        flush(&mut segment, &mut out);
970        out
971    };
972
973    let sig = PT::signature();
974    let mut functions: Vec<_> = sig.functions.iter().collect();
975    // Always sort by short name for readability
976    functions.sort_by(|(a, _), (b, _)| {
977        display(a.name)
978            .cmp(&display(b.name))
979            .then_with(|| a.name.cmp(b.name))
980    });
981
982    if sub_matches.subcommand_matches("symbols").is_some() {
983        for (shape, _) in &functions {
984            println!("{}", display(shape.name));
985        }
986    } else if sub_matches.subcommand_matches("signature").is_some() {
987        for (shape, _) in &functions {
988            let args = shape
989                .argument_types
990                .iter()
991                .map(|t| display(t.name))
992                .collect::<Vec<_>>()
993                .join(", ");
994            println!(
995                "{}({}) -> {}",
996                display(shape.name),
997                args,
998                display(shape.return_type.name)
999            );
1000        }
1001    } else if sub_matches.subcommand_matches("buildable").is_some() {
1002        // `min_gen_depth` and `min_gen_size` are `None` for exactly the symbols no closed term is
1003        // rooted at, at any budget (see [`crate::algebra::signature::Signature::min_gen_depth`]):
1004        // some argument type has no closed term either. The term zoo never generates for those.
1005        let rows: Vec<_> = functions
1006            .iter()
1007            .map(|(shape, _)| {
1008                (
1009                    display(shape.name),
1010                    shape.argument_types.len(),
1011                    sig.min_gen_depth(shape.name),
1012                    sig.min_gen_size(shape.name),
1013                )
1014            })
1015            .collect();
1016
1017        let name_width = rows
1018            .iter()
1019            .map(|(name, ..)| name.len())
1020            .chain(std::iter::once("SYMBOL".len()))
1021            .max()
1022            .unwrap_or_default();
1023        // Missing costs print as `-` rather than as a number, so a column stays scannable.
1024        let cell = |value: Option<String>| value.unwrap_or_else(|| "-".to_string());
1025
1026        println!(
1027            "{:<name_width$}  {:>4}  {:>9}  {:>8}  BUILDABLE",
1028            "SYMBOL", "ARGS", "MIN DEPTH", "MIN SIZE"
1029        );
1030        for (name, args, depth, size) in &rows {
1031            println!(
1032                "{:<name_width$}  {:>4}  {:>9}  {:>8}  {}",
1033                name,
1034                args,
1035                cell(depth.map(|depth| depth.to_string())),
1036                cell(size.map(|size| size.to_string())),
1037                if depth.is_some() { "yes" } else { "no" }
1038            );
1039        }
1040
1041        // On stderr, so that stdout stays a pipeable table.
1042        let unbuildable = rows
1043            .iter()
1044            .filter(|(_, _, depth, _)| depth.is_none())
1045            .count();
1046        eprintln!("\n{unbuildable} of {} symbols unbuildable", rows.len());
1047    } else {
1048        eprintln!(
1049            "mapper: expected a subcommand. Use 'mapper symbols', 'mapper signature' or 'mapper \
1050             buildable'"
1051        );
1052        return ExitCode::FAILURE;
1053    }
1054    ExitCode::SUCCESS
1055}