The Spearbook: Client side

###### tags: `Spearbook` # The Spearbook: Client side ## For clients: If you are a client **looking to get your project audited by expert security professionals from the Spearbit network** then this article is for you. In this section you will learn how the Spearbit process works and what to expect, as well as how to best prepare for your engagement in order to maximize the amount of findings. Below you can see a high level overview of the process. We will discuss each step in more detail throughout the article. ![Spearbit megabrain - Frame 6](https://hackmd.io/_uploads/BkOAk21MC.jpg) ## FAQ :::info ### When can we start addressing identified issues? As soon as you see them appearing on the audit repository. ### When does it make sense to deploy the contracts? Whenever you consider the contracts are not vulnerable to any known and identified issue. ### How is communication done? Discord and Github. Code is mostly communicated via Github, although we noticed that sharing small snippets via the private Discord channel set up between you and the auditor team to address fast concerns is helpful. Any other form of communication happens via Discord. ### What are helpful things to provide for the auditors? - Project background. - Specification files (if any). - Up to date documentation. - Clear scope. - Watch the private audit repository for auditor notifications. - Rationale behind functions and expected behaviors within the codebase. - Previous audit reports relevant to the client and specific scope. - Contingency plans. - List of all external services and 3rd parties interacting with the protocol. - Architecture diagrams. - Edge case scenarios and attack vectors. - Natspecs and code comments. - Extensive unit/integration testing suite. - Define what parts of the scope may be deployed already and any upgrade plans. - Go-live date for the code that will be in review. ### Will there be a report? Yes, as soon as the audit has ended you will receive a draft report containing all findings for your internal purposes, and ~2 weeks later a copywrited report delivered in`.PDF` format. ::: ## 1. 📝 Submitting an audit application The best and fastest way to schedule an audit is by filling the airtable form via our website [spearbit.com](https://spearbit.com/) , although you can also join our Discord server and post your request on `#request-for-audit` it is more likely to get a response if you do it using the official method. ![](https://i.imgur.com/SOwXrVF.png) After a successful form submission, the core team will reach out to you in the next 48 hours. In the meantime it is recommended that you: - Join the Discord server, where a private channel with you and the core team will be set up in the future. - Clarify the scope of the audit and desired start date with your team. :::info For security reasons the core team will perform due diligence on the client before moving onto the next steps. ::: ## 2. 🔎 Define scope and timeline **A video call will be scheduled in order to discuss your needs as well as:** - Scope of the audit. - Expected starting date. - Familiarize you with the Spearbit process. After these have been defined, you will receive access to a private channel inside the Spearbit Discord. :::success Congratulations 🎉! You now have a direct private communications channel with Spearbit! ::: To estimate workload and auditors required skillset you have to **authorize core members to access the target repository if it is private**. >👉 Note: Access to the target repository is needed to generate realistic estimates and continue the process. In certain occassions we will request you provide access to Lead Security Researchers to pre-evaluate the code base. **After realistic estimates have been set**, we make the audit offer public to the internal Spearbit network. :::info If you need a **private audit** or **want an auditor/s services explicitly**, please inform us in advance. Be advised these requirements could result in undefined waiting times. ::: ## 3. 👥 Gather interested auditors At this point in the process we reach out to our internal network of security experts with an audit offering. **Auditors react on the offering based on personal preferences such as availability and interest.** > 👉 Note: Based on interest from within the community the core team will reach out to you in regards to next steps. **We always make sure to have at least 2 Lead Security Researcher**, 1 Security Researcher, 1 Associate Security Researcher and 2 Junior Security Researchers on each engagement to assure audit quality through collaborative team effort. After the auditor team has been assembled we reach out to you in order to proceed with the next steps. **You have got yourself an audit!** 🥳 ## 4. 🤝 SOW To begin the audit you need to **sign an SOW (Statement Of Work)** with Spearbit where: - We will confirm target scope (commit hash) and timeline (dates). - We will agree on payment, with a 100% upfront deposit (USDC). ### **Base rates billed per engineering week:** <img src="https://hackmd.io/_uploads/ryDXIBsjR.png" width=400> After both parties have signed the SOW, a private channel with the auditor team and your team will be created in the Spearbit Discord to optimize communication. > Note: The marketplace fee is to pay for the logistical infrastructure to manage operations and attract + retain the best auditors. This is how we keep the lights on and assure high quality security reviews. ## 5. 🏁 Start audit **You will be invited to the audit repository were auditors leave comments which you can see and interact with asynchronously.** When a vulnerability has been found, an issue is created. When the issue has been validated it will become part of the final report. ### How it works Let's assume you have requested an audit on 2 extremely important implementations: `MyBank.sol` and `Vault.sol` ### I) Audit Repository Inside the audit repository you will see different branches proportional to the amount of files in scope. If a file has more than 500 lines of code we often split it to minimize latency in Github API requests when pulling issues for copywriting. **What matters to you are the Pull Requests.** ![](https://i.imgur.com/IzcwNNi.png) ### II) Pull Requests In the **Pull Requests section** you can see the 2 files in scope and ... some of the auditors have started leaving comments! ![](https://i.imgur.com/gdDE8Oc.png) ### III) Comments Comments address code related matters, questions and initiate technical discussions. **You are encouraged to actively engage in conversations to capture as much value as you can from auditors time and attention**. This incremental audit approach of commenting on the code as soon as a discovery is made **helps your team address and clarify issues earlier in the audit process**. When an a conversation has reached a conclusion, **a formal issue will be created containing your commit fix** (if you decided not to fix something, then a comment explaining why you made such decision) **and any other relevant conversation between you and the auditors**. :::warning 👀 It is **highly suggested you constantly monitor the audit repository** for notifications. ::: ![](https://i.imgur.com/GTkd1Jz.png) ### IV) Issues **Auditors turn comments into Github Issues** accompanied by its respective serverity and / or status label. ![](https://i.imgur.com/Ln7KjwS.png) **Issues will be reviewed and labeled** as Fixed or Acknowledged depending on your response and eventually become part of the final report. *Example of an Issue which has been fixed by the project developers:* ![](https://i.imgur.com/2dPkHDW.png) ## 6. 📞 Close-up call **After the audit has ended a close up call will be scheduled** between you, the auditor team and the core team to discuss findings and answer any other questions you may have. ## 7. ⚙️ Fix review After the close-up call, you can **request an extension period**. The security team will **estimate the amount of work requierd to review your implemented fixes and send a fix SOW for signatures.** :::info **Note:** Be sure to create one PR per issue to make reviewing the fixes easier. ::: ### I) Labeling In addition to the above notes, we recommend that the client follow this methodology for labeling issues as they go from ackowledged, fixed, reviewed: `Status: Changes Requested` Spearbit team will use this label on the issues that have the `Status: Fix` applied but still require some changes. Once the Client Team applies those changes to the PR, they can remove this label. `Status: Changes Requested` from the issue and apply a new label called `Status: Changes Applied`. `Status: Changes Applied` let's the Spearbit team know that a change has been approved which will now require an updated label `Status: Verified by USERNAME`. `Status: Verified by USERNAME` gets tagged if it has been validated by a Spearbit security researcher or re-add the `Status: Changes Requested` if new changes are required. `Fixed` if the project has fixed the issue. `Acknowledged` if the project has acknowledged the issue but not taken any further action. Mark the issue with `ReadyForReport` to confirm the issue is ready for the client report. :::info Note 3: In either case (verification or more changes) the `Status: Changes Applied` can be removed by the Spearbit team. The label swapping can go for a few rounds till Spearbit team approves/verifies the PR changes. ::: *Here is an example of the above labeling from a security review.* ![](https://hackmd.io/_uploads/SkSFKrHOj.png) ## 8. 🖺 Final Report **You will receive the final report on your private Discord communications channel with Spearbit in a maximum of ~2 weeks after your fixes have been implemented.** We will also send you a **draft report** containing all valid issues in case you need it for internal purposes as soon as the audit has ended. If after 1 week of receiving the report there are aren't any comments or concerns raised, you acknowledge the report is complete and therefore concluding the final report delivery phase. ## For more information... Feel free to reach us on our website [spearbit.com](https://spearbit.com/) or via email at `core-team [at] spearbit [dot] com`.