README.md

Scout Workshop

Welcome to the Scout Workshop repository! This repository contains all the necessary materials for our workshop on using Scout, CoinFabrik's bug detection tool for Soroban smart contracts.

Below you'll find a summary of the workshop agenda, installation guides, and examples we will work with during the sessions.

Workshop Agenda

The agenda for the workshop is as follows:

1. Intro and Tool Installation
   • Installing the CLI
   • Installing the VSCode Extension
   • Overview of Scout
   • Key features and benefits
2. Scout execution
3. Output interpretation
4. Practical examples: using Scout to solve an issue
5. CI/CD Integration: adding Scout to your GitHub pipeline

For more details, please visit the Workshop Landing Page.

Workshop Notes

Installation

CLI

Make sure that Cargo is installed on your computer. Then, follow install scout with the following command.

cargo install cargo-scout-audit

For more information on installation and usage, please refer to the Getting Started section in our documentation section below.

VSCode Extension

Add Scout to your development workspace with Scout's VS Code extension to run Scout automatically upon saving your file.

💡 Before installing Scout VS Code Extension, make sure to install rust-analyzer and Scout CLI.

👉 Install Scout VS Code from Visual Studio Marketplace.

💡 Tip: To see the errors highlighted in your code, we recommend installing the Error Lens Extension.

Excecution

CLI

To run Scout on your project, navigate to the directory of your smart contract and execute the following command:

cargo scout-audit

Generate an HTML report with:

cargo scout-audit --output-format html

⚠️ Currently Scout doesn't offer full support for workspaces. If you have a workspace, run Scout in each member instead of running it in the workspace Cargo.toml.

├── your-soroban-project
│   ├── your-smart-contract
│   │   ├── // Run Scout here.
│   │   ├── src
│   │   |   ├── contract.rs 
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── README.md

⚠️ Make sure that your smart contracts compile properly. Scout won't run if any compilation errors exist.

VSCode Extension

⚠️ To ensure the extension runs properly, make sure that you open the directory containing your smart contract, rather than the entire project. For example, if your smart contracts are located in myproject/contracts, and you want to work on the token contract while using the Scout VS Code Extension, open myproject/contracts/token.

Output Interpretation

Scout's output follows the following format.

warning: [Short description of the issue]
  --> src/lib.rs:[issue_line_start]:[issue_char_start]
   |
   |         some code;
   |         ^^^^^^^^^^^^^^^^^^
   |
   = help: [Recommendation on how to remediate the issue]
   = note: `#[warn([detector_name])]` on by default

Here:

• warning provides a short description of the detected issue.
• help provides a recommendation on how to fix the issue.
• note indicates the detector triggered, which is turned on by default on the user profile. Check on profile configuration to include or exclude detectors from your analysis.

Practical Examples

Take a look at example-1 and example-2. Let's run scout on these examples and see how to use the CLI and VSCode Extension.

Scout Action: CI/CD Example

Add Scout to every push to your repository with Scout Action.

Identify the path to the smart contract you want to be analyzed and create a .yml file in .github/workflows like scout.yml below.

name: scout-workflow
on:
  pull_request:
    branches:
      - main

jobs:
  scout-audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: write
      repository-projects: write
    steps:
      - name: checkout
        uses: actions/checkout@v4

      - name: do scout
        uses: coinfabrik/scout-actions@v3
        with:
          target: ''

      - uses: mshick/[email protected]
        with:
          message-path:  ${{ github.workspace }}/report.md