🔍Scoping and Information Gathering
The scoping process is a crucial step in which our researchers will analyze a variety of factors to determine the timeline and resources needed to complete a security review.
Initial Scoping
While it is common for the scope of the security review to occur during the initial phases of the review itself - we highly recommend provisioning the full scope of your security review elucidating the relevant areas of the system within scope as well as the location of the code repository and it's most recent commit hash for review. The client and Spearbit core team will have a scoping call in order to determine scope, estimate a start date, and familiarize the client with the Spearbit process as well as answer any further questions.
Note: Access to the target repository is needed to generate realistic estimates and continue the process. These access rights should be squared away for core members during this phase of the engagement and for the review team after formation during the phase. In the event there is a lack of clarity Spearbit will request access for Lead Security Researchers to pre-evaluate the code base prior to moving onto the next phase.
Upon completion and confirmation of the full scope required of the security review, the client will be provided with the following:
Total Amount Due
Review Start Date
Review Completion Date
For full details regarding the engagement after the scoping process - the client will be provided a Statement of Work (SOW) as shown here which will include the items listed above.
Team Formation
Upon the confirmation of scope, the client will be given their own personal communication channels with the core team inside of the Spearbit discord as discussed in the section.
To estimate workload and determine the relevant researchers with the required skillset for a client's scope, the client must authorize core members to access the target repository if it is private. Access to the target repository is necessary to generate realistic estimates and continue the engagement process.
Depending on codebase complexity, the core team may request the client provide access to Lead Security Researchers to pre-evaluate the code base. After the estimates have been set, the core team will make the security review offer public to the internal Spearbit network and reach out to you once researcher responses have been evaluated.
In order to maintain a high-level of quality assurance for our reviews, a security review is typically comprised of:
2 Lead Security Researchers
1 Security Researcher
1 Associate Security Researcher
1-2 Junior Security Researchers
Depending on the target scope however, this may be subject to change dependant on the needs of the client.
Note: If a client would like a private review or a specific researcher(s)' services explicitly, please inform us in advance. It's also worthy to mention should that specific researcher not have availability there could be modifications to the estimated start time for the review.
Documentation and Information Gathering
It is essential that the security researchers are provided any relevant documentation that may assist them in understanding the full landscape of the protocol or project's code that is under review. The documentation provided should be clear, concise, and updated and should elucidate the following:
Proper Code Specification
1. Clear Context
It is imperative for development teams to properly scope out the system and detail in writing - the key aspects of the system, their intended use cases and any other information deemed relevant in plain english regarding the purpose of the project itself.
We recommend documenting the following in detail:
• Definitions: Key terms used that are internal to the development team
• Participants: Any actor that interacts with the system
• Access Controls: Participants' allowed actions within the system
• Functionality: Public system entry points, their state interactions, and subsequent return values
2. Definitions of State
If at any point your system persists state, it should be classified as a state machine and documented accordingly. Clear definitions enable simplifying state transitions so that the system can become less complex. Spearbit recommends provisioning the following:
Identify States: Enumerate all possible states
Define Transitions: Detail state changes and conditions
Specify Events: Pinpoint triggers per transition
Describe Actions: Note outputs produced during transitions
Detail Exception Handling: Plan for unexpected events
Narrate Use Cases: Illustrate state machine operations with examples
3. Diagrams and Visuals
Well-constructed diagrams that detail the system or system components in depth are pivotal during scoping as well as during the review process itself. Examples include but are not limited to:
System and Components Diagrams
State Diagrams
ERDs
Flow of Funds Diagrams
Sequence Diagrams
Network Architecture Diagrams
4. Interfaces and Dependencies
Information regarding auxiliary items should be provided in detail such as interfaces, dependencies, or any external services / third parties that affect the system.
Interfaces
We recommend drafting system interfaces with precision so that the security research team with a full understanding of their relevant context in the scope of the review. The Ethereum Improvement Proposals (EIP) repository exemplifies this practice excellently as shown here.
Dependencies
Spearbit takes a very robust and comprehensive approach during its review process making it a point to analyze even the dependencies your code relies on for potential security issues. This has been demonstrated multiple times such as in the following examples:
5. Clearly Defined Natspec
Spearbit recommends that development teams ensure that they are following best practices for leveraging NatSpec when creating effective documentation to communicate the functionalities and constraints of your smart contracts more effectively.
Understanding NatSpec Tags - Natspec offers different tags to help guide the specificity of your descriptions. Two such tags are
@devand@notice. Understanding when to use these tags is crucial in crafting targeted documentation.Defining Ranges - In instances where a function accepts a range as an argument, it's crucial to clearly define whether the boundaries are inclusive or exclusive. This clarity will guide users in providing appropriate values and prevent potential transaction failures.
Contextual Descriptions - Natspec descriptions should provide additional context where possible. For instance, if a function requires a precision input scaled to
1e18or in the token's decimals, it should be explicitly stated in the description.Parameter Order Consistency - For better readability and understanding, ensure parameter order in your Natspec comments match function parameter order. Inconsistent ordering between the documentation and the function could lead to confusion for both developers and end-users.
Preconditions and Checks - Documenting preconditions and checks are essential so that a contract behaves securely and as intended. Additionally, providing these caveats can help users understand the contract's constraints and avoid transaction errors such as in this example:
6. Test Cases
It's essential that that there is a strong degree of test coverage amounting to at least 90% of the code provided so that the security researchers can have a basis upon which to validate and cross-reference their assumptions or findings. In an ideal world we would seek for clients to provide 100% test coverage and also to cover edge-cases or unforeseen scenarios. In complex protocols, comprehensive testing becomes even more critical, as the interconnectedness of various components increases the risk of vulnerabilities.
For an overview of the various types of test cases Spearbit recommends that clients provide, please see the following documentation on Smart Contract Testing by the Ethereum Foundation.