EIPs/EIPS/eip-1470.md

eip	title	author	discussions-to	status	type	created
1470	Smart Contract Weakness Classification (SWC)	Gerhard Wagner (@thec00n)	https://github.com/ethereum/EIPs/issues/1469	Draft	Informational	2018-09-18

Simple Summary

This EIP proposes a classification scheme for security weaknesses in Ethereum smart contracts.

Abstract

The SWC is a smart contract specific software weakness classification scheme for developers, tool vendors and security practitioners. The SWC is loosely aligned to the terminologies and structure used in the Common Weakness Enumeration - CWE scheme while overlaying a wide range of weakness variants that are specific to smart contracts.

The goals of the SWC scheme are as follows:

• Provide a straightforward way to classify weaknesses in smart contract systems.
• Provide a straightforward way to identify the weakness(es) that lead to a vulnerability in a smart contract system.
• Define a common language for describing weaknesses in smart contract systems' architecture, design and code.
• Train and increase the performance of smart contract security analysis tools.

Motivation

In the software security industry, it is a widely accepted practice to use a common terminology and to classify security related bugs and errors with a standardized scheme. While this has not stopped vulnerabilities from appearing in software, it has helped communities focusing on web applications, network protocols, IOT devices and various other fields to educate users and developers to understand the nature of security related issues in their software. It has also allowed the security community to quickly understand vulnerabilities that occur in production systems to perform root cause analysis or triage findings from various security analysis sources. In recent years various organizations and companies also published vulnerability data to find the most widespread security issues based on collected vulnerability data. Two examples that are widely used and referred to are the SANS TOP 25 Most Dangerous Software Errors and the OWASP TOP 10. None of those publications would have been possible without a common classification scheme.

At present no such weakness classification scheme exists for weaknesses specific to Ethereum Smart Contracts. Common language and awareness of security weaknesses is mostly derived from academic papers, best practice guides and published articles. Findings from audit reports and security tool analysis add to the wide range of terminologies that is used to describe the discovered weaknesses. It is often time consuming to understand the technical root cause and the risk associated to findings from different sources even for security experts.

Rationale

While recognizing the current gap, the SWC does not aim to reinvent the wheel in regards to classification of security weaknesses. It rather proposes to build on top of what has worked well in other parts of the software security community - specifically the Common Weakness Enumeration (CWE), a list of software vulnerability types that stands out in terms of adoption and breadth of coverage. While CWE does not describe any weaknesses specific to smart contracts, it does describe related weaknesses at higher abstraction layers. This EIP proposes to create smart contract specific variants while linking back to the larger spectrum of software errors and mistakes listed in the CWE that different platforms and technologies have in common.

Specification

Before discussing the SWC specification it is important to describe the terminology used:

• Weakness: A software error or mistake that in the right conditions can by itself or coupled with other weaknesses lead to a vulnerability.
• Vulnerability: A weakness or multiple weaknesses which directly or indirectly lead to an undesirable state in a smart contract system.
• Variant: A specific weakness that is described in a very low detail specific to Ethereum smart contracts. Each variant is assigned an unique SWC ID.
• Relationships: CWE has a wide range of Base and Class types that group weaknesses on higher abstraction layers. The CWE uses Relationships to link SWC smart contract weakness variants to existing Base or Class CWE types. Relationships are used to provide context on how SWCs are linked to the wider group of software security weaknesses and to be able to generate useful visualisations and insights through issue data sets. In its current revision it is proposed to link a SWC to its closest parent in the CWE.
• SWC ID: A numeric identifier linked to a variant (e.g. SWC-101).
• Test Case: A test case constitutes a micro-sample or real-world smart contract that demonstrates concrete instances of one or multiple SWC variants. Test cases serve as the basis for meaningful weakness classification and are useful to security analysis tool developers.

The SWC in its most basic form links a numeric identifier to a weakness variant. For example the identifier SWC-101 is linked to the Integer Overflow and Underflow variant. While a list with the weakness title and a unique id is useful by itself, it would also be ambiguous without further details. Therefore the SWC recommends to add a definition and test cases to any weakness variant.

SWC definition

A SWC definition is formated in markdown to allow good readability and tools to process them easily. It consists of the following attributes.

• Title: A name for the weakness that points to the technical root cause.
• Relationships: Links a CWE Base or Class type to its CWE variant. The Integer Overflow and Underflow variant for example is linked to CWE-682 - Incorrect Calculation.
• Description: Describes the nature and potential impact of the weakness on the contract system.
• Remediation: Describes ways on how to fix the weakness.
• References: Links to external references that contain relevant additional information on the weakness.

Test cases

Test cases include crafted as well as real-world samples of vulnerable smart contracts. A single test case consists of three components:

1. Source code of a smart contract sample; e.g. Solidity, Vyper, etc.
2. Compiled asset from an EVM compiler in machine readable format; e.g. JSON or ethPM.
3. Test result configuration that describes which and how many instances of a weakness variant can be found in a given sample. The YAML schema for the proposed test case configuration is listed below.

title: SWC config
type: object
required:
- description
- issues
properties:
  description:
    type: string
  issues:
    title: Issues
    type: array
    items:
      title: Issue
      type: object
      required:
      - id
      - count
      properties:
        id:
          type: string
        count:
          type: number
        locations:
          items:
            bytecode_offsets:
              type: object
            line_numbers:
              type: object

Implementation

The Smart Contract Weakness Classification registry located in this Github repository uses the SWC scheme proposed in this EIP. A Github Pages rendered version is also available here.

Copyright

Copyright and related rights waived via CC0.