From c90e319dd633f1d09295f290bf11e10c87692460 Mon Sep 17 00:00:00 2001 From: Anish Agrawal <32158883+robotrobo@users.noreply.github.com> Date: Mon, 1 Dec 2025 12:00:46 -0500 Subject: [PATCH] fixes redundant pages/adds styling --- docs/CLI/Analysis.md | 56 ---- docs/CLI/Mutation Testing.md | 225 ------------- docs/CLI/Unit Testing.md | 129 -------- docs/CLI/index.md | 283 ++++++++++++---- docs/ConfigOptions.md | 25 +- docs/Github Actions/index.md | 302 ++++++++++++++++++ docs/Github Actions/integrated-security.md | 114 ------- .../Github Actions/mutation-test-generator.md | 89 ------ docs/Github Actions/unit-test-generator.md | 119 ------- docs/Installation.md | 19 +- docs/Quickstart.md | 151 +++++++++ docs/Tools/Mutation Testing.md | 230 +++++++++++++ docs/Tools/Static Analysis.md | 114 +++++++ docs/Tools/Unit Testing.md | 157 +++++++++ docs/index.md | 117 ++++++- docs/stylesheets/extra.css | 173 ++++++++++ mkdocs.yml | 68 +++- overrides/partials/footer.html | 18 ++ 18 files changed, 1545 insertions(+), 844 deletions(-) delete mode 100644 docs/CLI/Analysis.md delete mode 100644 docs/CLI/Mutation Testing.md delete mode 100644 docs/CLI/Unit Testing.md create mode 100644 docs/Github Actions/index.md delete mode 100644 docs/Github Actions/integrated-security.md delete mode 100644 docs/Github Actions/mutation-test-generator.md delete mode 100644 docs/Github Actions/unit-test-generator.md create mode 100644 docs/Quickstart.md create mode 100644 docs/Tools/Mutation Testing.md create mode 100644 docs/Tools/Static Analysis.md create mode 100644 docs/Tools/Unit Testing.md create mode 100644 docs/stylesheets/extra.css diff --git a/docs/CLI/Analysis.md b/docs/CLI/Analysis.md deleted file mode 100644 index 5a674158..00000000 --- a/docs/CLI/Analysis.md +++ /dev/null @@ -1,56 +0,0 @@ -# Analysis - -This section covers how to perform static analysis using the Olympix CLI and explains the various reporting strategies available. - ---- - -## Finding Vulnerabilities via CLI - -The Olympix CLI allows you to scan your Solidity projects for vulnerabilities quickly and effectively. To get started, navigate to the root directory of your project and run the analysis command. This will inspect your code for known vulnerability patterns. - -!!! tip "Quick Start" - Run the following command in your terminal from the project root: - - ```bash - olympix analyze - ``` - -Depending on your project’s structure, the CLI will automatically look for all Solidity files in your root directory. You can also explicitly specify additional directories using the `-p` or `--path` option. - -The **`analyze`** command is designed to help you: -- **Identify vulnerabilities:** The tool checks for a wide range of issues such as uninitialized state variables, default visibility problems, and other common pitfalls. -- **Customize your scan:** Use options to narrow down the directories, exclude certain vulnerability checks, or alter the output format. - -These features ensure that you can integrate the analyzer into your development workflow or CI/CD pipeline, receiving feedback directly in your terminal or exported to files for further inspection :contentReference[oaicite:0]{index=0}. - ---- - -## Reporting Strategies via CLI - -Once the analysis is complete, Olympix offers several ways to view and export the results. The CLI supports four output formats: - -### Option 1: Tree -- **Description:** The results are displayed directly in your terminal in a structured tree format. -- **When to Use:** Ideal for a quick overview during development. -- **Default:** This is the default output format if no other option is specified. - -### Option 2: JSON -- **Description:** Outputs the results as JSON data. -- **Usage:** Useful when integrating the results into automated tools or further processing. -- **Additional Option:** Use the `-o` or `--output-path` option to write the JSON output to a file. - -### Option 3: SARIF -- **Description:** Outputs the analysis results in SARIF (Static Analysis Results Interchange Format). -- **When to Use:** Particularly beneficial if you wish to integrate with GitHub’s Code Scanning tools or other security platforms. -- **Additional Option:** Use the `-o` or `--output-path` option to specify the output file location. - -### Option 4: Email -- **Description:** Sends the analysis results in a tabular format directly to your registered email address. -- **When to Use:** Great for receiving detailed reports without needing to navigate the terminal output. - -!!! info "Choosing a Reporting Strategy" - Your choice of reporting format depends on your workflow. For a quick local review, the tree format works well. If you need to integrate the results with other tools or share them with a team, JSON, SARIF, or email options might be more appropriate. - -These reporting strategies are designed to cater to both manual review and automated processing, giving you flexibility in how you manage and respond to vulnerability findings. - ---- \ No newline at end of file diff --git a/docs/CLI/Mutation Testing.md b/docs/CLI/Mutation Testing.md deleted file mode 100644 index ae171a1d..00000000 --- a/docs/CLI/Mutation Testing.md +++ /dev/null @@ -1,225 +0,0 @@ -# Mutation Test Generation - -## Overview - -Mutation testing is a powerful technique for evaluating the effectiveness of your test suite by introducing small, systematic modifications (mutations) to your source code and verifying if your tests can detect these changes. While code coverage tells you what lines of code are executed by your tests, mutation testing tells you how effective your tests are at catching actual bugs. - -### Why Mutation Testing Matters - -Traditional metrics like code coverage can provide a false sense of security. Having 100% coverage doesn't necessarily mean your tests are meaningful—they might assert the wrong things or have weak assertions. Mutation testing provides a more meaningful metric by: - -1. Measuring test suite effectiveness over time -2. Identifying areas where tests might be insufficient -3. Forcing developers to write more thorough assertions -4. Discovering edge cases that weren't previously considered - -### Security Implications - -In blockchain and smart contract development, mutation testing is particularly crucial for security. Many historical smart contract hacks occurred due to seemingly minor changes in business logic that weren't caught by existing test suites. Our mutation operators are specifically derived from real-world smart contract exploits—each mutation pattern in our tool corresponds to actual changes that led to significant security breaches in production contracts. - ---- - -## Installation & Requirements - -The mutation test generator is designed to be dependency-free and works with any Forge project. The only prerequisite is having a Forge project with unit tests. - -:white_check_mark: No external dependencies -:white_check_mark: Works with standard Forge unit tests out of the box. - ---- - -## CLI Usage - -```none -generate-mutation-tests [-w ] [-p ] [-t ] - -Options - -w, --workspace-path: Root project directory path (default: current directory) - -p, --path: Solidity file path to mutate (can be specified multiple times) - -t, --timeout: Timeout in seconds for each mutant test run (default: 300s, range: 10-500s) - -env, --include-dot-env: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often need for fork testing). To specify a custom env file, include the --env-file argument. - --env-file: Defines the path of the file containing the environment variables. Make sure to follow foundry's .env format guidelines. Doesn't do anything if '--include-dot-env' is not set. - -ext, --extension: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: --extra-extension .json --extra-extension .txt. By default, only .sol/.t.sol and/or foundry.toml files are uploaded. - Tip: The timeout option is crucial as some mutations can cause infinite loops in test execution. Set this to slightly higher than your normal test suite execution time. -``` - -!!! tip "Including env variables" - We provide the ability to pass environment variables with your solidity files. If you would like to provide `RPC URLs`, `API keys`, `private keys`, etc. You can do so by using the `-env` flag which will read these parameters from your `.env` file. You can also specify a custom filepath for your `env` file using the `--env-file` flag. - Refer here for format guidelines: `https://book.getfoundry.sh/cheatcodes/env-string`. - - - Note: If you do require passing `env variables` for your `forge` run, this is the recommended way to do it. We encrypt all communication of this file with an extra layer of RSA on top of the regular encryption. - -## Mutation Operators - -Our mutation operators are directly inspired by real-world smart contract exploits. Each operator represents a pattern of change that has historically led to security incidents. - -Below is a comprehensive list of all currently supported operators. -
-### Arithmetic Operator Mutations (1) - - - -```solidity -// Original -amount + tax -// Mutated -amount - tax -``` - - -### Comparison Operator Mutations (2) -```solidity -// Original -amount > 0 -// Mutated -amount < 0 -``` -### Logical Operator Mutations (AND ↔ OR) (3) -```solidity -// Original -require(isEnabled && amount > 100) -// Mutated -require(isEnabled || amount > 100) -``` - -### Condition Negation Mutations (4) -```solidity -// Original -if (taxEnabled) -// Mutated -if (!taxEnabled) -``` -### Ternary Conditional Mutations (5) -```solidity -// Original -amount < 100 ? amount : 100 - tax -// Mutated -amount < 100 ? 100 - tax : amount -``` -### Function Call Mutations (delegatecall → call) (6) -```solidity -// Original -(address).delegatecall(data) -// Mutated -(address).call(data) -``` -### - -### Hex Number Literal Mutations (7) -```solidity -// Original -0xabcd1234 -// Mutated 1 (→ 0) -0x0 -// Mutated 2 (→ Another Random Hex) -0xdef12345 -``` -### Remove emit Statement (8) -```solidity -// Original -emit Transfer(msg.sender, recipient, amount); -// Mutated -// (empty string) -``` -### - -### Remove delete Operator (9) -```solidity -// Original -delete myStruct; -// Mutated -// (empty string) -``` -### - -### Storage Location Mutations (10) -```solidity -// Original -uint[] storage x; -// Mutated -uint[] memory x; -``` - -### Variable Assignment Operator Replacement (11) -```solidity -// Original -balances[msg.sender] += amount; -// Mutated -balances[msg.sender] -= amount; -``` -### State Variable Initialization Changes (12) -```solidity -// Original -bool public taxEnabled = true; -// Mutated -bool public taxEnabled = false; - -// Original -uint public maxSupply = 1000; -// Mutated -uint public maxSupply = 1001; - -// Original -string public greeting = "Hello"; -// Mutated -string public greeting = "Mutation text" -``` -### - -### Modifier Removal Mutations (13) -```solidity -// Original -function toggleTax() public onlyOwner { - // ... -} - -// Mutated -function toggleTax() public { - // ... -} -``` -### - -### Address swap Mutations (14) -```solidity -// Original -address(0xaaaaaaaaaaaaaaaaaaaaa).call(); -// Mutated -address(0xbbbbbbbbbbbbbbbbbbbbb).call(); // where 0xbbbbbbbbbbbbbbbbbbbbb is another address in the current function -``` -### -
-1. Arithmetic Operator Mutations: - - `+` ↔ `-` - - `%` ↔ `/` - - `-` ↔ `+` - - `/` ↔ `%` -2. Comparison Operator Mutations: Inverts comparison operators: - - `==` ↔ `!=` - - `> `↔ `<` - - `>=` ↔ `<` - - `<=` ↔ `>` -3. Logical Operator Mutations (AND ↔ OR): Swaps logical operators: - - `&&` ↔ `||` - - `||` ↔ `&&` -4. Condition Negation Mutations: Negates a condition by adding or removing the ! operator. -5. Ternary Conditional Mutations: Swaps the `true` and `false` branches in a ternary expression `(?:)`. -6. Function Call Mutations (`delegatecall` → `call`): Replaces `delegatecall` with `call`. -7. Hex Number Literal Mutations: - - Replaces any hex literal with `0x0`. - - Replaces a hex literal with a different randomly chosen hex literal found in the same function. -8. Remove emit Statement: Removes the `emit` statement. -9. Remove delete Operator: Removes the `delete` statement. -10. Storage Location Mutations: Swaps the variable declaration storage location: - - `storage` ↔ `memory` -11. Variable Assignment Operator Replacement: Swaps `+=` with `-=` (and vice versa). -12. State Variable Initialization Changes: Mutates state variable initial values based on type. -13. Modifier Removal Mutations: Removes function modifiers. -14. Address Swap Mutations: Swaps addresses in function calls. - -## Security Foundation - -Each mutation operator in this tool was carefully selected based on extensive analysis of historical smart contract exploits. By studying security incidents and identifying the precise commits that introduced vulnerabilities, we’ve created a comprehensive set of mutations that represent real-world attack vectors. - -This approach ensures that your test suite is validated against realistic threat models rather than purely theoretical vulnerabilities. diff --git a/docs/CLI/Unit Testing.md b/docs/CLI/Unit Testing.md deleted file mode 100644 index 12db0210..00000000 --- a/docs/CLI/Unit Testing.md +++ /dev/null @@ -1,129 +0,0 @@ - -# Unit Test Generation - -Welcome to the **Olympix Unit Test Generator** documentation! This guide will walk you through how to automatically generate unit tests (and even mutation tests) for your Solidity smart contracts using the Olympix CLI. Follow these steps to set up your environment and get started. - ---- - -## Overview - -The Olympix Unit Test Generator works in tandem with the [Foundry](https://book.getfoundry.sh/) toolchain to create: - -- **Unit tests** for your contracts -- **Mutation tests** to assess the quality of your existing tests - -> 💡 **Tip:** Running the test generator consumes Olympix credits. The credit usage details will be included in the email with your test results. - ---- - -## Prerequisites - -Before running the generator, ensure you have completed the following: - -!!! info "Forge Configuration" - - Verify that your Forge remappings are correctly set up for your project. - - [Learn more about Forge remappings](https://book.getfoundry.sh/projects/dependencies#remapping-dependencies). - ---- - -## Step-by-Step Guide - -### 1. Ensure Your Forge Remappings Are Accurate - -Your project must compile successfully with Forge. Double-check your remappings in the project configuration to avoid any compilation issues. - -### 2. Create `OlympixUnitTest.sol` - -A special file named **`OlympixUnitTest.sol`** is required in your Foundry test directory. This file contains the base contract for your unit tests. - -!!! note "Action Required" - Copy and paste the following content into `OlympixUnitTest.sol` to set up the foundation for your tests. - ```solidity - // SPDX-License-Identifier: MIT - pragma solidity ^0.8.0; - abstract contract OlympixUnitTest { - constructor(string memory _name) {} - } - - ``` -### 3. Create Your Unit Test Skeleton - -For each contract you wish to test, create a unit test file that adheres to the Forge naming convention: -**`.t.sol`** - -Your test skeleton should: -- Import the contract you intend to test -- Import the `OlympixUnitTest` contract from `OlympixUnitTest.sol` -- Define any required state variables -- Include a `setUp()` function to initialize the testing environment. -- Any helper functions/example tests that you want the test generator to build off of. -!!! note - Good tests require a good setup function, which correctly initializes all relevant smart contracts. - -Example unit test skeleton -```solidity -// SPDX-License-Identifier: MIT -pragma solidity ^0.8.0; - -import "../contracts/MyContract.sol"; // Adjust the path as needed -import "./OlympixUnitTest.sol"; - -contract MyContractTest is OlympixUnitTest("MyContract") { - MyContract public myContract; - - // setUp() is run before each test - function setUp() public { - myContract = new MyContract(); - } - - // Example test function - function testExample() public { - // Example assertion using a helper from OlympixUnitTest - uint expected = 42; - uint actual = myContract.someFunction(); - assertEqual(expected, actual); - } -} - -``` - -For a detailed example, check out this [YouTube tutorial](https://youtu.be/x7Apoq2PgT0). - -### 4. Run the Unit Test Generator - -Navigate to the root folder of your Solidity project and execute the following command in your terminal: - -```bash -olympix generate-unit-tests -w . -``` - -This command launches an interactive mode where you can select the contracts for which unit tests should be generated. After a brief processing period, the results will be emailed to your registered address. - -!!! info "What to Expect" - - **Email Notification:** You will receive an email containing all the generated unit tests along with statistics. - - **Credit Consumption:** Remember, using this feature consumes Olympix credits. - -### 5. Review and Utilize the Results -Once you receive the email:
- -- **Examine** the generated unit tests.
-- **Integrate** them into your project.
-- **Iterate** on the tests as needed to improve coverage. - ---- - -!!! tip "Including env variables" - We provide the ability to pass environment variables with your solidity files. If you would like to provide `RPC URLs`, `API keys`, `private keys`, etc. You can do so by using the `-env` flag which will read these parameters from your `.env` file. You can also specify a custom filepath for your `env` file using the `--env-file` flag. - Refer here for format guidelines: `https://book.getfoundry.sh/cheatcodes/env-string`. - - - Note: If you do require passing `env variables` for your `forge` run, this is the recommended way to do it. We encrypt all communication of this file with an extra layer of RSA on top of the regular encryption. - - -## Need Help? - -If you encounter any issues or have questions, feel free to reach out: - -**Email:** [contact@olympix.ai](mailto:contact@olympix.ai) - -Happy testing! 🎉 \ No newline at end of file diff --git a/docs/CLI/index.md b/docs/CLI/index.md index 8efc6e63..9da38f7e 100644 --- a/docs/CLI/index.md +++ b/docs/CLI/index.md @@ -1,120 +1,265 @@ -# Getting Started +# CLI Reference -Welcome to the Olympix CLI usage guide! This guide will help you quickly get started with the command-line interface for the Olympix Static Analyzer and Test Generator. +The Olympix CLI provides command-line access to all Olympix tools. This page documents all available commands and their options. --- -## CLI Commands Overview +## Installation -When you run the Olympix CLI, you have access to several commands: +See [Installation Guide](../Installation.md) for download and authentication instructions. -- **`analyze`**: Perform code analysis -- **`generate-unit-tests`**: Generate unit tests -- **`generate-mutation-tests`**: Generate mutation tests -- **`login`**: Request access and log in to your account -- **`show-vulnerabilities`**: Show the vulnerability types that the analyzer aims to find -- **`version`**: Show CLI version +--- + +## Commands Overview + +| Command | Description | +|---------|-------------| +| `analyze` | Scan contracts for vulnerabilities | +| `generate-unit-tests` | Generate unit tests | +| `generate-mutation-tests` | Run mutation testing | +| `login` | Authenticate with Olympix | +| `show-vulnerabilities` | List all vulnerability detectors | +| `version` | Display CLI version | --- -## Analysis Options +## analyze + +Performs static analysis on your Solidity contracts. See [Static Analysis](../Tools/Static%20Analysis.md) for concepts. + +### Usage + +```bash +olympix analyze [options] +``` + +### Options + +| Option | Description | Default | +|--------|-------------|---------| +| `-w, --workspace-path ` | Root project directory | Current directory | +| `-p, --path ` | Directory to analyze (repeatable) | `contracts/` and `src/` if present | +| `-f, --output-format ` | Output format: `tree`, `json`, `sarif`, `email` | `tree` | +| `-o, --output-path ` | Output directory (for `json`/`sarif`) | Terminal output | +| `--no-` | Ignore specific detector (repeatable) | None | -When using the `analyze` command, you can customize the analysis with the following options: +### Examples -- **`-w | --workspace-path`** - Defines the root project directory path. This helps in providing more accurate vulnerability analysis. - *Default:* current directory +```bash +# Basic scan with tree output +olympix analyze + +# Scan specific directory +olympix analyze -p src/core -- **`-p | --path`** - Defines the Solidity project directory path to be analyzed. Can be used multiple times. - *Default:* `'contracts'` and `'src'` directories if they exist, otherwise the workspace directory +# Output as SARIF for GitHub integration +olympix analyze -f sarif -o ./reports -- **`-f | --output-format`** - Defines the result output format. Supported formats: `tree`, `json`, `sarif`, `email`. - *Default:* `tree` +# Output as JSON +olympix analyze -f json -o ./reports -- **`-o | --output-path`** - Defines the result output directory path (enabled only for `json` and `sarif` formats). - *Default:* Results are shown directly in the terminal +# Ignore specific vulnerabilities +olympix analyze --no-unbounded-pragma --no-default-visibility -- **`--no-`** - Defines the vulnerabilities to be ignored. Can be used multiple times. - *Default:* Ignores nothing +# Multiple directories +olympix analyze -p src/ -p contracts/ +``` --- -## Unit Tests Generation Options +## generate-unit-tests + +Generates unit tests for your smart contracts. See [Unit Testing](../Tools/Unit%20Testing.md) for setup requirements. + +### Usage -When generating unit tests, you can use these options: +```bash +olympix generate-unit-tests [options] +``` -- **`-w | --workspace-path`** Defines the root project directory path. - *Default:* current directory +### Options -- **`-env | --include-dot-env`**: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often need for fork testing). To specify a custom env file, include the --env-file argument. +| Option | Description | Default | +|--------|-------------|---------| +| `-w, --workspace-path ` | Root project directory | Current directory | +| `-env, --include-dot-env` | Include `.env` file with request | Disabled | +| `--env-file ` | Custom env file path (requires `-env`) | `.env` | +| `-ext, --extension ` | Additional file extensions (repeatable) | `.sol`, `.t.sol`, `foundry.toml` | +| `-ca, --confirm-all` | Skip interactive prompts | Disabled | -- **`--env-file`**: Defines the path of the file containing the environment variables. Make sure to follow foundry's .env format guidelines. Doesn't do anything if '--include-dot-env' is not set. - *Default*: `.env` +### Examples -- **`-ext, --extension`**: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: `--extra-extension .json --extra-extension .txt`. By default, only `.sol/.t.sol` and/or `foundry.toml` files are uploaded. +```bash +# Interactive mode +olympix generate-unit-tests -w . -- **`-ca | --confirm-all`** - Confirm as 'yes' for all interactive questions. +# Non-interactive with env variables +olympix generate-unit-tests -w . -ca -env + +# Include additional file types +olympix generate-unit-tests -w . -ext .json -ext .txt + +# Custom env file +olympix generate-unit-tests -w . -env --env-file .env.local +``` + +### Output + +Results are emailed to your registered address, including: + +- Generated test files +- Coverage statistics +- Credit consumption --- -## Mutation Tests Generation Options +## generate-mutation-tests + +Runs mutation testing against your existing test suite. See [Mutation Testing](../Tools/Mutation%20Testing.md) for concepts. -When generating mutation tests, you have the following options: +### Usage -- **`-w | --workspace-path`** - Defines the root project directory path. - *Default:* current directory +```bash +olympix generate-mutation-tests [options] +``` + +### Options -- **`-p | --path`** - Defines the Solidity file path to run the mutation tests. Can be used multiple times. +| Option | Description | Default | +|--------|-------------|---------| +| `-w, --workspace-path ` | Root project directory | Current directory | +| `-p, --path ` | Solidity file to mutate (repeatable) | Required | +| `-t, --timeout ` | Timeout per mutant (10-500) | 300 | +| `-env, --include-dot-env` | Include `.env` file with request | Disabled | +| `--env-file ` | Custom env file path (requires `-env`) | `.env` | +| `-ext, --extension ` | Additional file extensions (repeatable) | `.sol`, `.t.sol`, `foundry.toml` | -- **`-t | --timeout`** - Sets a timeout (in seconds) for each mutant. This prevents infinite loops or hangs. - *Default:* 300 seconds - *Allowed Range:* 10 - 500 seconds +### Examples + +```bash +# Single contract +olympix generate-mutation-tests -p src/Vault.sol -- **`-env | --include-dot-env`**: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often need for fork testing). To specify a custom env file, include the --env-file argument. +# Multiple contracts +olympix generate-mutation-tests -p src/Vault.sol -p src/Token.sol + +# Custom timeout (for complex tests) +olympix generate-mutation-tests -p src/Vault.sol -t 500 + +# With environment variables for fork testing +olympix generate-mutation-tests -p src/Vault.sol -env +``` + +### Output + +Results are emailed to your registered address, including: + +- Mutation score (killed / total) +- List of surviving mutants +- Details for each mutation -- **`--env-file`**: Defines the path of the file containing the environment variables. Make sure to follow foundry's .env format guidelines. Doesn't do anything if '--include-dot-env' is not set. - *Default*: `.env` -- **`-ext, --extension`**: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: `--extra-extension .json --extra-extension .txt`. By default, only `.sol/.t.sol` and/or `foundry.toml` files are uploaded. --- -## Usage Examples +## login + +Authenticates with Olympix and retrieves your API token. + +### Usage ```bash -# Analyze command -analyze [-w | --workspace-path ] [-p | --path ] [-f | --output-format ] [-o | --output-path ] [--no-] +olympix login -e +``` -# Generate unit tests -generate-unit-tests [-w | --workspace-path ] [-ca | --confirm-all] [-env | --include-dot-env] [--env-file ] [-ext | --extension .] +### Options -# Generate mutation tests -generate-mutation-tests [-w | --workspace-path ] [-p | --path ] [-t | --t ] [-env | --include-dot-env] [--env-file ] [-ext | --extension .] +| Option | Description | +|--------|-------------| +| `-e, --email ` | Your registered email address | -# Login -login [-e | --email ] +### Process + +1. Run the login command with your email +2. Check your email for a one-time code +3. Enter the code when prompted +4. Your API token is displayed and saved to `~/.opix/config.json` + +!!! tip "Save Your Token" + The displayed API token is required for GitHub Actions integration. Copy it to a secure location. + +--- + +## show-vulnerabilities + +Lists all vulnerability detectors supported by the analyzer. + +### Usage + +```bash +olympix show-vulnerabilities ``` +This displays the detector slug (used with `--no-`) and description for each vulnerability type. + --- -## Helpful Links +## version + +Displays the installed CLI version. + +### Usage + +```bash +olympix version +``` + +--- + +## Common Options + +These options apply to multiple commands: -- **[Installation](../Installation.md)** - Get started by installing the CLI binaries and the VSCode extension. +### Workspace Path (`-w, --workspace-path`) + +Specifies the root project directory. This provides context for the analyzer to resolve imports and dependencies. + +```bash +olympix analyze -w /path/to/project +``` + +### Path (`-p, --path`) + +Specifies which directories or files to process. Can be used multiple times. + +```bash +olympix analyze -p src/ -p contracts/lib/ +``` + +### Environment Variables (`-env, --include-dot-env`) + +Includes your `.env` file with the request. Required for fork testing that needs RPC URLs or API keys. + +!!! warning "Security" + Environment variable data is encrypted with RSA before transmission. Only use this flag when necessary for fork testing. + +### Extension (`-ext, --extension`) + +Includes additional file types beyond the defaults (`.sol`, `.t.sol`, `foundry.toml`). + +```bash +olympix generate-unit-tests -ext .json -ext .txt +``` + +--- -- **[Unit Test Generation](./Unit%20Testing.md)** - Learn how to generate unit tests for your smart contracts using the Olympix Unit Test Generator. +## Exit Codes -- **[Mutation Tests Generation](./Mutation%20Testing.md)** - Find out how to generate mutation tests to assess your unit test quality. +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | Error (authentication, network, etc.) | --- -With these commands and options at your disposal, you're well-equipped to leverage Olympix for efficient static analysis and robust test generation. If you have any questions, our support team is ready to help at [contact@olympix.ai](mailto:contact@olympix.ai). +## Configuration File +The CLI stores authentication data in `~/.opix/config.json`. See [Config Options](../ConfigOptions.md) for project-level configuration. diff --git a/docs/ConfigOptions.md b/docs/ConfigOptions.md index fe1b20d1..4602715c 100644 --- a/docs/ConfigOptions.md +++ b/docs/ConfigOptions.md @@ -47,9 +47,8 @@ The `olympix-config.json` file follows the structure below. All paths should be * **`TrustedContracts`**: A dictionary used to mark entire contracts as trusted for a specific detector. This is useful when a contract's design is known to be safe against a particular vulnerability (e.g., a contract that is non-reentrant by design). ## Example -Here is an example `olympix-config.json` file demonstrating how to use the different options: -```json +```json title="olympix-config.json" { "IgnoredVulnerabilities": { "reentrancy" : { @@ -78,19 +77,25 @@ Here is an example `olympix-config.json` file demonstrating how to use the diffe - The settings apply **across all Olympix tools**. ## Usage + To use these features, ensure that: -1. The `olympix-config.json` -2. The specified detector slugs, filenames, and line numbers match the vulnerability reports. +1. Your configuration file is placed at the **workspace root** directory. +2. The specified detector slugs, filenames, and line numbers match the vulnerability reports exactly. +3. All file paths are relative to the project root. + +## Supported File Names -## Note +The tools will recognize any of these filenames at your project's root: -The original `.olympix-ignore.json` file is still supported for ignoring vulnerabilities and paths. +| Filename | Description | +|----------|-------------| +| `olympix-config.json` | Recommended config file | +| `.olympix-config.json` | Hidden config file variant | +| `olympix-ignore.json` | Legacy ignore file | +| `.olympix-ignore.json` | Hidden legacy ignore file | -If both files are present, their configurations will be merged. The tools will recognize any of these filenames at your project's root: -* `olympix-config.json` -* `.olympix-config.json` -* `.olympix-ignore.json` +If multiple files are present, their configurations will be merged. --- diff --git a/docs/Github Actions/index.md b/docs/Github Actions/index.md new file mode 100644 index 00000000..2422eb4a --- /dev/null +++ b/docs/Github Actions/index.md @@ -0,0 +1,302 @@ +# GitHub Actions + +Olympix provides GitHub Actions for integrating security analysis and test generation into your CI/CD workflows. This page covers setup and configuration for all available actions. + +--- + +## Available Actions + +| Action | Purpose | Marketplace | +|--------|---------|-------------| +| `olympix/integrated-security` | Static analysis with SARIF output | [View](https://github.com/marketplace/actions/olympix-integrated-security) | +| `olympix/test-generator` | Unit test generation | [View](https://github.com/marketplace/actions/olympix-unit-test-generator) | +| `olympix/mutation-test-generator` | Mutation testing | [View](https://github.com/marketplace/actions/olympix-mutation-test-generator) | + +--- + +## Prerequisites + +### API Token + +All actions require an Olympix API token: + +1. Run `olympix login -e your_email@domain.com` locally +2. Copy the displayed API token +3. Add it as a repository secret named `OLYMPIX_API_TOKEN` + +```yaml +env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} +``` + +--- + +## Static Analysis + +The `olympix/integrated-security` action scans your Solidity code for vulnerabilities. See [Static Analysis](../Tools/Static%20Analysis.md) for concepts. + +### Basic Usage + +```yaml title=".github/workflows/security.yml" +name: Security Scan +on: push + +jobs: + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run Olympix Security Scan + uses: olympix/integrated-security@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + + - name: Upload SARIF to GitHub + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: olympix.sarif +``` + +### With Custom Options + +```yaml +- name: Run Olympix Security Scan + uses: olympix/integrated-security@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + with: + args: -f json -p src/ --no-unbounded-pragma +``` + +### Options + +Pass CLI options via the `args` input: + +| Option | Description | +|--------|-------------| +| `-p, --path ` | Directory to analyze | +| `-f, --output-format ` | `tree`, `json`, `sarif` (default), `email` | +| `-o, --output-path ` | Output directory | +| `--no-` | Ignore specific detector | + +### Output Files + +| Format | Filename | +|--------|----------| +| SARIF | `olympix.sarif` | +| JSON | `olympix.json` | + +--- + +## Unit Test Generation + +The `olympix/test-generator` action generates unit tests for your contracts. See [Unit Testing](../Tools/Unit%20Testing.md) for setup requirements. + +### Basic Usage + +```yaml title=".github/workflows/unit-tests.yml" +name: Generate Tests +on: + push: + branches: [main] + +jobs: + generate-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + + - name: Install dependencies + run: forge install + + - name: Generate Unit Tests + uses: olympix/test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} +``` + +### Auto-Commit Generated Tests + +To automatically commit generated tests to your repository: + +1. Create a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +2. Add it as a secret named `OLYMPIX_GITHUB_TOKEN` +3. Create a branch named `opix-unit-test` + +```yaml +- name: Generate Unit Tests + uses: olympix/test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + OLYMPIX_GITHUB_ACCESS_TOKEN: ${{ secrets.OLYMPIX_GITHUB_TOKEN }} +``` + +### Trigger on PR Merge + +```yaml +name: Generate Tests on Merge +on: + pull_request: + types: [closed] + +jobs: + generate-tests: + if: github.event.pull_request.merged == true + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + # ... rest of workflow +``` + +### Output + +Results are emailed to the address associated with your API token. + +--- + +## Mutation Test Generation + +The `olympix/mutation-test-generator` action runs mutation testing against your test suite. See [Mutation Testing](../Tools/Mutation%20Testing.md) for concepts. + +### Basic Usage + +```yaml title=".github/workflows/mutation-tests.yml" +name: Mutation Testing +on: push + +jobs: + mutation-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + + - name: Install dependencies + run: forge install + + - name: Run Mutation Tests + uses: olympix/mutation-test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + with: + args: -p src/Vault.sol -p src/Token.sol +``` + +### Options + +| Option | Description | +|--------|-------------| +| `-p, --path ` | Solidity file to mutate (required, repeatable, max 5) | +| `-t, --timeout ` | Timeout per mutant (10-500, default 300) | + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `OLYMPIX_API_TOKEN` | Required. Your API token | +| `OLYMPIX_FAIL_MUTATION_GHA_THRESHOLD` | Optional. Fail if mutation score below this percentage | +| `OLYMPIX_GITHUB_COMMIT_HEAD_SHA` | Optional. Commit SHA for check run annotation | + +### GitHub Check Runs + +To receive mutation test results as GitHub Check Runs: + +1. Install the [Olympix Notifier GitHub App](https://github.com/apps/olympix-notifier) +2. Grant it permission to create check runs +3. Add the commit SHA to your workflow: + +```yaml +- name: Run Mutation Tests + uses: olympix/mutation-test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + OLYMPIX_GITHUB_COMMIT_HEAD_SHA: ${{ github.sha }} + OLYMPIX_FAIL_MUTATION_GHA_THRESHOLD: 30 + with: + args: -p src/Vault.sol +``` + +### Trigger on Commit Message + +```yaml +jobs: + mutation-tests: + if: contains(github.event.head_commit.message, 'OPIX-GEN-MUTATION-TESTS') + # ... +``` + +### Output + +Results are emailed to your registered address and optionally reported via GitHub Check Runs. + +--- + +## Complete Workflow Example + +This workflow runs security scanning on every push and generates tests on the main branch: + +```yaml title=".github/workflows/olympix-ci.yml" +name: Olympix CI +on: + push: + branches: [main, develop] + pull_request: + +jobs: + security-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Security Scan + uses: olympix/integrated-security@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + + - name: Upload SARIF + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: olympix.sarif + + generate-tests: + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: foundry-rs/foundry-toolchain@v1 + + - run: forge install + + - name: Generate Tests + uses: olympix/test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} +``` + +--- + +## Troubleshooting + +**"Invalid API token"** +: Verify your `OLYMPIX_API_TOKEN` secret is set correctly. + +**"No contracts found"** +: Ensure your contracts are in `contracts/` or `src/`, or specify the path with `-p`. + +**Workflow timeout** +: For mutation testing, set an appropriate `-t` timeout value. + +--- + +## Support + +For support, contact [contact@olympix.ai](mailto:contact@olympix.ai). diff --git a/docs/Github Actions/integrated-security.md b/docs/Github Actions/integrated-security.md deleted file mode 100644 index 77d6c2cb..00000000 --- a/docs/Github Actions/integrated-security.md +++ /dev/null @@ -1,114 +0,0 @@ -# Integrated Security - -The Olympix Integrated Security action enables you to incorporate Olympix's vulnerability analysis directly into your GitHub workflows. This powerful integration allows you to scan your Solidity code for vulnerabilities as part of your CI process, with results reported in various formats to fit your needs. -You can access this action from the [Github Marketplace](https://github.com/marketplace/actions/olympix-integrated-security) or visit the [GitHub repository](https://github.com/olympix/integrated-security). - ---- - -## Overview - -The Olympix Integrated Security action performs code analysis on Solidity projects, delivering detailed results in formats such as SARIF (default), JSON, and more. With this integration, you can: - -- **Quickly scan for vulnerabilities** in your smart contracts. -- **Customize scanning rules** to match your project's requirements. -- **Automatically upload results** to GitHub Code Scanning for easy review and tracking. - ---- - -## Features - -- **Code Scanning:** Automatically scan your GitHub repository for vulnerabilities during each workflow run. -- **Detailed Results:** View in-depth analysis reports directly in your GitHub workflow console or through GitHub's Code Scanning tool. -- **Customizable Rules:** Tailor the scanning rules using the provided inputs to exclude or focus on specific vulnerability types. - ---- - -## Getting Started - -1. **Set Up Repository Secret:** - - Add a GitHub repository secret named `OLYMPIX_API_TOKEN` with your Olympix API token as the value. - -2. **Configure the GitHub Action:** - - Add the `olympix/integrated-security` action to your workflow file. - -3. **(Optional) Customize Scanning Rules:** - - Use the `args` input to pass custom options for your vulnerability scan. - ---- - -## Usage Examples - -### Example 1: Default SARIF Output - -This workflow example uses the default settings to run the analysis and upload the SARIF results to GitHub Code Scanning. - -```yaml -name: Integrated Security Workflow -on: push -jobs: - security: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Run Olympix Integrated Security - uses: olympix/integrated-security@main - env: - OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} - - name: Upload result to GitHub Code Scanning - uses: github/codeql-action/upload-sarif@v3 - with: - sarif_file: olympix.sarif -``` - -### Example 2: JSON Output with Custom Vulnerability Exclusions - -In this example, the action is configured to output results in JSON format, and it excludes vulnerabilities related to uninitialized state variables and default visibility. - -```yaml -name: Integrated Security Workflow -on: push -jobs: - security: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Olympix Integrated Security - uses: olympix/integrated-security@main - env: - OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} - with: - args: -f json --no-uninitialized-state-variable --no-default-visibility -``` - - ---- - -## Analysis Options - -When running the analysis via the integrated action, you can customize the scan using the following options: - -- **`-w | --workspace-path`** - Defines the root project directory path. This provides the project context for more accurate analysis. - *Default:* current directory - -- **`-p | --path`** - Specifies the Solidity project directory path to analyze. Can be repeated for multiple directories. - *Default:* `contracts` and `src` directories if present, else the workspace directory - -- **`-f | --output-format`** - Sets the output format. Supported formats are `tree`, `json`, `sarif`, and `email`. - *Default:* `tree` (or `sarif` for GitHub Code Scanning) - -- **`-o | --output-path`** - Defines the output directory path for the results (applicable for `json` and `sarif` formats). - *Default:* Displays results in the terminal - -- **`--no-`** - Specifies vulnerabilities to ignore. Can be used multiple times to exclude each type. - *Default:* No vulnerabilities are ignored - ---- - -## Support Contact - -If you have any questions, need feedback, or require further assistance, feel free to reach out at [contact@olympix.ai](mailto:contact@olympix.ai). diff --git a/docs/Github Actions/mutation-test-generator.md b/docs/Github Actions/mutation-test-generator.md deleted file mode 100644 index 6cae663c..00000000 --- a/docs/Github Actions/mutation-test-generator.md +++ /dev/null @@ -1,89 +0,0 @@ -# Mutation Test Generation - -The Olympix Mutation Test Generation action allows you to integrate mutation testing into your CI/CD workflows on GitHub. This action automates the creation of mutation tests for your Solidity projects, helping ensure that your existing unit tests are robust and capable of catching code mutations. - ---- - -## Overview - -The Olympix Mutation Test Generation action leverages Olympix's powerful test generator tool to run mutation tests on your smart contracts. By integrating this into your CI workflow, you can focus on developing your smart contracts while the action handles the mutation testing process during your builds. - -You can access this action from the [GitHub Marketplace](https://github.com/marketplace/actions/olympix-mutation-test-generator) or visit the [GitHub repository](https://github.com/olympix/mutation-test-generator) for more details. - ---- - -## Features - -- **Mutation Tests Generation:** -Automatically generate mutation tests to evaluate the effectiveness of your unit tests and enhance test coverage. - -- **CI/CD Integration:** - Seamlessly integrate mutation testing into your GitHub workflows to continuously assess test quality. - -- **Automated Reporting:** - Once the mutation tests are complete, results are emailed to the address associated with your Olympix API token, including details about which mutants were killed or survived. - ---- - -## Getting Started -
-1. **Set Up API Token:** - - Add a GitHub repository secret with your Olympix API token. - - Set an environment variable `OLYMPIX_API_TOKEN` in your workflow using this secret. - -2. **Add the Mutation Test Generator Action:** - - Include the `olympix/mutation-test-generator` action in your workflow. -3. **Configure GitHub Access (Optional) (1):** - - Install the [Github Notifier service](http://github.com/apps/olympix-notifier/) to your repo. It will ask you to grant it permission to create check runs. This GitHub App enables test result reporting via GitHub Check Runs. It works seamlessly with Olympix’s GitHub Actions—currently supporting the Olympix Mutation Test Generator. - - -
-1. This allows the mutation-tester to access your private GitHub repository. - ---- - -## Usage Example - -Below is an example workflow that triggers on each commit containing the string `OPIX-GEN-MUTATION-TESTS`. This workflow installs the necessary dependencies with `npm install` and `forge install` , and then triggers the mutation test generator with the required paths for each target Solidity contract. - -```yaml -name: Mutation Test Generation Workflow -on: - push - -jobs: - mutation-test-generation: - if: contains(github.event.head_commit.message, 'OPIX-GEN-MUTATION-TESTS') # Modify this. - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - submodules: recursive - - - name: Install dependencies - run: npm install # or yarn install or bun etc. whatever your repository requires to setup before being able to call forge test. - - - name: Install Foundry - uses: foundry-rs/foundry-toolchain@v1 - - - name: Run forge install - run: | - forge install - - - name: Mutation Test Generator - uses: olympix/mutation-test-generator@main - env: - OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} - OLYMPIX_FAIL_MUTATION_GHA_THRESHOLD: 30 # optional, provides a threshold(in percentage) below which the check will fail. - OLYMPIX_GITHUB_COMMIT_HEAD_SHA: ${{ github.sha }} # optional, marks the commit on which the check run will appear in the repo. - with: - args: -p src/subjectContract1.sol -p src/subjectContract2.sol # Modify this: List of target contracts (we currently accept a maximum of 5 target contracts.) -``` - - - -The workflow will start, and an email with the mutation test results will be sent to the address associated with your API token. The generation time will vary based on the size and complexity of your contracts. - -## Github App integration - -If you chose to install the `olympix-notifier` GitHub app to your repository, you will receive a check run on this commit with the results as a json object. This check will fail based on the `OLYMPIX_GITHUB_COMMIT_HEAD_SHA` variable. You can choose to script on top of this check run as well. Read more [here](https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28). \ No newline at end of file diff --git a/docs/Github Actions/unit-test-generator.md b/docs/Github Actions/unit-test-generator.md deleted file mode 100644 index fbdba87a..00000000 --- a/docs/Github Actions/unit-test-generator.md +++ /dev/null @@ -1,119 +0,0 @@ -# Unit Test Generation - -The Olympix Test Generation action enables you to integrate our test generator tool directly into your GitHub CI/CD workflows. By using this action, you can automatically generate unit tests for your Solidity projects, ensuring code correctness and reliability—all without manually writing tests. - ---- - -## Overview - -The Olympix Test Generation action performs code analysis and test generation for Solidity projects. It allows developers to focus on building robust smart contracts while the tool handles test creation during CI runs. - -You can access this action from the [GitHub Marketplace](https://github.com/marketplace/actions/olympix-unit-test-generator) or visit the [GitHub repository](https://github.com/olympix/test-generator) for more details. - ---- - -## Features - -- **Unit Tests Generation:** - Automatically generate unit tests to help verify the functionality of your smart contracts. - -- **CI/CD Integration:** - Seamlessly integrate the test generation process into your GitHub workflows. - -- **Email Notifications:** - Once test generation completes, results are sent to the email address associated with your Olympix API token. - ---- - -## Getting Started - -1. **Set Up API Token:** - - Add a GitHub repository secret with your Olympix API token. - - Ensure an environment variable `OLYMPIX_API_TOKEN` is set in your workflow using the secret. - -2. **Add the Test Generator Action:** - - Include the `olympix/test-generator` action in your workflow. - -***Optional: Add Generated Tests Directly to Your Repository*** - -1. **Configure GitHub Access:** - - Create a GitHub [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - - Add a GitHub repository secret with this token. - - Set an environment variable `OLYMPIX_GITHUB_ACCESS_TOKEN` in your workflow with the secret value. - -2. **Branch Setup:** - - Create a branch named `opix-unit-test` where the generated tests will be committed. - ---- - -## Usage Examples - -### Example 1: Triggering Test Generation on PR Merge - -This workflow triggers test generation whenever a pull request is merged from the `main` branch to the `opix-unit-test` branch: - -```yaml -name: Unit Test Generation Workflow -on: - pull_request: - types: - - closed - -jobs: - test-generation: - if: github.event.pull_request.merged == true && github.head_ref == 'main' && github.base_ref == 'opix-unit-test' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: 18.17.1 - - - name: Install dependencies - run: npm install - - - name: Unit Test Generator - uses: olympix/test-generator@main - env: - OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} - OLYMPIX_GITHUB_ACCESS_TOKEN: ${{ secrets.OLYMPIX_GITHUB_TOKEN }} -``` - -### Example 2: Triggering on Specific Commit Message - -This example triggers the workflow on each commit that contains the string `OPIX-GEN-UNIT-TEST`. It installs dependencies, runs `forge install`, and then triggers the test generator: - -```yaml -name: Unit Test Generation Workflow -on: - push - -jobs: - test-generation: - if: contains(github.event.head_commit.message, 'OPIX-GEN-UNIT-TEST') - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - submodules: recursive - - - name: Install dependencies - run: npm install - - - name: Install Foundry - uses: foundry-rs/foundry-toolchain@v1 - - - name: Run forge install - run: | - forge install - - - name: Unit Test Generator - uses: olympix/test-generator@main - env: - OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} - OLYMPIX_GITHUB_ACCESS_TOKEN: ${{ secrets.OLYMPIX_GITHUB_TOKEN }} -``` - -Once triggered, the workflow starts the test generation process and sends the results via email. The generation time will vary depending on the size and complexity of your contracts. diff --git a/docs/Installation.md b/docs/Installation.md index dc5d7cda..97409177 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -1,6 +1,6 @@ # Installation Guide -Welcome to the Olympix installation guide! Get started by installing the CLI and the VSCode extension to access all of Olympix’s powerful features. This guide covers the full process—from downloading the CLI binaries to authenticating your account. +This guide covers the complete setup process for the Olympix CLI and VSCode extension, including binary installation and account authentication. --- @@ -24,17 +24,15 @@ Welcome to the Olympix installation guide! Get started by installing the CLI and ``` === "win-arm64" - ```bash - curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-arm64/olympix.exe - chmod +x olympix - ./olympix login -e user@olympix.ai + ```powershell + Invoke-WebRequest -Uri "https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-arm64/olympix.exe" -OutFile "olympix.exe" + .\olympix.exe login -e user@olympix.ai ``` === "win-x64" - ```bash - curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-x64/olympix.exe - chmod +x olympix - ./olympix login -e user@olympix.ai + ```powershell + Invoke-WebRequest -Uri "https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-x64/olympix.exe" -OutFile "olympix.exe" + .\olympix.exe login -e user@olympix.ai ``` === "linux-arm64" @@ -93,6 +91,5 @@ Our extension is available in the [VSCode Marketplace](https://marketplace.visua ## Additional Resources - **Olympix CLI Documentation:** Visit the [CLI documentation page](./CLI/index.md) for complete command reference and troubleshooting tips. -- **YouTube Tutorial:** For a video walkthrough of the setup and usage, watch our [YouTube tutorial](https://youtu.be/x7Apoq2PgT0). -If you encounter any issues or have questions, feel free to reach out to our support team at [contact@olympix.ai](mailto:contact@olympix.ai). +For support, contact [contact@olympix.ai](mailto:contact@olympix.ai). diff --git a/docs/Quickstart.md b/docs/Quickstart.md new file mode 100644 index 00000000..1d4c8fe8 --- /dev/null +++ b/docs/Quickstart.md @@ -0,0 +1,151 @@ +# Quickstart + +Get your first vulnerability scan running in under 5 minutes. + +--- + +## Prerequisites + +- A Solidity project (Foundry or Hardhat) +- An Olympix account (email [contact@olympix.ai](mailto:contact@olympix.ai) for access) + +--- + +## 1. Download the CLI + +=== "macOS (Apple Silicon)" + ```bash + curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/osx-arm64/olympix + chmod +x olympix + ``` + +=== "macOS (Intel)" + ```bash + curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/osx-x64/olympix + chmod +x olympix + ``` + +=== "Linux (x64)" + ```bash + curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/linux-x64/olympix + chmod +x olympix + ``` + +=== "Linux (ARM64)" + ```bash + curl -o olympix https://olympix-download.s3.amazonaws.com/cli/v0.10.12/linux-arm64/olympix + chmod +x olympix + ``` + +=== "Windows (x64)" + ```powershell + Invoke-WebRequest -Uri "https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-x64/olympix.exe" -OutFile "olympix.exe" + ``` + +=== "Windows (ARM64)" + ```powershell + Invoke-WebRequest -Uri "https://olympix-download.s3.amazonaws.com/cli/v0.10.12/win-arm64/olympix.exe" -OutFile "olympix.exe" + ``` + +--- + +## 2. Authenticate + +```bash +./olympix login -e your_email@domain.com +``` + +A one-time code will be sent to your email. Enter it when prompted. + +--- + +## 3. Run Your First Scan + +Navigate to your Solidity project and run: + +```bash +./olympix analyze +``` + +The CLI automatically detects your contracts in `contracts/` or `src/` directories. + +--- + +## Example Output + +``` +Starting connection +Connection established +Checking authorization +Scanning files +Finding bugs + +├── src/contracts/core/StrategyManager.sol +│ ├── LN:133 CL:5 SV:High CD:Medium ─ The contract is vulnerable to signature replay attacks, potentially allowing malicious actors to reuse valid signatures. +│ ├── LN:170 CL:9 SV:Medium CD:Medium ─ Calling a function without checking the return value may lead to silent failures. +│ ├── LN:313 CL:18 SV:Low CD:Medium ─ External calls in a loop may lead to denial of service if those calls revert. +│ │ +├── src/contracts/strategies/StrategyBase.sol +│ ├── LN:172 CL:32 SV:Medium CD:Medium ─ Performing integer division before multiplication can lead to unnecessary loss of precision. +│ ├── LN:60 CL:5 SV:Medium CD:Medium ─ Using uninitialized state variables may lead to unexpected behavior. +│ ├── LN:307 CL:34 SV:Low CD:Medium ─ Using an input parameter to a function as a divisor without checking the parameter may result in a division-by-zero error. +│ │ +``` + +Output key: + +- **LN** - Line number +- **CL** - Column number +- **SV** - Severity (Critical, High, Medium, Low, Info) +- **CD** - Confidence (Critical, High, Medium, Low) + +--- + +## Next Steps + +| Goal | Documentation | +|------|---------------| +| Understand vulnerability detectors | [Static Analysis](./Tools/Static%20Analysis.md) | +| See all CLI options | [CLI Reference](./CLI/index.md) | +| Generate unit tests | [Unit Testing](./Tools/Unit%20Testing.md) | +| Integrate with CI/CD | [GitHub Actions](./Github%20Actions/index.md) | +| Ignore false positives | [Config Options](./ConfigOptions.md) | +| Get real-time feedback in IDE | [VSCode Extension](./VSCode%20Extension/index.md) | + +--- + +## Common Commands + +```bash +# Scan specific directory +./olympix analyze -p src/core + +# Output as JSON +./olympix analyze -f json -o ./reports + +# Output as SARIF (for GitHub) +./olympix analyze -f sarif -o ./reports + +# List all detectors +./olympix show-vulnerabilities + +# Check CLI version +./olympix version +``` + +--- + +## Troubleshooting + +**"Permission denied" on macOS/Linux** +: Run `chmod +x olympix` to make the binary executable. + +**"Unidentified developer" warning on macOS** +: Go to System Preferences > Security & Privacy > General, then click "Open Anyway". + +**No vulnerabilities found** +: Verify your contracts are in `contracts/` or `src/`, or specify the path with `-p`. + +--- + +For support, contact [contact@olympix.ai](mailto:contact@olympix.ai). diff --git a/docs/Tools/Mutation Testing.md b/docs/Tools/Mutation Testing.md new file mode 100644 index 00000000..b4186fb9 --- /dev/null +++ b/docs/Tools/Mutation Testing.md @@ -0,0 +1,230 @@ +# Mutation Testing + +Mutation testing evaluates the effectiveness of your test suite by introducing small, systematic changes (mutations) to your source code and checking if your tests detect them. While code coverage tells you what lines are executed, mutation testing tells you how effective your tests are at catching actual bugs. + +--- + +## Why Mutation Testing? + +Traditional metrics like code coverage can provide a false sense of security. Having 100% coverage doesn't mean your tests are meaningful - they might have weak assertions or test the wrong things. + +Mutation testing provides a more meaningful metric by: + +1. **Measuring test effectiveness** - Do your tests actually catch bugs? +2. **Identifying weak tests** - Which tests pass even when code is broken? +3. **Forcing better assertions** - Encourages tests that verify behavior, not just execution +4. **Discovering edge cases** - Finds scenarios you haven't considered + +--- + +## Security Implications + +In smart contract development, mutation testing is critical for security. Many historical exploits occurred due to seemingly minor changes in business logic that weren't caught by existing test suites. + +**Olympix mutation operators are derived from real-world smart contract exploits.** Each operator represents a pattern of change that has historically led to security incidents in production contracts. + +--- + +## How It Works + +1. **Parse** - The tool analyzes your Solidity source code +2. **Mutate** - Small changes are applied to create "mutants" +3. **Test** - Your test suite runs against each mutant +4. **Report** - Results show which mutants were "killed" (detected) vs "survived" (undetected) + +### Interpreting Results + +| Outcome | Meaning | +|---------|---------| +| **Killed** | Your tests detected the mutation (good) | +| **Survived** | Your tests passed despite the bug (bad - improve your tests) | +| **Timeout** | Tests took too long (may indicate infinite loop) | + +A high **mutation score** (killed / total mutants) indicates an effective test suite. + +--- + +## Mutation Operators + +Olympix applies 14 types of mutations, each representing a real vulnerability pattern: + +### 1. Arithmetic Operator Mutations + +```solidity +// Original +amount + tax +// Mutated +amount - tax +``` + +Swaps: `+` with `-`, `%` with `/`, and vice versa. + +### 2. Comparison Operator Mutations + +```solidity +// Original +amount > 0 +// Mutated +amount < 0 +``` + +Swaps: `==` with `!=`, `>` with `<`, `>=` with `<`, `<=` with `>`. + +### 3. Logical Operator Mutations (AND/OR) + +```solidity +// Original +require(isEnabled && amount > 100) +// Mutated +require(isEnabled || amount > 100) +``` + +Swaps `&&` with `||` and vice versa. + +### 4. Condition Negation + +```solidity +// Original +if (taxEnabled) +// Mutated +if (!taxEnabled) +``` + +Adds or removes the `!` operator. + +### 5. Ternary Conditional Mutations + +```solidity +// Original +amount < 100 ? amount : 100 - tax +// Mutated +amount < 100 ? 100 - tax : amount +``` + +Swaps the true and false branches. + +### 6. Function Call Mutations (delegatecall to call) + +```solidity +// Original +(address).delegatecall(data) +// Mutated +(address).call(data) +``` + +### 7. Hex Literal Mutations + +```solidity +// Original +0xabcd1234 +// Mutated to 0 or another hex literal in scope +0x0 +``` + +### 8. Remove emit Statement + +```solidity +// Original +emit Transfer(msg.sender, recipient, amount); +// Mutated +// (removed) +``` + +### 9. Remove delete Operator + +```solidity +// Original +delete myStruct; +// Mutated +// (removed) +``` + +### 10. Storage Location Mutations + +```solidity +// Original +uint[] storage x; +// Mutated +uint[] memory x; +``` + +### 11. Assignment Operator Replacement + +```solidity +// Original +balances[msg.sender] += amount; +// Mutated +balances[msg.sender] -= amount; +``` + +### 12. State Variable Initialization + +```solidity +// Original +bool public taxEnabled = true; +// Mutated +bool public taxEnabled = false; +``` + +Also mutates integers (e.g., `1000` to `1001`) and strings. + +### 13. Modifier Removal + +```solidity +// Original +function toggleTax() public onlyOwner { ... } +// Mutated +function toggleTax() public { ... } +``` + +### 14. Address Swap + +```solidity +// Original +address(0xaaa...).call(); +// Mutated +address(0xbbb...).call(); // another address in scope +``` + +--- + +## Prerequisites + +The mutation test generator requires: + +- A Foundry project with existing unit tests +- Tests that pass before mutation testing begins + +No additional dependencies are needed. + +--- + +## Timeout Configuration + +Some mutations can cause infinite loops or extremely slow execution. Configure a timeout per mutant to prevent hanging: + +- **Default**: 300 seconds +- **Range**: 10 - 500 seconds +- **Recommendation**: Set slightly higher than your normal test suite execution time + +--- + +## Using Mutation Testing + +=== "CLI" + See [CLI Reference](../CLI/index.md#generate-mutation-tests) for command-line options. + + ```bash + olympix generate-mutation-tests -p src/MyContract.sol + ``` + +=== "GitHub Actions" + See [GitHub Actions](../Github%20Actions/index.md#mutation-test-generation) for CI/CD integration. + + ```yaml + - uses: olympix/mutation-test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + with: + args: -p src/MyContract.sol + ``` diff --git a/docs/Tools/Static Analysis.md b/docs/Tools/Static Analysis.md new file mode 100644 index 00000000..39046e68 --- /dev/null +++ b/docs/Tools/Static Analysis.md @@ -0,0 +1,114 @@ +# Static Analysis + +Static analysis scans your Solidity code for security vulnerabilities and code quality issues without executing it. Olympix's analyzer checks for 80+ vulnerability patterns derived from real-world smart contract exploits. + +--- + +## How It Works + +The Olympix static analyzer parses your Solidity source code and applies a set of security detectors to identify potential vulnerabilities. Each detector targets a specific vulnerability pattern and reports: + +- **Location**: File path and line number +- **Severity**: Critical, High, Medium, Low, or Info +- **Confidence**: How certain the analyzer is about the finding +- **Description**: What the vulnerability is and why it matters +- **Recommended Fix**: How to remediate the issue + +--- + +## Vulnerability Categories + +Olympix detects vulnerabilities across several categories: + +| Category | Description | +|----------|-------------| +| **Access Control** | Unauthorized access, privilege escalation, arbitrary calls | +| **Reentrancy** | State manipulation from external calls | +| **Input Validation** | Missing or improper validation of inputs | +| **Arithmetic** | Integer overflow, underflow, precision loss | +| **Low-Level Calls** | Unchecked return values, unsafe call patterns | +| **Oracle Manipulation** | Price oracle and data feed vulnerabilities | +| **Signature Issues** | Replay attacks, malleability, missing validation | +| **Code Quality** | Best practices, visibility, shadowing, unused code | + +For the complete list of 80+ detectors with detailed descriptions, see the [Detector Documentation](https://detectors.olympixdevsectools.com/) or run: + +```bash +olympix show-vulnerabilities +``` + +--- + +## Severity Levels + +| Severity | Description | +|----------|-------------| +| **Critical** | Immediate exploitation risk, funds at risk | +| **High** | Serious vulnerability that should be fixed before deployment | +| **Medium** | Moderate risk, should be addressed | +| **Low** | Minor issue or best practice violation | +| **Info** | Informational finding, no immediate risk | + +--- + +## Output Formats + +The analyzer supports multiple output formats for different use cases: + +### Tree (Default) +Human-readable hierarchical display in the terminal. Best for interactive development. + +``` +├── src/contracts/Vault.sol +│ ├── LN:45 CL:5 SV:High CD:Medium ─ The contract is vulnerable to reentrancy attacks. +│ ├── LN:72 CL:9 SV:Medium CD:Medium ─ Calling a function without checking the return value may lead to silent failures. +│ │ +``` + +Output key: **LN** (line), **CL** (column), **SV** (severity), **CD** (confidence) + +### JSON +Structured data format for programmatic processing and integration with other tools. + +### SARIF +Static Analysis Results Interchange Format. Used for: + +- GitHub Code Scanning integration +- IDE integrations +- Security dashboard tools + +### Email +Sends a formatted report to your registered email address. + +--- + +## Configuration + +You can customize the analyzer behavior using a configuration file. See [Config Options](../ConfigOptions.md) for details on: + +- Ignoring specific vulnerabilities by file and line +- Marking paths as trusted (e.g., audited libraries) +- Marking contracts as trusted for specific detectors + +--- + +## Using Static Analysis + +=== "CLI" + See [CLI Reference](../CLI/index.md#analyze) for command-line options. + + ```bash + olympix analyze -p src/ + ``` + +=== "GitHub Actions" + See [GitHub Actions](../Github%20Actions/index.md#static-analysis) for CI/CD integration. + + ```yaml + - uses: olympix/integrated-security@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + ``` + +=== "VSCode" + See [VSCode Extension](../VSCode%20Extension/index.md) for real-time scanning in your editor. diff --git a/docs/Tools/Unit Testing.md b/docs/Tools/Unit Testing.md new file mode 100644 index 00000000..5c162e67 --- /dev/null +++ b/docs/Tools/Unit Testing.md @@ -0,0 +1,157 @@ +# Unit Test Generation + +Olympix automatically generates unit tests for your Solidity smart contracts, targeting branch coverage to help verify contract functionality. The generated tests are compatible with the Foundry testing framework. + +--- + +## How It Works + +The Olympix Unit Test Generator analyzes your smart contracts and generates test cases that: + +1. **Target branch coverage** - Tests are designed to exercise different code paths +2. **Use your existing setup** - Builds on your `setUp()` function and existing test structure +3. **Follow Foundry conventions** - Output is compatible with `forge test` + +After generation, results are emailed to your registered address with: + +- Generated test files +- Coverage statistics +- Credit consumption details + +--- + +## Prerequisites + +Before generating unit tests, ensure your project meets these requirements: + +### 1. Foundry Project Structure + +Your project must be a valid Foundry project that compiles successfully. + +``` +my-project/ + contracts/ # or src/ + MyContract.sol + test/ + MyContract.t.sol + foundry.toml +``` + +### 2. Correct Remappings + +Verify your Forge remappings are correctly configured. The generator needs to resolve all imports. + +```toml title="foundry.toml" +[profile.default] +src = "contracts" +test = "test" +libs = ["lib"] +remappings = [ + "@openzeppelin/=lib/openzeppelin-contracts/", +] +``` + +See [Foundry remappings documentation](https://book.getfoundry.sh/projects/dependencies#remapping-dependencies) for details. + +### 3. OlympixUnitTest Base Contract + +Create a file named `OlympixUnitTest.sol` in your test directory: + +```solidity title="test/OlympixUnitTest.sol" +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +abstract contract OlympixUnitTest { + constructor(string memory _name) {} +} +``` + +This base contract is required for the generator to identify which contracts to generate tests for. + +--- + +## Test Skeleton Structure + +For each contract you want to test, create a test skeleton that the generator will build upon: + +```solidity title="test/MyContract.t.sol" +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +import "../contracts/MyContract.sol"; +import "./OlympixUnitTest.sol"; + +contract MyContractTest is OlympixUnitTest("MyContract") { + MyContract public myContract; + + function setUp() public { + // Initialize your contract and any dependencies + myContract = new MyContract(); + } + + // Optional: Add example tests for the generator to learn from + function testExample() public { + uint expected = 42; + uint actual = myContract.getValue(); + assertEq(expected, actual); + } +} +``` + +### Key Elements + +| Element | Purpose | +|---------|---------| +| `OlympixUnitTest("ContractName")` | Identifies this as a test target | +| `setUp()` | Initializes the testing environment | +| State variables | Declares contracts and test fixtures | +| Example tests | (Optional) Helps generator understand testing patterns | + +!!! tip "Quality Setup Matters" + The quality of generated tests depends heavily on your `setUp()` function. Ensure it properly initializes all contracts and their dependencies. + +--- + +## Environment Variables + +If your tests require environment variables (RPC URLs, API keys, private keys for fork testing), you can include them securely: + +- Pass your `.env` file using the `-env` flag +- Specify a custom env file path with `--env-file` + +All environment variable data is encrypted with an additional RSA layer on top of standard encryption. + +See [Foundry environment variables](https://book.getfoundry.sh/cheatcodes/env-string) for format guidelines. + +--- + +## Credit Consumption + +Unit test generation consumes Olympix credits. The exact consumption depends on: + +- Number of contracts being tested +- Complexity of the contracts +- Number of functions to cover + +Credit usage details are included in the results email. + +--- + +## Using Unit Test Generation + +=== "CLI" + See [CLI Reference](../CLI/index.md#generate-unit-tests) for command-line options. + + ```bash + olympix generate-unit-tests -w . + ``` + +=== "GitHub Actions" + See [GitHub Actions](../Github%20Actions/index.md#unit-test-generation) for CI/CD integration. + + ```yaml + - uses: olympix/test-generator@main + env: + OLYMPIX_API_TOKEN: ${{ secrets.OLYMPIX_API_TOKEN }} + ``` + diff --git a/docs/index.md b/docs/index.md index c1221614..cab75d6a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,29 +1,116 @@ # Olympix -Welcome to the official Olympix documentation! Here you'll find everything you need to get started with our CLI, test generation tools, and integrated security features. Whether you're setting up your environment, scanning for vulnerabilities, or automating test generation, our documentation provides clear instructions and detailed examples. +

Smart contract security suite for Solidity developers

-**Visit our Website:** -Explore more about Olympix and our solutions at [olympix.ai](https://olympix.ai). +
-**Detector Documentation:** -For in-depth information on our vulnerability detectors, check out the [Detector Documentation](https://detectors.olympixdevsectools.com/). +- **Static Analysis** + + --- + + Scan contracts for 80+ vulnerability patterns derived from real-world exploits + + [Learn more](./Tools/Static%20Analysis.md) + +- **Unit Test Generation** + + --- + + Automatically generate Foundry-compatible tests targeting branch coverage + + [Learn more](./Tools/Unit%20Testing.md) + +- **Mutation Testing** + + --- + + Validate your test suite catches real bugs, not just achieves coverage + + [Learn more](./Tools/Mutation%20Testing.md) + +- **VSCode Extension** + + --- + + Real-time vulnerability scanning with one-click quick fixes + + [Learn more](./VSCode%20Extension/index.md) + +
+ +--- + +## Getting Started + +
+ +- **Installation** + + --- + + Download the CLI and authenticate your account + + [Install now](./Installation.md) + +- **Quickstart** + + --- + + Run your first vulnerability scan in under 5 minutes + + [Get started](./Quickstart.md) + +
--- -## Contents +## Documentation + +### Tools -- [Installation](./Installation.md) - Get started with downloading and installing the Olympix CLI and VSCode extension. +| Tool | Description | +|------|-------------| +| [Static Analysis](./Tools/Static%20Analysis.md) | Vulnerability scanning concepts, categories, and severity levels | +| [Unit Testing](./Tools/Unit%20Testing.md) | Automated test generation setup and prerequisites | +| [Mutation Testing](./Tools/Mutation%20Testing.md) | Test suite quality assessment and mutation operators | -- [CLI](./CLI/index.md) - Learn about the Olympix CLI commands, options, and usage examples to integrate into your workflow. +### Interfaces -- [GitHub Actions](./Github%20Actions/integrated-security.md) - Learn about GitHub Actions integrations provided by Olympix. +| Interface | Description | +|-----------|-------------| +| [CLI Reference](./CLI/index.md) | All commands, options, and usage examples | +| [GitHub Actions](./Github%20Actions/index.md) | CI/CD integration workflows | +| [VSCode Extension](./VSCode%20Extension/index.md) | IDE integration with quick fixes | -- [VSCode Extension](./VSCode%20Extension/index.md) - Learn about Olympix's features integrated directly into your editor, including real-time scanning and automatic quick fixes. +### Configuration + +| Reference | Description | +|-----------|-------------| +| [Config Options](./ConfigOptions.md) | Ignore rules, trusted paths, and custom settings | +| [Ignore Options](./IgnoreOptions.md) | Legacy configuration format | --- -Happy exploring, and feel free to reach out to us at [contact@olympix.ai](mailto:contact@olympix.ai) if you have any questions or need support. \ No newline at end of file +## Resources + +
+ +- **Website** + + --- + + [olympix.ai](https://olympix.ai) + +- **Detector Docs** + + --- + + [detectors.olympixdevsectools.com](https://detectors.olympixdevsectools.com/) + +- **Support** + + --- + + [contact@olympix.ai](mailto:contact@olympix.ai) + +
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..e4a97900 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,173 @@ +/* Olympix Documentation Custom Styles */ + +/* ===== Typography ===== */ +.subtitle { + font-size: 1.25rem; + color: var(--md-default-fg-color--light); + margin-top: -0.5rem; + margin-bottom: 2rem; + font-weight: 400; +} + +/* ===== Grid Cards ===== */ +.grid.cards > ul > li { + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 0.5rem; + transition: border-color 0.2s, box-shadow 0.2s; +} + +.grid.cards > ul > li:hover { + border-color: var(--md-accent-fg-color); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +} + +/* Card icon styling */ +.grid.cards > ul > li > :first-child { + font-size: 1.1rem; +} + +/* ===== Tables ===== */ +.md-typeset table:not([class]) { + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 0.375rem; + overflow: hidden; +} + +.md-typeset table:not([class]) th { + background-color: var(--md-default-fg-color--lightest); + font-weight: 600; + text-transform: uppercase; + font-size: 0.75rem; + letter-spacing: 0.05em; +} + +.md-typeset table:not([class]) td, +.md-typeset table:not([class]) th { + padding: 0.75rem 1rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset table:not([class]) tr:last-child td { + border-bottom: none; +} + +/* ===== Code Blocks ===== */ +.md-typeset pre > code { + border-radius: 0.375rem; +} + +.md-typeset code { + border-radius: 0.25rem; + padding: 0.125rem 0.375rem; +} + +/* Code block titles */ +.md-typeset .highlight > .filename { + background-color: var(--md-code-bg-color); + border-bottom: 1px solid var(--md-default-fg-color--lightest); + font-size: 0.75rem; + font-weight: 600; + padding: 0.5rem 1rem; + margin-bottom: 0; + border-radius: 0.375rem 0.375rem 0 0; +} + +/* ===== Admonitions ===== */ +.md-typeset .admonition, +.md-typeset details { + border-radius: 0.375rem; + border-width: 1px; + border-left-width: 4px; +} + +.md-typeset .admonition-title, +.md-typeset summary { + font-weight: 600; +} + +/* ===== Navigation ===== */ +.md-tabs__link { + font-weight: 500; +} + +/* ===== Content ===== */ +.md-typeset h1 { + font-weight: 700; + margin-bottom: 1rem; +} + +.md-typeset h2 { + font-weight: 600; + margin-top: 2.5rem; + padding-bottom: 0.5rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset h3 { + font-weight: 600; + margin-top: 1.5rem; +} + +/* ===== Horizontal Rules ===== */ +.md-typeset hr { + border-top: 1px solid var(--md-default-fg-color--lightest); + margin: 2rem 0; +} + +/* ===== Links ===== */ +.md-typeset a:not(.md-button) { + text-decoration: none; +} + +.md-typeset a:not(.md-button):hover { + text-decoration: underline; +} + +/* ===== Buttons ===== */ +.md-typeset .md-button { + border-radius: 0.375rem; + font-weight: 500; + padding: 0.625rem 1.25rem; + transition: all 0.2s; +} + +.md-typeset .md-button:hover { + transform: translateY(-1px); + box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15); +} + +.md-typeset .md-button--primary { + background-color: var(--md-primary-fg-color); + border-color: var(--md-primary-fg-color); +} + +/* ===== Tabs ===== */ +.md-typeset .tabbed-labels > label { + font-weight: 500; + font-size: 0.85rem; +} + +/* ===== Definition Lists (for troubleshooting) ===== */ +.md-typeset dt { + font-weight: 600; + margin-top: 1rem; +} + +.md-typeset dd { + margin-left: 1.5rem; + margin-bottom: 1rem; +} + +/* ===== Footer ===== */ +.md-footer-meta { + background-color: var(--md-default-fg-color); +} + +/* ===== Dark Mode Adjustments ===== */ +[data-md-color-scheme="slate"] .grid.cards > ul > li { + background-color: var(--md-code-bg-color); +} + +[data-md-color-scheme="slate"] .grid.cards > ul > li:hover { + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3); +} diff --git a/mkdocs.yml b/mkdocs.yml index 9d4cede9..7e66a9c9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,15 +1,20 @@ site_name: Olympix User Guide site_url: https://olympix.github.io/ +repo_url: https://github.com/olympix/olympix.github.io +repo_name: olympix/olympix.github.io +edit_uri: edit/main/docs/ + theme: name: material custom_dir: overrides logo: assets/olymp-x-logo.png + favicon: assets/olymp-x-logo.png palette: # Palette toggle for light mode - scheme: default primary: black toggle: - icon: material/brightness-7 + icon: material/brightness-7 name: Switch to dark mode # Palette toggle for dark mode @@ -19,22 +24,66 @@ theme: icon: material/brightness-4 name: Switch to light mode features: - - navigation.instant - - navigation.instant.progress - - navigation.tabs - - navigation.tab.sticky - - navigation.top + - navigation.instant + - navigation.instant.progress + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.sections + - navigation.expand + - navigation.path + - search.suggest + - search.highlight + - search.share + - content.code.copy + - content.action.edit + - toc.follow icon: annotation: material/arrow-right-circle + repo: fontawesome/brands/github + +plugins: + - search: + separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' + +nav: + - Home: index.md + - Getting Started: + - Installation: Installation.md + - Quickstart: Quickstart.md + - Tools: + - Static Analysis: Tools/Static Analysis.md + - Unit Testing: Tools/Unit Testing.md + - Mutation Testing: Tools/Mutation Testing.md + - Interfaces: + - CLI Reference: CLI/index.md + - GitHub Actions: Github Actions/index.md + - VSCode Extension: VSCode Extension/index.md + - Configuration: + - Config Options: ConfigOptions.md + - Ignore Options (Legacy): IgnoreOptions.md +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/olympix + - icon: fontawesome/brands/twitter + link: https://twitter.com/olympaboratories + generator: false +extra_css: + - stylesheets/extra.css markdown_extensions: - admonition - attr_list - md_in_html + - tables + - toc: + permalink: true + toc_depth: 3 - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: anchor_linenums: true @@ -46,3 +95,8 @@ markdown_extensions: - pymdownx.details - pymdownx.tabbed: alternate_style: true + - pymdownx.keys + - pymdownx.mark + - def_list + - pymdownx.tasklist: + custom_checkbox: true diff --git a/overrides/partials/footer.html b/overrides/partials/footer.html index e69de29b..9aa1f57d 100644 --- a/overrides/partials/footer.html +++ b/overrides/partials/footer.html @@ -0,0 +1,18 @@ +