coinfabrik / scout

Scout is an extensible open-source tool intended to assist ink! smart contract developers and auditors detect common security issues and deviations from best practices.

Scout: Security Analysis Tool

Scout is an extensible open-source tool intended to assist ink! smart contract developers and auditors detect common security issues and deviations from best practices.

This tool will help developers write secure and more robust smart contracts.

Our interest in this project comes from our experience in manual auditing and our usage of comparable tools in other blockchains. To improve coverage and precision, we´ll persist in research efforts on static and dynamic analysis techniques. Find more about our ongoing research at our associated repository.

Quick Start

For a quick start, make sure that Cargo is installed on your computer. Then, install Scout dependencies by running the following command:

cargo install cargo-dylint dylint-link

Afterwards, install Scout with the following command:

cargo install cargo-scout-audit

To run Scout on your project, navigate to its root directory and execute the following command:

cargo scout-audit

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

Documentation

• Getting Started
• Vulnerabilities
• Detectors
• Contribute
• Architecture
• Blog

Visit Scout's website to view the full documentation.

Detectors

Detector ID	What it Detects	Test Cases	Severity
integer-overflow-or-underflow	An arithmetic operation overflows or underflows the available memory allocated to the variable.	1, 2	Critical
set-contract-storage	Insufficient access control on set_contract_storage() function.	1	Critical
reentrancy	Consistency of contract state under recursive calls.	1, 2, 3	Critical
panic-error	Code panics on error instead of using descriptive enum.	1	Enhancement
unused-return-enum	Return enum from a function is not completely used.	1	Minor
dos-unbounded-operation	DoS due to unbounded operation.	1	Medium
dos-unexpected-revert-with-vector	DoS due to improper storage.	1	Medium
unsafe-expect	Improper usage of the expect method, leading to unexpected program crashes.	1	Medium
unsafe-unwrap	Inappropriate usage of the unwrap method, causing unexpected program crashes.	1	Medium
divide-before-multiply	Performing a division operation before a multiplication, leading to loss of precision.	1	Medium
delegate-call	Invoking code in another contract keeping the first contract's context.	1	Critical
zero-or-test-address	Avoid zero or test address assignment to prevent contract control loss.	1	Medium
insufficiently-random-values	Avoid using block attributes for random number generation to prevent manipulation.	1	Critical
unrestricted-transfer-from	Avoid passing an user-defined parameter as a from field in transfer-from	1	Critical
assert-violation	Avoid the usage of the macro assert!, it can panic.	1	Enhancement
avoid-core-mem-forget	The use of core::mem::forget could lead to memory leaks and logic errors	1	Enhancement
avoid-format-string	The format! macro is not recommended. A custom error is recommended instead.	1	Enhancement
unprotected-self-destruct	If users are allowed to call terminate_contract, they can intentionally or accidentally destroy the contract.	1	Critical
iterators-over-indexing	Iterating with hardcoded indexes is slower than using an iterator. Also, if the index is out of bounds, it will panic.	1	Enhancement
ink-version	Using an old version of ink! can be dangerous, as it may have bugs or security issues. Use the latest version available.	1	Enhancement
unprotected-set-code-hash	If users are allowed to call terminate_contract, they can intentionally modify the contract behaviour.	1	Critical
unprotected-mapping-operation	Modifying mappings with an arbitrary key given by the user could lead to unintented modifications of critical data, modifying data belonging to other users, causing denial of service, unathorized access, and other potential issues.	1	Critical
lazy-delegate	Delegated calls in ink! need lazy storage.	1	Critical

Tests

To validate our tool, we provide a set of code examples located in the test-cases folder.

In order to run the integration tests, navigate to apps/cargo-scout-audit and run:

cargo test --all --all-features

In order to run the tests for a particular test-case, run the same command on that particular test-case folder (e.g: test-cases/delegate-call/delegate-call-1/vulnerable-example)

Acknowledgements

Scout is an open source vulnerability analyzer developed by CoinFabrik's Research and Development team.

We received support through grants from both the Web3 Foundation Grants Program and the Aleph Zero Ecosystem Funding Program.

Grant Program	Description
	Proof of Concept: We collaborated with the Laboratory on Foundations and Tools for Software Engineering (LaFHIS) at the University of Buenos Aires to establish analysis techniques and tools for our detectors, as well as to create an initial list of vulnerability classes and code examples. View Grant | Application Form. Prototype: We built a functioning prototype using linting detectors built with Dylint and expanded the list of vulnerability classes, detectors, and test cases. View Prototype | Application Form.
	We improved the precision and number of detectors for the tool with a multi-phase approach. This included a manual vulnerability analysis of projects within the Aleph Zero ecosystem, comprehensive testing of the tool on leading projects, and refining its detection accuracy.

About CoinFabrik

We - CoinFabrik - are a research and development company specialized in Web3, with a strong background in cybersecurity. Founded in 2014, we have worked on over 180 blockchain-related projects, EVM based and also for Solana, Algorand, and Polkadot. Beyond development, we offer security audits through a dedicated in-house team of senior cybersecurity professionals, currently working on code in Substrate, Solidity, Clarity, Rust, and TEAL.

Our team has an academic background in computer science and mathematics, with work experience focused on cybersecurity and software development, including academic publications, patents turned into products, and conference presentations. Furthermore, we have an ongoing collaboration on knowledge transfer and open-source projects with the University of Buenos Aires.

License

Scout is licensed and distributed under a MIT license. Contact us if you're looking for an exception to the terms.

scout's Issues

Cargo-scout detectors build repository

Description

Detectors are being downloaded from the old web3-grant repository, causing the tests of new detectors to fail.

Acceptance Criteria

• Come up with a solution to run those tests successfully
• Build cargo-scout with the new detectors

Add `cargo-scout` prototype

Description

We need to have a basic working CLI, and then start adding features to it.

Acceptance Criteria

• The prototype should work with known vulnerabilities
• It should download and compile the linter libraries
• It should call dylint to run the linters against the given smart contract
• It should detect if the tool is being run in a cargo project

Estimate

8 days

Sprint number

1

Update detector table on main README.md

Ensure the following columns are in the table:

• Detector ID
• What it Detects
• Test Cases
• Severity (if it fits)

Add --help, -h, --version to CLI

Description

Display help message and version message.

Acceptance Criteria

Implements the following commands:
cargo scout --help
cargo scout -h
cargo scout --version

Estimate

1

Sprint number

1

Add test-case for `unsafe-expect`

Description

A detector and test-case for unsafe-expect. This vulnerability is done when calling any sort of expect() operation on a Result or Option or any other. The correct way would be to define a custom Error type.

Acceptance Criteria

• A test-case for unsafe-expect should be created

Add unsafe-unwrap test case documentation

Add Vulnerabilities section to docs

Description

Complete Vulnerability documentation to docs.

Acceptance Criteria

Add an intro to vulnerabilities.
Add references for further reading.
Add separate pages for each class of vulnerability

Estimate

3

Sprint number

1

Validate tool against deployed projects

Description

Tool should be ran against deployed projects in order to verify false positives and general usage.

Acceptance Criteria

• Run tool against a set of deployed projects (e.g. Paraswap)
• Create document that summarize findings

Add test-case for `floating-point-and-numerical-precision`

Description

Due to the impossibility to represent floating point numbers in Ink, order of multiplications and divisions are important to ensure numerical precision.

Take for example the following function. It is intended to return the percentage of a total profit:

#[ink::message]
pub fn split_profit(uint64 percentage, uint64 total_profit) -> uint64 {
    (percentage / 100) * total_profit
}

The result however, will always be zero, given the integer division percentage / 100 yields zero.

Reordering operations to perform multiplications before divisions is a good way to avoid loss of precision:

#[ink::message]
pub fn split_profit(uint64 percentage, uint64 total_profit) -> uint64 {
    (percentage * total_profit) / 100
}

Acceptance Criteria

• Add a test-case that shows the vulnerability of floating-point-and-numerical-precision

Deploy docs

Description

Deploy documentation in Github Pages.

Add detector for `unsafe-unwrap`

Description

A detector for unsafe-unwrap. This vulnerability is done when calling any sort of unwrap() operation on a Result or Option or any other. The correct way would be to define a custom Error type.

Acceptance Criteria

• A detector for unsafe-unwrap should be created

Estimate

3

Sprint number

1

Add Detectors section to docs

Description

Complete documentation on detectors.

Acceptance Criteria

Add intro to detectors.
Add references to types of detectors and detection techniques
Add a separate page for each detector.

Estimate

5

Sprint number

1

Add test-case for `check-zero-or-test-address`

Description

User provided addresses should not be the zero address or any of the default test accounts (e.g. Bob, Alice).

Acceptance Criteria

• Add a test-case that breaks a contract for passing a zero address or a default test account

Add unrestricted-transfer-from test case documentation

Add key features to front page

Description

Add sections and links associated to the key features of our project to the front page.

Acceptance Criteria

• The file docs/docusaurus.config.js should be updated with the project's relevant data.
• The file docs/src/components/HomepageFeatures/index.txt should be updated with the project's relevant data.
• The file docs/src/pages/index.txt should be modified to link to doc's intro page.

Estimate

2

Sprint number

1

Add Contribute to documentation

Evaluate `scout` vscode extension

Description

This is an exploratory issue about creating a vscode extension for scout.

Acceptance Criteria

• Evaluate the difficulty of building a vscode extension instead of using rust-analyzer
• Create follow-up issues

Estimate

3

Sprint number

1

Update Cargo.toml ink versions to 4.2.1

Add filtering, exclusion and listing for detectors in `cargo-scout`

Description

Add options to allow:

• filtering by detector
• exclusion by detector
• listing existing detectors

Acceptance Criteria

Implements the following commands:

• cargo scout -–filter-by-detectors <DETECTOR_LIST_SEPARATED_BY_COMAS>
• cargo scout –-exclude-detectors <DETECTOR_LIST_SEPARATED_BY_COMAS>
• cargo scout –-list-detectors

Estimate

5

Sprint number

1

Correct path scout

Test-cases directory structure

Description

The goal of this task is to enhance the repository by adding a vulnerabilities folder and/or tests folder. The folder should contain examples of vulnerabilities, both before and after remediation, as specified in the Proof of Concept (PoC) milestone.

Acceptance Criteria

• Adds a vulnerabilities and/or tests folder to the repo with the vulnerability examples (before and after remediation) from the PoC milestone.

Estimate

1

Sprint number

1

Add test-case for `unsafe-unwrap`

Description

A test-case for unsafe-unwrap. This vulnerability is done when calling any sort of unwrap() operation on a Result or Option or any other. The correct way would be to define a custom Error type.

Acceptance Criteria

• A test-case for unsafe-unwrap should be created

Estimate

3

Sprint number

1

Try scout on Linux

Description

Install and try scout on Linux

Acceptance Criteria

Command cargo scout runs successfully without errors on sample repo.

Estimate

1

Sprint number

1

Add detector for `unsafe-unwrap`

Description

Usage of unwrap() is frowned upon in production code, which can cause the contract execution to revert with panic without providing a reason or a proper error control. This is similar to the panic-error vulnerability.

Acceptance Criteria

• Add detector for the vulnerability
• Add to integration tests

Add detector for `divide-before-multiply`

Description

Due to the impossibility to represent floating point numbers in Ink, order of multiplications and divisions are important to ensure numerical precision.

Take for example the following function. It is intended to return the percentage of a total profit:

#[ink::message]
pub fn split_profit(uint64 percentage, uint64 total_profit) -> uint64 {
    (percentage / 100) * total_profit
}

The result however, will always be zero, given the integer division percentage / 100 yields zero.

Reordering operations to perform multiplications before divisions is a good way to avoid loss of precision:

#[ink::message]
pub fn split_profit(uint64 percentage, uint64 total_profit) -> uint64 {
    (percentage * total_profit) / 100
}

Acceptance Criteria

• Add a detector for this vulnerability
• Add to integration tests

Add `delegate-call` test-case and detector

Description

In the same way as slither detects delegate-calls, we should have a detector for it. This is an exploratory issue for learning the usage of MIR and testing in a low-hanging fruit example such as delegatecall.

Acceptance Criteria

• Create test-case

Estimate

5

Sprint number

1

Try scout on Mac

Description

Install and try scout on Mac.

Acceptance Criteria

Command cargo scout runs successfully without errors on sample repo.

Estimate

1

Sprint number

1

Remove READMEs in each test-case and add basic documentation linking to docs

Description

Remove READMEs from all test-cases and add a README.md in the main test-case folder linking to the docusaurus.

Add delegate call test case documentation

Add test-case for `unsafe-unwrap`

Description

Usage of unwrap() is frowned upon in production code, which can cause the contract execution to revert with panic without providing a reason or a proper error control. This is similar to the panic-error vulnerability.

Acceptance Criteria

• Add a test-case for the vulnerability

Add `delegate-call` detector

Description

In the same way as slither detects delegate-calls, we should have a detector for it. This is an exploratory issue for learning the usage of MIR and testing in a low-hanging fruit example such as delegatecall.

Acceptance Criteria

• Create detector using MIR

Estimate

5

Sprint number

1

Add integration tests

Description

Add integrations tests to ensure that detectors mantain their expected behaviour as we modify scout and add new detectors. Proposal: create a vulnerabilities folder with the vulnerability examples and a tests folder with the necessary scripts to automate scout's run on these vulnerabilities.

Acceptance Criteria

• Adds required scripts to run scout on all involved files.
• Adds a script that compares the result against the output file generated in the last run.

Estimate

To be defined.

Sprint number

1

Add detector for `check-zero-or-test-address`

Description

User provided addresses should not be the zero address or any of the default test accounts (e.g. Bob, Alice).

Acceptance Criteria

• Add a detector for the vulnerability
• Add to integration tests

Improve CI formatting and linting to include missing dirs

Description

test-cases directory is not being included for linting and formatting. It should be included in order to detect lint or formatting errors.

Acceptance Criteria

• Add to Makefile the missing formatting and linting of the test-cases directory
• Add necessary scripts to list cargo directories recursively

Add detector for `unsafe-expect`

Description

A detector and test-case for unsafe-expect. This vulnerability is done when calling any sort of expect() operation on a Result or Option or any other. The correct way would be to define a custom Error type.

Acceptance Criteria

• A detector for unsafe-expect should be created

Add Tests section in README

Description

Add minimum test section (just a paragraph) explaining:

• How to run the integration tests for cargo-scout
• How to run the tests for each test-case

Add Getting Started section to docs

Description

Complete doc for Getting Started section.

Acceptance Criteria

Include these subsections

• About Scout
• Features
• What you'll need
• CLI
  • Installation
  • Usage
• VSCode Extension
  • Installation
  • Usage

Estimate

2

Sprint number

1

Improve CI times

Description

CI github workflow takes now around 40 minutes. This is too long and we will run out of our monthly free quota in no time.

Acceptance Criteria

• Improve cache usage so as to reduce build times.

Add --manifest-path to CLI

Description

Allows user to set path where to run the tool

Acceptance Criteria

Implements the following command:
cargo scout –manifest-path <PATH_TO_CARGO_TOML>

Estimate

1

Sprint number

1

Add unsafe-expect test case documentation

Add front-page images and icons

Description

For each icon, image or logo in this drive create an equivalent image for scout, maintaining file format an size.
Please take a look at the subfolder Image Ideas for an idea on how each image should look like.
Leave all the new image files in the folder Scout Icons.
Follow the image names specified in the Acceptance Criteria below.

Acceptance Criteria

The following files in bold must be saved in the Scout Icons folder.

• docusaurus-social-card.jpg -> scout-social-card.png. The phrase in this image is the one in this file.
• docusaurus.png -> scout.png. Use as inspiration this image.
• favicon.ico (keep file name and change its image for scout).
• logo.svg (keep file name and change its image for scout).
• undraw_docusaurus_mountain.svg -> scout_tool.svg (see Image Ideas).
• undraw_docusaurus_tree.svg -> scout_security.svg (see Image Ideas).
• undraw_docusaurus_react.svg -> scout_research.svg (see Image Ideas).

Estimate

To be confirmed

Sprint number

1

Check `integer-overflow-underflow` for all arithmetic operations

Description

A verification should be done in order to verify the detector for integer-overflow-underflow is complete for all arithmetic operations that could produce an overflow/underflow.

Acceptance Criteria

• Validate for all other arithmetic operations
• Add test-cases for other arithmetic operations
• Add new test-cases to integration tests

Sprint number

1

Changing general rust-toolchain to 1 per detector

Some detectors needs other toolchains to work as intended. We need to make that each detector has his own rust-toolchain

Add --output-file to CLI

Description

Add an option to allow output to be exported to a file (e.g: json file).

Acceptance Criteria

Specifies the output file type.
Implements the following command:
cargo scout –output-file <OUTPUT_FILE_NAME>

Estimate

To be discussed

Sprint number

1

Add Ink! detection to vscode extension

Description

In the current iteration of the vscode extension, whenever a Rust project is detected, doesn't matter if it's a smart contract or not, the extension is activated. This is not the correct behaviour as the linter is only suitable for Ink! smart contracts.

As a suggestion, the detection could be done verifying if the Cargo.toml has the dependencies needed to create a smart contract.

Acceptance Criteria

• Enable the extension only if we're running in an Ink! project

Subtasks

• Detect if we're in an Ink! project
• Enable the extension depending on the detection of the Ink! project

Estimate

2

Sprint number

1

Add Floating point and numerical precision test case documentation

Description

Write documentation for floating point and numerical precision test case.

Acceptance Criteria

• Add documentation to the test case

Estimate

Sprint number

1

Add filtering, excluding and listing for detector categories in `cargo-scout`

Description

Add options to allow:

• filtering by detector categories
• exclusion by detector categories
• listing existing detector categories

Acceptance Criteria

Implements the following commands:

• cargo scout –-filter-by-categories <CATEGORY_LIST_SEPARATED_BY_COMAS>
• cargo scout –-exclude-categories <CATEGORY_LIST_SEPARATED_BY_COMAS>
• cargo scout -–list-categories

Estimate

3

Sprint number

1

Add sections and scout image to README.md

Description

Add main sections and image to README.md

Acceptance Criteria

Add scout image within assets folder. Link the image to the README.md
Add license and license badge.
Add the following sections:

• (Introduction)
• Getting Started
• Documentation
• Detectors
• About CoinFabrik
• License

Estimate

1

Sprint number

1

Try scout on Windows

Description

Install and try scout on Windows 10.

Acceptance Criteria

Command cargo scout runs successfully without errors on sample repo.

Estimate

1

Sprint number

1

Add detector and test-cases for `insufficiently-random-values`

Description

Using block.number or block.timestamp together with a hash function to produce random numbers is insecure, since these attributes can be manipulated by miners for the current block or read by anyone else if using attributes of a previous block.

Acceptance Criteria

• Add test-case demonstrating this vulnerability
• Add a detector for this vulnerability
• Add to integration tests