Merge branch 'dev' into 2586-use-enum-track-var-location

Author: nsiregar

.github/workflows/linter.yml

@@ -44,6 +44,10 @@ jobs:
         run: |
           echo "::add-matcher::.github/workflows/matchers/yamllint.json"
 
+      - name: Remove part of the doc
+        run: |
+          rm -rf docs/src/
+
       - name: Lint everything else
         uses: super-linter/super-linter/[email protected]
         if: always()

.gitignore

@@ -113,8 +113,5 @@ test_artifacts/
 # crytic export 
 crytic-export/
 
-# Auto-generated Github pages docs
-docs/
-
 # slither.db.json 
 slither.db.json

README.md

@@ -258,15 +258,14 @@ See the [Printer documentation](https://github.com/crytic/slither/wiki/Printer-d
 
 ## Tools
 
-* `slither-check-upgradeability`: [Review `delegatecall`-based upgradeability](https://github.com/crytic/slither/wiki/Upgradeability-Checks)
-* `slither-prop`: [Automatic unit test and property generation](https://github.com/crytic/slither/wiki/Property-generation)
-* `slither-flat`: [Flatten a codebase](https://github.com/crytic/slither/wiki/Contract-Flattening)
-* `slither-check-erc`: [Check the ERC's conformance](https://github.com/crytic/slither/wiki/ERC-Conformance)
-* `slither-format`: [Automatic patch generation](https://github.com/crytic/slither/wiki/Slither-format)
-* `slither-read-storage`: [Read storage values from contracts](./slither/tools/read_storage/README.md)
-* `slither-interface`: [Generate an interface for a contract](./slither/tools/interface/README.md)
-
-See the [Tool documentation](https://github.com/crytic/slither/wiki/Tool-Documentation) for additional tools.
+* `slither-check-upgradeability`: [Review `delegatecall`-based upgradeability](./docs/src/tools/Upgradeability-Checks.md)
+* `slither-prop`: [Automatic unit test and property generation](./docs/src/tools/Property-generation.md)
+* `slither-flat`: [Flatten a codebase](./docs/src/tools/Contract-Flattening.md)
+* `slither-check-erc`: [Check the ERC's conformance](./docs/src/tools/ERC-Conformance.md)
+* `slither-read-storage`: [Read storage values from contracts](./docs/src/tools/ReadStorage.md)
+* `slither-interface`: [Generate an interface for a contract](./docs/src/tools/Interface.md)
+
+See the [Tool documentation](./docs/src/tools/README.md) for additional tools.
 
 [Contact us](https://www.trailofbits.com/contact/) to get help on building custom tools.
 

docs/src/README.md

@@ -0,0 +1,20 @@
+# [Slither, the smart contract static analyzer](https://crytic.github.io/slither/slither.html)
+
+<img src="https://raw.githubusercontent.com/crytic/slither/master/logo.png" alt="Slither Static Analysis Framework Logo" width="500" />
+
+[**Slither**](https://github.com/crytic/slither) is a Solidity & Vyper static analysis framework written in Python3. It runs a suite of vulnerability detectors, prints visual information about contract details, and provides an API to easily write custom analyses. Slither enables developers to find vulnerabilities, enhance their code comprehension, and quickly prototype custom analyses.
+
+If you are looking to use Slither's cli:
+
+- [Usage](./Usage.md) the most common flags
+
+If you are looking to leverage Slither inbuilt features:
+
+- [Detectors](./detectors/): Vulnerabilities detectors
+- [Printers](./printers): Printers (code vizualiation)
+- [Tools](./tools): Custom tools
+
+If you are looking to learn how to extend Slither's capabilities:
+
+- [API](./api): Introduction to static analysis & Slither's API
+- [Tutorial](./tutorials/): Hands-on exercises

docs/src/SUMMARY.md

@@ -0,0 +1,31 @@
+- [Introduction](./README.md)
+- [Usage](./Usage.md)
+- [API](./api/README.md)
+  - [Static Analysis](./api/static_analysis.md)
+  - [API](./api/api.md)
+  - [SlithIR](./api/SlithIR.md)
+  - [SSA](./api/SlithIR-SSA.md)
+  - [Data dependency](./api/Data-dependency.md)
+  - [JSON output](./api/JSON-output.md)
+- [Detectors](./detectors/Detector-Documentation.md)
+  - [Detectors](./detectors/Detector-Documentation.md)
+  - [Adding a detector](./detectors/Adding-a-new-detector.md)
+- [Printers](./printers/Printer-documentation.md)
+- [Tools](./tools/README.md)
+  - [Adding a new tool](./tools/Adding-a-new-utility.md)
+  - [Code Similarity](./tools/Code-Similarity-Detector.md)
+  - [Contract Flattening](./tools/Contract-Flattening.md)
+  - [Documentation](./tools/Documentation.md)
+  - [Doctor](./tools/Doctor.md)
+  - [ERC Conformance](./tools/ERC-Conformance.md)
+  - [Interface](./tools/Interface.md)
+  - [Mutator](./tools/Mutator.md)
+  - [Path Finding Utility](./tools/Path-Finding-Utility.md)
+  - [Property Generation](./tools/Property-generation.md)
+  - [Read Storage](./tools/ReadStorage.md)
+  - [Format](./tools/Slither-format.md)
+  - [Upgradeability checks](./tools/Upgradeability-Checks.md)
+- [Tutorials](./tutorials/README.md)
+  - [Exercise 1](./tutorials/exercise1.md)
+  - [Exercise 2](./tutorials/exercise2.md)
+  - [Exercise 3](./tutorials/exercise3.md)

docs/src/Usage.md

@@ -0,0 +1,170 @@
+## Usage
+
+- [How to run Slither](#how-to-run-slither)
+  - [Foundry/Hardhat](#foundryhardhat)
+  - [solc](#solc)
+  - [Etherscan](#etherscan)
+  - [AST input](#ast-file)
+- [Options](#options)
+  - [Detector selection](#detector-selection)
+  - [Printer selection](#printer-selection)
+  - [Path Filtering](#path-filtering)
+  - [Triage mode](#triage-mode)
+  - [Configuration file](#configuration-file)
+- [IDE integrations](#ide-integration)
+
+## How to run Slither
+
+All the [`crytic-compile`](https://github.com/crytic/crytic-compile/wiki/Configuration) options are available through Slither.
+
+### Foundry/hardhat
+
+To run Slither on a Foundry/hardhat directory:
+
+```
+slither .
+```
+
+### solc
+
+To run Slither from a Solidity file:
+
+```
+slither file.sol
+```
+
+### Etherscan
+
+To run Slither from a contract hosted on Etherscan, run
+
+```
+slither 0x7F37f78cBD74481E593F9C737776F7113d76B315
+```
+
+We recommend installing [solc-select](https://github.com/crytic/solc-select/) so Slither can switch to the expected solc version automatically.
+
+### Detector selection
+
+Slither runs all its detectors by default.
+
+To run only selected detectors, use `--detect detector1,detector2`. For example:
+
+```
+slither file.sol --detect arbitrary-send,pragma
+```
+
+To exclude detectors, use `--exclude detector1,detector2`. For example:
+
+```
+slither file.sol --exclude naming-convention,unused-state,suicidal
+```
+
+To exclude detectors with an informational or low severity, use `--exclude-informational` or `--exclude-low`.
+
+`--list-detectors` lists [available detectors](https://github.com/crytic/slither/wiki/Detector-Documentation).
+
+### Printer selection
+
+By default, no printers are run.
+
+To run selected printers, use `--print printer1,printer2`. For example:
+
+```
+slither file.sol --print inheritance-graph
+```
+
+`--list-printers` lists [available printers](https://github.com/crytic/slither/wiki/Printer-Documentation).
+
+### Path filtering
+
+`--filter-paths path1` will exclude all the results that are only related to `path1`. The path specified can be a path directory or a filename. Direct string comparison and [Python regular expression](https://docs.python.org/3/library/re.html) are used.
+
+Examples:
+
+```
+slither . --filter-paths "openzepellin"
+```
+
+Filter all the results only related to openzepellin.
+
+```
+slither . --filter-paths "Migrations.sol|ConvertLib.sol"
+```
+
+Filter all the results only related to the file `SafeMath.sol` or `ConvertLib.sol`.
+
+### Triage mode
+
+Slither offers two ways to remove results:
+
+- By adding `//slither-disable-next-line DETECTOR_NAME` before the issue
+- By adding `// slither-disable-start [detector] ... // slither-disable-end [detector]` around the code to disable the detector on a large section
+- By adding `@custom:security non-reentrant` before the variable declaration will indicate to Slither that the external calls from this variable are non-reentrant
+- By running the triage mode (see below)
+
+### Triage mode
+
+`--triage-mode` runs Slither in its triage mode. For every finding, Slither will ask if the result should be shown for the next run. Results are saved in `slither.db.json`.
+
+Examples:
+
+```
+slither . --triage-mode
+[...]
+0: C.destination (test.sol#3) is never initialized. It is used in:
+	- f (test.sol#5-7)
+Reference: https://github.com/trailofbits/slither/wiki/Vulnerabilities-Description#uninitialized-state-variables
+Results to hide during next runs: "0,1,..." or "All" (enter to not hide results):  0
+[...]
+```
+
+The second run of Slither will hide the above result.
+
+To show the hidden results again, delete `slither.db.json`.
+
+### Configuration File
+
+Some options can be set through a json configuration file. By default, `slither.config.json` is used if present (it can be changed through `--config-file file.config.json`).
+
+Options passed via the CLI have priority over options set in the configuration file.
+
+The following flags are supported:
+
+```
+{
+    "detectors_to_run": "all",
+    "printers_to_run": None,
+    "detectors_to_exclude": None,
+    "detectors_to_include": None,
+    "exclude_dependencies": False,
+    "exclude_informational": False,
+    "exclude_optimization": False,
+    "exclude_low": False,
+    "exclude_medium": False,
+    "exclude_high": False,
+    "fail_on": FailOnLevel.PEDANTIC,
+    "json": None,
+    "sarif": None,
+    "disable_color": False,
+    "filter_paths": None,
+    "include_paths": None,
+    "generate_patches": False,
+    "skip_assembly": False,
+    "legacy_ast": False,
+    "zip": None,
+    "zip_type": "lzma",
+    "show_ignored_findings": False,
+    "sarif_input": "export.sarif",
+    "sarif_triage": "export.sarif.sarifexplorer",
+    "triage_database": "slither.db.json",
+    # codex
+    "codex": False,
+    "codex_contracts": "all",
+    "codex_model": "text-davinci-003",
+    "codex_temperature": 0,
+    "codex_max_tokens": 300,
+    "codex_log": False,
+}
+```
+
+For flags related to the compilation, see the [`crytic-compile` configuration](https://github.com/crytic/crytic-compile/blob/master/crytic_compile/cryticparser/defaults.py)

docs/src/api/Data-dependency.md

@@ -0,0 +1,55 @@
+# Data dependency
+
+Data dependency allows knowing if the value of a given variable is influenced by another variable's value.
+
+Because smart contracts have a state machine based architecture, the results of the data dependency depend on the context (function/contract) of the analysis. Consider the following example:
+
+```solidity
+contract MyContract{
+    uint a = 0;
+    uint b = 0;
+
+    function setA(uint input_a) public{
+        a = input_a;
+    }
+
+    function setB() public{
+        b = a;
+    }
+
+}
+```
+
+In this example, if we consider only `setA`, we have the following dependency:
+
+- `a` is dependent on `input_a`
+
+If we consider only `setB`, we have:
+
+- `b` is dependent on `a`
+
+If we consider the contract entirely (with all the functions), we have:
+
+- `a` is dependent on `input_a`
+- `b` is dependent on `a` and `input_a` (by transitivity)
+
+`slither.analyses.is_dependent(variable, variable_source, context)` allows to know if `variable` is dependent on `variable_source` on the given context.
+
+As a result, in our previous example, `is_dependent(b, a, funcA)` will return `False`, while `is_dependent(b, a, myContract)` will return `True`:
+
+```
+from slither import Slither
+from slither.analyses import is_dependent
+
+slither = Slither('data_dependency_simple_example.sol')
+
+myContract = slither.get_contract_from_name('MyContract')
+funcA = myContract.get_function_from_signature('setA(uint256)')
+input_a = funcA.parameters[0]
+
+a = myContract.get_state_variable_from_name('a')
+b = myContract.get_state_variable_from_name('b')
+
+print(f'{b.name} is dependant from {input_a.name}?: {is_dependent(b, a, funcA)}')
+print(f'{b.name} is dependant from {input_a.name}?: {is_dependent(b, a, myContract)}')
+```