test-fuzz

test-fuzz هي أمر فرعي لـ Cargo ومجموعة من ماكروات Rust لأتمتة مهام معينة تتعلق بـ fuzzing باستخدام afl.rs، وتشمل:

• توليد corpus للـ fuzzing
• تنفيذ harness للـ fuzzing

test-fuzz تحقق هذه الأمور (جزئيًا) باستخدام أدوات الاختبار في Rust. على سبيل المثال، لتوليد corpus للـ fuzzing، يسجّل test-fuzz وسائط الهدف في كل مرة يُستدعى فيها أثناء تشغيل cargo test. وبالمثل، ينفّذ test-fuzz harness للـ fuzzing كاختبار إضافي في ملف ثنائي مُولَّد بواسطة cargo-test. هذا التكامل الوثيق مع أدوات الاختبار في Rust هو ما يبرر الاسم test-fuzz.

المحتويات

1. [التثبيت]
2. [نظرة عامة]
3. [المكوّنات]
   • [ماكرو test_fuzz]
   • [ماكرو test_fuzz_impl]
   • [أمر cargo test-fuzz]
   • [دوال وماكروات مساعدة]
4. [ميزات حزمة test-fuzz]
5. [ملفات corpus المُولَّدة تلقائيًا]
6. [متغيرات البيئة]
7. [القيود]
8. [نصائح وحيل]
9. [سياسة الإصدارات الدلالية]
10. [الترخيص]

التثبيت

ثبّت cargo-test-fuzz وafl.rs بالأمر التالي:```sh cargo install cargo-test-fuzz cargo-afl

## نظرة عامة

التضمين باستخدام `test-fuzz` يتم أساسًا في ثلاث خطوات:\*

1. **حدد هدف التضمين**:
   - أضف التبعيات `dependencies` التالية إلى ملف `Cargo.toml` الخاص بالكريت الهدف:
     ```toml
     serde = "*"
     test-fuzz = "*"
     ```
   - سبق الدالة الهدف بماكرو [`test_fuzz`]:
     ```rust
     #[test_fuzz::test_fuzz]
     fn foo(...) {
         ...
     }
     ```
2. **أنشئ مجموعة بيانات** بتشغيل `cargo test`:   ```
   cargo test

3. اختبر هدفك بالتزوير عن طريق تشغيل cargo test-fuzz: ``` cargo test-fuzz foo
   root@kitploit:~

* قد تكون هناك حاجة إلى خطوة إضافية أولية بعد إعادة التشغيل:```sh cargo afl system-config

لاحظ أن الأمر أعلاه يشغّل `sudo` داخليًا. لذلك، قد يُطلب منك إدخال كلمة المرور.

## المكونات

### الماكرو `test_fuzz`

وضعُ الماكرو `test_fuzz` قبل دالة يشير إلى أن هذه الدالة هي هدف fuzzing.

الآثار الرئيسية للماكرو `test_fuzz` هي:

- إضافة أدوات قياس إلى الهدف لتسلسل وسائطه وكتابتها إلى ملف مجموعة (corpus file) في كل مرة يُستدعى فيها الهدف. الأدوات محمية بواسطة `#[cfg(test)]` بحيث يتم إنشاء ملفات المجموعة فقط عند تشغيل الاختبارات (ومع ذلك، انظر [`enable_in_production`] أدناه).
- إضافة اختبار لقراءة الوسائط وفك تسلسلها من الإدخال القياسي وتطبيق الهدف عليها. يفحص الاختبار متغير بيئة معيّنًا بواسطة [`cargo test-fuzz`]، بحيث لا يعلق الاختبار في محاولة القراءة من الإدخال القياسي أثناء استدعاء عادي لـ `cargo test`. الاختبار موضوع داخل وحدة (module) لتقليل احتمالية تعارض الأسماء. حاليًا، اسم الوحدة هو `target_fuzz`، حيث `target` هو اسم الهدف (ومع ذلك، انظر [`rename`] أدناه).

#### الوسائط

##### `bounds = "where_predicates"`

فرض `where_predicates` (مثل قيود الخصائص) على البنية المستخدمة لتسلسل/فك تسلسل الوسائط. قد يكون هذا ضروريًا، مثلًا، إذا كان نوع وسيط الهدف نوعًا مرتبطًا (associated type). لمثال، انظر [associated_type.rs] في هذا المستودع.

##### `generic_args = "parameters"`

استخدم `parameters` كمعاملات نوع الهدف عند fuzzing. مثال:```rust
#[test_fuzz(generic_args = "String")]
fn foo<T: Clone + Debug + Serialize>(x: &T) {
    ...
}

ملاحظة: يجب أن تكون وسائط الهدف قابلة للتسلسل (serializable) لكل instantiation من معاملات النوع الخاصة به. لكن وسائط الهدف مطلوبة لتكون قابلة لإلغاء التسلسل (deserializable) فقط عندما يتم إنشاء الهدف باستخدام parameters.

impl_generic_args = "parameters"

استخدم parameters كمعاملات النوع Self الخاصة بالهدف عند الفازينج (fuzzing). مثال:```rust #[test_fuzz_impl] impl<T: Clone + Debug + Serialize> for Foo { #[test_fuzz(impl_generic_args = "String")] fn bar(&self, x: &T) { ... } }

ملاحظة: يجب أن تكون وسيطات الهدف قابلة للتسلسل (serializable) لكل **instantiation** (نسخة) من معاملات النوع `Self` الخاصة به. لكن وسيطات الهدف مطلوبة لتكون قابلة لإلغاء التسلسل (deserializable) فقط عندما يتم إنشاء نسخة `Self` الخاصة بالهدف باستخدام `parameters`.

##### `convert = "X, Y"`

عند تسلسل وسيطات الهدف، حوّل القيم من النوع `X` إلى النوع `Y` باستخدام تنفيذ `Y` لـ `From<X>`، أو من النوع `&X` إلى النوع `Y` باستخدام تنفيذ `Y` للخاصية غير القياسية `test_fuzz::FromRef<X>`. عند إلغاء التسلسل، حوّل تلك القيم مرة أخرى إلى النوع `X` باستخدام تنفيذ `Y` للخاصية غير القياسية `test_fuzz::Into<X>`.

أي أنّ استخدام `convert = "X, Y"` يجب أن يكون مصحوبًا بتنفيذات معيّنة. إذا كان `X` يطبّق [`Clone`]، فإن `Y` يمكن أن يطبّق ما يلي:```rust
impl From<X> for Y {
    fn from(x: X) -> Self {
        ...
    }
}

إذا كان X لا يطبّق Clone، فيجب أن يطبّق Y ما يلي:```rust impl test_fuzz::FromRef for Y { fn from_ref(x: &X) -> Self { ... } }

بالإضافة إلى ذلك، يجب أن يطبّق `Y` ما يلي (بغض النظر عما إذا كان `X` يطبّق [`Clone`]):```rust
impl test_fuzz::Into<X> for Y {
    fn into(self) -> X {
        ...
    }
}

تعريف test_fuzz::Into مطابق تمامًا لتعريف std::convert::Into. والسبب في استخدام trait غير قياسي هو تجنّب التعارضات التي قد تنشأ عن التطبيقات الشاملة (blanket implementations) للـ traits القياسية.

enable_in_production

قم بإنشاء ملفات corpus عند عدم تشغيل الاختبارات، بشرط أن يكون متغير البيئة TEST_FUZZ_WRITE مضبوطًا. السلوك الافتراضي هو إنشاء ملفات corpus فقط عند تشغيل الاختبارات، بغض النظر عن ضبط TEST_FUZZ_WRITE أو عدمه. عند تشغيل هدف من خارج مجلد الحزمة، اضبط TEST_FUZZ_MANIFEST_PATH على مسار ملف Cargo.toml الخاص بالحزمة.

تحذير: ضبط enable_in_production قد يُدخل ناقل رفض خدمة (denial-of-service). على سبيل المثال، ضبط هذا الخيار لدالة تُستدعى مرات عديدة بوسائط مختلفة قد يملأ القرص. ويأتي التحقق من TEST_FUZZ_WRITE ليوفر بعض الحماية ضد هذا الاحتمال. ومع ذلك، فكّر في هذا الخيار بعناية قبل استخدامه.

execute_with = "function"

بدلاً من استدعاء الهدف مباشرة:

• أنشئ إغلاقًا (closure) من النوع FnOnce() -> R، حيث R هو نوع القيمة المعادة للهدف، بحيث يكون استدعاء الإغلاق هو استدعاء الهدف؛
• استدعِ function مع تمرير الإغلاق إليه.

استدعاء الهدف بهذه الطريقة يتيح لـ function إعداد بيئة الاستدعاء. وقد يكون هذا مفيدًا، مثلًا، للـ fuzzing على Substrate externalities.

no_auto_generate

لا تحاول إنشاء auto-generate corpus files للهدف.

only_generic_args

سجّل الوسائط العامة (generic args) للهدف عند تشغيل الاختبارات، لكن لا تُنشئ ملفات corpus ولا تنفّذ أداة fuzzing harness. قد يكون هذا مفيدًا عندما يكون الهدف دالة عامة، ولكن من غير الواضح ما هي معاملات الأنواع (type parameters) التي ينبغي استخدامها في الـ fuzzing.

سير العمل المقصود هو: فعّل only_generic_args، ثم شغّل cargo test متبوعًا بـ cargo test-fuzz --display generic-args. قد تكون إحدى الوسائط العامة الناتجة صالحة للاستخدام كـ parameters لـ generic_args. وبالمثل، قد تكون الوسائط العامة الناتجة عن cargo test-fuzz --display impl-generic-args صالحة للاستخدام كـ parameters لـ impl_generic_args.

لاحظ، مع ذلك، أن مجرد استدعاء الهدف بمعاملات معينة أثناء الاختبارات لا يعني أن وسائط الهدف قابلة للـ serialization/deserialization عند استخدام تلك المعاملات. نتائج --display generic-args/--display impl-generic-args هي مجرد مؤشرات إرشادية.

rename = "name"

تعامل مع الهدف كما لو كان اسمه name عند إضافة وحدة (module) إلى النطاق المحيط. توسيع الماكرو test_fuzz يضيف تعريف وحدة إلى النطاق المحيط. افتراضيًا، تُسمى الوحدة على النحو التالي:

• إذا لم يظهر الهدف داخل كتلة impl، تكون الوحدة باسم target_fuzz__، حيث target هو اسم الهدف.
• إذا ظهر الهدف داخل كتلة impl، تكون الوحدة باسم path_target_fuzz__، حيث path هو الجزء الأخير من مسار نوع Self في impl.

لكن استخدام هذا الخيار يجعل الوحدة تُسمى بدلًا من ذلك name_fuzz__. مثال:```rust #[test_fuzz(rename = "bar")] fn foo() {}

// Without the use of rename, a name collision and compile error would result. mod foo_fuzz__ {}

#### سمات حقول Serde على وسائط الدوال

تسمح وحدة الماكرو `test_fuzz` بتطبيق [سمات حقول Serde] على وسائط الدوال. وهذا يوفر أداة إضافية للتعامل مع الأنواع الصعبة.

فيما يلي مثال. لا يمكن اشتقاق خصائص `serde::Serialize` و`serde::Deserialize` لـ `Context` لأنها تحتوي على `Mutex`. ومع ذلك، فإن `Context` تنفّذ `Default`. لذا فإن تطبيق `#[serde(skip)]` على وسيط `Context` يتسبب في تخطيه عند التسلسل، وأخذ قيمته الافتراضية عند إلغاء التسلسل.```rust
use std::sync::Mutex;

// Traits `serde::Serialize` and `serde::Deserialize` cannot be derived for `Context` because it
// contains a `Mutex`.
#[derive(Default)]
struct Context {
    lock: Mutex<()>,
}

impl Clone for Context {
    fn clone(&self) -> Self {
        Self {
            lock: Mutex::new(()),
        }
    }
}

#[test_fuzz::test_fuzz]
fn target(#[serde(skip)] context: Context, x: i32) {
    assert!(x >= 0);
}

لاحظ أنه عند تطبيق سمات حقول Serde على وسيط، فإن ماكرو test_fuzz لا يُجري أي conversions أخرى على الوسيط.

ماكرو `test_fuzz_impl`

متى تم استخدام ماكرو test_fuzz في كتلة impl، يجب أن يسبق impl ماكرو test_fuzz_impl. مثال:```rust #[test_fuzz_impl] impl Foo { #[test_fuzz] fn bar(&self, x: &str) { ... } }

السبب وراء هذا المطلب هو كما يلي. توسيع ماكرو [`test_fuzz`] يضيف تعريف وحدة نمطية إلى النطاق المحيط. لكن لا يمكن أن يظهر تعريف وحدة نمطية داخل كتلة `impl`. إضافة ماكرو `test_fuzz_impl` قبل `impl` يؤدي إلى إضافة الوحدة خارج كتلة `impl`.

إذا رأيت خطأً مشابهاً لما يلي، فمن المحتمل أن ذلك يعني أن استخدام ماكرو `test_fuzz_impl` مفقود:```
error: module is not supported in `trait`s or `impl`s

test_fuzz_impl لا يحتوي حاليًا على أي خيارات.

أمر cargo test-fuzz

يُستخدم أمر cargo test-fuzz للتفاعل مع أهداف التلقيح، ومعالجة مجاميع البيانات، وحالات الانهيار، والتعلقات، وقوائم العمل الخاصة بها. تتضمن أمثلة الاستدعاءات ما يلي:

1. سرد أهداف التلقيح ``` cargo test-fuzz --list
   root@kitploit:~

2. اعرض مجموعة نصوص الهدف foo ``` cargo test-fuzz foo --display corpus
   root@kitploit:~

3. هدف الـ Fuzzing foo ``` cargo test-fuzz foo
   root@kitploit:~

4. إعادة إنتاج الأعطال المكتشفة للهدف foo ``` cargo test-fuzz foo --replay crashes
   root@kitploit:~

الاستخدام```

Usage: cargo test-fuzz [OPTIONS] [TARGETNAME] [-- ...]

Arguments: [TARGETNAME] String that fuzz target's name must contain [ARGS]... Arguments for the fuzzer

Options: --backtrace Display backtraces --consolidate Move one target's crashes, hangs, and work queue to its corpus; to consolidate all targets, use --consolidate-all --coverage Generate coverage for corpus, crashes, hangs, or work queue. Note that generating coverage for instrumented fuzz targets is not supported. --cpus Fuzz using at most cpus; default is all but one --display Display corpus, crashes, generic args, impl generic args, hangs, or work queue. By default, an uninstrumented fuzz target is used. To display with instrumentation, append -instrumented to , e.g., --display corpus-instrumented. --exact Target name is an exact name rather than a substring --exit-code Exit with 0 if the time limit was reached, 1 for other programmatic aborts, and 2 if an error occurred; implies --no-ui, does not imply --run-until-crash or --max-total-time --features Space or comma separated list of features to activate --list List fuzz targets --manifest-path Path to Cargo.toml --max-total-time Fuzz at most of time (equivalent to -- -V ) --no-default-features Do not activate the default feature --no-run Compile, but don't fuzz --no-ui Disable user interface -p, --package Package containing fuzz target --persistent Enable persistent mode fuzzing --pretty Pretty-print debug output when generating coverage, displaying, or replaying --release Build in release mode --replay Replay corpus, crashes, hangs, or work queue. By default, an uninstrumented fuzz target is used. To replay with instrumentation, append -instrumented to , e.g., --replay corpus-instrumented. --reset Clear fuzzing data for one target, but leave corpus intact; to reset all targets, use --reset-all --resume Resume target's last fuzzing session --run-until-crash Stop fuzzing once a crash is found --slice If there are not sufficiently many cpus to fuzz all targets simultaneously, fuzz them in intervals of [default: 1200] --test Integration test containing fuzz target --timeout Number of seconds to consider a hang when fuzzing or replaying (equivalent to -- -t <TIMEOUT * 1000> when fuzzing) --verbose Show build output when generating coverage, displaying, or replaying -h, --help Print help -V, --version Print version