Smart Contract Weakness Classification Registry
The Smart Contract Weakness Classification Registry (SWC Registry) is an implementation of the weakness classification scheme proposed in EIP-1470. It is loosely aligned to the terminologies and structure used in the Common Weakness Enumeration (CWE) while overlaying a wide range of weakness variants that are specific to smart contracts.
The goals of this project are as follows:
- Provide a straightforward way to classify security issues in smart contract systems.
- Define a common language for describing security issues in smart contract systems' architecture, design, or code.
- Serve as a way to train and increase performance for smart contract security analysis tools.
Create a new SWC entry
Make sure that there is no matching weakness in the registry. Ideally, also coordinate with the community in #swc-registry to prevent conflicting entries. Create a file with a new SWC ID in the entries directory. Use the template and describe all weakness attributes.
# Title Pick a meaningful title. ## Relationships Link a CWE Base or Class type to the CWS variant. e.g. [CWE-682: Incorrect Calculation](https://cwe.mitre.org/data/definitions/682.html) ## Description Describe the nature and potential impact of the weakness on the contract system. ## Remediation Describe ways on how to fix the weakness. ## References Link to external references that contain useful additional information on the issue.
Create a new test case
Test cases should be as varied as possible and include both simple test cases and real-world samples of vulnerable smart contracts. The test cases are grouped into subdirectories based on a single weakness variant or based on more complex real world contract systems that can contain various weakness variants. A single test case consists of the following structure:
- A directory that contains all files belonging to a single test case (e.g. overflow_simple_add)
- One or multiple source files containing issues. Zero issues is valid as well. These test cases demonstrate how a vulnerable test case can be fixed (e.g. overflow_simple_add.sol and overflow_simple_add_fixed.sol).
- A single combined JSON file that contains the compilation result for the main source file and its imports. It should at least include the runtime as well as the creation byte code, ASTs, source code mappings and the used compiler version (e.g. overflow_simple_add.json)
The combined JSON can be generated in the following way:
$ solc --pretty-json --combined-json ast,bin,bin-runtime,srcmap,srcmap-runtime overflow_simple_add.sol > overflow_simple_add.json
- The configuration file defining the types and number of weaknesses contained in the contract file (e.g. overflow_simple_add.yaml)
One more thing, make sure the credit the author and mention the source if you don't write the contract sample yourself.
/* * @source: <link> * @author: <name> */
The configuration contains meta-information about the weaknesses contained in a particular sample. E.g.:
1: description: Plain and simple ADD overflow example 2: issues: 3: - id: SWC-101 4: count: 1 5: locations: 6: - bytecode_offsets: 7: '0x75ad68f906456e1cbfd6190a8f2e2dc5cb2794af4a4929448378642c992e151a':  8: line_numbers: 9: overflow_simple_add.sol: 
- Line 1:
descriptionprovides additional information and context for the test case.
- Line 2: A test case has zero, one or multiple
issuesthat are listed in the configuration file.
- Line 3:
idcontains the SWC identifier for the particular weakness. Each weakness is described in a markdown file in the entries directory.
- Line 4:
countis the number of times that the weakness occurs in the test case.
- Line 5:
locationshas sub attributes that allow humans and tools to easier identify where issues exists in the test case.
- Line 6-7:
bytecode_offsetsis a tuple consisting of the keccak256 hash of the runtime or creation byte code and a list of valid offsets.
- Line 8-9:
line_numbersis a tuple consisting of the source file and a list of valid line numbers.
Before you create a PR for the first time make sure you have read:
- the sections Create a new SWC entry and Create a new test case.
- read several existing SWC definitions and their test cases.
From time to time there will be challenges on Gitcoin. Follow the below link to check what challenges are currently open.
Scope of Weaknesses
SWCs should be concerned with weaknesses that can be identified within the code of a smart contract, typically Solidity. Weaknesses in 'smart contract adjacent' code should not be included. For example, the gas siphoning attack occurs in wallet code, and should be protected against in wallet code.
This repository is maintained by the team behind MythX.
Please join the #swc-registry channel on the MythX Discord for discussions.