As was described in the Introduction to Web3 SDLC Design Phase blog, the design phase takes seeds of ideas and formulates them into software models. As we take the time to understand how these models will function, we should also understand all built-in systemic risks. The Security Maturity Model (SMM) for the Design phase allows designers to confidently innovate while staying aware of risks which may be present.
This blog focuses on three subdomains within Design: Documentation, Design Patterns and Architecture, and Risk Analysis and Management. We will describe the criteria which compose these subdomains, as well as the rationale behind why we think they are important.
Documentation
In this subdomain, we identify the documentation important to convey a team's intended design for a project. This allows designers and developers to reason on potentially complex interactions among system components. In addition, this early documentation will feed directly into user-specific documentation later in the development process. This subdomain is directed towards the innovators and designers of a protocol.
Protocol Documentation
- Definition: A written document of critical design decisions, unique algorithms, and formulas. In addition, this documentation should strip away marketing hype and concentrate on conveying key protocol ideas.
- Rationale: Early identification of key protocol behavior allows designers to take a step back and verify the protocol will operate as intended. It also provides a foundation for security analysis and development.
Maturity Level
- Minimum: Created a concise description of the protocol. Protocol use cases have been created.
- Improved: Published a white paper describing the protocol.
- Advanced: White paper is version controlled and updated regularly.
Protocol Diagrams
- Definition: Visual documentation of protocol interactions and key system states. Examples of these include state diagrams, sequence diagrams, and flow charts.
- Rationale: Creating visualizations of a protocol's intended behaviors allows designers to more readily identify potential errors. It also helps to solidify understanding and come to consensus on design approaches.
Maturity Level
- Minimum: Protocol use cases have been created.
- Improved: Published schema and architecture diagrams.
- Advanced: Schema and architecture diagrams are version controlled and updated regularly.
Design Patterns and Architecture
This subdomain serves as a guide to help protocol designers consider and make early decisions on aspects of a project which could pose high risk to the system and its users. A major part of this subdomain focuses on how external code and actors are allowed to modify protocol state. This subdomain is relevant to protocol designers and development leads.
External Contract Interactions
- Definition: Any on-chain contracts used by this protocol which fall outside of its purview. Examples include price feeds, protocol assets, external assets, decentralized exchanges (DEXes), and bridges.
- Rationale: Identification and understanding of external contract interactions not only allows for an early assessment of security risks from code outside the control of this protocol, but also helps developers scope interface code.
Maturity Level
- Minimum: Defined external on-chain interactions.
- Improved: External contracts which handle critical protocol logic have been audited. Defined external off-chain interactions.
- Advanced: All external contracts have been fully audited.
Third-Party Contracts and Libraries
- Definition: Any external contracts and libraries included in contract or deployment code. Examples include the many implementations within the OpenZeppelin contracts library.
- Rationale: Identification of third-party contracts and/or libraries to be used in development affords designers an opportunity to explore options, justify use of a particular library, and evaluate a library’s security risk.
Maturity Level
- Minimum: Relevant third-party contracts and libraries have been identified.
- Improved: Identified third-party contracts and libraries are well-known standards (OZ libraries, Paradigm).
- Advanced: Third-party contracts and libraries have been assessed for quality, usage, and overall compatibility.
Smart Contract Roles
- Definition: All roles which allow modification of contract state. This includes actions such as pausing withdrawals, changing administration roles, and transfers.
- Rationale: Identification of contract roles allows designers to build a picture of permissions needed by various protocol actors. This helps to limit exposure of critical portions of code. The existence of each role should be justified and its scope well-defined.
Maturity Level
- Minimum: None.
- Improved: Roles for the designed smart contracts have been identified.
- Advanced: Defined ownership lifecycle. All roles have been defined. Defined account types for each role. All role-based access control (RBAC) roles defined.
Protocol Governance
- Definition: Any systems, automated or manual, which allow modification of protocol functionality and general organizational processes. Protocol functionality includes contract code and operational parameters.
- Rationale: This provides an opportunity to understand how or if protocol stakeholders can modify a protocol’s functionality. Governance can enable a protocol to stay relevant in a particular market by granting, to various degrees, stakeholders the right to update how a protocol behaves.
Maturity Level
- Minimum: None
- Improved: Governance has been identified for the protocol.
- Advanced: Clearly defined for each portion of the protocol. Flowchart defining the governance process has been created. Defined process for introducing a new proposal. Defined voting requirements. Defined voting process. Defined quorum for each stage. Defined time delay for each stage.
Security Patterns
- Definition: The algorithms and coding standards which will be used to address specific risks. This can include the use of modifiers for permissions checks and the use of events to monitor contract activity.
- Rationale: This allows designers to call out security pitfalls and best practice mitigations in development. It also provides developers with clear direction with regard to how particular items should be implemented.
Maturity Level
- Minimum: None.
- Improved: Identified unique/non-standard security patterns to be used in code.
- Advanced: Identified standard security patterns to be used in code.
Upgrade Patterns
- Definition: The design pattern(s) used for upgrading a contract’s code or parameters. This can include patterns such as Transparent Proxy, UUPS, DiamondPattern Proxy, and more.
- Rationale: Supporting contract upgrades adds additional complexity to the overall protocol. If a choice is made to support upgrades, this criteria allows for time to weigh all available upgrade options based on their functionality and risk.
Maturity Level
- Minimum: None
- Improved: Identified unique/non-standard upgrade patterns to be used in code.
- Maximum: Identified standard upgrade patterns to be used in code.
Risk Analysis and Management
This subdomain focuses on the reality that any operational code and systems have inherent risks. We attempt to categorically identify those risks in the design phase so that mitigations are appropriately built into the resulting protocol. This subdomain applies to protocol designers, development leads, and company management.
Deployment
- Definition: The process used to release code into an operational environment. This includes release to testnets and production environments.
- Rationale: Deployment options should be assessed early to enable consideration of all potential pitfalls. A concise outline of how a protocol should be deployed can help move the final product towards a configuration-based deployment.
Maturity Level
- Minimum: None.
- Improved: Defined deployment process.
- Advanced: Identified manual vs scripted portions of the deployment process. Identified deployment artifacts to be published.
Upgrade
- Definition: The process used to modify functionality of an individual contract. This includes the mechanisms used for upgrading.
- Rationale: It should be determined which contracts in a protocol’s contract suite should be upgradeable. With the understanding that upgradeability adds extra complexity, designers have an opportunity to determine clear justification for a contract's upgrade posture. This can also provide direction regarding a protocol's governance model.
Maturity Level
- Minimum: None.
- Improved: None.
- Advanced: Identified protocol portions subject to upgrade. Defined upgrade process. Defined process for proposing and approving upgrades.
Threat Modeling
- Definition: The exercise of analyzing the ways in which different actors interact with the protocol to identify side effects that may be vulnerable to exploitation.
- Rationale: Software designers tend to view their product through the lens of its intended use cases. The exercise of Threat Modeling gives designers an opportunity to explore alternate use cases of their protocol and potentially modify their design early in the process to avoid these cases. This also provides input to the Develop and Defend phases’ SMM.
Maturity Level
- Minimum: Defined threat modeling plan.
- Improved: Created an initial threat model.
- Advanced: Version controlled threat model. Version controlled threat mitigation plan.
Market Risk
- Definition: The identification of market forces which could adversely affect the protocol.
- Rationale: Most protocols are subject to market forces, especially in DeFi. This criterion provides an opportunity for designers or third-party security partners to develop market scenarios in which a protocol could suffer losses. This risk analysis could provide insight as to whether circuit breakers or other safety mechanisms should be built into the protocol.
Maturity Level
- Minimum: Identified external market risk.
- Improved: Preliminary market risk analysis.
- Advanced: Preliminary market risk analysis from a third party. Preliminary market risk strategy has been created.
Security Partners
- Definition: Third-party companies which specialize in security, be it Web3, Web2, or infrastructure.
- Rationale: Security partners not only provide an outsider's perspective, but also have expertise in the security domain. Allowing for third-party security involvement early in the protocol design process can help educate a design team about best practices, review a team's design, and create a relationship which can continue through production.
Maturity Level
- Minimum: Planned for bug bounty program.
- Improved: Identification of third-party auditor(s).
- Advanced: Security design review from a third-party auditor(s).
Why You Can Trust Arbitrary Execution
Arbitrary Execution (AE) is an engineering-focused organization that specializes in securing decentralized technology. Our team of security researchers leverage their offensive security expertise, tactics, techniques, and hacker mindset to help secure the crypto ecosystem. In the two years since the company’s inception, Arbitrary Execution has performed more than 50 audits of Web3 protocols and projects, as well as created tools that continuously monitor the blockchain for anomalous activity. For more information on Arbitrary Execution's professional services, contact info@arbitraryexecution.com. Follow us on Twitter and LinkedIn for updates on our latest projects, including the Web3 SDLC.
