diff --git a/documentation/docs/fuzzing/execute/debug.md b/documentation/docs/fuzzing/execute/debug.md new file mode 100644 index 00000000..5eb459fc --- /dev/null +++ b/documentation/docs/fuzzing/execute/debug.md @@ -0,0 +1,25 @@ +# Debug + +To debug your program with values from a crash file: + +```bash +# fuzzer will run the with the specified +trident fuzz run-debug +# for example: +trident fuzz run-debug fuzz_0 trident-tests/fuzz_tests/fuzzing/fuzz_0/cr1.fuzz +``` + + +## Debug Output + +!!! important + + The debug output is at current development stage really verbose and contains lldb parts. We are working on improving this experience. In the picture below you can see an example of provided debug output. + + 1. Series of Transaction Logs + 2. Structures of data send within the Instructions + 3. **Panic** or **Crash**, based on if the Fuzzing paniced within the Solana Program or Invariant Check failed. + + + +![alt text](../../images/run-debug.png) diff --git a/documentation/docs/fuzzing/fuzzing-run-debug.md b/documentation/docs/fuzzing/execute/run.md similarity index 50% rename from documentation/docs/fuzzing/fuzzing-run-debug.md rename to documentation/docs/fuzzing/execute/run.md index 110233c5..f3f66ff0 100644 --- a/documentation/docs/fuzzing/fuzzing-run-debug.md +++ b/documentation/docs/fuzzing/execute/run.md @@ -1,7 +1,6 @@ -# Run and Debug +# Run -## Run -Once you have finished the implementation of the Fuzz Test, you can run the Test as follows: +To execute the desired fuzz test, run: ```bash # Replace with the name of particular @@ -9,6 +8,35 @@ Once you have finished the implementation of the Fuzz Test, you can run the Test trident fuzz run ``` +## Trident output + +!!! important + + The output provided by Honggfuzz is as follows + + 1. Number of Fuzzing Iterations. + 2. Feedback Driven Mode = Honggfuzz generates data based on the feedback (i.e. feedback based on Coverage progress). + 3. Average Iterations per second + 4. Number of crashes it found (**panics** or failed **invariant checks**) + + +```bash +------------------------[ 0 days 00 hrs 00 mins 01 secs ]---------------------- + Iterations : 688 (out of: 1000 [68%]) # -- 1. -- + Mode [3/3] : Feedback Driven Mode # -- 2. -- + Target : trident-tests/fuzz_tests/fuzzing.....wn-linux-gnu/release/fuzz_0 + Threads : 16, CPUs: 32, CPU%: 1262% [39%/CPU] + Speed : 680/sec [avg: 688] # -- 3. -- + Crashes : 1 [unique: 1, blocklist: 0, verified: 0] # -- 4. -- + Timeouts : 0 [10 sec] + Corpus Size : 98, max: 1048576 bytes, init: 0 files + Cov Update : 0 days 00 hrs 00 mins 00 secs ago + Coverage : edge: 10345/882951 [1%] pc: 163 cmp: 622547 +---------------------------------- [ LOGS ] ------------------/ honggfuzz 2.6 /- +``` + + +## Customize Fuzzing Under the hood {{ config.site_name }} uses [honggfuzz-rs](https://github.com/rust-fuzz/honggfuzz-rs). You can pass [supported parameters](https://github.com/Ackee-Blockchain/trident/blob/develop/examples/fuzz-tests/hello_world/Trident.toml) via the **{{ config.site_name }}.toml** configuration file: @@ -54,31 +82,16 @@ allow_duplicate_txs = false fuzzing_with_stats = true ``` -Or you can pass any parameter via [environment variables](https://github.com/rust-fuzz/honggfuzz-rs#environment-variables). +??? note -A list of hongfuzz parameters can be found in honggfuzz [usage documentation](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md#cmdline---help). The parameters passed via **environment variables** have **higher priority**. For example: + Or you can pass any parameter via [environment variables](https://github.com/rust-fuzz/honggfuzz-rs#environment-variables). -```bash -# Time-out: 10 secs -# Number of concurrent fuzzing threads: 1 -# Number of fuzzing iterations: 10000 -# Display Solana logs in the terminal -HFUZZ_RUN_ARGS="-t 10 -n 1 -N 10000 -Q" trident fuzz run -``` - -### Fuzzing statistics -Sometimes, it's useful to know how often a particular instruction has been invoked and how many times it has succeeded or failed. To display these statistics when fuzzing is finished or interrupted, set the `fuzzing_with_stats` option to `true` in the `[fuzz]` section of the Trident.toml configuration file. Please note that this option is disabled by default because it impacts performance. - -The statistics show the total number of invocations for each instruction, which is the sum of successful and failed invocations. Successful invocations are those that return an `Ok()` result. Failed invocations are those that return an `Err()` result. Additionally, the statistics also show as `Check Failed` the number of successful invocations that did not pass the user-defined invariants check. Note that unhandled panics are currently logged only as crashes and are not displayed in the fuzzing statistics table. + A list of hongfuzz parameters can be found in honggfuzz [usage documentation](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md#cmdline---help). The parameters passed via **environment variables** have **higher priority**. For example: -Keep in mind that the number of fuzz iterations does not directly correspond to the total number of invocations. In one fuzz iteration, the fuzzer might be unable to deserialize fuzz data into instructions, causing the entire iteration to be skipped. - -## Debug -To debug your program with values from a crash file: - -```bash -# fuzzer will run the with the specified -trident fuzz run-debug -# for example: -trident fuzz run-debug fuzz_0 trident-tests/fuzz_tests/fuzzing/fuzz_0/cr1.fuzz -``` + ```bash + # Time-out: 10 secs + # Number of concurrent fuzzing threads: 1 + # Number of fuzzing iterations: 10000 + # Display Solana logs in the terminal + HFUZZ_RUN_ARGS="-t 10 -n 1 -N 10000 -Q" trident fuzz run + ``` diff --git a/documentation/docs/fuzzing/execute/statistics.md b/documentation/docs/fuzzing/execute/statistics.md new file mode 100644 index 00000000..f450067e --- /dev/null +++ b/documentation/docs/fuzzing/execute/statistics.md @@ -0,0 +1,27 @@ +# Fuzzing statistics + +!!! important + + In order to show statistics of fuzzing session (statistics are displayed after the fuzzing session ended), set `fuzzing_with_stats` within the Trident.toml to `true`. + + ```toml + [fuzz] + # ... + fuzzing_with_stats = true + # ... + ``` + + +Currently exported statistics from the Fuzzing Session + +#### Simple + +- Number of invocations of each instruction during the fuzzing session. +- Number of successful invocations of each instruction during the fuzzing session. +- Number of failed invariants checks for each instruction during the fuzzing session. + +??? note + + Keep in mind that the number of fuzz iterations does not directly correspond to the total number of invocations. In one fuzz iteration, the fuzzer might be unable to deserialize fuzz data into instructions, causing the entire iteration to be skipped. + + On the other hand this is expected behavior as the underlying data are randomly (with coverage feedback) generated, so the Honggfuzz will not necessarily find appropriate data each iteration. diff --git a/documentation/docs/fuzzing/fuzzing-current-limitations.md b/documentation/docs/fuzzing/extra/current-limitations.md similarity index 100% rename from documentation/docs/fuzzing/fuzzing-current-limitations.md rename to documentation/docs/fuzzing/extra/current-limitations.md diff --git a/documentation/docs/fuzzing/extra/examples.md b/documentation/docs/fuzzing/extra/examples.md new file mode 100644 index 00000000..9d706811 --- /dev/null +++ b/documentation/docs/fuzzing/extra/examples.md @@ -0,0 +1,53 @@ +--- +hide: + - toc +--- + +# Trident by Examples + +
+ +- :material-hand-wave:{ .lg .middle } __Hello World!__ + + --- + + Hello World example with Trident. + + [Hello World!](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/hello_world) + +- :octicons-bug-16:{ .lg .middle } __Possible vulnerabilities and bugs__ + + --- + + Check the possible attack vectors and bugs that can be detected using Trident. + + [Unchecked Arithmetic](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/unchecked-arithmetic-0) + + [Incorrect Instruction Sequence](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/incorrect-ix-sequence-1) + + [Unauthorized Access](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/unauthorized-access-2) + + [Incorrect Integer Arithmetic](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/incorrect-integer-arithmetic-3) + +- :octicons-tools-24:{ .lg .middle } __Customize with Arbitrary__ + + --- + + You can use Arbitrary crate to your advantage and limit or customize the data that are sent to the instructions. + + [Custom Data Types](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/arbitrary-custom-types-4) + + + [Limiting Instructions Inputs](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/arbitrary-limit-inputs-5) + +- :material-call-made:{ .lg .middle } __Cross-Program Invocation__ + + --- + + Trident supports Cross-Program Invocation, you can fuzz your programs and create NFTs at the same time. + + [Simple CPI](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/simple-cpi-6) + + [CPI with Metaplex Metadata Program](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/cpi-metaplex-7) + +
diff --git a/documentation/docs/fuzzing/fuzzing-lifecycle.md b/documentation/docs/fuzzing/extra/lifecycle.md similarity index 100% rename from documentation/docs/fuzzing/fuzzing-lifecycle.md rename to documentation/docs/fuzzing/extra/lifecycle.md diff --git a/documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz.md b/documentation/docs/fuzzing/first-steps/fuzz-test-initialization.md similarity index 79% rename from documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz.md rename to documentation/docs/fuzzing/first-steps/fuzz-test-initialization.md index 00a2cb11..be89c0fa 100644 --- a/documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz.md +++ b/documentation/docs/fuzzing/first-steps/fuzz-test-initialization.md @@ -1,6 +1,6 @@ -# Fuzz test-only +# Initialize Fuzz Test -If you are interested only in generating templates for fuzz tests run +For initialization of workspace for fuzz tests, call: ```bash trident init fuzz ``` @@ -21,3 +21,10 @@ project-root ├── Trident.toml └── ... ``` + +## Add new Fuzz Test + +If you wish to generate template for a new fuzz test, call: +```bash +trident fuzz add +``` diff --git a/documentation/docs/fuzzing/first-steps/writing-fuzz-test.md b/documentation/docs/fuzzing/first-steps/writing-fuzz-test.md new file mode 100644 index 00000000..534958e2 --- /dev/null +++ b/documentation/docs/fuzzing/first-steps/writing-fuzz-test.md @@ -0,0 +1,32 @@ +# Writing Fuzz Test + +!!! important + + At the current development stage, there are some manual steps required to start the Fuzzing Session. In principle: + + **Prerequisites:** + + - Add dependencies specific to your program to `trident-tests/fuzz_tests/Cargo.toml` (such as anchor-spl etc.). + - Add necessary `use` statements into `trident-tests/fuzz_tests//accounts_snapshots.rs` to import missing types. + + **Writing Fuzz Tests** + + 1. Include desired Programs [Include Programs](../writing-fuzz-test/programs.md). + 2. Specify pseudo-random accounts to re-use [Accounts to re-use](../writing-fuzz-test/accounts.md). + 3. Specify instruction data [Instruction Data](../writing-fuzz-test/instruction-data.md). + 4. Specify instruction accounts [Instruction Accounts](../writing-fuzz-test/instruction-accounts.md). + + **Run and Debug** + + 1. Execute desired fuzz test [Run](../execute/run.md) + 2. See the found crash with more details [Debug](../execute/debug.md) + +!!! note + + For better fuzzing results and experience you can also manually adjust the following: + + 1. Define Invariants checks [Invariants Checks](../writing-fuzz-test-extra/invariants-checks.md). + 2. Specify instruction sequences[Instruction sequences](../writing-fuzz-test-extra/instruction-sequences.md). + 3. Specify custom data types[Custom Data types](../writing-fuzz-test-extra/custom-data-types.md). + 4. Well structured data[Arbitrary](../writing-fuzz-test-extra/arbitrary.md). + 4. AccountsSnapshots macro[AccountsSnapshots](../writing-fuzz-test-extra/accounts-snapshots.md). diff --git a/documentation/docs/fuzzing/fuzzing-examples.md b/documentation/docs/fuzzing/fuzzing-examples.md deleted file mode 100644 index c8cf6055..00000000 --- a/documentation/docs/fuzzing/fuzzing-examples.md +++ /dev/null @@ -1,23 +0,0 @@ -# Fuzzing Examples - -### Hello World! Example -- [hello_world](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/hello_world) - -### Possible vulnerabilities and bugs -- [unchecked-arithmetic-0](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/unchecked-arithmetic-0) -- [incorrect-ix-sequence-1](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/incorrect-ix-sequence-1) -- [unauthorized-access-2](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/unauthorized-access-2) -- [incorrect-integer-arithmetic-3](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/incorrect-integer-arithmetic-3) - -### Example usage of Arbitrary Trait with Custom Data type as Instruction parameter -- [arbitrary-custom-types-4](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/arbitrary-custom-types-4) - -### Example usage of limiting the Instruction data structure with the Arbitrary trait -- [arbitrary-limit-inputs-5](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/arbitrary-limit-inputs-5) - -### Example usage of CPI with available source code to the callee program -- [simple-cpi-6](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/simple-cpi-6) - - -### Example usage of CPI with unavailable source code to the callee program (i.e. callee as SBF) -- [cpi-metaplex-7](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/cpi-metaplex-7) diff --git a/documentation/docs/fuzzing/fuzzing-introduction.md b/documentation/docs/fuzzing/fuzzing-introduction.md deleted file mode 100644 index 76a1da8a..00000000 --- a/documentation/docs/fuzzing/fuzzing-introduction.md +++ /dev/null @@ -1,22 +0,0 @@ -# Introduction - -Fuzzing is a software testing technique that involves providing invalid, unexpected, or random data as inputs to a computer program. The aim is to uncover bugs and vulnerabilities that might not be detected with conventional testing strategies. - -# {{ config.site_name }} - -The `{{ config.site_name }}` testing framework equips developers with tools to efficiently develop fuzz tests for Anchor-based programs. It streamlines the fuzz testing process through automation and comprehensive support: - -- Automatically parses Anchor-based programs to generate necessary implementations for deserializing instruction accounts. -- Generates templates for developers to customize according to the specific needs of their fuzz test scenarios. -- Offers derive macros to effortlessly implement required traits, reducing manual coding efforts. -- Includes a bank client and helper functions for simplified account management during testing. -- Provides a Command-Line Interface (CLI) for executing and debugging fuzz tests with ease. - -`{{ config.site_name }}` is built for customization, enabling developers to tailor their fuzz tests by adjusting: - -- **Execution Order of Instructions**: Test different sequences and their effects on the program to uncover sequence-related vulnerabilities. -- **Instruction Parameters**: Identify how variations in inputs influence program behavior, testing for robustness against a wide range of data. -- **Instruction Accounts**: Explore the impact of different account states on the software's functionality, ensuring comprehensive account testing. -- **Comprehensive Testing**: Conduct thorough and effective fuzz testing by combining any of the above aspects. - -This framework supports a detailed and methodical approach to fuzz testing, facilitating the identification and remediation of potential vulnerabilities in software applications. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p0.md b/documentation/docs/fuzzing/howto/fuzzing-howto-p0.md deleted file mode 100644 index ee24ab98..00000000 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p0.md +++ /dev/null @@ -1,6 +0,0 @@ -# First Steps - -At the current development stage, there are some manual steps required to make your fuzz test compile: - -1. Add dependencies specific to your program to `trident-tests/fuzz_tests/Cargo.toml` (such as anchor-spl etc.). -2. Add necessary `use` statements into `trident-tests/fuzz_tests//accounts_snapshots.rs` to import missing types. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p1.md b/documentation/docs/fuzzing/howto/fuzzing-howto-p1.md deleted file mode 100644 index b80607c4..00000000 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p1.md +++ /dev/null @@ -1,21 +0,0 @@ -# Specify accounts to reuse -{{ config.site_name }} fuzzer helps you to generate only a limited amount of pseudo-random accounts and reuse them in the instructions. - -Always generating only random accounts would **in most cases lead to a situation where the fuzzer would be stuck because the accounts would be almost every time rejected by your Anchor program**. Therefore it is necessary to specify, what accounts should be used and also limit the number of newly created accounts to reduce the space complexity. - -- Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `FuzzAccounts` structure. It contains all accounts used in your program. You have to determine if the account is a: - - Signer - - PDA - - Token Account - - Program account - -Then use the corresponding `AccountsStorage` types such as: - -```rust -pub struct FuzzAccounts { - signer: AccountsStorage, - some_pda: AccountsStorage, - token_vault: AccountsStorage, - mint: AccountsStorage, -} -``` diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p2.md b/documentation/docs/fuzzing/howto/fuzzing-howto-p2.md deleted file mode 100644 index 183ef87b..00000000 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p2.md +++ /dev/null @@ -1,20 +0,0 @@ -# Specify instruction data - -{{ config.site_name }} fuzzer generates random instruction data for you. - -Currently, it is however required, that you manually assign the random fuzzer data to the instruction data. It is done using the `IxOps` trait and its method `get_data`. - -- Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `get_data` methods for each instruction such as: - -```rust -fn get_data( - &self, - _client: &mut impl FuzzClient, - _fuzz_accounts: &mut FuzzAccounts, -) -> Result { - let data = fuzz_example1::instruction::Invest { - amount: self.data.amount, - }; - Ok(data) -} -``` diff --git a/documentation/docs/fuzzing/initialization/fuzzing-initialization-all.md b/documentation/docs/fuzzing/initialization/fuzzing-initialization-all.md deleted file mode 100644 index 23d4c8af..00000000 --- a/documentation/docs/fuzzing/initialization/fuzzing-initialization-all.md +++ /dev/null @@ -1,27 +0,0 @@ - -# All-Suite - -To initialize {{ config.site_name }} and generate all-suite test templates, navigate to your project's root directory and run - -```bash -trident init both -``` - -The command will generate the following folder structure: -```bash -project-root -├── .program_client -├── trident-tests -│ ├── fuzz_tests # fuzz tests folder -│ │ ├── fuzz_0 # particular fuzz test -│ │ │ ├── accounts_snapshots.rs # generated accounts deserialization methods -│ │ │ ├── test_fuzz.rs # the binary target of your fuzz test -│ │ │ └── fuzz_instructions.rs # the definition of your fuzz test -│ │ ├── fuzz_1 -│ │ ├── fuzz_X # possible multiple fuzz tests -│ │ ├── fuzzing # compilations and crashes folder -│ │ └── Cargo.toml -│ └── poc_tests # integration tests folder -├── Trident.toml -└── ... -``` diff --git a/documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz-add.md b/documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz-add.md deleted file mode 100644 index c355269a..00000000 --- a/documentation/docs/fuzzing/initialization/fuzzing-initialization-fuzz-add.md +++ /dev/null @@ -1,21 +0,0 @@ - -# Add new Fuzz Test -If you have already initialized {{ config.site_name }} within your project, and you are interested in initializing a new fuzz test run. -```bash -trident fuzz add -``` - -The command will generate a new fuzz test as follows: -```bash -project-root -├── trident-tests -│ ├── fuzz_tests # fuzz tests folder -│ │ ├── fuzz_X # new fuzz test folder -│ │ │ ├── accounts_snapshots.rs -│ │ │ ├── test_fuzz.rs -│ │ │ └── fuzz_instructions.rs -│ │ ├── fuzzing -│ │ └── Cargo.toml # already present -├── Trident.toml # already present -└── ... -``` diff --git a/documentation/docs/fuzzing/writing-fuzz-test-extra/accounts-snapshots.md b/documentation/docs/fuzzing/writing-fuzz-test-extra/accounts-snapshots.md new file mode 100644 index 00000000..e870db0f --- /dev/null +++ b/documentation/docs/fuzzing/writing-fuzz-test-extra/accounts-snapshots.md @@ -0,0 +1,98 @@ +# AccountsSnapshots + +Trident provides AccountsSnapshots macro that can be derived for each Instruction Context you have specified in your Solana Program for real-time updates of the Instruction Context. + +!!! important + + AccountsSnapshots macro requires additional deps and source code additions in your Solana Program. On the other hand can provide real-time updates of Context modifications, instead of re-generating the `accounts_snapshots.rs`. + + + +## Add required imports + +To the Cargo.toml of the Solana Program add the following feature and deps. + +```toml +[package] +name = "..." +version = "0.1.0" +description = "Created with Anchor" +edition = "2021" + +[lib] +crate-type = ["cdylib", "lib"] +name = "..." + +[features] +default = [] +cpi = ["no-entrypoint"] +no-entrypoint = [] +no-idl = [] +no-log-ix-name = [] +idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"] +# add the feature below +# --- +trident-fuzzing = ["dep:trident-fuzz"] +# --- + + +[dependencies] +# --- +# add the following Trident deps with the desired version +trident-derive-accounts-snapshots = "..." +trident-fuzz = { version = "...", optional = true } +# --- +# Your deps +anchor-lang = "0.30.1" +anchor-spl = "0.30.1" +... +``` + +## Derive the AccountsSnapshots + +For each context in your program you can derive the AccountsSnapshots. + +```rust +use trident_derive_accounts_snapshots::AccountsSnapshots; + +// ... + +#[derive(AccountsSnapshots, Accounts)] +pub struct TheContextName<'info> { + #[account(...)] + pub account1: ...<'info>, + + #[account(...)] + pub account2: ...<'info, ...>, + + #[account( + ... + )] + pub account3: ..., + + // additional accounts +} +``` + + +## Use AccountsSnapshots in the Fuzz Tests + +### Use defined feature + +In the Cargo.toml within the `trident-tests/fuzz_tests`. Activate the new feature next to the program dependency. + +```toml +[dependencies.] +path = "../../programs/" +features = ["trident-fuzzing"] +``` + +### Use the derived AccountsSnapshots within the Fuzz Test + +Now you can use the derived AccountsSnapshots within the Fuzz Test instead of using generated `accounts_snapshots.rs`. + +## Example + +!!! tip + + Check the [Fuzz Example](https://github.com/Ackee-Blockchain/trident/tree/master/examples/fuzz-tests/arbitrary-limit-inputs-5) that uses the AccountsSnapshots macro. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p7.md b/documentation/docs/fuzzing/writing-fuzz-test-extra/arbitrary.md similarity index 97% rename from documentation/docs/fuzzing/howto/fuzzing-howto-p7.md rename to documentation/docs/fuzzing/writing-fuzz-test-extra/arbitrary.md index 0abc59e9..d09ed6fc 100644 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p7.md +++ b/documentation/docs/fuzzing/writing-fuzz-test-extra/arbitrary.md @@ -1,4 +1,4 @@ -# How to use Arbitrary crate +# Structured Data The [Arbitrary](https://docs.rs/arbitrary/latest/arbitrary/) crate in Rust is used for generating well-typed, structured instances of data from raw byte buffers, making it useful for fuzzing by producing random but structured data for tests. @@ -157,5 +157,9 @@ impl<'a> Arbitrary<'a> for InitVestingData { } ... ``` + ## Example -For a practical example, please refer to the [Examples](../fuzzing-examples.md) section. + +!!! tip + + For a practical example, please refer to the [Examples](../extra/examples.md) section. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p6.md b/documentation/docs/fuzzing/writing-fuzz-test-extra/custom-data-types.md similarity index 97% rename from documentation/docs/fuzzing/howto/fuzzing-howto-p6.md rename to documentation/docs/fuzzing/writing-fuzz-test-extra/custom-data-types.md index 9a7cb797..6c956725 100644 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p6.md +++ b/documentation/docs/fuzzing/writing-fuzz-test-extra/custom-data-types.md @@ -1,4 +1,4 @@ -# How to use Custom Data Types +# Custom Data Types If you use Custom Types as Instruction data arguments, you may encounter a problem that the Custom Type does not implement @@ -147,4 +147,7 @@ impl<'info> IxOps<'info> for InitVestingData { ``` ## Example -For a practical example, please refer to the [Examples](../fuzzing-examples.md) section. + +!!! tip + + For a practical example, please refer to the [Examples](../extra/examples.md) section. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p5.md b/documentation/docs/fuzzing/writing-fuzz-test-extra/instruction-sequences.md similarity index 60% rename from documentation/docs/fuzzing/howto/fuzzing-howto-p5.md rename to documentation/docs/fuzzing/writing-fuzz-test-extra/instruction-sequences.md index c8af525a..c3ee5137 100644 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p5.md +++ b/documentation/docs/fuzzing/writing-fuzz-test-extra/instruction-sequences.md @@ -1,8 +1,10 @@ -# Customize instructions generation +# Instruction sequences It is possible to customize how the instructions are generated and which instructions will be executed at the beginning (`pre_ixs`), in the middle (`ixs`) and at the end (`post_ixs`) of each fuzz iteration. This can be useful for example if your program needs an initialization or you want to fuzz some specific program state. -- Go to the `trident-tests/fuzz_tests//test_fuzz.rs` and implement the corresponding optional method of the `FuzzDataBuilder` trait. For example, in order to always call the `initialize` instruction, modify the trait's implementation as follows: +!!! important + + - Go to the `trident-tests/fuzz_tests//test_fuzz.rs` and implement the corresponding optional method of the `FuzzDataBuilder` trait. For example, in order to always call the `initialize` instruction, modify the trait's implementation. ```rust impl FuzzDataBuilder for MyFuzzData { @@ -13,3 +15,8 @@ impl FuzzDataBuilder for MyFuzzData { } } ``` + + +!!! tip + + Consider checking the [Examples](../extra/examples.md) section for more tips. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p4.md b/documentation/docs/fuzzing/writing-fuzz-test-extra/invariants-checks.md similarity index 79% rename from documentation/docs/fuzzing/howto/fuzzing-howto-p4.md rename to documentation/docs/fuzzing/writing-fuzz-test-extra/invariants-checks.md index 70182d86..6593aade 100644 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p4.md +++ b/documentation/docs/fuzzing/writing-fuzz-test-extra/invariants-checks.md @@ -1,8 +1,10 @@ -# Define invariants checks +# Invariants checks After each successful instruction execution, the `check()` method is called to check the account data invariants. -For each instruction, you can compare the account data **before** and **after** the instruction execution such as: +!!! important + + For each instruction, you can compare the account data **before** and **after** the instruction execution. ```rust fn check( @@ -30,3 +32,8 @@ fn check( Ok(()) } ``` + + +!!! tip + + Consider checking the [Examples](../extra/examples.md) section for more tips. diff --git a/documentation/docs/fuzzing/writing-fuzz-test/accounts.md b/documentation/docs/fuzzing/writing-fuzz-test/accounts.md new file mode 100644 index 00000000..2e797c9c --- /dev/null +++ b/documentation/docs/fuzzing/writing-fuzz-test/accounts.md @@ -0,0 +1,35 @@ +# Accounts to reuse + +{{ config.site_name }} helps you to generate only a limited amount of pseudo-random accounts and reuse them in the instructions. + +??? note + + **Details:** + + Always generating only random accounts would **in most cases lead to a situation where the fuzzer would be stuck because the accounts would be almost every time rejected by your Anchor program**. Therefore it is necessary to specify, what accounts should be used and also limit the number of newly created accounts to reduce the space complexity. + + +!!! important + + Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `FuzzAccounts` structure. It contains all accounts used in your program. You have to determine if the account is a: + + - Signer + - PDA + - Token Account + - Program account + + Then use the corresponding AccountsStorage. + + +```rust +pub struct FuzzAccounts { + signer: AccountsStorage, + some_pda: AccountsStorage, + token_vault: AccountsStorage, + mint: AccountsStorage, +} +``` + +!!! tip + + Consider checking the [Examples](../extra/examples.md) section for more tips. diff --git a/documentation/docs/fuzzing/howto/fuzzing-howto-p3.md b/documentation/docs/fuzzing/writing-fuzz-test/instruction-accounts.md similarity index 81% rename from documentation/docs/fuzzing/howto/fuzzing-howto-p3.md rename to documentation/docs/fuzzing/writing-fuzz-test/instruction-accounts.md index 5e98a739..0ea90012 100644 --- a/documentation/docs/fuzzing/howto/fuzzing-howto-p3.md +++ b/documentation/docs/fuzzing/writing-fuzz-test/instruction-accounts.md @@ -1,10 +1,13 @@ -# Specify instruction accounts +# Instruction accounts -{{ config.site_name }} fuzzer generates random indexes of accounts to use in each instruction. Each created account is saved in the global `FuzzAccounts` structure which helps you to reuse already existing accounts across all instructions. +{{ config.site_name }} generates random indexes of accounts to use in each instruction. Each created account is saved in the global FuzzAccounts structure which helps you to reuse already existing accounts across all instructions. -You are required to define, how these accounts should be created and which accounts should be passed to an instruction. It is done using the `IxOps` trait and its method `get_accounts`. +!!! important + + You are required to define, how these accounts should be created and which accounts should be passed to an instruction. It is done using the `IxOps` trait and its method `get_accounts`. + + - Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `get_accounts` methods for each instruction. -- Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `get_accounts` methods for each instruction such as: ```rust fn get_accounts( @@ -35,7 +38,10 @@ fn get_accounts( Ok((signers, acc_meta)) } ``` -Notice especially the helper method `fuzz_accounts..get_or_create_account` that is used to create a Keypair or retrieve the Public key of the already existing account. + +!!! note + + Notice especially the helper method `fuzz_accounts..get_or_create_account` that is used to create a Keypair or retrieve the Public key of the already existing account. ## Create an arbitrary account The `AccountsStorage` type provides an implementation of the `get_or_create_account` method that helps you create new or read already existing accounts. There are different implementations for different types of storage (`Keypair`, `TokenStore`, `MintStore`, `PdaStore`) to simplify the creation of new accounts. @@ -112,3 +118,10 @@ let my_pda = fuzz_accounts } }).pubkey(); ``` + + +## Example + +!!! tip + + Consider checking the [Examples](../extra/examples.md) section for more tips. diff --git a/documentation/docs/fuzzing/writing-fuzz-test/instruction-data.md b/documentation/docs/fuzzing/writing-fuzz-test/instruction-data.md new file mode 100644 index 00000000..8cfb9782 --- /dev/null +++ b/documentation/docs/fuzzing/writing-fuzz-test/instruction-data.md @@ -0,0 +1,27 @@ +# Instruction data + +{{ config.site_name }} generates random instruction data for you. + +!!! important + + Currently, it is however required, that you manually assign the random fuzzer data to the instruction data. It is done using the `IxOps` trait and its method `get_data`. + + - Go to the `trident-tests/fuzz_tests//fuzz_instructions.rs` file and complete the pre-generated `get_data` methods for each instruction. + +```rust +fn get_data( + &self, + _client: &mut impl FuzzClient, + _fuzz_accounts: &mut FuzzAccounts, +) -> Result { + let data = fuzz_example1::instruction::Invest { + amount: self.data.amount, + }; + Ok(data) +} +``` + + +!!! tip + + Consider checking the [Examples](../extra/examples.md) section for more tips. diff --git a/documentation/docs/fuzzing/writing-fuzz-test/programs.md b/documentation/docs/fuzzing/writing-fuzz-test/programs.md new file mode 100644 index 00000000..1356496e --- /dev/null +++ b/documentation/docs/fuzzing/writing-fuzz-test/programs.md @@ -0,0 +1,180 @@ +# Include Programs + +With Trident you can and need to specify which programs will be included in the Testing Environment. + +!!! important + + As Trident supports Cross-Program Invocations you need to specify all of the programs that the Solana Environment should start with, same as for the ProgramTest. Go to the `trident-tests/fuzz_tests//test_fuzz.rs` and customize the Solana Environment as shown below. + +```rust +// use statements ... +use ... as FuzzInstruction_hello_world; + +use hello_world::entry as entry_hello_world; +use hello_world::ID as PROGRAM_ID_HELLO_WORLD; +const PROGRAM_NAME_HELLO_WORLD: &str = "hello_world"; + +// TODO specify this type for Instructions generation. +pub type FuzzInstruction = FuzzInstruction_hello_world; + +struct MyFuzzData; + +impl FuzzDataBuilder for MyFuzzData {} + +fn main() { + loop { + fuzz_trident!(fuzz_ix: FuzzInstruction, |fuzz_data: MyFuzzData| { + + // Include the program and its entrypoint in the Testing Environment + let fuzzing_program1 = FuzzingProgram::new( + PROGRAM_NAME_HELLO_WORLD, + &PROGRAM_ID_HELLO_WORLD, + processor!(convert_entry!(entry_hello_world)) + ); + + let mut client = + ProgramTestClientBlocking::new( + &[fuzzing_program1] + ).unwrap(); + + // fill Program ID of program you are going to call + let _ = fuzz_data.run_with_runtime( + PROGRAM_ID_HELLO_WORLD, + &mut client + ); + }); + } +} +``` + +## SBF + +!!! important + + If you want to include Solana Programs from some of the clusters (for example Mainnet). Follow these steps: + + 1. Dump the program from the desired cluster (`solana program dump -u m .so`). + 2. Create folder `trident-genesis` in the root of the Anchor Workspace (i.e. next to the Anchor.toml) + 3. Copy the dumped file to the `trident-genesis`. + 4. Include the program as described below. + +!!! warning + + The name of the dumped .so file has to be the same as the program name you are including (i.e. you are including metaplex-token-metadata, then the file name has to be metaplex-token-metadata.so) + +```rust +// use statements ... +use ... as FuzzInstruction_hello_world; + +use hello_world::entry as entry_hello_world; +use hello_world::ID as PROGRAM_ID_HELLO_WORLD; +const PROGRAM_NAME_HELLO_WORLD: &str = "hello_world"; + +// TODO specify this type for Instructions generation. +pub type FuzzInstruction = FuzzInstruction_hello_world; + +struct MyFuzzData; + +impl FuzzDataBuilder for MyFuzzData {} + +fn main() { + loop { + fuzz_trident!(fuzz_ix: FuzzInstruction, |fuzz_data: MyFuzzData| { + + // Include the program and its entrypoint in the Testing Environment + let fuzzing_program1 = FuzzingProgram::new( + PROGRAM_NAME_CPI_METAPLEX_7, + &PROGRAM_ID_CPI_METAPLEX_7, + processor!(convert_entry!(entry_cpi_metaplex_7)) + ); + + + let metaplex = FuzzingProgram::new( + "metaplex-token-metadata", + &mpl_token_metadata::ID, + None + ); + + let mut client = + ProgramTestClientBlocking::new(&[fuzzing_program1,metaplex]) + .unwrap(); + + // fill Program ID of program the fuzzer will call. + let _ = fuzz_data.run_with_runtime( + PROGRAM_NAME_PROGRAM_1, + &mut client + ); + }); + } +} + +``` + +## Native + +!!! important + + If you want to include additional Solana programs within the Testing Environment for example for CPI purposes you can include them with the same approach as including only one program. More details in the snippet below. + +```rust +// use statements ... +use ... as FuzzInstruction_program1; +use ... as FuzzInstruction_program2; + + +use program1::entry as entry_program1; +use program1::ID as PROGRAM_ID_PROGRAM_1; +const PROGRAM_NAME_PROGRAM_1: &str = "program1"; + +use program2::entry as entry_program2; +use program2::ID as PROGRAM_ID_PROGRAM_2; +const PROGRAM_NAME_PROGRAM_2: &str = "program2"; + + +// TODO specify this type for Instructions generation. +// These instructions are going to be called by the Fuzzer +pub type FuzzInstruction = FuzzInstruction_program1; + +struct MyFuzzData; + +impl FuzzDataBuilder for MyFuzzData {} + +fn main() { + loop { + fuzz_trident!(fuzz_ix: FuzzInstruction, |fuzz_data: MyFuzzData| { + + // Include the program and its entrypoint in the Testing Environment + let fuzzing_program1 = FuzzingProgram::new( + PROGRAM_NAME_PROGRAM_1, + &PROGRAM_ID_PROGRAM_1, + processor!(convert_entry!(entry_program1)) + ); + + let fuzzing_program2 = FuzzingProgram::new( + PROGRAM_NAME_PROGRAM_2, + &PROGRAM_ID_PROGRAM_2, + processor!(convert_entry!(entry_program2)) + ); + + + let mut client = + ProgramTestClientBlocking::new( + &[fuzzing_program1,fuzzing_program2] + ).unwrap(); + + // fill Program ID of program the fuzzer will call. + let _ = fuzz_data.run_with_runtime( + PROGRAM_NAME_PROGRAM_1, + &mut client + ); + }); + } +} +``` + + +## Example + +!!! tip + + For a practical example of CPI, please refer to the [Examples](../extra/examples.md) section. diff --git a/documentation/docs/getting-started/docker-image.md b/documentation/docs/getting-started/docker-image.md new file mode 100644 index 00000000..16c47935 --- /dev/null +++ b/documentation/docs/getting-started/docker-image.md @@ -0,0 +1,3 @@ +# Docker Image + +TBD diff --git a/documentation/docs/getting-started/getting-started.md b/documentation/docs/getting-started/getting-started.md new file mode 100644 index 00000000..f14b38fc --- /dev/null +++ b/documentation/docs/getting-started/getting-started.md @@ -0,0 +1,63 @@ +# Installation + +This guide will walk you through the Installation process of Trident. + +!!! important + + **Prerequisite** + + It is expected that you have installed: + + - Rust ([Install Rust](https://www.rust-lang.org/tools/install)) + - Solana CLI ([Install Solana CLI](https://docs.solanalabs.com/cli/install)) + - Anchor Framework ([Install Anchor](https://www.anchor-lang.com/docs/installation)) + + For supported versions check the [Supported Versions](#supported-versions) + +## Install System Dependencies + +Update your package list and install the required packages: + +```bash +sudo apt-get update +sudo apt-get install -y \ + curl \ + git \ + build-essential \ + pkg-config \ + libssl-dev \ + npm \ + vim \ + nano \ + wget \ + binutils-dev \ + libunwind-dev \ + lldb +``` + +## Install Trident and Honggfuzz + +Install them using the following commands: + + +```bash +cargo install trident-cli +cargo install honggfuzz +``` + +## Supported versions + +| {{ config.site_name }} CLI | Anchor | Solana | Rust | Honggfuzz | +|--------------|---------|----------|-----------------------|-----------------------| +| `v0.7.0` | `>=0.29.*`1 | `^1.17.4` | `nightly` | `0.5.56` | +| `v0.6.0` | `>=0.29.*`1 | `^1.17` | `nightly` | `0.5.55` | +| `v0.5.0` | `~0.28.*` | `=1.16.6` | - | - | +| `v0.4.0` | `~0.27.*` | `>=1.15` | - | - | +| `v0.3.0` | `~0.25.*` | `>=1.10` | - | - | +| `v0.2.0` | `~0.24.*` | `>=1.9` | - | - | + +1. To use Trident with Anchor 0.29.0, run the following commands from your project's root directory after Trident initialization: +```bash +cargo update anchor-client@0.30.0 --precise 0.29.0 +cargo update anchor-spl@0.30.0 --precise 0.29.0 +``` diff --git a/documentation/docs/home/home-installation.md b/documentation/docs/home/home-installation.md deleted file mode 100644 index 089bab1d..00000000 --- a/documentation/docs/home/home-installation.md +++ /dev/null @@ -1,39 +0,0 @@ -# Installation - -## Dependencies - -Check [supported versions](#supported-versions) section for further details. - -- Install [Rust](https://www.rust-lang.org/tools/install) -- Install [Solana tool suite](https://docs.solana.com/cli/install-solana-cli-tools) -- Install [Anchor](https://www.anchor-lang.com/docs/installation) -- Install [Honggfuzz-rs](https://github.com/rust-fuzz/honggfuzz-rs#how-to-use-this-crate) for fuzz testing - -## Installation - -```bash -cargo install trident-cli - -# or the specific version - -cargo install --version trident-cli -``` - -### Supported versions - -- We support `Anchor` and `Solana` versions specified in the table below. - -| {{ config.site_name }} CLI | Anchor | Solana | Rust | -|--------------|:---------:|----------:|:-----------------------| -| `v0.7.0` | `>=0.29.*`1 | `^1.17.4` | `nightly` | -| `v0.6.0` | `>=0.29.*`1 | `^1.17` | `nightly` | -| `v0.5.0` | `~0.28.*` | `=1.16.6` | | -| `v0.4.0` | `~0.27.*` | `>=1.15` | | -| `v0.3.0` | `~0.25.*` | `>=1.10` | | -| `v0.2.0` | `~0.24.*` | `>=1.9` | | - -1. To use Trident with Anchor 0.29.0, run the following commands from your project's root directory after Trident initialization: -```bash -cargo update anchor-client@0.30.0 --precise 0.29.0 -cargo update anchor-spl@0.30.0 --precise 0.29.0 -``` diff --git a/documentation/docs/images/run-debug.png b/documentation/docs/images/run-debug.png new file mode 100644 index 00000000..6800627e Binary files /dev/null and b/documentation/docs/images/run-debug.png differ diff --git a/documentation/docs/images/trident-logo-smaller.png b/documentation/docs/images/trident-logo-smaller.png new file mode 100644 index 00000000..3fad1e2f Binary files /dev/null and b/documentation/docs/images/trident-logo-smaller.png differ diff --git a/documentation/docs/images/trident-logo.png b/documentation/docs/images/trident-logo.png new file mode 100644 index 00000000..3a53a10d Binary files /dev/null and b/documentation/docs/images/trident-logo.png differ diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 508069cf..6a67e0c3 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -1,12 +1,78 @@ +--- +hide: + - navigation + - toc +--- + # {{ config.site_name }} -{{ config.site_name }} is a Rust-based framework to fuzz and integration test Solana programs to help you ship secure code. +![Trident](./images/trident-logo-smaller.png){ align=right } + +Rust-based Fuzzing framework for Solana programs to help you ship secure code. + +
+ +- :material-download:{ .lg .middle } __Getting Started__ + + --- + + Install the Trident Fuzz Testing Framework + + [Getting started](./getting-started/getting-started.md) + +- :material-test-tube:{ .lg .middle } __Start Fuzzing__ + + --- + + Focus on security and start fuzzing immediatelly + + [Start Fuzzing](./fuzzing/first-steps/fuzz-test-initialization.md) + +- :octicons-mark-github-24:{ .lg .middle } __Check the GitHub for unreleased features__ + + --- + + Check our GitHub repository to see the unreleased features + + [Trident Repository](https://github.com/Ackee-Blockchain/trident/tree/develop) + +- :material-run-fast:{ .lg .middle } __Trident by Examples__ + + --- + + Try the Fuzzing Examples + + [Trident Examples](./fuzzing/extra/examples.md) + +
+ + +## What is Fuzzing ? + +*"Fuzz testing is an automated technique that provides generated random, invalid, or unexpected input data to your program. This helps discover unknown bugs and vulnerabilities, potentially preventing zero-day exploits."* + + +{{ config.site_name }} equips developers with tools to efficiently develop fuzz tests for Anchor-based programs. It streamlines the fuzz testing process through automation and comprehensive support + +
+ +- __Trident Workflow__ + + --- + + - **Automatically parses Anchor-based programs** to generate necessary implementations for deserializing instruction accounts. + - **Generates templates** for developers to customize according to the specific needs of their fuzz test scenarios. + - **Offers derive macros** to effortlessly implement required traits, reducing manual coding efforts. + - **Includes a bank client** and helper functions for simplified account management during testing. + - **Provides a Command-Line Interface** (CLI) for executing and debugging fuzz tests with ease. -# Features +- __Trident Capabilities__ -- **Automated Test Generation**: Simplifies the testing process by automatically creating templates for fuzz and integration tests for programs written using the Anchor Framework. + --- -- **Dynamic Data Generation**: Increases test coverage with random instruction data and pseudo-random accounts for unpredictable fuzz test scenarios. + - **Execution Order of Instructions**: Test different sequences and their effects on the program to uncover sequence-related vulnerabilities. + - **Instruction Parameters**: Identify how variations in inputs influence program behavior, testing for robustness against a wide range of data. + - **Instruction Accounts**: Explore the impact of different account states on the software's functionality, ensuring comprehensive account testing. + - **Comprehensive Testing**: Conduct thorough and effective fuzz testing by combining any of the above aspects. -- **Custom Instruction Sequences**: Provides the flexibility to design specific sequences of instructions to meet particular testing needs or to focus on particular aspects of program behavior during fuzz testing. -Invariant Checks: Allows for custom invariants checks to spot vulnerabilities and unwanted behaviors. +
diff --git a/documentation/docs/overrides/partials/copyright.html b/documentation/docs/overrides/partials/copyright.html index 1a235f31..627147fc 100644 --- a/documentation/docs/overrides/partials/copyright.html +++ b/documentation/docs/overrides/partials/copyright.html @@ -1,4 +1,4 @@
{{ config.site_name }} is developed by Ackee + href="https://ackee.xyz/" target="_blank">Ackee Blockchain Security
diff --git a/documentation/docs/stylesheets/extra.css b/documentation/docs/stylesheets/extra.css index 7b3c8644..b2659ff0 100644 --- a/documentation/docs/stylesheets/extra.css +++ b/documentation/docs/stylesheets/extra.css @@ -14,3 +14,60 @@ [data-md-color-scheme="default"] span.excalidraw { filter: invert(1) hue-rotate(90deg); } + +.md-typeset h1 { + font-weight: 700; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4 { + color: rgb(102, 101, 244); +} + +.md-typeset h2, +.md-typeset h3 { + font-weight: 600; +} + + + +:root { + --md-admonition-icon--important: url('data:image/svg+xml;charset=utf-8,') +} + +[data-md-color-scheme="default"] .md-typeset .admonition.important, +[data-md-color-scheme="default"] .md-typeset details.important { + border-color: rgb(69, 69, 255); +} + +[data-md-color-scheme="default"] .md-typeset .important>.admonition-title, +[data-md-color-scheme="default"] .md-typeset .important>summary { + background-color: rgb(172, 172, 242); + color: rgb(0, 0, 0); +} + +[data-md-color-scheme="default"] .md-typeset .important>.admonition-title::before, +[data-md-color-scheme="default"] .md-typeset .important>summary::before { + background-color: rgb(95, 95, 252); + -webkit-mask-image: var(--md-admonition-icon--important); + mask-image: var(--md-admonition-icon--important); +} + +[data-md-color-scheme="slate"] .md-typeset .admonition.important, +.md-typeset details.important { + border-color: rgb(69, 69, 255); +} + +[data-md-color-scheme="slate"] .md-typeset .important>.admonition-title, +.md-typeset .important>summary { + background-color: rgb(39, 39, 77); +} + +[data-md-color-scheme="slate"] .md-typeset .important>.admonition-title::before, +.md-typeset .important>summary::before { + background-color: rgb(95, 95, 252); + -webkit-mask-image: var(--md-admonition-icon--important); + mask-image: var(--md-admonition-icon--important); +} diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 5bcd4972..c8227330 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -4,33 +4,37 @@ repo_url: https://github.com/Ackee-Blockchain/trident repo_name: Ackee-Blockchain/trident edit_uri: edit/master/docs site_description: Trident is a Rust-based testing framework providing several convenient developer tools for testing Solana programs written in Anchor. -site_author: Ackee Blockchain +site_author: Ackee Blockchain Security nav: - - Trident: - - index.md - - home/home-installation.md - - Fuzz Tests: - - fuzzing/fuzzing-introduction.md - - Initialization: - - fuzzing/initialization/fuzzing-initialization-fuzz.md - - fuzzing/initialization/fuzzing-initialization-fuzz-add.md - - fuzzing/initialization/fuzzing-initialization-all.md - - fuzzing/fuzzing-lifecycle.md - - How-To write Fuzz Test: - - fuzzing/howto/fuzzing-howto-p0.md - - fuzzing/howto/fuzzing-howto-p1.md - - fuzzing/howto/fuzzing-howto-p2.md - - fuzzing/howto/fuzzing-howto-p3.md - - fuzzing/howto/fuzzing-howto-p4.md - - fuzzing/howto/fuzzing-howto-p5.md - - fuzzing/howto/fuzzing-howto-p6.md - - fuzzing/howto/fuzzing-howto-p7.md - - fuzzing/fuzzing-run-debug.md - - fuzzing/fuzzing-current-limitations.md - - fuzzing/fuzzing-examples.md - - Integration Tests: + - Getting Started: + - getting-started/getting-started.md + - getting-started/docker-image.md + - Fuzz Tests: + - First Steps: + - fuzzing/first-steps/fuzz-test-initialization.md + - fuzzing/first-steps/writing-fuzz-test.md + - Writing Fuzz Test: + - fuzzing/writing-fuzz-test/programs.md + - fuzzing/writing-fuzz-test/accounts.md + - fuzzing/writing-fuzz-test/instruction-data.md + - fuzzing/writing-fuzz-test/instruction-accounts.md + - Writing Fuzz Test (Extra): + - fuzzing/writing-fuzz-test-extra/invariants-checks.md + - fuzzing/writing-fuzz-test-extra/instruction-sequences.md + - fuzzing/writing-fuzz-test-extra/custom-data-types.md + - fuzzing/writing-fuzz-test-extra/arbitrary.md + - fuzzing/writing-fuzz-test-extra/accounts-snapshots.md + - Run and Debug: + - fuzzing/execute/run.md + - fuzzing/execute/statistics.md + - fuzzing/execute/debug.md + - Extra: + - fuzzing/extra/examples.md + - fuzzing/extra/lifecycle.md + - fuzzing/extra/current-limitations.md + - Integration Tests: - integration-tests/poc-introduction.md - Initialization: - integration-tests/initialization/poc-initialization-poc.md @@ -51,8 +55,6 @@ theme: logo: 'images/logo.png' favicon: 'images/favicon.ico' custom_dir: docs/overrides - font: - text: Inter # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/?h=palette+sw#color-palette-toggle palette: # Palette toggle for light mode @@ -70,8 +72,6 @@ theme: features: # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs - navigation.tabs - # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion - - navigation.expand # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button - navigation.top # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages @@ -80,8 +80,10 @@ theme: - content.code.copy # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections - navigation.sections - # may be used + # may be used # - navigation.footer + icon: + repo: fontawesome/brands/github # https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/?h=social#social-links extra: @@ -123,6 +125,13 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true + - admonition + - attr_list + - md_in_html + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.details exclude_docs: | requirements.txt.