Merge pull request #8563 from sylvestre/uufuzz

prepare the publication of uufuzz + add emojis

Author: sylvestre

.github/workflows/fuzzing.yml

@@ -17,6 +17,40 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 jobs:
+  uufuzz-examples:
+    name: Build and test uufuzz examples
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+    - uses: dtolnay/rust-toolchain@stable
+    - uses: Swatinem/rust-cache@v2
+      with:
+        shared-key: "uufuzz-cache-key"
+        cache-directories: "fuzz/target"
+    - name: Build uufuzz library
+      run: |
+        cd fuzz/uufuzz
+        cargo build --release
+    - name: Run uufuzz tests
+      run: |
+        cd fuzz/uufuzz
+        cargo test --lib
+    - name: Build and run uufuzz examples
+      run: |
+        cd fuzz/uufuzz
+        echo "Building all examples..."
+        cargo build --examples --release
+
+        # Run all examples except integration_testing (which has FD issues in CI)
+        for example in examples/*.rs; do
+          example_name=$(basename "$example" .rs)
+          if [ "$example_name" != "integration_testing" ]; then
+            cargo run --example "$example_name" --release
+          fi
+        done
+
   fuzz-build:
     name: Build the fuzzers
     runs-on: ubuntu-latest

fuzz/uufuzz/Cargo.toml

@@ -12,5 +12,5 @@ console = "0.16.0"
 libc = "0.2.153"
 rand = { version = "0.9.0", features = ["small_rng"] }
 similar = "2.5.0"
-uucore = { path = "../../src/uucore", features = ["parser"] }
+uucore = { version = "0.1.0", path = "../../src/uucore", features = ["parser"] }
 tempfile = "3.15.0"

fuzz/uufuzz/README.md

@@ -0,0 +1,137 @@
+# uufuzz
+
+A Rust library for **differential fuzzing** of command-line utilities. Originally designed for testing uutils coreutils against GNU coreutils, but can be used to compare any two implementations of command-line tools.
+
+Differential fuzzing is a testing technique that compares the behavior of two implementations of the same functionality using randomly generated inputs. This helps identify bugs, inconsistencies, and security vulnerabilities by finding cases where implementations diverge unexpectedly.
+
+## Features
+
+- **Command Execution**: Run and capture output from both Rust and reference implementations
+- **Result Comparison**: Detailed comparison of stdout, stderr, and exit codes with diff output
+- **Input Generation**: Utilities for generating random strings, files, and test inputs
+- **GNU Compatibility**: Built-in support for detecting and running GNU coreutils
+- **Pretty Output**: Colorized and formatted test result display
+
+## Usage
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+uufuzz = "0.1.0"
+```
+
+### Basic Example
+
+```rust
+use std::ffi::OsString;
+use uufuzz::{generate_and_run_uumain, run_gnu_cmd, compare_result};
+
+// Your utility's main function
+fn my_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    // Implementation here
+    0
+}
+
+// Test against GNU implementation
+let args = vec![OsString::from("echo"), OsString::from("hello")];
+
+// Run your implementation
+let rust_result = generate_and_run_uumain(&args, my_echo_main, None);
+
+// Run GNU implementation
+let gnu_result = run_gnu_cmd("echo", &args[1..], false, None).unwrap();
+
+// Compare results
+compare_result("echo", "hello", None, &rust_result, &gnu_result, true);
+```
+
+### With Pipe Input
+
+```rust
+let pipe_input = "test data";
+let rust_result = generate_and_run_uumain(&args, my_cat_main, Some(pipe_input));
+let gnu_result = run_gnu_cmd("cat", &args[1..], false, Some(pipe_input)).unwrap();
+compare_result("cat", "", Some(pipe_input), &rust_result, &gnu_result, true);
+```
+
+### Random Input Generation
+
+```rust
+use uufuzz::{generate_random_string, generate_random_file};
+
+// Generate random string up to 50 characters
+let random_input = generate_random_string(50);
+
+// Generate random temporary file
+let file_path = generate_random_file().expect("Failed to create file");
+```
+
+## Use Cases
+
+### Fuzzing Testing
+Perfect for libFuzzer-based differential fuzzing:
+
+```rust
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use uufuzz::*;
+
+fuzz_target!(|_data: &[u8]| {
+    let args = generate_test_args();
+    let rust_result = generate_and_run_uumain(&args, my_utility_main, None);
+    let gnu_result = run_gnu_cmd("utility", &args[1..], false, None).unwrap();
+    compare_result("utility", &format!("{:?}", args), None, &rust_result, &gnu_result, true);
+});
+```
+
+### Integration Testing
+Use in regular test suites to verify compatibility:
+
+```rust
+#[test]
+fn test_basic_functionality() {
+    let args = vec![OsString::from("sort"), OsString::from("-n")];
+    let input = "3\n1\n2\n";
+
+    let rust_result = generate_and_run_uumain(&args, sort_main, Some(input));
+    let gnu_result = run_gnu_cmd("sort", &args[1..], false, Some(input)).unwrap();
+
+    assert_eq!(rust_result.stdout, gnu_result.stdout);
+    assert_eq!(rust_result.exit_code, gnu_result.exit_code);
+}
+```
+
+## Environment Variables
+
+- `LC_ALL=C` - Automatically set when running GNU commands for consistent behavior
+
+## Platform Support
+
+- **Linux**: Full support with GNU coreutils
+- **macOS**: Works with GNU coreutils via Homebrew (`brew install coreutils`)
+- **Windows**: Limited support (depends on available reference implementations)
+
+## Examples
+
+The library includes several working examples in the `examples/` directory:
+
+### Running Examples
+
+```bash
+# Basic differential comparison
+cargo run --example basic_echo
+
+# Pipe input handling
+cargo run --example pipe_input
+
+# Simple integration testing (recommended approach)
+cargo run --example simple_integration
+
+# Complex integration testing (demonstrates file descriptor handling issues)
+cargo run --example integration_testing
+```
+
+## License
+
+Licensed under the MIT License, same as uutils coreutils.

fuzz/uufuzz/examples/basic_echo.rs

@@ -0,0 +1,61 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use std::ffi::OsString;
+use uufuzz::{compare_result, generate_and_run_uumain, run_gnu_cmd};
+
+// Mock echo implementation for demonstration
+fn mock_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let args: Vec<OsString> = args.collect();
+
+    // Skip the program name (first argument)
+    for (i, arg) in args.iter().skip(1).enumerate() {
+        if i > 0 {
+            print!(" ");
+        }
+        print!("{}", arg.to_string_lossy());
+    }
+    println!();
+    0
+}
+
+fn main() {
+    println!("=== Basic uufuzz Example ===");
+
+    // Test against GNU implementation
+    let args = vec![
+        OsString::from("echo"),
+        OsString::from("hello"),
+        OsString::from("world"),
+    ];
+
+    println!("Running mock echo implementation...");
+    let rust_result = generate_and_run_uumain(&args, mock_echo_main, None);
+
+    println!("Running GNU echo...");
+    match run_gnu_cmd("echo", &args[1..], false, None) {
+        Ok(gnu_result) => {
+            println!("Comparing results...");
+            compare_result(
+                "echo",
+                "hello world",
+                None,
+                &rust_result,
+                &gnu_result,
+                false,
+            );
+        }
+        Err(error_result) => {
+            println!("Failed to run GNU echo: {}", error_result.stderr);
+            println!("This is expected if GNU coreutils is not installed");
+
+            // Show what our implementation produced
+            println!("\nOur implementation result:");
+            println!("Stdout: '{}'", rust_result.stdout);
+            println!("Stderr: '{}'", rust_result.stderr);
+            println!("Exit code: {}", rust_result.exit_code);
+        }
+    }
+}