Process Quality Audit Process

Version 0.2 June 2020

Overview

This document describes the process for a PQ Audit (Process Quality) on a deployed smart contract.

The intent is generation of a simple quality score for the smart contract application being audited. It will indicate the overall quality of the development process and the documents that the process generated. The readers can dig into the details of the audit in order to learn how the score was generated. Every step will be documented and available for review.

The basic premise of these audits is that developers following and documenting a good software development process should have secure code and maintain security. For blockchain developments a good process should have public readily auditable documents and other traces, making the process clear.

These audits are developed and focused towards released operating smart contract applications. The initial focus is on DeFi applications as these bring in many new users investing significant sums that are trusted by the smart contracts.

PQ audits are initially done without the audited organization’s permission or support using exclusively documents publicly available such as the website, the software repository of the code (GitHub, etc), and the code available from Etherscan. After the initial audit report is generated, it will be presented to the developers of the audited organization for correction or improvement. The results of these corrections will be clear and publicly documented in a new version of the report.

The author has no commercial arrangement with the organizations being audited. These audits are not funded by the organization being audited. The author is aiming for community support to audit as a public good.

Aerospace

The author of this process has a long history in the avionics industry. Aerospace software development has always maintained that a rigorous and frequently audited software development process leads to safe and secure software that can be supported for many decades. The avionics process is DO-178C. It is significantly more rigorous than the expectation of this audit process, however the steps used and overarching philosophy has guided the specification of this audit process.

Disclaimer

This report is for informational purposes only and does not constitute investment advice of any kind, nor does it constitute an offer to provide investment advisory or other services. Nothing in this report shall be considered a solicitation or offer to buy or sell any security, future, option or other financial instrument or to offer or provide any investment advice or service to any person in any jurisdiction. Nothing contained in this report constitutes investment advice or offers any opinion with respect to the suitability of any security, and the views expressed in this report should not be taken as advice to buy, sell or hold any security. The information in this report should not be relied upon for the purpose of investing. In preparing the information contained in this report, we have not taken into account the investment needs, objectives and financial circumstances of any particular investor. This information has no regard to the specific investment objectives, financial situation and particular needs of any specific recipient of this information and investments discussed may not be suitable for all investors.

Any views expressed in this report by us were prepared based upon the information available to us at the time such views were written. Changed or additional information could cause such views to change. All information is subject to possible correction. Information may quickly become unreliable for various reasons, including changes in market conditions or economic circumstances.

Summary of the Audit Process

The process looks at the available document through the following steps;

  1. Deployed Code

  2. Requirements and other documentation for the Deployed Code

  3. Overall test strategy for Deployed Code

  4. Review of Software Security Audits

Scoring

The final audit score is indicated as a percentage. The percentage is calculated as (Total Possible Points) / (Achieved Points). For each element the answer can be either Yes/No or a percentage. For each element there is a “Scoring Weight”. The element points achieved is the scoring weight times the answer. The Achieved Points is the sum of every element’s points.

Deployed Code

Any PQ audit starts with code being executed and used by the application. It answers and generates a score on the following questions;

  1. Is the deployed code address(s) readily available? (Y/N)

  2. Is the code actively being used? (%)

  3. Are the Contract(s) Verified/Verifiable? (Y/N)

  4. Does the code match a tagged version in the code hosting platform? (%)

  5. Is the software repository healthy? (%)

Obviously this process lends itself to code already deployed and in use on the mainnet. These are the initial targets of these audits. The process could be adapted in the future toward code in the development process but not yet deployed.

Is the deployed code address(s) readily available? (Y/N)

Scoring weight: 10

Is the address of the deployed mainnet available on the main webpage for the service? An image of the webpage with the address will be recorded as part of the audit. If the answer of this question is no, the rest of the audit takes place without code so the score will be close to zero.

How to improve this score

Make the ethereum addresses of the smart contract utilized by your application available on either your website or your github (in the README for instance). Ensure the address is up to date.

Is the code actively being used? (%)

Scoring weight: 5

This looks at the transaction history of the contract through Etherscan. The results are scored as indicated below. The proof is documented in an appendix. The chart is generated by searching the address, clicking Analytics, then Transactions (for the Transaction chart) and scale it to one month.

More than 10 transactions a day - 100% More than 10 transactions a week - 70% More than 10 transactions a month - 40% Less than 10 transactions a month - 10% No activity - 0%

Are the Contract(s) Verified/Verifiable? (Y/N)

Scoring weight: 5

This checks that the contract code that is executing on the mainnet (taking into account proxy contracts for updated code) is indicated as verified by Etherscan/ETHPM as appropriate. This means the contract tab for the address has “Contract Source Verified (Exact Match)” indicated. The code for this contract is the code that will be audited. As this information is on the blockchain and cannot be edited, no screenshot is required.

How to improve this score

Ensure that the deployed code is verified as described in this article for Etherscan or ETHPM. Improving this score may require redeployment.

Does the code match a tagged version on a code hosting platform (GitHub, GitLab, etc.)? (%)

Scoring weight: 10

The contract’s verified source code is copied from the previous question. This is the exact code executing on the mainnet. Next we find the same code in the software repository the project’s developers share publicly.

First find the developer’s software repository, usually in the “developers” section of the project’s website.

Next we find the software release used to build the deployed code. Often it is in a Release tag where the date matches the deployed date.

Compare source file by source file to ensure a code match.

The outputs of this process are;

  • The address to the developer’s software repository

  • The commit hash or release tag of the deployed contracts

  • A % comparison of the deployed code to the indicated repository. Ideally of course they 100% match.

Percentage Score Guidance

100% - The repository source matches deployed code 100%. The repository was easy to find (labelled clearly). The repository was tagged for the deployed version

90% - The repository source matches deployed code 100% Tag was not labelled appropriately.

80% - The repository source matches deployed code 100% Release is not tagged.

60% - Minor differences in the software repository not in deployed code. Release is not tagged

20% - Deployed code has significant differences not found in any public repository

0% - No reference to deployed code in a public repository was found

How to improve this score

Ensure there is a clearly labelled repository holding all the contracts, documentation and tests for the deployed code. Ensure an appropriately labeled tag exists corresponding to deployment dates. Release tags are clearly communicated.

Is development software repository healthy? (Y/N)

Scoring weight: 20

A healthy software repository has evidence of activity that indicates the deployed code was developed and tested in that repository. A number of commits, branches and releases indicates health. An unhealthy repository has so few actions that it is obvious the code was not developed or tested there.

The response is subjective by the author. Continued development after a release indicates that the team takes the security of their application seriously, and is continuously looking for issues in their code that could lead to a vulnerability against the deployed version of the code.

How to improve this score

Ensure there is a clearly labelled repository holding all the contracts, documentation and tests for the deployed code. Continue to test and perform other verification activities after deployment, including routine maintenance updating to new releases of testing and deployment tools. Is there a whitepaper?

Requirements

The requirements section describes the quality of the system and software documentation and commenting. In this initial version of the Process Audit standard, only basic documentation is requested. For perspective, the aerospace software requirements are mentioned below.

Required questions are;

  1. Is there a whitepaper? (Y/N)

  2. Are the basic application requirements documented? (Y/N)

  3. Are the requirements available publicly? (Y/N)

  4. Do the requirements fully (100%) cover the deployed contracts? (%)

  5. Are there sufficiently detailed comments for all functions within the deployed contract code (%)

  6. Is it possible to trace software requirements to the implementation in code (%)

Is there a whitepaper?

Scoring weight: 5

This is simple. Is there a white paper or other basic description of what the project is doing referenced by either the web site or the GitHub. Yes/No.

How to improve this score

Ensure the white paper is available for download from your website or at least the software repository. Ideally update the whitepaper to meet the capabilities of your present application.

Are the basic application requirements documented? (Y/N)

Scoring weight: 10

This is also simple but very important. Are the basic system requirements of the smart contracts documented in either the website or the GitHub? Yes/No. A requirements document is the foundation of application documentation. You can write it after if it did not exist before deployment. This document says what the smart contracts do and should have some connection with the code and contracts allowing at least general traceability of requirements to code.

How to improve this score

Write the document based on the deployed code. For guidance, refer to the SecurEth System Description Document.

Are the requirements available publicly? (Y/N)

Scoring weight: 5

Is still a very simple question. Are the requirements referenced in the question above documented in the contract’s software repository, or available via some other public repository Yes/No.

How to improve this score

Assuming the requirements document exists, add a reference or copy into the software repository, bringing the code and documents together. If one doesn’t exist, create it.

Do the requirements fully (100%) cover the deployed contracts? (%)

Scoring weight: 15

The goal for a 100% score is for documented requirements (in either the website or the GitHub) that cover all of the developed source code. It does not have to cover public libraries, though they should be mentioned. The requirements do not need rigid requirement diction (such as a “shall” in every requirement). For guidance, refer to the SecurEth System Description Document.

For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100. Include example source in the appendices to justify the score.

How to improve this score

This score can improve by adding content to the requirements document such that it comprehensively covers the requirements. For guidance, refer to the SecurEth System Description Document. Using tools that aid traceability detection will help.

Are there sufficiently detailed comments for all functions within the deployed contract code (%)

Scoring weight: 5

Software requirements are not the same as system requirements (that are referenced in the previous questions). Software requirements refer specifically to the code implementation. It is an additional layer of documentation within the code and must exclusively be in comments in the source file. Ideally the comments have fixed formatting giving consistent comments for all authors in all source files for the project. For guidance refer to the SecurEth Software Requirements.

For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100. Include example source in the appendices to justify the score.

How to improve this score

This score can improve by adding comments to the deployed code such that it comprehensively covers the code. For guidance, refer to the SecurEth Software Requirements.

Is it possible to trace software requirements to the implementation in code (%)

Scoring weight: 5

Traceability is a documented link between the requirement and the code. It can be a number or other simple identifier (such as a shortened content hash) that connects a text requirement to the code it implements. Since requirements are usually in separate documents from the software requirements/comments traceability links each requirement to the code that implements it. Ideally there are requirements for every piece of code, 100% requirement traceability. For reference, check the SecurEth guidelines on traceability.

For this initial version of the Process Audit process the auditor qualitatively determines the number between 0 and 100. Include example source in the appendices to justify the score.

How to improve this score

This score can improve by adding traceability from requirements to code such that it is clear where each requirement is coded. For reference, check the SecurEth guidelines on traceability.

Aerospace Requirements

For reference, this presents the software and system requirements for aerospace code certification in an extremely simplified format. It makes a useful comparison.

  1. All System Requirements documented in proper requirements diction

  2. There is documented traceability from each system requirement to software requirements or low level requirements

  3. All software requirements (or low-level requirements/comments) exist for each part of software code

  4. There is documented traceability from the low level requirements to the software code they cover

  5. Every piece of software code is covered by both unit tests and system tests. If a unit test covers the requirements of the system test, the single test suffices.

  6. There is documented traceability from the software to the tests

  7. They were requirement review meetings held according to a documented process to review every requirement

  8. There are documented software requirement reviews held according to a documented process for each software requirement

  9. There are test reviews held according to a documented process for each test

  10. When there is a requirement to change software code for which already reviewed requirements, code or test must change than a change impact analysis document must review the changes and recommend which reviews must be held again on the requirements, software and tests

  11. During the audit any test can be chosen by the auditor and the auditor can review traceability from the test through the code to the requirements with reviews for each step in the process

Testing

This section covers the test suite that the deployed passed before its deployment on the mainnet. Ideally the suite is in the same repository, completely covers all code as the deployed contracts and has a report indicating a successful run. Additional testing can include Formal Verification and active test/stress environments.

In future versions of this process, the auditor will attempt to run the tests on the deployed code, independently verifying the test results. In this initial version we look for the test artifacts in the repository and give a qualitative score based on the artifacts that exist and those that do not.

  1. Full test suite (Covers all the deployed code) (%)

  2. Code coverage (Covers all the deployed lines of code, or explains misses) (%)

  3. Scripts and instructions to run the tests (Y/N)

  4. Packaged with the deployed code (Y/N)

  5. Report of the results (%)

  6. Formal Verification test done (%)

  7. Stress Testing environment (%)

Full test suite (Covers all the deployed code) (%)

Scoring weight: 20

Does the deployed code have a suite of tests and scripts to run them? Do the tests allow for comprehensive testing of the code? If the tests are not in the deployed software repository, then tests done on identical or very similar have value. It is better to test after deployment than never test at all. Testing is described in the SecurEth guidelines.

In later versions of this process we will run the test suite to verify coverage and completeness. At this point we compare the software lines of code between the tests and the smart contracts. A comprehensive test suite might have a test SLOC/ contract SLOC of 150% or more. A 100% ratio is considered minimally acceptable. These numbers are just guidelines. The score for this element is a qualitative number decided by the author after reviewing the tests and the ratio.

How to improve this score

This score can improve by adding tests to fully cover the code. Document what is covered by traceability or test results in the software repository.

Code coverage (Covers all the deployed lines of code, or explains misses) (%)

Scoring weight: 10

Here we consider if the unit tests fully cover the code. Ideally there is a report of a code coverage run with results in the repository. The normal goal is 100% code coverage. Without a report, the author determines a percentage based on the test suite percentage, artifacts in the test scripts and qualitative estimation. If there are any departures, there should be documentation on why certain pieces of code cannot be tested. This should be minimal and well-argued.

How to improve this score

This score can improve by adding tests achieving full code coverage. A clear report and scripts in the software repository will guarantee a high score.

Scripts and instructions to run the tests (Y/N)

Scoring weight: 10

Can 3rd parties run the full test suite using well documented scripts in the deployed software repository? Yes/No. If the scripts and tests are in a similar repository with the same code this is acceptable (but not ideal).

How to improve this score

Add the scripts to the repository and ensure they work. Ask an outsider to create the environment and run the tests. Improve the scripts and docs based on their feedback.

Packaged with the deployed code (Y/N)

Scoring weight: 10

Simple question. Are the tests in the same software repository as the deployed code, Yes / No?

How to improve this score

Improving this score requires redeployment of the code, with the tests. This score gives credit to those who test their code before deployment and release them together. If a developer adds tests after deployment they can gain full points for all test elements except this one.

Report of the results (%)

Ideally there is a test report in the repository of the test results before the code was deployed. Surprisingly most repositories don’t have one. Most testing tools make tests that only report errors. No output means a pass. When auditing deployed code this is not informative. A test report also indicates what is not covered and why. Often there are corner cases of code that are difficult or impossible to test. A report indicates this with a brief explanation.

Code coverage proof actually needs a report. The output should indicate the successful coverage, on what code and using what options.

The output is a percentage. This allows the author to “grade” the report, if it exists.

How to improve this score

Add a report with the results. The test scripts should generate the report or elements of it.

Formal Verification test done (%)

Scoring weight: 5

Formal verification is a specific process of testing software processes that is well suited to some blockchain software. Its use is still limited, but it adds value in some cases. For this reason the weight is lower than other elements. The output is a percentage. This allows the author to “grade” the report, if it exists.

Stress Testing environment (%)

Scoring weight: 5

A Stress testing environment is an active test environment (not the active mainnet) that is used for testing limits of the application. This would run on a testnet with simulated inputs. By maintaining an up to date test environment, the developers can test possible limit cases as they develop. It adds another layer of protection. The output is a percentage determined by the author.

Audits

Scoring weight: 50

Smart contract audits are typically an indicator of quality in the blockchain world. The intent is to have 3rd party blockchain software experts review your code and tests to look for overall quality and the subtle blockchain specific weaknesses that could be utilized by an attacker.

For this reason the score multiplier is high; 50.

  1. Multiple Audits performed before deployment and results public and implemented or not required (100%)

  2. Single audit performed before deployment and results public and implemented or not required (90%)

  3. Audit(s) performed after deployment and no changes required. Audit report is public. (70%)

  4. No audit performed (20%)

  5. Audit Performed after deployment, existence is public, report is not public and no improvements deployed (0%)